Manage Probes

Probes connect to an asset to report back about the asset's status, readiness, or health.

Codiac manages probes in a "one and done" way that maximizes your ability to deploy uniform probes across all of your assets consistently:

You only have to provide the settings for a probe the first time you add it to Codiac.
Codiac stores the probe's settings.
From then on, you only have to enter the probe's settings if you want to customize its usage.

Prerequisites

Basic Codiac Prerequisites
Existing Codiac asset, cluster, and cabinet.
The probe script, which you have customized for your asset.

Overview

A probe is a bespoke script or package of code that you have customized for your asset.

tip

Instructions on creating a probe are beyond the scope of this documentation. Michael Levan's "Getting Started with Liveness Probes and Readiness Probes" is an excellent starting point.

Codiac supports three probe types:

Startup: Monitors an asset when it is deployed and reports back when the deployment is complete.
Readiness: Is the asset ready to accept traffic?
Liveness: Is the asset running?

info

Each asset can have only one probe of each type (startup, readiness, and liveness).

Codiac supports four probe methods:

Basic:
- Executable: An executable CLI command that treats a zero response code as success and non-zero as failure.
- HTTP: An HTTP request that treats a response code between 200 and 400 as success and any other value as failure.
Advanced:
- GRPC: A GRPC API request.
- Socket: A TCP socket request.

Add a Probe to Codiac

Use codiac asset probe create to add a probe to Codiac. Customize this command with the details of your probe, like the type of probe and how often it should run.

If you do not specify the asset you want to deploy the probe on, the command will prompt you to choose one. Each probe you create is specific to its asset.

Example

This command:

codiac probe create \
    -a grafana \
    -p 15 \
    --exec \
    -- cat /app/data/last-heartbeat.json

Tells Codiac to create a probe which:

On the grafana asset.
Every 15 seconds.
As an executable CLI command which treats a response code of zero as success and non-zero as failure.
Runs the specified command on the specified asset.

As a result, every 15 seconds this probe runs "cat /app/data/example-command.json" on the grafana asset. The command returns zero if it's a success. Any other return value is interpreted as a failure.

bash-$ codiac probe create -a grafana -p 15 --exec -- cat /app/data/last-heartbeat.json
You are about to set this readiness probe on grafana:

type: readiness
action:
  actionType: exec
  command:
    - cat
    - /app/data/last-heartbeat.json
periodSeconds: 15

? Continue: Yes
Writing new Probe... Done
SUCCESSFUL! Created exec action as readiness probe for asset grafana in main.
bash-$ codiac asset probe list
grafana: readiness @ 15s -> exec (cat /app/data/last-heartbeat.json)
bash-$ 

tip

This example was submitted by a customer who uses it to check an error file. If no errors have been logged, the error file is empty, and the probe returns a value of zero (success). If an error has been logged, the probe returns a non-zero value (failure). This is a "no news is good news" approach to heartbeat monitoring.

Executable

Usage and Options

codiac asset probe create [CMD] declares the implementation of a health or readiness probe for an asset.

$ codiac asset probe create -h
USAGE
  $ codiac asset probe create [CMD] -u readiness|liveness|startup [-h] [-n <value>] [-a <value>] [-v <value>] [-d
    <value>] [-p <value>] [--predefined <value> | --exec | --grpc | --http | --socket] [-x <value>] 
    <value> ] [--grpcHost <value> ] [--grpcPort <value> ] [--httpScheme http|https ] [--httpHost <value> ] [--httpPort
    <value> ] [--httpPath <value> ] [-h <value> ] [--socketHost <value> ] [--socketPort <value> ]

ARGUMENTS
  CMD  (requires --exec) command and its space-separated arguments to run in the target replica.

FLAGS
  -a, --asset=<value>          The name of the asset to which this probe is to apply.
  -d, --delay=<value>          The time (in seconds) to wait before the first execution of the probe.
  -h, --httpHeader=<value>...  (For use only with http) Key value pair (in format x=y) to be used as an http header in
                               an http probe action.
  -n, --enterprise=<value>     The name of the enterprise to which this probe is to apply.
  -p, --period=<value>         [default: 10] How often (in seconds) to fire the probe.
  -u, --usage=<option>         (required) [default: readiness] The diagnostic purpose the probe will serve.
                               <options: readiness|liveness|startup>
  -v, --versions=<value>       Asset version range for which this probe is to be used. (optional: defaults to >=latest)
  -x, --action=<value>         The JSON specification for the probe action itself.  The structure follows the
                               actionType.
  --exec                       Declares the probe shall be carried out as an executable CLI command. A return code of
                               zero indicates success.  Any non-zero result indicates failure.

