Podos A lightweight container platform Early development · not released

Reference

Environments and overrides

One manifest describes all environments of a project. Everything outside environment.<name> is the shared part and applies to every environment. An override changes single keys of a service for one environment.

Available Overrides work for all keys of a service, including context, lint_ignore, domains, tls, health, restart, publish, volumes and files.

Declaring environments

TOML
project = "shop"
environments = ["test", "prod"]
YAML
project: shop
environments: [test, prod]

Overrides inline

Write the override under environment.<name>.service.<service>. Only the keys you write change; every other key keeps its shared value.

TOML
project = "shop"
environments = ["test", "prod"]

[service.web]
image = "ghcr.io/example/shop:1.4.2"
replicas = 3
resources = { cpu = 1, memory = "512M" }
env.LOG_LEVEL = "info"

[environment.test.service.web]
replicas = 1
resources = { memory = "256M" }
env.LOG_LEVEL = "debug"
YAML
project: shop
environments: [test, prod]

service:
  web:
    image: ghcr.io/example/shop:1.4.2
    replicas: 3
    resources: { cpu: 1, memory: 512M }
    env:
      LOG_LEVEL: info

environment:
  test:
    service:
      web:
        replicas: 1
        resources: { memory: 256M }
        env:
          LOG_LEVEL: debug

In test, web runs 1 replica with 1 CPU, 256M of memory and LOG_LEVEL=debug. In prod it runs 3 replicas with 1 CPU and 512M.

How values merge

Key Merge rule
image, build, command, port, replicas, tls, restart The override replaces the value.
domains, publish The override replaces the whole list.
env, volumes, files Merged by name: the override adds or replaces entries; others stay.
health, resources Merged by sub-key: resources = { memory = "256M" } keeps the shared cpu.
lint_ignore Available The override replaces the whole list.
only Cannot be overridden.

An override may switch between image and build: setting one replaces the other. It cannot set both.

Overrides in their own file

The overrides of one environment can live in a separate file next to the manifest: podos.<environment>.toml (or .yaml, .yml). It holds only the differences, written like the main file but without the environment.<name> prefix:

TOML
# podos.test.toml
[service.web]
replicas = 1
env.LOG_LEVEL = "debug"
YAML
# podos.test.yaml
service:
  web:
    replicas: 1
    env:
      LOG_LEVEL: debug

unset

An override can remove a key it inherits with unset, a list of key paths inside that service:

TOML
[environment.test.service.web]
unset = ["resources", "env.SENTRY_DSN"]
YAML
environment:
  test:
    service:
      web:
        unset: [resources, env.SENTRY_DSN]

A service in some environments only

An override cannot add a service. Declare the service in the shared part and limit it with only:

TOML
[service.mailcatcher]
image = "ghcr.io/example/mailcatcher:1.0"
only = ["test"]
YAML
service:
  mailcatcher:
    image: ghcr.io/example/mailcatcher:1.0
    only: [test]

An override for a service in an environment where only excludes it is an error.

Binding an environment to a server

Available An environment can name the context (server) it is deployed to. This is a key of the environment, not of a service. Write it inline:

TOML
[environment.prod]
context = "prod-eu"
YAML
environment:
  prod:
    context: prod-eu

or as the top-level key context of the override file of that environment:

TOML
# podos.prod.toml
context = "prod-eu"
YAML
# podos.prod.yaml
context: prod-eu

Set it in one place only; both is an error. The value is the name of a context made with podos login, never an address or a token. It is only read by the CLI and is not uploaded, so it does not change the release.

A manifest comes from a repository, perhaps somebody else's, and a context holds a token for a real server. So the CLI does not follow the key blindly:

What each environment has of its own

Available Each environment has its own private network and its own volumes, and holds its own domains and published ports. Services of test cannot reach services of prod, and the same volume name in two environments is two separate directories. A domain or a published port belongs to one environment on the server, so give each environment its own domains, for example with an override.

Differences that need no override

Env values and secrets are stored per environment on the server. A manifest that says env.DATABASE_URL = "${secret.DATABASE_URL}" works in every environment; you set a different secret in each:

podos secret set DATABASE_URL --env test
podos secret set DATABASE_URL --env prod

Files work the same way: podos file set stores a file per environment, and files.NAME in the manifest mounts it in every environment, with different content in each. See Files in containers.

See Environments and secrets.

Checking the result

podos manifest validate shows the merged result of every environment, or of one with --env:

podos.toml: valid
project: shop
environments: test, prod

environment test: 1 service
  web  image ghcr.io/example/shop:1.4.2  replicas 1

environment prod: 1 service
  web  image ghcr.io/example/shop:1.4.2  replicas 3

A problem caused by an override names the override's file and line.