Image Pull Secret

An Image Pull Secret is a standard Kubernetes Secret resource with type: kubernetes.io/dockerconfigjson. The core data field, .dockerconfigjson, contains a base64-encoded JSON structure conforming to the Docker config file format. This structure maps registry URLs to their respective authentication tokens.

• Auths Object: Contains key-value pairs where the key is the registry hostname (e.g., private-registry.io) and the value holds the credentials.
• Credential Encoding: The username and password are concatenated as username:password and base64-encoded into an auth field.
• Credential Helpers: The config can specify external credential helpers instead of storing static passwords, though static auth is most common for machine identities.

When a Pod references a private image, the kubelet executes a precise authentication sequence against the target registry. The process is triggered during the image pull stage of the Pod lifecycle, before any container starts.

• Secret Retrieval: The kubelet reads the Secret from etcd via the API server, decrypting it using the envelope encryption provider.
• Bearer Token Exchange: The kubelet presents the decoded credentials to the registry's /v2/token endpoint to obtain a time-limited Bearer token.
• Manifest Authorization: The Bearer token is attached as an Authorization header to download the image manifest and subsequent filesystem layers.
• Credential Caching: The kubelet caches the obtained Bearer token locally for the duration of its validity to avoid repeated authentication for concurrent pulls.

To use an Image Pull Secret, it must be explicitly referenced in the Pod specification. There are two distinct scoping mechanisms that determine which containers can leverage the credentials.

• imagePullSecrets Field: An array at the Pod spec level that applies the secret to all containers within that specific Pod. This is the most common method.
• Service Account Attachment: The secret can be added to a ServiceAccount via its imagePullSecrets field. This automatically injects the credential into all Pods running under that identity, eliminating the need to specify it per-Pod.
• Namespace Default: A ServiceAccount named default exists in every namespace. Adding the secret to this account applies it globally to all Pods in the namespace that don't specify a different account.

The kubectl create secret docker-registry command is the standard imperative method to generate an Image Pull Secret. This command correctly formats the .dockerconfigjson payload and applies the required type label.

• Command Syntax: kubectl create secret docker-registry <name> --docker-server=<registry> --docker-username=<user> --docker-password=<pass> --docker-email=<email>
• Direct Config Upload: For complex registries with multiple credentials, you can pass an existing Docker config.json file directly using --from-file=.dockerconfigjson=<path>.
• Declarative Equivalent: The same object can be defined in YAML, but the .dockerconfigjson data must be manually base64-encoded, making the imperative command less error-prone for initial creation.

A single Image Pull Secret can hold credentials for multiple distinct private registries. This is critical for Pods that assemble containers from different internal sources, such as a proxy sidecar from one registry and an application image from another.

• Composite Config: The .dockerconfigjson payload contains an auths map where each key is a unique registry hostname (e.g., harbor.internal.io and gcr.private.io).
• Per-Image Matching: During the pull process, the kubelet iterates through the Pod's list of imagePullSecrets and matches the hostname in the image URL to the corresponding entry in the secret's auth map.
• Fallback Behavior: If no matching hostname is found in any attached secret, the kubelet attempts an anonymous pull, which will fail against a private registry, resulting in an ErrImagePull status.

While Image Pull Secrets solve authentication, they introduce a security surface that must be hardened. The secret object itself is a static credential stored within the cluster's control plane.

• etcd Encryption at Rest: The Secret is stored in etcd. Without encryption at rest enabled, the base64-encoded credentials are effectively plaintext to anyone with etcd access.
• RBAC Protection: Access to the Secret resource must be tightly controlled via RBAC rules. Any identity with get or list verbs on the Secret can decode and exfiltrate the registry password.
• Ephemeral Token Alternatives: For cloud-managed registries (e.g., ECR, ACR), prefer token-refreshing controllers (like ecr-credential-helper) that generate short-lived tokens over long-lived static secrets stored in Kubernetes.

