Dockplane 0.3.0-rc.2

Dockplane 0.3.0-rc.2

The second candidate for 0.3.0. It is 0.3.0-rc.1 with one defect fixed, and
the defect is one an operator could have been bitten by without noticing: a
stack whose containers were running reported that it had never been deployed,
and deleting it reported success while leaving the containers where they were.

Everything 0.3.0 adds is unchanged — responsive management lists, version
visibility, host archival — and so is the way Dockplane manages Docker. The
agent's capability catalog is the same eighteen typed capabilities.

What was wrong

Dockplane labels every container it creates for a stack with three things: which
stack it belongs to, which of the stack's services it is, and which revision it
is running. The control server reads those labels to decide which containers on
a host are a given stack's own.

The agent never sent them. It reports containers through an allow list — labels
are free-form and routinely carry deployment detail and credentials, so only the
ones the product groups by leave the host — and the three stack labels were not
on it. They had been on the containers since stacks arrived and on the list
since before stacks existed.

What an operator saw:

• A stack deployed successfully, its containers started, and the deployment was
  reported as failed with STACK_APPLY_FAILED — "the host is as it was", which
  was not true.
• The stack stayed at not deployed while its containers ran.
• Starting, stopping and restarting it found no containers to act on.
• Deploying it again was refused because the container names were taken, by
  containers the server did not recognise as the stack's own.
• Deleting it answered 200 deleted, removed the stack from Dockplane, sent
  nothing to the host, and left the containers running.

The last of those is the one that matters most. The check that refuses to delete
a stack whose containers are still on its host was there and was correct; it
looks for containers that claim the stack, found none because none could claim
anything, and concluded there was nothing to remove.

This has been present since 0.2.0-rc.1 and is in the released 0.2.0. It is
not a regression in 0.3.0-rc.1.

What changed

The agent forwards the three stack labels. The allow list is still an allow
list — no wildcard, no prefix matching, nothing an operator wrote on a container
of their own. The three labels are identifiers Dockplane generated and a service
name it read from a revision it compiled.

Stack operations require an agent from this release. A control server is
upgraded before its fleet, so an upgraded server will be talking to agents that
still cannot report attribution. Deploying, starting, stopping, restarting and
removing a stack are refused for such a host with AGENT_UPGRADE_REQUIRED,
before anything is sent to it — a host is never given work whose result cannot
be read back.

This is not a protocol incompatibility. The protocol version is unchanged at 1,
those agents remain connected and supported, and inventory, metrics, logs,
container operations and Compose discovery on their hosts are untouched. The
version report still shows them as an older release in a mixed fleet, not as
incompatible.

A stack that was never deployed is still deletable on any host. Nothing can
have been left behind by a deployment that never happened.

Upgrading

The control plane first, then the agents, as always:

VERSION=0.3.0-rc.2

sha256sum -c SHA256SUMS
tar xzf "dockplane-$VERSION.tar.gz"
cd "dockplane-$VERSION"
sudo ./install-control-plane.sh --domain dockplane.example.com

No migration is applied. The schema is 0016_host_archive, as in
0.3.0-rc.1; upgrading from 0.2.0 applies that one migration as it did
before.

Then upgrade the agent on every host that runs stacks. Until you do, that host's
stacks are readable and unchangeable.

Recovering a host that ran an older agent

Upgrade the agent. Nothing else is needed, and no database repair is involved:
the next inventory carries the labels, discovery attributes the containers to
their stack, and the stack's services resolve again.

Two states do not resolve themselves, because neither is Dockplane's to decide:

A stack whose deployment never completed still reads as not deployed. That
deployment genuinely never completed, and the record says so. Apply its revision
again — the containers are recognised as the stack's own and the stack is
reconciled to what you applied.

A stack that was deleted is not recreated. Its containers keep running and
still carry a label naming a stack that no longer exists. Dockplane leaves them
alone: they stay visible as managed containers on their host, belonging to no
stack, and nothing invents a stack to hold them.

They are also not removed. You can stop such a container from Dockplane, but
removing it answers CONTAINER_NOT_MANAGED: removing a container through
Dockplane needs a configuration Dockplane holds for that container, and one that
belonged to a stack has none of its own. Cleaning these up means connecting to
the Docker host, confirming which containers they are, and removing them there
with docker rm. See Stacks.

Supported platforms

Control plane	Ubuntu 24.04, Ubuntu 22.04 or Debian 12, amd64
Managed hosts	Debian 12, Ubuntu 24.04 or Ubuntu 22.04 with systemd

Ports: 80 and 443 for browsers, 9443 for agents. The API and PostgreSQL are not
published. See Supported Platforms.

ARM64

experimental — built and inspected, not runtime-tested

Packages, binaries and images are produced for arm64 and inspected, and no arm64
machine has run them in production. Use amd64 in production.

This is a release candidate

It is the 0.3.0 feature set, verified end to end, and it has not been run in
anger. Deploy it where you can afford to restore a backup.

Known limitations

Read Known Limitations before deploying,
and Archiving Hosts and
Stacks for what this release changes.

License

GNU Affero General Public License v3 only. See
LICENSE.