systemd-creds driver for secrets management

[jonas-hagen]

The very powerful integration of podman and systemd via quadlets makes systemd-creds (also see here) the obvious choice for secure secrets management.

This is not easily possible with one of the current drivers (file, shell, pass) and a new systemd secrets driver would be highly appreciated. The driver would:

• Store encrypted credential files in a directory on the host using systemd-creds
• Add a LoadCredentialEncrypted= directive upon systemd unit generation for every secret requested in a quadlet Secret= directive

There are workarounds to make it work with the shell driver. One of them looks like below. Unfortunately one has to put the SECRET_ID in the container quadlet file, which has to be extracted from /var/lib/containers/storage/secrets/secrets.json after creation of the secret with podman.

/etc/containers/containers.conf :

[secrets]
driver = "shell"

[secrets.opts]
# list and lookup only works in service context where $CREDENTIALS_DIRECTORY is set
list = "/usr/bin/ls $CREDENTIALS_DIRECTORY" 
lookup = "/usr/bin/cat $CREDENTIALS_DIRECTORY/$SECRET_ID"

# store and delete only works in host context where /etc/containers/secrets is available
store = "systemd-creds --name=$SECRET_ID encrypt - /etc/containers/secrets/$SECRET_ID.cred" 
delete = "rm /etc/containers/secrets/$SECRET_ID.cred"

/etc/containers/systemd/printenv.container

[Unit]
Description=Test container

[Service]
LoadCredentialEncrypted=4494b6510222c8b856834c8cb:/etc/containers/secrets/4494b6510222c8b856834c8cb.cred

[Container]
Image=alpine:latest
Secret=foobar,type=env,target=FOOBAR_SECRET
Exec=env

/var/lib/containers/storage/secrets/secrets.json (created by podman)

{
  "secrets": {
    "4494b6510222c8b856834c8cb": {
      "name": "foobar",
      "id": "4494b6510222c8b856834c8cb",
      "createdAt": "2025-08-06T16:49:45.901741684+02:00",
      "updatedAt": "2025-08-06T16:49:45.901741684+02:00",
      "driver": "shell",
      "driverOptions": {
        "delete": "rm /etc/containers/secrets/$SECRET_ID.cred",
        "list": "/usr/bin/ls $CREDENTIALS_DIRECTORY",
        "lookup": "/usr/bin/cat $CREDENTIALS_DIRECTORY/$SECRET_ID",
        "store": "systemd-creds --name=$SECRET_ID encrypt - /etc/containers/secrets/$SECRET_ID.cred"
      }
    }
  },
  "nameToID": {
    "foobar": "4494b6510222c8b856834c8cb"
  },
  "idToName": {
    "4494b6510222c8b856834c8cb": "foobar"
  }
}

/var/lib/containers/storage/secrets/ would possibly be used instead of /etc/containers/secrets/.

[limelimao]

Red Hat reference points are the systemd_creds_decrypt and systemd_creds_encrypt modules in the Ansible community.general collection

https://github.com/ansible-collections/community.general/blob/main/plugins/modules/systemd_creds_encrypt.py

[jonas-hagen]

How would you use that to provide a secret to a podman container?

[pkoch]

Register a name, refer to a name on a Quadlet with LoadCredentialEncrypted? I'm not using Ansible, but the pattern applies.

[fhemberger]

Also systemd v258 supports user scoped systemd-creds, which would be nice for rootless podman.

[dereulenspiegel]

I really like this idea. Since systemd simply puts the loaded credentials into a file in a folder specified by CREDENTIALS_DIRECTORY the part for loading the secret shouldn't be hard. However the concept of the current secrets management isn't really suited for secrets managed externally. Every secret is recorded in a central database (afaik a JSON file). This is useful so every secret is known to podman including potential metadata like labels. But it makes integration with externally managed secrets harder imho.
With credentials loaded via systemd we can't really list, delete or create secrets.
When implementing this feature I can currently see two potential directions to achieve this:

A rather simple implementation following the current design in container-libs. This would mean that we need to store "empty" secrets with the correct name to add them to the secrets database. Actual secret data would then be retrieved from credentials directory. This would mean that we need to fail delete and list operations with this driver (or just do nothing and pretend a success). This is probably rather easy to implement. But has the downside that available secrets kinda need to be "synchronized" between podman and systemd. Just having the LoadCredential/LoadCredentialEncrypted directive wouldn't be sufficient.

Another approach would be to change how podman handles secrets in general and allow for more flexible management of external secrets. But that would probably mean a larger change in container-libs and podman itself and require a larger discussion about the specific goals and desired architecture here.

[fhemberger]

FYI, there is already a proof of concept implementation as shell driver: https://github.com/ivanfed0t0v/podman-encrypted-secrets/blob/main/podman-encrypted-secrets.py

Haven't tested it yet, but looking at the code, it seems at least like a good starting point.

It decrypts the secret inside the script and hands it over to Podman, but using LoadCredentialEncrypted instead would be my preferred approach.

[dereulenspiegel]

Looks interesting and would roughly match the first approach. A "pure" approach via LoadCredential/LoadCredentialEncrypted would have the benefit that we can use the full featureset of systemd-credentials. The feature I am looking at is that secrets can also be acquired via an unix socket with LoadCredentials. Imho this would make the integration of external secret management solutions (vault, sops based solutions etc.) easier and uniform across systemd units.

[fhemberger]

Oh, that sounds interesting. Would be great to have a unified approcach to secrets management rather than separate drivers for each type.

[jonas-hagen]

Nice. However, for the use in quadlets, you would still need to mention the secret explicitly, because by default services do not have access to all secrets. Or am I missing something?

It would thus be nice that when podman generates systemd service files, it would go through all mentioned secrets, find their id by name, then mention those in the generated service file.

[pkoch]

I like the explicitness of just looking for the LoadCredential entries, and go off of that.