The StackPath Developer Portal

Integrate our platform directly into your products and dynamically protect your edge.

Get Started    API Reference

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:

Name
Default Value
Min Value
Description

initialDelaySeconds

0

0

The initial delay before the probe starts

timeoutSeconds

1

1

The number of seconds before the probe times out and is considered a failure

periodSeconds

10

1

The frequency of the probe in seconds

successThreshold

1

1

The minimum consecutive successes required before a probe is considered successful after a failure. This must be 1 for liveness probes

failureThreshold

3

1

The amount of failures seen before the probe is considered a failure.

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"
    }
  }
}'

Liveness and Readiness Probes


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.