Liveness and Readiness Probes

Liveness and readiness probes can be used to remove your instances from anycast routing ensuring that your application is always available if an instance within your edge computing workload fails. Probes work with both container and virtual machine workloads.

Probe Basics

Probes can check either HTTP endpoints or a TCP port, and it's possible to configure the frequency, timeout, initial delay, and success and failure thresholds of the probes. However, liveness and readiness probes behave differently when a failure is seen.

Both liveness and readiness probes remove the instance from anycast routing when a failure is seen, however a liveness probe also reboots the instance in an attempt to recover it.

HTTP

HTTP checks (HTTPS is also possible) make a request to the specified path and any HTTP status codes greater than or equal to 200 but less than 400 is considered a success. Any other HTTP status codes are considered a failure. As the check only tests the HTTP status code you need to implement an endpoint in your application to test your business logic and return the appropriate response code, if required. With HTTP checks it's also possible to configure the scheme, the port, and HTTP headers.

TCP

TCP checks attempt to open a socket to your instances on the specified port. If this is successful the probe is considered successful, otherwise the probe is considered a failure.

Common Configuration Options

Readiness and liveness probes share some common configuration options:

Configuring Probes

Probes can be configured when the workload is created, or they can be added later in a workload update.

Creating a Workload With Probes

Simply add the probe to your workload specification when creating the workload. For example, to set an HTTP readiness probe checking the /health endpoint on port 8080 with a basic auth header every 10 seconds you need to add the following to your workload specification:

"readinessProbe": {
  "httpGet": {
    "path": "/health",
    "port": 8080,
    "scheme": "HTTP",
    "httpHeaders": {
      "Authorization": "Basic QWxhZGRpbjpPcGVuU2VzYW1l"
    }
  },
  "initialDelaySeconds": "30",
  "timeoutSeconds": "2",
  "periodSeconds": "10",
  "successThreshold": "1",
  "failureThreshold": "3"
}

For example, when creating a virtual machine workload:

{
  "workload": {
    "spec": {
      "virtualMachines": {
        "$DNS_NAME": {
          "readinessProbe": {
            "httpGet": {
              "path": "/health",
              "port": 8080,
              "scheme": "HTTP",
              "httpHeaders": {
                "Authorization": "Basic QWxhZGRpbjpPcGVuU2VzYW1l"
              }
            },
            "initialDelaySeconds": "30",
            "timeoutSeconds": "2",
            "periodSeconds": "10",
            "successThreshold": "1",
            "failureThreshold": "3"
          }
        }
      }
    }
  }
}

The readinessProbe object should be added to your container or virtual machine specification, as per the above example.

Updating a Workload

🚧

Provide the Current Metadata Version

You must provide the current metadata version when issuing a PATCH request, else the request will fail.

If you want to enable liveness or readiness probes on an existing workload you need to send a PATCH request to update your workload configuration and include the probe configuration within your containers or virtualMachines spec objects. For example, to add a TCP liveness probe checking port 22 every 10 seconds with a 2 second timeout and a failure threshold of 3 on a virtual machine workload you would need to issue a request similar to below, updating the $STACK_ID and $WORKLOAD_ID in the URL and configuring the probe as required:

curl -s -X PATCH https://gateway.stackpath.com/workload/v1/stacks/$STACK_ID/workloads/$WORKLOAD_ID \
-H "Authorization: bearer BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "workload": {
    "spec": {
      "virtualMachines": {
        "$DNS_NAME": {
          "livenessProbe": {
            "tcpSocket": {
              "port": "22"
            },
            "initialDelaySeconds": "30",
            "timeoutSeconds": "2",
            "periodSeconds": "10",
            "successThreshold": "1",
            "failureThreshold": "3"
          } 
        }
      }
    },
    "metadata": {
      "version": "7"
    }
  }
}'