Guides
Files in containers
Available
This page describes what is in the code on the main branch. There are no release binaries yet.
Many programs read their settings from a file: an nginx.conf, a TLS key, a
config.toml. With podos file you store such a file on the server, per
project and environment, and the manifest mounts it into a service at a
path you choose. If you know Kubernetes, this is what a ConfigMap or a mounted
Secret does.
Files live next to env values and secrets. They are
per environment, so test and prod can hold different content under the
same name.
A plain config file
Store a file under a name. The name follows the rule of env names:
[A-Za-z_][A-Za-z0-9_]*, at most 256 characters, not starting with PODOS_.
podos file set NGINX_CONF ./default.conf
file NGINX_CONF set in site/prod (plain, 214 B, sha256:4f1c0a9d2b7e)
services that list it under files mount it from the next 'podos deploy'
Then mount it in the manifest, under files of a service. The key is the
file name, the value is the path inside the container:
project = "site"
[service.web]
image = "nginx:1.27"
port = 80
files.NGINX_CONF = { path = "/etc/nginx/conf.d/default.conf", mode = "0444" }
project: site
service:
web:
image: nginx:1.27
port: 80
files:
NGINX_CONF: { path: /etc/nginx/conf.d/default.conf, mode: "0444" }
podos deploy
The container sees the file at that path, byte for byte, read-only. List and read back what you stored:
podos file list
podos file get NGINX_CONF
file set reads from a path, or from standard input with -. Standard input
must not be a terminal: pipe the content in.
generate-config --env prod | podos file set APP_CONFIG -
A secret file
For a TLS key or any file that must not be readable later, add --secret:
podos file set --secret TLS_KEY ./site.key
A secret file is stored encrypted and is never shown again: not by
podos file get, not by podos file list, not by the API. It needs
permission to write secrets: a deploy token needs --secrets-write, while
project-admin and admin tokens and root on the local socket have it. It
must not be empty.
Mount it like any other file:
project = "site"
[service.web]
image = "nginx:1.27"
port = 80
files.NGINX_CONF = { path = "/etc/nginx/conf.d/default.conf", mode = "0444" }
files.TLS_KEY = "/etc/ssl/private/site.key"
project: site
service:
web:
image: nginx:1.27
port: 80
files:
NGINX_CONF: { path: /etc/nginx/conf.d/default.conf, mode: "0444" }
TLS_KEY: /etc/ssl/private/site.key
The short form files.NAME = "/path" uses mode 0400: only the user the
container runs as can read it.
file set warns when a plain file looks like it should be a secret: its name
has a word such as PASSWORD, TOKEN, SECRET or KEY, it holds a private
key, or it holds a URL with a user name and password. The warning never
shows the content and never blocks anything.
The kind of a name cannot change. To turn a plain file into a secret file
(or the other way round), remove it with podos file unset NAME, then set it
again.
Whoever may deploy to an environment can mount one of its secret files and
read it from inside their own container, the same as with ${secret.NAME}.
The permission to write secrets guards writing and removing a secret file,
not reading it through a container. See the Security model.
Templates: fill in values
A file mounted with template = true can refer to env values and secrets of
the environment. Podos replaces the references when a container is created.
Store a file that has references in it:
# shop.conf
price_note = "costs $${env.CURRENCY} 5"
database = "postgres://shop:${secret.DB_PASSWORD}@${env.DB_HOST}:5432/shop"
log_format = "$remote_addr - ${request_id}"
podos file set SHOP_CONF ./shop.conf
Mount it as a template:
project = "shop"
[service.web]
image = "ghcr.io/example/shop:1.4.2"
files.SHOP_CONF = { path = "/etc/shop/shop.conf", template = true }
project: shop
service:
web:
image: ghcr.io/example/shop:1.4.2
files:
SHOP_CONF: { path: /etc/shop/shop.conf, template: true }
The rules are narrower than for env values in the manifest, because
configuration files are full of $ of their own:
- Only
${env.NAME}and${secret.NAME}are replaced. Every other$and every other${...}stays as it is. In the example,$remote_addrand${request_id}reach the container unchanged. $${env.NAME}gives the literal text${env.NAME}. In the example the container readsprice_note = "costs ${env.CURRENCY} 5".- A value that is put in is never scanned again.
- A template must be text: valid UTF-8 without NUL bytes. Without
template = truea file can be anything. - A template refers to at most 256 different values, and the result is at most 1 MiB, like any file.
- Every referenced value must be set in the environment. Otherwise
podos deployis refused and the error names the service, the file and the missing reference. - The stored file stays what you uploaded, with the references in it.
podos file getshows the template, not the result. - A template that refers to a secret counts as a secret file: it is rendered to memory only (see Where files are stored).
Values are read when a container is created. A release pins the content of the template, not the values it refers to. A restart of a container, a new replica or a rollback renders the pinned template with the values the environment holds at that moment. This is the same as for
envvalues. If you changeDB_HOSTand a container restarts later, it starts with the newDB_HOST, even without a deploy. Deploy after changing a value so that all replicas agree.
If you remove an env value or a secret that a template of the running release
refers to, podos env unset and podos secret unset print a warning: the
next container start of those services fails until the value is set again.
How changes take effect
- A release pins the content of every file it mounts. After
podos file setthe running containers keep the old content. The new content is mounted at the nextpodos deploy. - A rollback to an earlier release mounts the content that release pinned. This is also what an automatic rollback after a failed rollout does.
- A deploy that names a file which is not set in that environment is refused, and the error lists the services and files.
- You can remove a file that the running release uses, with
podos file unset NAME. Nothing asks for confirmation. Running containers keep what they have and a rollback still works, but the next deploy that names the file is refused until you set it again. The command prints a note when the running release mounts the file. - There is no live update. To see a change, deploy.
podos file list shows, for each file, its name, kind, size, a short digest
of the content, the update time and the services of the running release that
mount it (a template is marked). The digest of a secret file is that of its
encrypted form, so it changes at every file set.
Paths and mode
In the manifest, files.NAME is either a path or a table:
| Form | Meaning |
|---|---|
files.NAME = "/path" |
Mounted at /path with mode 0400. |
files.NAME = { path = "/path", mode = "0444", template = true } |
mode and template are optional. |
- The path is absolute and clean: no
..,.,//or trailing/, and not/. - The mode is an octal string in quotes, three or four digits, at most
0777. Setuid, setgid and sticky bits are refused. The default is0400. - The file belongs to the user (and group) the container runs as and is mounted read-only. A program that runs as another user can only read it if the mode allows.
- One name is one file. There are no directories of files and no files from
your repository: you store each with
podos file set. - A path in the image is created if it is missing. If the image has a directory or a symbolic link at that path, the release fails at once and the error says why.
Podos refuses these paths in the manifest:
- the files Podos provides itself:
/etc/resolv.conf,/etc/hostsand/etc/hostname, or a path above or below one of them; /proc,/sys,/devand anything inside them;- a path inside a volume of the service, or above one;
- a path inside or above the path of another file of the same service, and the same path twice.
A service mounts at most 16 files. See files in the
manifest reference.
Where files are stored
- Plain files are written to the data disk, with the container's other state. Every container gets its own copy.
- Secret files, and templates that hold a secret once rendered, are written only to a memory file system of the daemon, never to the data disk. A reboot empties it; the containers that come back get new copies from the pinned content. On Linux 6.4 or newer the memory file system is mounted so that it is not swapped out. On an older kernel its pages can reach swap unless swap is encrypted or off, and the daemon logs a warning.
- The memory file system has a fixed size, set with
podos daemon --files-memory. It is counted inside the system reserve. See Limits.
Limits
| What | Limit |
|---|---|
| One file, also a rendered template | 1 MiB |
| Files in one environment | 64 |
| Files mounted by one service | 16 |
| Different values in one template | 256 |
| Stored content of a project, including what old releases pin | 256 MiB |
File changes (set, unset) per token |
60 per minute |
More about the memory used by secret files and how a rollout counts it is in Limits.
Not offered: bundles or directories of files, files taken from the repository, and live update of running containers.
Troubleshooting
| You see | Cause and fix |
|---|---|
the manifest mounts 1 files that are not set in shop/prod: web/SHOP_CONF (set them with 'podos file set') |
The manifest names a file the environment does not have. Set it, or check --env. |
template file SHOP_CONF of service web refers to secret DB_PASSWORD, which is not set in shop/prod |
A template refers to a value that is missing. Set it with podos secret set or podos env set. |
file SHOP_CONF of service web is mounted as a template, but a template must be text: valid UTF-8 without NUL bytes |
The stored file is binary. Remove template = true or store a text file. |
file target "/etc/app": the image has a directory at this path; a file cannot be mounted over a directory |
The image has a directory where the file should go. Choose another path. A symbolic link gives a similar error. |
file "TLS_KEY" is a secret file and cannot become a plain file; delete it first, then set it again |
The kind of a name cannot change. podos file unset it and set it again. |
this token may not write secret files: it lacks the permission to write secrets |
Use a token with --secrets-write, or root on the server. |
file "TLS_KEY" is a secret file; the content of a secret file is never returned |
podos file get never shows a secret file. |
refusing to read a file from a terminal; pipe the content in or give a path |
podos file set NAME - needs piped input. |
the file is larger than the limit of 1048576 bytes |
Files are at most 1 MiB. |
the environment already has the most files it may (64); remove a file first |
Remove files you no longer use. |
the secret files of this release (...) need more of the memory this server reserves for secret files than one release may use ... |
Use fewer or smaller secret files or fewer replicas, or raise --files-memory. |
file X ...; refusing to print it to a terminal |
The plain file is not clean text. Redirect to a file or a pipe, or use --raw. |