Guides
Environments and secrets
Available This guide sets up a test and a prod environment for one
application, with different values and secrets in each.
Declare the environments
podos init --namespace shop --environments test,prod
This writes podos.toml with environments = ["test", "prod"] and two
override files, podos.test.toml and podos.prod.toml, that hold only
comments. Edit the manifest:
namespace = "shop"
environments = ["test", "prod"]
[service.web]
image = "ghcr.io/example/shop:1.4.2"
replicas = 2
env.LOG_LEVEL = "${env.LOG_LEVEL}"
env.DATABASE_URL = "postgres://shop:${secret.DB_PASSWORD}@${env.DB_HOST}:5432/shop"
namespace: shop
environments: [test, prod]
service:
web:
image: ghcr.io/example/shop:1.4.2
replicas: 2
env:
LOG_LEVEL: "${env.LOG_LEVEL}"
DATABASE_URL: "postgres://shop:${secret.DB_PASSWORD}@${env.DB_HOST}:5432/shop"
And put the one structural difference into the override file of test:
# podos.test.toml
[service.web]
replicas = 1
# podos.test.yaml
service:
web:
replicas: 1
Set values and secrets per environment
With two environments declared, every command needs --env (-e):
podos env set --env test LOG_LEVEL=debug DB_HOST=db-test.internal
podos env set --env prod LOG_LEVEL=info DB_HOST=db-prod.internal
podos secret set --env test DB_PASSWORD
podos secret set --env prod DB_PASSWORD
podos secret set asks for the value twice without echo. In a script, pipe
it from your secret store instead; one trailing newline is removed:
your-secret-tool read shop/prod/db-password | podos secret set --env prod DB_PASSWORD
Check what is set. Secret values are never shown:
podos env list --env prod
podos secret list --env prod
Deploy each environment
podos deploy --env test
podos deploy --env prod
If a referenced value is missing, the deployment is refused before anything starts, and the error lists every missing name and the services that use it.
Change a value
Values are read when a container is created. After changing one, deploy again:
podos env set --env prod LOG_LEVEL=warn
podos deploy --env prod
Files next to values
Programs that read a config file or a key file need a file, not an
environment variable. Available podos file set stores one per
environment, like a value or a secret, and files.NAME in the manifest mounts
it into a service. A file can even be a template that fills in ${env.NAME}
and ${secret.NAME}. If you remove a value or a secret that a template of the
running release refers to, podos env unset and podos secret unset warn
you. See Files in containers.
How secrets are protected
- Secrets are encrypted at rest with the server's secrets key, created by
podos setup. They are not in the database in clear text, not in logs and not in API responses. - A release stores
${secret.NAME}, not the value. The value is inserted into the container's environment only when the container is created. - The CLI never reads secret values; it only sends them to the daemon.
- A container can read its own environment, and its output can contain secrets. Anyone who can deploy to an environment can therefore read its secrets, by deploying a container that prints them.
Available podos manifest validate and podos deploy warn when a literal
env value in the manifest looks like a secret, and name the command to
store it. If a value is not a secret, silence the warning with
lint_ignore. podos env create creates an
environment without setting a value in it.
See the Security model.
Remove an environment
podos down --env test
This deletes the environment's containers, releases, values, secrets and
files.
The prod environment is not touched. Available The environment's network,
domains and published ports go too; its volume data stays on the server
unless you add --delete-volumes.