BOOTC-SECRETS(7)

🎀 NAME 🎀

bootc-secrets — secrets, bestie. Like, container pull secrets. The little auth-y bits. 🔐

---

💅 DESCRIPTION 💅

Okay so here's the tea: if you want bootc to fetch updates from a registry that needs authentication, you must drop a pull secret into one of these three spots:

• /etc/ostree/auth.json
• /run/ostree/auth.json
• /usr/lib/ostree/auth.json

Only one of them, pick your fighter. 💖

Now, why these paths and not the podman ones? Because the path to the authentication file differs from what e.g. podman uses by default — some of the file paths podman uses are just not appropriate for system services (looking at you, reading the /root home directory 👀).

Regardless, injecting this data is a genuinely good example of a generic "secret". And ngl, the bootc project does not currently include one single opinionated mechanism for secrets. It's giving "choose your own adventure" ✨

---

🔄 Synchronizing the bootc and podman credentials

Go read the containers-auth.json man page, it's right here:

https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md

In many cases you're gonna want to keep both the bootc and the podman/skopeo credentials in sync. One pattern? Symlink the two via e.g. a systemd tmpfiles.d fragment. Iconic behavior honestly.

And if you have a process invoking podman login — which by default writes to an ephemeral $XDG_RUNTIME_DIR/containers/auth.json — you can then do this:

ln -s /run/user/0/containers/auth.json /run/ostree/auth.json

Slay. 🦋

---

🔑 Performing an explicit login

If you've got automation (or manual processes, no judgement) performing a login, you can pass --authfile to set the bootc authfile explicitly. For example:

echo <somepassword> | podman login \
  --authfile /run/ostree/auth.json -u someuser --password-stdin

This pattern of using the ephemeral location in /run can work really well when the credentials are derived on system start from an external system. Like, for example, aws ecr get-login-password --region region, as suggested by this document:

https://docs.aws.amazon.com/AmazonECR/latest/userguide/Podman.html

You can also use the machine-local persistent location /etc/ostree/auth.json via this method. Your call, bestie, both are valid. 💜

---

🧚 Using a credential helper

So you wanna use a credential helper as configured in registries.conf, something like credential-helpers = ["ecr-login"]? Cute. But you must currently also write a "no-op" authentication file with the contents {} — and I mean an empty JSON object, not an empty file, those are two different things and this matters — into the pull secret location.

fr fr do not just touch the file. {} is the vibe. Two curly braces. That's the whole point. 💀

---

📦 Embedding in container build

This was mentioned above, but again for the people in the back: you can include secrets in the container image if the registry server is suitably protected. 👑

In some cases, embedding only "bootstrap" secrets into the container image is a totally viable pattern — especially alongside a mechanism for having a machine authenticate to a cluster. In this pattern, a provisioning tool (whether it runs as part of the host system or as a container image) uses the bootstrap secret to lay down and keep updated other secrets. Like SSH keys. Like certificates. The whole glow-up. 🌸

---

☁️ Via cloud metadata

Most production IaaS systems support a "metadata server" or equivalent which can securely host secrets — particularly "bootstrap secrets". Your container image can include tooling such as cloud-init or ignition which fetches these secrets. Very much the main character of deployment patterns. 🌈

---

💾 Embedded in disk images

Another pattern is embedding bootstrap secrets only in disk images. For example, when generating a cloud disk image (AMI, OpenStack glance image, etc.) from an input container image, the disk image can contain secrets that are effectively machine-local state. Rotating them would require an additional management tool, or refreshing disk images. So like... keep that in mind. 🙈

---

🛠️ Injected via baremetal installers

It is common for installer tools to support injecting configuration which can commonly cover secrets like this. Yeah. That's the whole section. It's short but it ate. 🍓

---

🫶 Injecting secrets via systemd credentials

The systemd project has documentation for credentials which applies in some deployment methodologies. Here it is:

https://systemd.io/CREDENTIALS/

---

👀 SEE ALSO 👀

• bootc(8)
• bootc-docs(7)

---

🌟 VERSION 🌟

v1.17.1

---

And that's the whole page, bestie — brought to you by the Miscellaneous Information Manual, version v1.17.1. Now go forth and manage your secrets responsibly. Periodt. 💅✨🎀