Commands Reference

Command reference sub-specification for Programmable Preflight Checks and Test Procedures.

This content is associated with a legacy version of the Replicated product. For the current Replicated product docs, click here.

Commands

Commands are a sub-specification of both Programmable Preflight Checks and Test Procedures. They return result messages, a status code and an error. Next we will look at examples. For details on the properties please see the resource specification section at the bottom of the page.

Scheduler

The scheduler command references a container in the components section of the YAML. Standard out and standard error will be captured and returned via the result message. Any exit code as a result of the container will be returned via the status code of the command. When the container cannot be run due to an error, an error will be returned. The container will be run on the nodes as specified by the component section of the container YAML.

Id: scheduler

Status Codes: 1, 22, 62 *

Name	Type	Required	Description
data	`{replicated: {component: string, container: string}}`	yes	A component and container reference
cmd	string	no	Optionally override the container cmd
config_files	array[ConfigFile]	no	v2.7.0 Additional config files to mount as volumes in the container
entrypoint	array[string]	no	Optionally override the container entrypoint
ports	array[ExposedPort]	no	Optionally override the container exposed ports

Example

id: scheduler
timeout: 30 # in seconds, default to 15, -1 == no timeout
data:
  component: DB # the component and container from the components section of the YAML
  container: mysql
  cmd: "[\"sh\", \"-c\", \"'exec mysql -h {{repl ThisNodePrivateIPAddress }} -u myuser -p {{repl ConfigOption \"mysql_pass\" }} yourdatabase < /opt/check-schema-version.sql'\"]"
  config_files:
    - filename: /opt/check-schema-version.sql
  contents: |
    select version from schema limit 1;    
  ports: [] # override scheduler container properties

Raw

The raw command is run inside Replicated’s command container. The clustering and tags properties will determine where the command is run. If clustering is disabled the command will run on all nodes in the cluster. Additional properties to the raw command are all that can be specified in the container section of the YAML.

Id: raw

Status Codes: 1, 22, 62 *

Name	Type	Required	Description
cmd	string	yes	The cmd to be run when executing the container
cluster	string	no	Is clustering enabled (evaluated to a boolean value)
tags	array[string]	no	Determines nodes where the check is performed when cluster=true
conflicts	array[string]	no	Skips nodes with the tag when cluster=true
additional…		no	all possible container properties

Example

id: raw
data:
  cmd: '["test", "-e", "/host/etc/vendor-license"]'
  volumes:
    - host_path: /etc
  container_path: /host/etc
  options: ["ro"]

Disk Space Available

The disk space available command will return the disk space available in bytes. Note that the result is always a string and must be parsed (e.g. {{repl .Result | ParseFloat | lt 1e+9 }} or {{repl .Result | ParseFloat | HumanSize }}). The clustering and tags properties will determine where the command is run. If cluster is false the command will run on all nodes in the cluster.

Id: disk_space_available

Status Codes: 1, 22, 62 *

Name	Type	Required	Description
dir	string	yes	The directory to check
cluster	string	no	Is clustering enabled (evaluated to a boolean value)
tags	array[string]	no	Determines nodes where the check is performed when cluster=true
conflicts	array[string]	no	Skips nodes with the tag when cluster=true

Example

id: disk_space_available
data:
  cluster: true
  tags: ["db"]
  dir: /data/mysql

Disk Space Total

The disk space total command will return the disk space available in bytes. Note that the result is always a string and must be parsed (e.g. {{repl .Result | ParseFloat | lt 1e+9 }} or {{repl .Result | ParseFloat | HumanSize }}). The clustering and tags properties will determine where the command is run. If cluster is false the command will run on all nodes in the cluster.

Id: disk_space_total

Status Codes: 1, 22, 62 *

Name	Type	Required	Description
dir	string	yes	The directory to check
cluster	string	no	Is clustering enabled (evaluated to a boolean value)
tags	array[string]	no	Determines nodes where the check is performed when cluster=true
conflicts	array[string]	no	Skips nodes with the tag when cluster=true

Example

id: disk_space_total
data:
  cluster: true
  tags: ["db"]
  dir: /data/mysql

Port Available

The port available command will determine whether the port and ip are available for use. Status code 98 (address already in use) will be returned when unable to bind to the address. The clustering and tags properties will determine where the command is run. If cluster is false the command will run on all nodes in the cluster.

