Podos A lightweight container platform Early development · not released

Get started

Concepts

Podos has a small vocabulary. This page explains each term and how they fit together.

server (one podos daemon)
└── project "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"
        └── ...

Project

A project is one application, or a group of services that belong together. The manifest names it with the project key. Everything else (environments, values, secrets, releases, containers) lives inside a project.

Names of projects, 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 project.service address. localhost is reserved, and podos is reserved as a project name.

Environment

An environment is one running copy of a project, for example test and prod. Each environment has its own values, secrets, files, releases and containers.

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 project 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 project.

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:

  1. The CLI validates the manifest locally and resolves it for the chosen environment (shared part plus overrides).
  2. 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.
  3. The daemon pulls each image, verifies every blob against its digest and starts the new containers. Available A service with build is 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.
  4. 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 health check it is ready when the check passes.
  5. 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 project 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:

TOML
[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"
YAML
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"

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:

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 project 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 projects 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.