Configure pull credentials on an edge device for VM applications

Configure container registry pull credentials so the Red Hat Edge Manager agent can pull the Red Hat virt-launcher image from registry.redhat.io. Without valid credentials, VM applications fail to start. Store credentials at /root/.config/containers/auth.json on the device.

Before you begin

  • SSH or console access to the edge device.
  • A Red Hat account with access to the Red Hat container catalog.
  • The device is running Red Hat Enterprise Linux (EL9 or EL10).
  • Podman is installed on the device.
  • The worker.vmRender.launcherImage value is configured on the Red Hat Edge Manager control plane. See Virt-launcher image configuration values in the Additional resources section for configuration details.
Note

Every command in this procedure requires root privileges because it reads or writes files owned by root. If you access the device through the Red Hat Edge Manager web console terminal, that session does not start as root, so prefix each command with sudo as shown. If you connect over SSH as the root user, sudo is not required, but running the commands with sudo is still safe.

Procedure

  1. Log in to registry.redhat.io from the edge device, specifying --authfile to write the credentials to the path the Red Hat Edge Manager agent reads: 
    sudo podman login --authfile /root/.config/containers/auth.json registry.redhat.io

    Enter your Red Hat account username and password when prompted.

  2. Verify that the credentials file was created: 
    sudo cat /root/.config/containers/auth.json

    The output contains an auths object with an entry for registry.redhat.io:

    {
  "auths": {
    "registry.redhat.io": {
      "auth": "<base64_encoded_credentials>"
    }
  }
}
  3. Verify that the device can pull the Red Hat virt-launcher image. Replace <tag> with the image tag configured in worker.vmRender.launcherImage on your Red Hat Edge Manager control plane. To retrieve this value, see Checking the current value in Virt-launcher image configuration values in the Additional resources section: 
    sudo podman pull --authfile /root/.config/containers/auth.json registry.redhat.io/container-native-virtualization/virt-launcher-rhel9:<tag>

    After the pull completes successfully, remove the image to reclaim disk space:

    sudo podman rmi registry.redhat.io/container-native-virtualization/virt-launcher-rhel9:<tag>

Results

  • Confirm that the auth.json file exists at /root/.config/containers/auth.json and contains a valid entry for registry.redhat.io: 
    sudo test -f /root/.config/containers/auth.json && echo "Credentials file exists"
Note

For fleet-scale deployments, you have two additional options:

  • Configure credentials declaratively using device or fleet specifications. See Configure pull credentials using device or fleet configuration in the Additional resources section.
  • Include the auth.json file in your bootc operating system image build. Add the credentials file to the image at /root/.config/containers/auth.json during the image build process. See Operating system images for the Red Hat Edge Manager in the Additional resources section for details on building custom OS images.

If the podman pull command fails with Error: unauthorized, verify the following:

  • The Red Hat account credentials are correct. Re-run sudo podman login --authfile /root/.config/containers/auth.json registry.redhat.io to refresh the credentials.
  • The credentials file exists at /root/.config/containers/auth.json. If the file is empty or missing, the login may not have written to the correct path. Podman writes credentials to a session-specific path such as /run/containers/0/auth.json by default; always specify --authfile to target the path the agent reads.
  • The device has network connectivity to registry.redhat.io. Test connectivity with curl -s https://registry.redhat.io/v2/ -o /dev/null -w '%{http_code}', which returns 401 if the registry is reachable.