Reference
Environments and overrides
One manifest describes all environments of a namespace. 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
namespace = "shop"
environments = ["test", "prod"]
namespace: shop
environments: [test, prod]
- Without
environments, the namespace has one environment,prod. Commands then need no--env. - With several environments, commands that work on one environment need
--env, and an undeclared name is an error. There is no default. - At most 20 environments; names follow the usual name rule.
Overrides inline
Write the override under environment.<name>.service.<service>. Only the
keys you write change; every other key keeps its shared value.
namespace = "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"
namespace: 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:
# podos.test.toml
[service.web]
replicas = 1
env.LOG_LEVEL = "debug"
# podos.test.yaml
service:
web:
replicas: 1
env:
LOG_LEVEL: debug
- An override file may not contain
namespace,environmentsorenvironment. - For one environment, overrides are either inline or in its file, not both.
- A file for an environment that is not declared is an error. If such a file is not meant as an override, rename it.
- An empty override file is ignored.
podos init --environments test,prodcreates one file per environment, with only comments, as a starting point. - The main manifest and the override files may use different formats.
unset
An override can remove a key it inherits with unset, a list of key paths
inside that service:
[environment.test.service.web]
unset = ["resources", "env.SENTRY_DSN"]
environment:
test:
service:
web:
unset: [resources, env.SENTRY_DSN]
- Paths:
port,command,domains,tls,replicas,restart,health,resources,publish,env,volumes,files, or a sub-key such asenv.NAME,volumes.NAME,files.NAME,health.path,health.type,health.interval,health.timeout,health.start_period,health.retries,health.success_threshold,resources.cpu,resources.memory. imageandbuildcannot be unset; set the one you want instead.onlycannot be changed.- You can only unset what the shared part sets, and you cannot unset and set the same key in one override.
- When an override empties
domains(withdomains = []orunset = ["domains"]), an inheritedtlsis dropped too.
A service in some environments only
An override cannot add a service. Declare the service in the shared part and
limit it with only:
[service.mailcatcher]
image = "ghcr.io/example/mailcatcher:1.0"
only = ["test"]
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:
[environment.prod]
context = "prod-eu"
environment:
prod:
context: prod-eu
or as the top-level key context of the override file of that environment:
# podos.prod.toml
context = "prod-eu"
# 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:
- The first time a manifest selects a context for a namespace, the CLI shows
the context, the server address and the namespace and asks you to type
yes. It then remembers the choice for that context and namespace in your contexts file. - Without a terminal it refuses, and says to pass
--context NAME, which confirms the choice by itself. --contextandPODOS_CONTEXTare typed by you and never ask.- If the context does not exist on your machine, the command fails and says
how to create it with
podos login.--context local(or--socket) talks to the daemon on the current machine instead.
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.
Checking the result
podos manifest validate shows the merged result of every environment, or
of one with --env:
podos.toml: valid
namespace: 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.