Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Building and Registries

Registries and Authentication

Pull and push images with Podman: image name anatomy, short names and unqualified-search-registries, registries.conf, mirrors, podman login and auth.json, tagging and pushing.

A registry is a server that stores and serves container images: Docker Hub, Quay.io, GitHub's ghcr.io, a cloud provider's registry or one you run yourself. Podman downloads images with pull and uploads them with push. Getting comfortable with image names, the registry configuration file and logging in saves a lot of confusion, especially the "which registry did that short name come from?" question.

This lesson covers the anatomy of an image reference, how short names are resolved, how registries.conf configures mirrors and insecure registries, authentication, and the push workflow. Registries are remote services, so commands are read-only; the stand-ins parse references and a configuration file.

Anatomy of an image reference

TEXT
registry.example.com:5000/team/app:1.4@sha256:9f86d0...
|______________________| |_______| |_| |____________|
        registry          path    tag     digest
  • Registry: host name, optionally with a port. Omitted names are "short names".
  • Path: repository, often namespace/name. Official Docker Hub images live under library/.
  • Tag: a human-friendly label, mutable (it can point to a different image tomorrow).
  • Digest: a cryptographic hash of the image manifest, immutable. name@sha256:... always means exactly the same bytes.

For reproducible deployments pin a digest, or at least a precise tag, instead of latest.

Python Image reference parser (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Short names

Typing podman pull nginx leaves out the registry. Podman has to decide where to look. The rules, in order:

  1. Short-name aliases: a built-in and user-editable table mapping some well-known short names to full names (nginx to docker.io/library/nginx). Files live under /etc/containers/registries.conf.d/ (and ~/.config/containers/registries.conf.d/).
  2. Search registries: otherwise Podman tries each entry of unqualified-search-registries in order.
  3. Mode: short-name-mode controls what happens when an unaliased short name matches several registries: enforcing (prompt on a terminal, fail otherwise), permissive (prompt or warn) or disabled (use the first match).

Because the result depends on the machine, writing the full name in scripts, Containerfiles and Compose files avoids surprises, and prevents a "typosquatting" image on another registry from being pulled by accident.

registries.conf

The main file is /etc/containers/registries.conf; a user can override it with ~/.config/containers/registries.conf, and fragments go in registries.conf.d/. It is TOML:

TOML
unqualified-search-registries = ["docker.io", "quay.io"]
short-name-mode = "enforcing"

[aliases]
"myalpine" = "docker.io/library/alpine"

[[registry]]
location = "registry.internal:5000"
insecure = true          # allow plain HTTP / untrusted TLS (avoid in production)

[[registry]]
prefix = "docker.io"
location = "docker.io"

[[registry.mirror]]
location = "mirror.internal:5000"
  • [aliases] define short-name shortcuts.
  • insecure = true lets Podman talk to a registry over HTTP or with an unverified certificate. Use it only for a local test registry.
  • A [[registry.mirror]] is tried before the primary location: ideal for a pull-through cache inside a company network.
  • blocked = true forbids a registry entirely.

The stand-in below reads such a configuration with Python's tomllib and applies the short-name and mirror rules.

Python Resolve a short name and mirrors (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Mirrors are listed first, so the pull would try mirror.internal:5000 before Docker Hub.

Logging in

Anonymous pulls work on public registries. Pushing, and pulling private images, require credentials:

Terminal
podman login registry.example.com
podman login -u myuser --password-stdin quay.io < token.txt
podman login --get-login registry.example.com
podman logout registry.example.com
podman logout --all

Credentials are stored in ${XDG_RUNTIME_DIR}/containers/auth.json (a temporary file in memory-backed storage, gone after logout of the session), unless you set --authfile or the REGISTRY_AUTH_FILE environment variable. Podman also reads ~/.docker/config.json as a fallback. The file contains base64-encoded credentials, which are not encrypted: treat it like a password. Prefer access tokens over your account password, and pipe the token through stdin (--password-stdin) so it does not appear in your shell history or process list. Credential helpers (credsStore in auth.json) can keep secrets in your OS keychain instead.

Searching, pulling and pushing

Terminal
podman search --limit 5 nginx
podman pull docker.io/library/nginx:stable
podman pull --platform linux/arm64 docker.io/library/nginx:stable
podman tag localhost/myapp:1.0 registry.example.com/team/myapp:1.0
podman push registry.example.com/team/myapp:1.0

tag gives an existing image a second name; the name must include the registry and path you want to push to. push uploads missing layers (layers the registry already has are skipped). To copy between registries without a local pull, use the companion tool skopeo copy docker://source docker://destination.

For a throwaway registry on your machine:

Terminal
podman run -d --name registry -p 5000:5000 docker.io/library/registry:2
podman push --tls-verify=false localhost/myapp:1.0 localhost:5000/myapp:1.0

localhost:5000 is accepted without TLS in many setups; otherwise mark it insecure in registries.conf or pass --tls-verify=false.

--tls-verify=false disables certificate checks and invites man-in-the-middle attacks. Use it only against registries on your own machine or a lab network.

Next you can control which images are trusted at all: see Image Signing and Trust Policy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of an image reference is immutable?

    A digest is a hash of the manifest, so it always identifies exactly the same image. Tags can be moved.
  2. 2. What does unqualified-search-registries do?

    When a short name has no alias, Podman searches these registries in the listed order.
  3. 3. Why is --password-stdin recommended for podman login?

    Passing a secret as a command-line argument exposes it; reading it from stdin avoids that.
  4. 4. What must a tag contain before you can push an image to a registry?

    podman push uses the image name to choose the destination, so retag it as registry/path:tag first.

Summary

  • An image reference is registry, path, tag and optionally digest; pin digests for exact reproducibility.
  • Short names are resolved by aliases, then unqualified-search-registries, guarded by short-name-mode; prefer fully qualified names.
  • registries.conf (TOML) defines search registries, aliases, mirrors, insecure and blocked registries.
  • podman login stores credentials in auth.json; treat the file as sensitive and use tokens with --password-stdin.
  • tag then push uploads an image; skopeo copy moves images between registries without pulling.

Next: Image Signing and Trust Policy