DESCRIPTION
  Declares the implementation of a health or readiness probe for an asset.

ALIASES
  $ codiac asset probe create

EXAMPLES
  cod asset probe create -a myasset --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --http --httpScheme https --httpHost myapi.acme.com --httpPort 443 --httpPath /diag/heartbeat -h Accept=application/json -h user-agent=MyUserAgent

Flag	Description
--exec	An executable CLI command which treats a response code of zero as success and non-zero as failure.

Associated parameters:

Parameter	Example	Description
-- [COMMAND_TO_RUN]	`-- cat /app/data/example-command.json`	The command you want the probe to run.

HTTP

Usage and Options

codiac asset probe create [CMD] declares the implementation of a health or readiness probe for an asset.

$ codiac asset probe create -h
USAGE
  $ codiac asset probe create [CMD] -u readiness|liveness|startup [-h] [-n <value>] [-a <value>] [-v <value>] [-d
    <value>] [-p <value>] [--predefined <value> | --exec | --grpc | --http | --socket] [-x <value>] 
    <value> ] [--grpcHost <value> ] [--grpcPort <value> ] [--httpScheme http|https ] [--httpHost <value> ] [--httpPort
    <value> ] [--httpPath <value> ] [-h <value> ] [--socketHost <value> ] [--socketPort <value> ]

ARGUMENTS
  CMD  (requires --exec) command and its space-separated arguments to run in the target replica.

FLAGS
  -a, --asset=<value>          The name of the asset to which this probe is to apply.
  -d, --delay=<value>          The time (in seconds) to wait before the first execution of the probe.
  -h, --httpHeader=<value>...  (For use only with http) Key value pair (in format x=y) to be used as an http header in
                               an http probe action.
  -n, --enterprise=<value>     The name of the enterprise to which this probe is to apply.
  -p, --period=<value>         [default: 10] How often (in seconds) to fire the probe.
  -u, --usage=<option>         (required) [default: readiness] The diagnostic purpose the probe will serve.
                               <options: readiness|liveness|startup>
  -v, --versions=<value>       Asset version range for which this probe is to be used. (optional: defaults to >=latest)
  -x, --action=<value>         The JSON specification for the probe action itself.  The structure follows the
                               actionType.
  --http                       Declares the probe shall be carried out as an http request. Any code greater than or
                               equal to 200 and less than 400 indicates success. Any other code indicates failure.
  --httpHost=<value>           .
  --httpPath=<value>           (For use only with http).
  --httpPort=<value>           (For use only with http).
  --httpScheme=<option>        (For use only with http) The http protocol to use.
                               <options: http|https>

DESCRIPTION
  Declares the implementation of a health or readiness probe for an asset.

ALIASES
  $ codiac asset probe create

EXAMPLES
  cod asset probe create -a myasset --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --http --httpScheme https --httpHost myapi.acme.com --httpPort 443 --httpPath /diag/heartbeat -h Accept=application/json -h user-agent=MyUserAgent

Flag	Description
--http	An HTTP request which treats a response code between 200 and 400 as success and any other value as failure.

Associated parameters:

Parameter	Example	Description
--h [HTTP_HEADER]	`-h user-agent=MyUserAgent`	A key/value pair to send as an HTTP header.
--httpHost=[HOSTNAME]	`--httpHost myapi.acme.com`	The HTTP host.
--httpPath=[PATH]	`--httpPath /diag/heartbeat`	The path to the target script on the HTTP host.
--httpPort=[PORT_NUMBER]	`--httpPort 443`	The port the probe uses.
--httpScheme=[SCHEME]	`--httpScheme https`	The HTTP protocol. Options are `http` and `https`.

Example

This command:

codiac probe create \
    -n acme \
    -a myapi \
    -u readiness \
    -p 15 \
    --http \
    --httpScheme https \
    --httpHost myapi.acme.com \
    --httpPort 443 \
    --httpPath /diag/heartbeat \
    -h Accept=application/json \
    -h user-agent=MyUserAgent

