Docker — system/ping

Lightweight check: system/ping calls the Docker API /_ping endpoint which returns a single-byte response. It is significantly cheaper than system/info and should be used whenever you only need to confirm that the daemon is reachable — not retrieve metadata.

When to Use

Scheduled health monitoring: Ping the Docker daemon every 30–60 seconds on a scheduled workflow trigger; alert operations if the ping fails or times out.
Pre-workflow dependency gate: Verify Docker connectivity at the start of any multi-step deployment workflow so subsequent nodes fail fast with a clear error rather than timing out individually.
Failover detection: Ping the primary Docker host; if unreachable, route work to a standby host — preventing deployment failures during host maintenance.
Connection validation in setup: Use as the last step when configuring a new Docker connection credential to confirm settings are correct before saving.

Configuration

Connection

Field	Type	Default	Description
`dockerHost`	string	`unix:///var/run/docker.sock`	Docker daemon socket path or TCP endpoint.
`connectionType`	string	`unixsocket`	One of: `unixsocket`, `tcp`, `tcptls`.
`tlsCertPath`	string	—	TLS certificate directory. Required for `tcptls`. optional
`timeoutSeconds`	int	5	Ping timeout in seconds. Keep low for health-check workflows. optional

Operation Fields

This operation requires no additional input fields. Set resource to system and operation to ping.

Sample Configuration

{
  "resource": "system",
  "operation": "ping",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket",
    "timeoutSeconds": 5
  }
}

Validation Errors

Error Code	Condition	Resolution
`CONFIG_ERROR`	Connection settings malformed.	Check `dockerHost` format and `connectionType` value.
`AUTH_FAILED`	TLS handshake failed on `tcptls` connection.	Verify certificates in `tlsCertPath`.
`DOCKER_API_ERROR`	Daemon is unreachable (socket not found, refused connection, or timeout).	Verify the Docker daemon is running on the host. Check socket path or TCP endpoint.

Output

Success Port

Field	Type	Description
`status`	string	`"ok"` when daemon responds to ping.
`resource`	string	`"system"`
`operation`	string	`"ping"`
`pingStatus`	string	`"ok"` — confirmation from the daemon response.
`APIVersion`	string	Docker API version from the response header (e.g., `"1.45"`).

Error Port

Fires when the daemon is unreachable or the ping times out. Output contains status: "error", errorCode, and errorMessage. This is the primary path for alerting in health-check workflows.

Sample Output

{
  "status": "ok",
  "resource": "system",
  "operation": "ping",
  "pingStatus": "ok",
  "APIVersion": "1.45"
}

Expression Reference

Expression	Returns
`{{ $output.status }}`	`"ok"` — gate downstream operations on this value.
`{{ $output.pingStatus }}`	`"ok"` — daemon responded normally.
`{{ $output.APIVersion }}`	API version from response header — use for a quick version sanity check without calling `system/version`.
`{{ $output.errorCode }}`	On error port: `"DOCKER_API_ERROR"` or `"AUTH_FAILED"` — route failover logic on this value.

Node Policies & GuardRails

Policy	Enforcement
Never expose Docker daemon TCP without TLS	Use `tcptls` for remote connections. Plain `tcp` is blocked in production GuardRail profiles.
Store TLS certificates in Credentials Manager	Reference `tlsCertPath` via `{{ $credentials.dockerTlsCertPath }}`.
Keep timeoutSeconds low for health-check workflows	Set `timeoutSeconds` to 5 or less for ping nodes in monitoring workflows. A long timeout delays alerting when the daemon is down.
Always wire the error port in health-check workflows	The entire purpose of `system/ping` is to detect downtime. An unwired error port makes the health check silently ineffective.
Prefer ping over info for connectivity-only checks	Use `system/ping` when you only need a reachability signal. `system/info` returns a large payload and is slower.
Restrict container/exec to approved commands	Arbitrary exec access is root-equivalent. GuardRail exec policies restrict allowed command prefixes.

Examples

Example 1 — Scheduled Daemon Health Check

A scheduled workflow pings the Docker daemon every 60 seconds. If the ping fails, the error port routes to an alerting node that pages the on-call engineer.

// Scheduled trigger: every 60 seconds
{
  "resource": "system",
  "operation": "ping",
  "connection": {
    "dockerHost": "{{ $credentials.prodDockerHost }}",
    "connectionType": "tcptls",
    "tlsCertPath": "{{ $credentials.dockerTlsCertPath }}",
    "timeoutSeconds": 5
  }
}
// Success port → log "Docker daemon healthy"
// Error port   → send PagerDuty alert: "Docker daemon unreachable on {{ $credentials.prodDockerHost }}"

Example 2 — Pre-Deployment Dependency Gate

At the start of a multi-step deployment workflow, ping the target Docker host to confirm it is reachable before any container operations begin. Abort the workflow immediately if the ping fails.

// First node in deployment workflow:
{
  "resource": "system",
  "operation": "ping",
  "connection": { "timeoutSeconds": 5 }
}
// Success → continue to image/pull
// Error   → abort workflow with error: "Docker host unreachable — deployment cancelled"

Example 3 — Primary/Standby Failover

Ping the primary Docker host. If unreachable, switch all downstream container operations to the standby host endpoint.

// Step 1: Ping primary
{
  "resource": "system",
  "operation": "ping",
  "connection": {
    "dockerHost": "{{ $vars.primaryHost }}",
    "connectionType": "tcptls"
  }
}
// Success → set targetHost = primaryHost → proceed
// Error   → set targetHost = standbyHost → send alert + proceed on standby