docker

Docker Engine: an infrastructure controller type, version 1. A controller of this type is written under controllers.infrastructure with type: docker.

Its connectivity test identifies the system it reaches by swarm.cluster_id, so that a second controller for the same system is warned of.

Connection

In the controller’s connection:

• endpoint (string, required): unix:///var/run/docker.sock, tcp://host:2375, or https://host:2376 (mutual TLS)
• api_version (string, default 1.43): Engine API version requests are pinned to
• tls_ca_file (string): CA certificate file the Engine’s certificate is checked against
• insecure_skip_verify (bool): accept any Engine certificate
• timeout (duration, default 10s): per-request timeout

Auth methods

The controller’s auth.method is one of these. A field marked secret comes only from the secret auth.credentials_ref names; the others are set in auth.config, or in that secret.

mtls

Client certificate and key.

• tls_cert (pem, required, secret)
• tls_key (pem, required, secret)

none

A unix socket, or an Engine that asks for no credentials.

No fields: no credentials_ref.

Capabilities

The controller enables each it uses in its capabilities list.

container.stop

Stop the container; start it again on unfence.

Category: actuator; bound as fence; fencing level compute; resource container.

Per binding, in its params:

• stop_timeout (duration, default 10s): how long Docker waits before killing the container

service.shape

Run the swarm service in its fenced shape; its active shape on unfence.

Category: actuator; bound as fence; fencing level compute; resource service.

Per binding, in its params:

• fenced_replicas (int): replicas while fenced, e.g. 0
• fenced_env (list of strings): KEY=VALUE entries while fenced, e.g. ROLE=standby
• active_replicas (int): replicas while active
• active_env (list of strings): KEY=VALUE entries while active, e.g. ROLE=primary

Validation checks: swarm.manager.

node.drain

Drain the swarm node, by hostname: its tasks stop, and the swarm runs them on its other nodes; its availability before is restored on unfence. A site fence drains every node of the site.

Category: actuator; bound as fence; fencing level compute; resource node.

Advertised once its setup is done: validation.

Validation checks: swarm.manager.

container.disconnect

Disconnect the container from networks.

Category: actuator; bound as fence or shield; fencing level network; resource container.

Per binding, in its params:

• networks (list of strings, required): networks the container is disconnected from

service.unpublish

Remove the swarm service’s published ports; restore them on unfence.

Category: actuator; bound as fence or shield; fencing level network; resource service.

Validation checks: swarm.manager.

container.restart

Restart the container where it runs, or start it if it has stopped: local recovery at the owner site (ADR 0005 §6).

Category: actuator; bound as recovery; resource container.

Per binding, in its params:

• stop_timeout (duration, default 10s): how long Docker waits before killing the container

Its recovery policy, in the recovery binding’s params (ADR 0005 §6):

• max_attempts (int, default 3): restarts at most, within window, before recovery escalates
• window (duration, default 10m): the period max_attempts is counted over
• backoff (duration, default 30s): the wait before the second restart, doubling for each one after
• grace (duration, default 60s): how long after a restart health is not counted
• flag_after_episodes (int, default 3): episodes of recovery within flag_period that raise an attention item
• flag_period (duration, default 24h): the period flag_after_episodes is counted over

service.restart

Replace the swarm service’s tasks with a forced update, including tasks that exited and would not be restarted: local recovery at the owner site (ADR 0005 §6).

Category: actuator; bound as recovery; resource service.

Its recovery policy, in the recovery binding’s params (ADR 0005 §6):

• max_attempts (int, default 3): restarts at most, within window, before recovery escalates
• window (duration, default 10m): the period max_attempts is counted over
• backoff (duration, default 30s): the wait before the second restart, doubling for each one after
• grace (duration, default 60s): how long after a restart health is not counted
• flag_after_episodes (int, default 3): episodes of recovery within flag_period that raise an attention item
• flag_period (duration, default 24h): the period flag_after_episodes is counted over

Validation checks: swarm.manager.

engine.ping

The Engine, and its swarm if it is in one, is up: enough to promote a stateless workload.

Category: observation; bound as readiness or health; resource controller.

container.health

The container runs, and its health check, if any, passes.

Category: observation; bound as readiness or health; resource container.

service.health

The swarm service’s task on this Engine runs, and its health check, if any, passes.

Category: observation; bound as readiness or health; resource service.

Validation checks: swarm.manager.

container.lag

As container.health, and the replication lag the command prints is within bound.

Category: observation; bound as readiness; resource container.

Per binding, in its params:

• command (list of strings, required): command run in the workload that prints its replication lag in seconds
• max_replication_lag (duration, required): the most lag that still allows promotion, e.g. 300s

service.lag

As service.health, and the replication lag the command prints is within bound.

Category: observation; bound as readiness; resource service.

Per binding, in its params:

• command (list of strings, required): command run in the workload that prints its replication lag in seconds
• max_replication_lag (duration, required): the most lag that still allows promotion, e.g. 300s

Validation checks: swarm.manager.

containers.list

The Engine’s containers, by name.

Category: discovery; resource container.

services.list

The swarm’s services, by name.

Category: discovery; resource service.

Validation checks: swarm.manager.

nodes.list

The swarm’s nodes, by hostname.

Category: discovery; resource node.

Validation checks: swarm.manager.

networks.list

The Engine’s networks, by name.

Category: discovery; resource network.

Addresses

Every address the type contacts. A secret’s scope (-scope-host) is checked against each that receives credentials.

• connection.endpoint (port url, receives credentials): the Docker Engine API: a Unix socket is localhost; over TCP it is given the client certificate