Get started
Concepts
Podos has a small vocabulary. This page explains each term and how they fit together.
server (one podos daemon)
└── namespace "shop" one application
├── environment "test" values, secrets, files, releases
│ ├── release 3 (active) one deployment of the manifest
│ │ ├── service "web" replicas web/0, web/1
│ │ └── service "worker" replica worker/0
│ └── release 2 (replaced)
└── environment "prod"
└── ...
Namespace
A namespace is one application, or a group of services that belong
together. The manifest names it with the namespace key. Everything else
(environments, values, secrets, releases, containers) lives inside a
namespace.
Names of namespaces, environments, services and volumes follow one rule:
1 to 63 lowercase letters, digits and hyphens, starting with a letter and
ending with a letter or digit. That makes every name a valid DNS label.
Dots are reserved for a later namespace.service address. localhost is
reserved, and podos is reserved as a namespace name.
Environment
An environment is one running copy of a namespace, for example test and
prod. Each environment has its own values, secrets, files, releases and
containers.
- Without an
environmentskey, a namespace has one environment,prod, and commands need no--envflag. - With
environments = ["test", "prod"], every command that works on one environment needs--env. There is no default, so you cannot deploy toprodby accident.
The manifest is shared by all environments. Small differences, such as
fewer replicas in test, are written as
overrides. Most differences need no override at all,
because values and secrets are stored per environment on the server.
Available Each namespace and environment pair has its own private
network: services in shop/test reach each other by name, and cannot reach
shop/prod or any other namespace.
Service
A service is a long-running process, described under service.<name> in
the manifest: which image to run, how many replicas, its command, env
values and resources. Each replica is one container; replicas are numbered
from 0 (web/0, web/1).
A service must keep running. A container that exits during the first
seconds of a deployment fails the deployment. Available After that, the
restart key decides what happens when a container stops by itself:
always (the default), on-failure or never. A container that is
restarted waits first, with a delay that grows from 1 second up to 5
minutes. Run-to-completion jobs (job.<name>) are planned and not
supported yet.
Release
Each podos deploy creates a release: a numbered, stored copy of the
resolved manifest for one environment. Releases are numbered 1, 2, 3 and so
on within an environment.
A deployment does this, in order:
- The CLI validates the manifest locally and resolves it for the chosen environment (shared part plus overrides).
- It sends the resolved manifest to the daemon. The daemon validates it
again and checks that every
${env.NAME}and${secret.NAME}exists in that environment. - The daemon pulls each image, verifies every blob against its digest and
starts the new containers. Available A service with
buildis built first: the CLI uploads the source, the server builds it with BuildKit, and the release names the built image by its digest. See Build from source. - When all new containers are ready, the release becomes active, the
previous release becomes superseded and its containers are removed.
A container without a health check is ready when it has kept running for
a short settle time (3 seconds); Available with a
healthcheck it is ready when the check passes. - If anything fails, the new containers are removed, the release is marked failed and the previous release keeps running. The error shows the last lines of the failing container's output, with the service's secrets masked on a best-effort basis.
Only one deployment per environment runs at a time; a second one is refused with exit code 3 (try again later).
Available Updates are rolling: a new replica is started before an old one is
stopped, so a service with replicas keeps serving during the update. If a
service has no ready replica for 15 seconds within 60 seconds after a
release became active, the release fails and the previous one is restored
automatically. podos releases lists the history of an environment and
shows the reason of a failed release.
A restart of the daemon does not restart containers; they keep running. After a reboot of the server, all containers of the active releases come back.
Env values and secrets
Values that change between environments, or that should not be in the repository, live on the server, per namespace and environment.
| Env values | Secrets | |
|---|---|---|
| Set with | podos env set KEY=VALUE |
podos secret set NAME (standard input or no-echo prompt) |
| Stored | in clear text | encrypted with the server's secrets key |
| Read back | podos env list shows values |
never; podos secret list shows names and times only |
| Used in the manifest as | ${env.NAME} |
${secret.NAME} |
References are allowed in the values of a service's env table:
[service.web]
image = "ghcr.io/example/shop:1.4.2"
env.DATABASE_URL = "postgres://app:${secret.DB_PASSWORD}@db.internal:5432/shop"
env.LOG_LEVEL = "${env.LOG_LEVEL}"
env.PRICE_NOTE = "costs $$5"
service:
web:
image: ghcr.io/example/shop:1.4.2
env:
DATABASE_URL: "postgres://app:${secret.DB_PASSWORD}@db.internal:5432/shop"
LOG_LEVEL: "${env.LOG_LEVEL}"
PRICE_NOTE: "costs $$5"
- References are resolved by the daemon, from the release's own namespace and environment only. The CLI never reads secret values.
$$is a literal dollar sign. Any other$is an error, so a typo never turns silently into text.- A stored release keeps
${secret.NAME}unexpanded. Secrets are put into a container's environment only when the container is created.
Changing a value or a secret does not change running containers. Run
podos deploy again to use the new value.
Files
Available When a program needs a config file or a key file, store it per
environment with podos file set NAME PATH and mount it with
files.NAME = "/path/in/container" in a service. It is mounted read-only. A
file is plain (shown again by podos file get) or, with --secret, a secret
file: encrypted, kept in memory when mounted, and never shown again. A
template file replaces ${env.NAME} and ${secret.NAME} when a container is
created. A release pins the content of its files, so a change takes effect at
the next podos deploy. See Files in containers.
Server, daemon and CLI
One podos binary has both roles:
- The daemon (
podos daemon) runs as root on the server. It keeps the state in SQLite under/var/lib/podos, pulls images, and runs containers withcrun. Each container is supervised by its ownconmonprocess, so containers keep running when the daemon stops or restarts. - The CLI is every other command. On the server it talks to the daemon
over the local Unix socket
/run/podos/podos.sock, as root.
Available The daemon can also serve an HTTPS API (podos daemon --listen),
podos login saves a server address, its CA and a token as a named context,
and you deploy from your laptop. Each server stays independent; see
Several servers with contexts.
Available The same HTTPS address also serves the web UI, which is part of the binary too (when it was built with it).
Networks
Available Each namespace and environment pair has its own private network.
A service reaches another service of the same environment by its name, for
example http://web:8080/. Other namespaces and other environments are
never reachable. Services are private by default. Containers reach the
internet and, by default, the server's private networks; the cloud metadata
address is always blocked. An operator can restrict this with
podos setup --strict-egress. A service without resources.memory gets
512 MiB.
Ingress and domains
Available A service with domains and a port is reachable from the
internet through the built-in proxy in the daemon, which listens on ports 80
and 443. TLS is chosen per service with tls: auto (Let's Encrypt),
self-signed (a Podos internal CA), off (plain HTTP), or cert:<name>
(an uploaded certificate). For other protocols, publish opens a host port.
Data that must survive a redeploy goes into volumes. See
Domains and HTTPS,
Published ports and Volumes.