Tells Codiac to create a probe which:

On the acme enterprise.
The myapi asset.
A readiness probe.
Every 15 seconds.
As an HTTP request which treats a response code between 200 and 400 as success and any other value as failure.
Using the HTTPS protocol.
At myapi.acme.com.
On port 443.
At the path /diag/heartbeat.
With the Accept=application/json and user-agent=MyUserAgent key/value pairs as HTTP headers.

As a result, every 15 seconds this probe will make an HTTP request to https://myapi.acme.com/diag/heartbeat on port 443, passing user-agent=MyUserAgent as an HTTP header.

Advanced

GRPC

Usage and Options

codiac asset probe create [CMD] declares the implementation of a health or readiness probe for an asset.

$ codiac asset probe create -h
USAGE
  $ codiac asset probe create [CMD] -u readiness|liveness|startup [-h] [-n <value>] [-a <value>] [-v <value>] [-d
    <value>] [-p <value>] [--predefined <value> | --exec | --grpc | --http | --socket] [-x <value>] 
    <value> ] [--grpcHost <value> ] [--grpcPort <value> ] [--httpScheme http|https ] [--httpHost <value> ] [--httpPort
    <value> ] [--httpPath <value> ] [-h <value> ] [--socketHost <value> ] [--socketPort <value> ]

ARGUMENTS
  CMD  (requires --exec) command and its space-separated arguments to run in the target replica.

FLAGS
  -a, --asset=<value>          The name of the asset to which this probe is to apply.
  -d, --delay=<value>          The time (in seconds) to wait before the first execution of the probe.
  -h, --httpHeader=<value>...  (For use only with http) Key value pair (in format x=y) to be used as an http header in
                               an http probe action.
  -n, --enterprise=<value>     The name of the enterprise to which this probe is to apply.
  -p, --period=<value>         [default: 10] How often (in seconds) to fire the probe.
  -u, --usage=<option>         (required) [default: readiness] The diagnostic purpose the probe will serve.
                               <options: readiness|liveness|startup>
  -v, --versions=<value>       Asset version range for which this probe is to be used. (optional: defaults to >=latest)
  -x, --action=<value>         The JSON specification for the probe action itself.  The structure follows the
                               actionType.
  --grpc                       Declares the probe shall be carried out as a grpc api request.
  --grpcHost=<value>           (For use only with grpc).
  --grpcPort=<value>           (For use only with grpc).

DESCRIPTION
  Declares the implementation of a health or readiness probe for an asset.

ALIASES
  $ codiac asset probe create

EXAMPLES
  cod asset probe create -a myasset --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --http --httpScheme https --httpHost myapi.acme.com --httpPort 443 --httpPath /diag/heartbeat -h Accept=application/json -h user-agent=MyUserAgent

Flag	Description
--grpc	A GRPC API request.

Associated parameters:

Parameter	Example	Description
--grpcHost=[HOSTNAME]	`--grpcHost api.acme.com`	The GRPC host.
--grpcPort=[PORT_NUMBER]	`--grpcPort 443`	The port the probe uses.

Socket

Usage and Options

codiac asset probe create [CMD] declares the implementation of a health or readiness probe for an asset.

$ codiac asset probe create -h
USAGE
  $ codiac asset probe create [CMD] -u readiness|liveness|startup [-h] [-n <value>] [-a <value>] [-v <value>] [-d
    <value>] [-p <value>] [--predefined <value> | --exec | --grpc | --http | --socket] [-x <value>] 
    <value> ] [--grpcHost <value> ] [--grpcPort <value> ] [--httpScheme http|https ] [--httpHost <value> ] [--httpPort
    <value> ] [--httpPath <value> ] [-h <value> ] [--socketHost <value> ] [--socketPort <value> ]

ARGUMENTS
  CMD  (requires --exec) command and its space-separated arguments to run in the target replica.

