Manage Probes

Probes enable you to get information about the health and readiness of assets that are starting up or running.

Codiac supports three probe types:

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

And four probe methods:

Basic probes:
- Executable: An executable CLI command that treats a response code of zero 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 probes:
- GRPC: A GRPC API request.
- Socket: A TCP socket request.

Usage and Options

Use codiac asset probe -h to see all the available options:

$ codiac asset probe -h
Declares the implementation of a health or readiness probe for an asset.

USAGE
  $ codiac asset probe COMMAND

COMMANDS
  asset probe create  Declares the implementation of a health or readiness probe for an asset.
  asset probe delete  Removes an asset probe definition.  DOES NOT running assets; assets will need to be
                      redeployed for this change to affect their runtime instances.
  asset probe list    Retrieves the list of existing secret stores captured for a given enterprise.

Prerequisites

Basic Codiac Prerequisites
Existing Codiac asset, cluster, and cabinet.
The script you want the probe to run.

Create a Probe

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>] [--execCommand
    <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.
  --execCommand=<value>...     (For use only with exec) The executable command to run as the probe, as a single string,
                               or as an array of commands and arguments.  If it returns any non-zero result, the probe
                               gets interpreted as a negative/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 probe create -p 15 --exec --execCommand="cat /app/data/last-heartbeat.json"

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

  cod probe create -n acme -a myapi -u readiness -p 15 --exec --execCommand cat --execCommand /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

Codiac supports four probe methods:

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

Executable

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
--execCommand=[COMMAND_TO_RUN]	`--execCommand="cat /app/data/example-command.json"`	The command you want the probe to run.

Example

This command:

codiac probe create \
    -p 15 \
    --exec \
    --execCommand="cat /app/data/example-command.json"

Tells Codiac to create a probe which:

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.

As a result, every 15 seconds this probe will run "cat /app/data/example-command.json". If the command returns zero, Codiac interprets it as a success. If the command returns any other value, Codiac interprets it as a failure.

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.

HTTP

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

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

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.

Delete a Probe

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

caution

This command does not remove running assets. You will need to redeploy an asset for the change to affect its runtime instances.

Create a Probe​

Executable​

Example​

HTTP​

Example​

Advanced​

List Probes​

Delete a Probe​

Create a Probe

Executable

Example

HTTP

Example

Advanced

List Probes

Delete a Probe