ssh-container-rollout

Files (1)

• SKILL.md

SKILL.md (first lines)

# SSH Container Rollout

For hosts running **standalone `docker run`** containers (not
compose-managed). Pulls the new image first, stops + removes the old
container, starts the new one with the same config, then verifies
healthy. If verification fails, rolls back to the previous image.

## Default-on cheatsheet rejection (since v1.9.0)

`ssh_exec_run` refuses commands that have a native MCP tool -- see
`skills/ssh-exec-run/SKILL.md`. The native-tool flow below avoids
that. Composite scripts (where the script IS the artefact) opt out
via `SSH_EXEC_ALLOW_CHEATSHEET_PATTERNS=true` at the operator level.

Sections 4 and 6 below intentionally use `ssh_exec_run` for
`docker run` with persistent-service flags (`-p`, `-v`, `-e`,
`--restart`, `--network`). These match the `docker` cheatsheet
pattern; the operator must enable the opt-out for this runbook
because `ssh_docker_run` is intentionally limited to ephemeral
one-shot containers and cannot express those flags.

For compose-managed stacks, use
[ssh-deploy-verify](../ssh-deploy-verify/SKILL.md) + `ssh_docker_compose_up`
instead -- compose handles the stop/start/dependency ordering, re-deriving
it here is error-prone.

## Sequence

1. Capture current config (so you can recreate it)
2. Pull the new image (no service impact yet)
3. Stop + remove the old container
4. Start the new container with identical config
5. Verify health
6. Roll back on failure

## 1. Capture current config

```python
ssh_docker_inspect(host="web01", target="my-service", kind="container")
ssh_docker_ps(host="web01")  # confirm it's actually running
```

From the inspect payload, record everything you'll need to recreate the
container on the new tag:

- Image ID **and** image tag (`Image` vs `Config.Image`). The tag is
  what you'll bump; the image ID is your rollback anchor.
- `HostConfig.PortBindings`, `HostConfig.Mounts`, `HostConfig.Binds`
  (bind mounts + volumes).
- `Config.Env` (environment variables). Note: some env vars may be
  secrets -- handle accordingly, don't dump them into logs.
- `HostConfig.RestartPolicy`.
- `HostConfig.NetworkMode` + `NetworkSettings.Networks` (which user-
  defined networks to attach to).
- `Config.Cmd` / `Config.Entrypoint` if overridden from the image default.
- `Config.Labels` (some orchestrators key off these).

If any of the above is surprising or undocumented, **stop** and get
operator confirmation that a rollout is safe. Recreating a container
from a partially-captured config is how you end up with a service
missing its database connection string in prod.

## 2. Pull the new image

```python
ssh_docker_pull(host="web01", image="ghcr.io/myorg/my-service:v2.3.0")
```

Pull before stopping anything -- pulls take seconds to minutes and can
fail (registry auth, network, rate limit). Failing a pull while the
current container is still serving traffic is a non-event; failing a
pull after you've stopped the old container is an outage.

Optional but recommended: hash/signature-verify the pulled image before
activation. See
[ssh-verify-signature](../ssh-verify-signature/SKILL.md) for the
runbook. Image digest pinning (`...@sha256:<digest>`) is a stronger
pattern than tag pinning; tags are mutable.

## 3. Stop + remove the old container

Requires `ALLOW_LOW_ACCESS_TOOLS` (stop) + `ALLOW_DANGEROUS_TOOLS` (rm):

```python
ssh_docker_stop(host="web01", container="my-service")
ssh_docker_rm(host="web01", container="my-service")
```

The default SIGTERM grace period is whatever the daemon / image defines
(usually 10s). `ssh_docker_stop` does not expose `--time` -- if the
service needs a longer drain window (databases, queue workers), call
`docker stop -t <seconds>` via `ssh_exec_run` instead. Too-short
shutdown + `rm` = data loss for stateful workloads; if the container is
stateful, confirm volumes hold the state (Section 1's `Mounts`) before
removing it.

## 4. Start the new container

`ssh_docker_run` is intentionally a thin wrapper for ephemeral one-shot
containers -- its argv is hardcoded to `docker run --rm -d --name <n>
-- <image> [container-cmd...]` and the `args` list is passed **after**
the image (so it becomes the container's command, not docker options).
That means flags like `--restart`, `-p`, `-v`, `-e`, `--network`
cannot be set through it. For a persistent service rollout, drive
`docker run` through `ssh_exec_run` instead. This call matches the
`docker` cheatsheet pattern and requires
`SSH_EXEC_ALLOW_CHEATSHEET_PATTERNS=true` on the server because the
persistent-service flag surface is intentionally outside
`ssh_docker_run`:

```python
import shlex

flags = [
    "--name", "my-service",
    "-d",
    "--restart", "unless-stopped",
    "-p", "8080:8080",
    "-v", "/opt/my-service/data:/data",

From Nightreaver/python-ssh-mcp, GPL-3.0.

More from Nightreaver/python-ssh-mcp