FLAGS
  -a, --asset=<value>          The name of the asset to which this probe is to apply.
  -d, --delay=<value>          The time (in seconds) to wait before the first execution of the probe.
  -h, --httpHeader=<value>...  (For use only with http) Key value pair (in format x=y) to be used as an http header in
                               an http probe action.
  -n, --enterprise=<value>     The name of the enterprise to which this probe is to apply.
  -p, --period=<value>         [default: 10] How often (in seconds) to fire the probe.
  -u, --usage=<option>         (required) [default: readiness] The diagnostic purpose the probe will serve.
                               <options: readiness|liveness|startup>
  -v, --versions=<value>       Asset version range for which this probe is to be used. (optional: defaults to >=latest)
  -x, --action=<value>         The JSON specification for the probe action itself.  The structure follows the
                               actionType.
  --exec                       Declares the probe shall be carried out as an executable CLI command. A return code of
                               zero indicates success.  Any non-zero result indicates failure.
  --grpc                       Declares the probe shall be carried out as a grpc api request.
  --grpcHost=<value>           (For use only with grpc).
  --grpcPort=<value>           (For use only with grpc).
  --http                       Declares the probe shall be carried out as an http request. Any code greater than or
                               equal to 200 and less than 400 indicates success. Any other code indicates failure.
  --httpHost=<value>           .
  --httpPath=<value>           (For use only with http).
  --httpPort=<value>           (For use only with http).
  --httpScheme=<option>        (For use only with http) The http protocol to use.
                               <options: http|https>
  --socket                     Declares the probe shall be carried out as a TCP Socket request.
  --socketHost=<value>         (For use only with socket).
  --socketPort=<value>         (For use only with socket).

DESCRIPTION
  Declares the implementation of a health or readiness probe for an asset.

ALIASES
  $ codiac asset probe create

EXAMPLES
  cod asset probe create -a myasset --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --exec -- cat /app/data/last-heartbeat.json

  cod probe create -n acme -a myapi -u readiness -p 15 --http --httpScheme https --httpHost myapi.acme.com --httpPort 443 --httpPath /diag/heartbeat -h Accept=application/json -h user-agent=MyUserAgent

Flag	Description
--socket	A TCP socket request.

Associated parameters:

Method	Parameter	Example	Description
Socket	--socketHost=[HOSTNAME]	`--socketHost host.acme.com`	The TCP socket host.
Socket	--socketPort=[PORT_NUMBER]	`--socketPort 80`	The port the probe uses.
Socket	--success-threshold=[THRESHOLD]	`--success-threshold 2	The minimum number of consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup Probes. Minimum value is 1.

List Probes

Use codiac asset probe list to list all existing probes.

bash-$ codiac asset probe list
grafana: readiness @ 15s -> exec (cat /app/data/last-heartbeat.json)

Edit a Probe

To change the parameters of an existing probe, repeat the codiac asset probe create command with your new parameters.

tip

Don't worry about accidentally creating a duplicate probe on your asset. Each asset can only have one of each probe type (startup, readiness, and liveness). A new probe definition will always override the existing probe of that type.

Example

In our previous example, we used the following command to create a readiness probe on the micro-01 asset that runs every 15 seconds:

codiac probe create -a micro-01 -p 15 --exec -- cat /app/data/last-heartbeat.json

Let's say we want this probe to run every 5 seconds instead. To do this, use the following command:

codiac probe create -a micro-01 -p 5 --exec -- cat /app/data/last-heartbeat.json

You can then use codiac asset probe list to verify the change.

bash-$ codiac asset probe list
micro-01: readiness @ 15s -> exec (cat /app/data/last-heartbeat.json)
bash-$ codiac probe create -a micro-01 -p 5 --exec -- cat /app/data/last-heartbeat.json
You are about to set this readiness probe on micro-01:

type: readiness
action:
  actionType: exec
  command:
    - cat
    - /app/data/last-heartbeat.json
periodSeconds: 5

? Continue: Yes
Writing new Probe... Done
SUCCESSFUL! Created exec action as readiness probe for asset micro-01 in main.
bash-$ codiac asset probe list
micro-01: readiness @ 5s -> exec (cat /app/data/last-heartbeat.json)

Delete a Probe

warning

Deleting a probe is a global action. The probe is deleted from the asset across your entire account.

Use codiac asset probe delete to delete an asset probe definition.

caution

This command does not change running assets. For the changes to take effect, you must redeploy a running asset.

Overview​

Add a Probe to Codiac​

Example​

Executable​

HTTP​

Example​

Advanced​

GRPC​

Socket​

List Probes​

Edit a Probe​

Example​

Delete a Probe​

Overview

Add a Probe to Codiac

Example

Executable

HTTP

Example

Advanced

GRPC

Socket

List Probes

Edit a Probe

Example

Delete a Probe