Podman Registry Mirror and Auth Configuration Prompt
Configure registries.conf mirrors, short-name resolution, and auth.json credential storage so Podman pulls from the right registry with the right credentials on every host.
- Target user
- Platform engineers configuring Podman registry access across build hosts and CI runners
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a senior platform engineer who knows Podman's registry configuration precisely. You know `registries.conf` is TOML v2 with `[[registry]]` blocks carrying `prefix`, `location`, and nested `[[registry.mirror]]` entries; that `unqualified-search-registries` and `short-name-mode` decide what a bare `nginx` resolves to; that rootless credentials live in `$XDG_RUNTIME_DIR/containers/auth.json` by default and therefore do not survive a reboot; and that `REGISTRY_AUTH_FILE` or `--authfile` is how you point at a persistent one. I will describe the registry topology and the hosts. Produce the configuration. Steps: 1. **Map the topology**: list every registry in play — upstream public registries, an internal mirror or pull-through cache, and the private registry holding first-party images — with which images come from where. 2. **Write the registry blocks**: build the `[[registry]]` entries with correct `prefix` versus `location` semantics, add `[[registry.mirror]]` entries in preference order, and set `pull-from-mirror` where you want a mirror used for digest-only or tag pulls. 3. **Decide short-name behavior**: set `unqualified-search-registries` and choose `short-name-mode` — recommend `enforcing` for CI and production so a bare image name can never silently resolve to an unintended registry, and explain the interactive prompt behavior of `permissive`. 4. **Handle insecure and blocked registries**: use `insecure = true` only where TLS genuinely cannot be fixed and say what it gives up, and use `blocked = true` to positively prevent pulls from registries policy forbids. 5. **Design credential storage**: choose between the default runtime `auth.json`, a persistent path via `REGISTRY_AUTH_FILE`, or a credential helper, and specify file permissions — note that `podman login` writes base64-encoded, not encrypted, credentials. 6. **Make CI work without interactive login**: give the non-interactive pattern using `--authfile` or a mounted credentials file with a scoped robot/deploy token, and state that the token must be pull-scoped where writes are not needed. 7. **Cover rootless versus root divergence**: point out that root and each rootless user have separate config and auth paths, so a working root pull says nothing about the rootless user, which is a very common CI-versus-laptop discrepancy. 8. **Verify explicitly**: give commands proving resolution and auth work — a fully qualified pull, a short-name pull, and `podman pull --log-level=debug` to confirm which mirror was actually contacted. Fill in: - Registries and mirrors in use: [DESCRIBE] - Which images come from which registry: [LIST] - Rootless users and CI runner identity: [DESCRIBE] - Credential type available: [robot account / deploy token / user credentials] - Is any registry on plain HTTP or a private CA: [DESCRIBE] Output as: (a) the complete `registries.conf` with comments explaining each block, (b) the credential storage design with exact paths, permissions, and the env var or flag that selects it, and (c) the verification commands including how to confirm which mirror served the pull. Do not set `insecure = true` as a way past a certificate error. Install the private CA into the host trust store instead, and reserve `insecure` for registries you have deliberately accepted the risk on.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
Registry configuration is where Podman diverges most visibly from Docker, and the divergence is not cosmetic. Docker has one daemon with one configuration; Podman has per-user configuration, which means root and every rootless user carry separate registries.conf and separate auth.json files. That single fact explains an enormous share of “it pulls on my machine but not in CI” reports, and step seven makes checking it a required part of any registry design rather than a debugging afterthought.
The short-name discussion matters more than it first appears. A bare nginx resolves through unqualified-search-registries in order, which means the image a pipeline pulls depends on configuration rather than on the manifest, and a mirror added at the front of that list can change what a build produces without any change to the build itself. Recommending short-name-mode = "enforcing" for CI and production turns an implicit resolution into an explicit one, so a pipeline either names its registry or fails loudly instead of quietly pulling something else.
The credential guidance targets two specific traps. The first is the default rootless auth.json path under $XDG_RUNTIME_DIR, which is wiped on reboot — perfectly fine on a laptop, and a scheduled outage on an unattended host where pulls simply begin failing days after the login that appeared to work. The second is that auth.json contents are base64-encoded rather than encrypted, which people consistently read as protection. Naming both plainly, and steering insecure = true back toward installing the CA properly, keeps a convenience setting from quietly becoming the security posture.
Related prompts
-
Podman Container Security Hardening Prompt
Harden a Podman container with dropped capabilities, no-new-privileges, a read-only rootfs, a tuned seccomp profile, and a user namespace mapping that actually fits the workload.
-
Docker to Podman Team Migration Plan Prompt
Produce a phased Docker-to-Podman migration plan covering socket compatibility, CI impact, rootless gaps, and the developer workflow changes a team will actually hit.
-
Dockerfile to Buildah Build Script Conversion Prompt
Convert a Dockerfile into an equivalent scripted buildah build so image construction can use host tooling, secrets, and logic that Dockerfile syntax cannot express.
-
Podman cgroup v2 Resource Limits & OOM Diagnosis Prompt
Set correct memory, CPU, and PID limits for Podman containers under cgroup v2 and trace exactly why a container was OOM-killed or CPU-throttled.
More Podman prompts & error guides
Browse every Podman prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.