Podos A lightweight container platform Early development · not released

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 namespace 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:

TOML
namespace = "site"

[service.web]
image = "nginx:1.27"
port = 80
files.NGINX_CONF = { path = "/etc/nginx/conf.d/default.conf", mode = "0444" }
YAML
namespace: 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 namespace-admin and admin tokens and root on the local socket have it. It must not be empty.

Mount it like any other file:

TOML
namespace = "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"
YAML
namespace: 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:

TOML
namespace = "shop"

[service.web]
image = "ghcr.io/example/shop:1.4.2"
files.SHOP_CONF = { path = "/etc/shop/shop.conf", template = true }
YAML
namespace: 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:

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 env values. If you change DB_HOST and a container restarts later, it starts with the new DB_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

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.

Podos refuses these paths in the manifest:

A service mounts at most 16 files. See files in the manifest reference.

Where files are stored

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 namespace, 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.