Id: port_available

Status Codes: 1, 22, 62, 98 *

Name	Type	Required	Description
port	string	yes	The port to check
proto	string	no	The protocol, one of `tcp` (default) or `udp`
ip	string	no	The ip to bind to, defaults to 0.0.0.0 (will take precedence over interface if set)
interface	string	no	The interface to bind to
cluster	string	no	Is clustering enabled (evaluated to a boolean value)
tags	array[string]	no	Determines nodes where the check is performed when cluster=true
conflicts	array[string]	no	Skips nodes with the tag when cluster=true

Example

id: port_available
data:
  port: '80'
  ip: '{{repl ThisNodePrivateIPAddress }}'
  cluster: true
  tags: ["lb"]

TCP Dial

The tcp dial command will determine whether a connection can be made over tcp to the address specified. Status code 111 (connection refused) will be returned when unable to connect to the address. The clustering and tags properties will determine where the command is run. If cluster is false the command will run only on the local node.

Id: tcp_dial

Status Codes: 1, 22, 62, 111 *

Name	Type	Required	Description
addr	string	yes	The address to connect to
cluster	string	no	Is clustering enabled (evaluated to a boolean value)
tags	array[string]	no	Determines nodes where the check is performed when cluster=true
conflicts	array[string]	no	Skips nodes with the tag when cluster=true

Example

id: tcp_dial
data:
  addr: 'github.com:443'
  cluster: false

HTTP Request

The HTTP Request command will make an HTTP request to the URL specified. The HTTP Status Code will be returned upon a successful HTTP request. Status code 111 (connection refused) will be returned when unable to connect to the address. The clustering and tags properties will determine where the command is run. If cluster is false the command will run only on the local node.

Id: http_request

Status Codes: 1, 22, 62, 111 * and all HTTP Status Codes

Name	Type	Required	Description
url	string	yes	The HTTP request URL
method	string	no	The HTTP request method (default “GET”)
headers	map[string]array[string]	no	Additional HTTP request headers
body	string	no	The HTTP request body
insecureSkipVerify	boolean	no	Skip TLS certificate verification
noProxy	boolean	no	Bypass any HTTP proxy

Example

id: http_request
data:
  url: 'https://github.com'
  method: 'HEAD'
  cluster: false

Resource Specification

Command

The command resource represents the command that is to be run. The command will return messages, a status code and possibly an error. See the commands section for a list of supported operations.

Name	Type	Required	Description
id	string	yes	The command id
timeout	int	no	Timeout in seconds, default 15 seconds, -1 denotes no timeout
data	object	no	The command data

Result

The result resource represents the different possible outcomes of the command. A result contains a status, message and condition. Result are evaluated in order and the first matching result will determine the requirement status. If no condition properties are specified that result will always evaluate to true. If no results match the requirement will receive status error.

Name	Type	Required	Description
status	string	yes	One of success, warn or error
message	string or Message	yes	A description of the result
condition	Condition	no	The condition that must be met

Condition

All properties of a condition must be met to determine that condition to be true. The bool_expr property is intended to be evaluated using Replicated templates. This template will receive the following variables from the result of the command: .Results (array of messages), .Result (the first message), .StatusCode, .Error.

Name	Type	Required	Description
error	boolean	no	Did the command result in an error?
status_code	int	no	The command status code
bool_expr	string	no	An expression that can be evaluated and parsed as a boolean

Message

A message resource can be localized via the id. It contains a default message that will be displayed when no localization is present. Messages have arguments that can be substituted into the text via templates.

Name	Type	Required	Description
id	string	no	The message identifier. Can be used to localize the message.
default_message	string	yes	The default message
args	map[string]string	no	Arguments to the message

Status Codes

Code	Description
1	Catchall for general errors
22	Invalid argument
62	Timeout
98	Address already in use
111	Connection refused

Programmable Test Procedures

Admin Commands

Commands Reference

Replicated Native Scheduler

Replicated Native Scheduler

Packaging An Application

Managing Customer Installations

Native Scheduler Examples

Commands

Scheduler

Example

Raw

Example

Disk Space Available

Example

Disk Space Total

Example

Port Available

Example

TCP Dial

Example

HTTP Request

Example

Resource Specification

Command

Result

Condition

Message

Status Codes