Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Rootless and Security

Podman Secrets and Image Trust

Handle passwords safely with podman secret, mount or inject them into containers, then decide which images to trust with digests, policy.json and signatures.

Two security questions come up as soon as you run real software: how do I give a container a password without leaking it, and how do I know the image I pull is the one I meant to pull. Podman has an answer for each. Secrets keep sensitive values out of images, command lines and podman inspect. Image trust policies and signatures make Podman refuse images that do not come from where you expect.

This lesson covers both, starting with secrets.

Why not environment variables or baked-in files?

Three common habits are leaky:

  • -e DB_PASSWORD=... is visible in your shell history, in podman inspect, and to any process that can read the container's environment.
  • COPY .env /app/.env in a Containerfile puts the password into the image, in a layer that anyone who gets the image can read. Deleting the file later does not remove it from the earlier layer.
  • A password in --env-file is better for history, but it still ends up in the environment.

A secret is a named piece of sensitive data stored by Podman, which you attach to containers at run time. It is not part of the image, and it does not appear in inspect output as a plain value.

Creating and using secrets

Terminal
# from a file
printf '%s' 's3cr3t-passw0rd' > db_password.txt
podman secret create db_password db_password.txt
shred -u db_password.txt        # or just rm; Podman has its own copy

# from standard input (no file on disk)
printf '%s' 's3cr3t-passw0rd' | podman secret create db_password -

podman secret ls
podman secret inspect db_password        # metadata only, not the value (unless --showsecret)
podman secret rm db_password

Use the secret in a container with --secret:

Terminal
podman run -d --name db \
  --secret db_password \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/db_password \
  docker.io/library/postgres:17

By default a secret appears as a file at /run/secrets/NAME inside the container, on an in-memory file system. Many official images (Postgres, MariaDB, and others) support the *_FILE convention for exactly this reason: they read the value from the file you point to. The options let you change where and how it appears:

Syntax Result
--secret name file /run/secrets/name
--secret name,target=/etc/app/key file at another path (relative targets go under /run/secrets)
--secret name,type=env,target=API_KEY environment variable API_KEY
--secret name,mode=0400,uid=1000,gid=1000 file with an owner and permissions the app's user can read

The type=env form is convenient for programs that only read the environment, but you lose the benefit of keeping the value out of the process environment, so prefer a file when the program allows it.

Where secrets are stored

The default driver is file: the secret is saved in Podman's data directory, with restricted permissions, and not encrypted. That is acceptable for single-user machines but should not be mistaken for a vault. Other drivers exist: pass stores secrets in the pass password manager (GPG-encrypted), and shell calls scripts you provide to store and retrieve. For team and production secrets, use a proper secret manager and fetch the value into Podman at start-up, for instance with a Quadlet unit that runs a small script.

Secrets belong to one user's Podman storage: a rootless secret is not visible to sudo podman. In Kubernetes YAML (podman kube play), secrets are referenced with the usual Kubernetes Secret objects.

Anyone who can run podman exec in the container, or who can read /run/secrets in it, can read the value. Secrets protect values from images, logs, history and inspect output. They do not protect against someone who already controls the container or your account.

Here is a stand-in that shows which leak channels each way of passing a password creates. It is a simple table lookup in JavaScript, written for teaching.

JS Stand-in: where does the password leak?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Trusting images

Pulling an image is running someone else's code, so you want two guarantees: you get the right image, and it has not been tampered with.

1. Prefer trusted sources. Official images, verified publishers, and your own registry.

2. Pin by digest. A tag can be moved to a different image; a digest cannot:

Terminal
podman pull docker.io/library/alpine@sha256:<the-64-hex-digest>
skopeo inspect --format '{{.Digest}}' docker://docker.io/library/alpine:3.20

Record the digest at the moment you review an image, and refer to it afterwards (many tools keep a lock file for this).

3. Enforce a policy. Podman reads /etc/containers/policy.json (or ~/.config/containers/policy.json) before it pulls. The policy chooses a requirement per registry or repository:

JSON
{
  "default": [{ "type": "reject" }],
  "transports": {
    "docker": {
      "registry.example.com/team": [{ "type": "sigstoreSigned", "keyPath": "/etc/pki/containers/team.pub" }],
      "quay.io/podman": [{ "type": "insecureAcceptAnything" }]
    },
    "docker-daemon": { "": [{ "type": "insecureAcceptAnything" }] }
  }
}

The type values you will meet:

Type Meaning
insecureAcceptAnything accept without checking (most default policies use this)
reject refuse to pull
signedBy require a valid GPG signature from a given key
sigstoreSigned require a Sigstore (cosign-style) signature checked against a key or certificate

With "default": reject, an image from any registry that is not listed is refused: a strong default for production hosts. A shortcut to edit the policy is podman image trust:

Terminal
podman image trust show
sudo podman image trust set --type reject default
sudo podman image trust set --type signedBy --pubkeysfile /etc/pki/containers/team.gpg registry.example.com/team

Where signatures are stored is described in registries.d files: some registries keep GPG signatures in a separate "lookaside" web server, while Sigstore signatures live in the registry next to the image. When you push your own images, Podman can sign them:

Terminal
podman push --sign-by [email protected] registry.example.com/team/app:1.0               # GPG
podman push --sign-by-sigstore-private-key ./cosign.key registry.example.com/team/app:1.0   # Sigstore

(Check podman push --help on your version: signing options were extended over several releases.)

4. Scan for known vulnerabilities. Podman does not include a scanner, but tools such as Trivy or Grype read the image. A scan reports packages with known problems, so you know when to rebuild. Scanning does not prove an image is safe; it finds known issues only.

A habit list for trusted images

  • Use fully qualified names and digests for anything that matters.
  • Build your own images from a small, trusted base; rebuild regularly for security updates.
  • Run containers as non-root, with capabilities dropped (the previous lesson).
  • Keep secrets in podman secret, not in images.
  • On servers, make policy.json reject everything except the registries you use.

The last stand-in checks whether a pull would be allowed under a policy like the example, by choosing the most specific matching entry.

JS Stand-in: policy.json lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does a secret appear inside a container by default?

    podman run --secret NAME mounts it as a file on an in-memory file system at /run/secrets/NAME.
  2. 2. Why is COPY .env /app/.env in a Containerfile a bad way to pass a password?

    Layers are permanent; deleting the file later does not remove it from the earlier layer.
  3. 3. What does an insecureAcceptAnything entry in policy.json do?

    It is the permissive requirement type. A hardened policy sets default to reject and lists exceptions.
  4. 4. Why pin an image by digest?

    Tags are mutable pointers; digests are content hashes.
  5. 5. Does the default file secret driver encrypt secrets?

    The file driver is not a vault. Use pass or an external secret manager for stronger protection.

Summary

  • Keep passwords out of images, command lines and inspect by using podman secret and --secret.
  • Secrets mount as files in /run/secrets by default; type=env and target, mode, uid, gid adjust this.
  • The default secret driver is not encrypted; choose pass or an external manager for stronger needs.
  • Pull trusted sources, pin by digest, and scan images for known vulnerabilities.
  • policy.json and podman image trust can reject unsigned or unlisted images; signatures can be GPG or Sigstore.

Next: Pods: Containers That Share a Network