Architecture

The problem

Several teams need containers running on a small number of shared machines, and each team must be unable to see or disturb the others. Doing that with a container runtime alone means somebody holds the whole picture in their head: which machine has room, which container belongs to whom, what the running configuration was supposed to be, and what to do when a machine disappears at three in the morning.

How the platform solves it

Odysseus splits that picture into three parts, and only one of them is authoritative.

You declare what you want. A deployment is a description — an image, how many copies, what they can reach, what shapes them. You write it once, on whichever surface suits you: a YAML manifest, the REST API, the dashboard, or an agent tool. All four end in the same stored record.

The control plane decides. It admits or refuses your change (every refusal names the field and the accepted form — see rejections and alterations), chooses which node runs each container, and turns the stored description into a versioned dispatch payload. The payload carries a hash of everything that shapes the container, so the difference between “you edited the description” and “the container must be replaced” is computed rather than judged. The mutability column of the deployment reference is that hash, measured.

The agent acts. One agent runs on each node. It receives dispatches, drives the local container runtime, and reports what it sees. It never decides placement and never invents configuration: a node that loses contact keeps running what it has rather than improvising.

What is running is never the truth of what should be running. The stored description is that truth, the hash says whether the containers match it, and the reconciler’s job is to close the gap. The containers are watched constantly — the agent reports what it observes, and the control plane repairs against those reports — but an observation never becomes the description.

The same loop runs work that repeats. A schedule creates a job when the job is due, and the platform tracks whether that job ever reached a node: one that never did — because the node it was pinned to is not enrolled, or because no container for it was ever seen — can still be corrected by editing the schedule, and a schedule whose firings keep achieving nothing is reported as stuck rather than left looking healthy. What each of those words means is in scheduled work.

Not this

This page does not describe how to install a node, and it does not list ports, hostnames or environment variables for a particular installation. Those belong to the operations runbooks, which describe one deployment of the platform rather than the platform.

It also does not cover the routing edge. Traefik terminates TLS and routes to containers; what a deployment declares about that is ingress, in the deployment reference.

Where to see it

• The stored description, field by field: deployment manifest.
• What the control plane refuses, and the changes it makes that you did not send: rejections and alterations.
• The words this documentation uses for each part: glossary.