Skip to content

secrets: Expand on authfile #1393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 1, 2025
Merged

secrets: Expand on authfile #1393

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 34 additions & 5 deletions docs/src/building/secrets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,46 @@
# Secrets (e.g. container pull secrets)

To have `bootc` fetch updates from registry which requires authentication,
you must include a pull secret in `/etc/ostree/auth.json` (or
as of recent versions in `/usr/lib/ostree/auth.json`).
you must include a pull secret in one of `/etc/ostree/auth.json`,
`/run/ostree/auth.json` or `/usr/lib/ostree/auth.json`.

Another common case is to also fetch container images via
`podman` or equivalent. There is a [pull request to add `/etc/containers/auth.json`](https://github.com/containers/image/pull/1746)
which would be shared by the two stacks by default.
The path to the authentication file differs from that used
by e.g. `podman` by default as some of the file paths used
there are not appropriate for system services (e.g. reading
the `/root` home directory).

Regardless, injecting this data is a good example of a generic
"secret". The bootc project does not currently include one
single opinionated mechanism for secrets.

## Synchronizing the bootc and podman credentials

See the [containers-auth.json](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md) man page. In many cases, you will
want to keep both the bootc and podman/skopeo credentials
in sync. One pattern is to symlink the two via e.g. a systemd `tmpfiles.d` fragment.

If you have a process invoking `podman login` (which by default writes to
an ephemeral `$XDG_RUNTIME_DIR/containers/auth.json`) you can then
`ln -s /run/user/0/containers/auth.json /run/ostree/auth.json`.

## Performing an explicit login

If you have automation (or manual processes) performing a login,
you can pass `--authfile` to set the bootc authfile explicitly;
for example

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

This pattern of using the ephemeral location in `/run` can work
well when the credentials are derived on system start from
an external system. 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.

## Using a credential helper

In order to use a credential helper as configured in `registries.conf`
Expand Down