The underlying credential format stored within an image pull secret. This JSON file contains one or more registry URLs mapped to base64-encoded username:password pairs or identity tokens.

• Structure: {"auths": {"registry.example.com": {"auth": "base64string"}}}
• Credential helpers: External binaries like docker-credential-gcr can generate these dynamically
• Multi-registry support: A single config can hold credentials for multiple private registries
• Location on disk: Typically stored at $HOME/.docker/config.json on developer workstations

The kubelet reads this exact format when authenticating to a registry. Any syntax error in the base64 encoding or JSON structure will cause image pull failures with ErrImagePull status.

A mechanism that automatically mounts short-lived, audience-scoped tokens into pods, enabling passwordless authentication to cloud provider registries like Amazon ECR, Google Artifact Registry, and Azure Container Registry.

• Token audience: Must match the registry's expected aud claim (e.g., sts.amazonaws.com for ECR)
• Expiration: Tokens typically expire in 1 hour, requiring kubelet-side refresh
• No secret management: Eliminates the need to manually create and rotate image pull secrets
• IAM integration: Cloud providers map the projected token to IAM roles for authorization

This approach is preferred over long-lived static credentials because it removes the operational burden of secret rotation and reduces the risk of credential leakage.

The Kubernetes pod status indicating repeated failure to pull a container image. This error state is the most common symptom of misconfigured image pull secrets.

• Root causes: Invalid credentials, expired tokens, non-existent image tag, network policy blocking registry access, or missing image pull secret reference
• Backoff behavior: The kubelet retries with exponential backoff starting at 5 seconds, capping at 5 minutes between attempts
• Diagnostic command: kubectl describe pod <name> reveals the exact error message in the Events section
• Registry-specific errors: HTTP 401 (unauthorized) vs HTTP 403 (forbidden) vs DNS resolution failure

When troubleshooting, verify the secret exists in the pod's namespace, the imagePullSecrets field references the correct secret name, and the registry URL in the image field matches the credential's server address.

Kubernetes admission webhooks can validate or mutate pod specifications to enforce organizational policies around image pull secrets before the pod is persisted to etcd.

• Mutation: Automatically inject a default image pull secret into every pod in a namespace, eliminating developer toil
• Validation: Reject pods that reference public images or lack required signature verification annotations
• Common implementations: Kyverno, OPA Gatekeeper, and custom webhook servers
• Combined with Binary Authorization: Admission controllers can verify image signatures and enforce that only images from approved registries are deployed

This pattern ensures that security policies are applied consistently across all workloads, preventing developers from accidentally or intentionally bypassing private registry authentication requirements.

A pluggable architecture where the container runtime delegates credential retrieval to external programs rather than storing static secrets. This pattern is essential for cloud-native registry authentication.

• How it works: The runtime executes a configured binary (e.g., docker-credential-ecr-login) which returns a JSON payload with temporary credentials
• Cloud provider helpers: AWS, GCP, and Azure each provide CLI tools that generate time-limited registry tokens
• Kubelet integration: The kubelet can be configured with credential provider plugins that fetch tokens on-demand during image pulls
• Advantage over secrets: Credentials are never stored in Kubernetes etcd; they exist only in memory during the pull operation

This pattern aligns with zero-standing-credentials security models and is the foundation for keyless authentication to private registries.

Image pull secrets are namespace-scoped resources, meaning a secret created in one namespace cannot be referenced by pods in another. This isolation has important operational implications.

• Per-namespace duplication: The same registry credentials must be created in every namespace that runs workloads pulling from that registry
• Automation strategies: Tools like External Secrets Operator or Sealed Secrets can synchronize credentials across namespaces
• Default service account: Each namespace has a default service account; patching it with an image pull secret automatically applies to all pods using that account
• RBAC considerations: The service account that creates the secret must have create permissions on secrets in the target namespace

Understanding this scoping is critical for multi-tenant clusters where different teams operate in isolated namespaces with distinct registry access requirements.