imagePullSecrets and credential rotation — authentication to registries

imagePullSecrets authenticate Pods to registries. This lesson walks the Secret types, the Pod integration, credential rotation, IRSA / Workload Identity, and the discipline.

The dockerconfigjson Secret

# Create a dockerconfigjson
echo '{"auths":{"registry.example.com":{"username":"ci","password":"***","auth":"***"}}}' | \
  base64 -w 0 > dockerconfig.base64

apiVersion: v1
kind: Secret
metadata:
  name: my-registry-creds
  namespace: prod-app
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

The Secret contains a Docker-style config JSON with the registry credentials. The auth field is the base64-encoded username:password.

Per-namespace vs cluster-wide

flowchart LR
    A[imagePullSecrets] --> B[Per-namespace Secret]
    A --> C[Cluster-wide via service account]
    B --> B1[Each namespace has its own Secret]
    B --> B2[Credential isolation]
    C --> C1[Service account references Secret]
    C --> C2[All Pods in namespace share]

The two approaches:

• Per-namespace Secret. Each namespace has its own Secret; isolation between namespaces.
• Cluster-wide via ServiceAccount. The default ServiceAccount references a Secret; every Pod in the namespace uses it.

For production, per-namespace is preferred for isolation. Cluster-wide via ServiceAccount is simpler for small clusters.

ServiceAccount integration

apiVersion: v1
kind: ServiceAccount
metadata:
  name: prod-app
  namespace: prod-app
imagePullSecrets:
  - name: my-registry-creds
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: prod-app
spec:
  template:
    spec:
      serviceAccountName: prod-app
      containers:
        - name: app
          image: registry.example.com/myapp:1.2.3

The ServiceAccount references the Secret. Pods that use the ServiceAccount inherit the imagePullSecrets.

Credential rotation

flowchart LR
    A[New credential] --> B[Create new Secret]
    B --> C[Replace existing Secret]
    C --> D[Existing Pods use old credential]
    D -->|kubelet refresh| E[New credential used]
    E -->|or restart| F[Immediate refresh]

The rotation:

1. Create a new credential in the registry.
2. Create a new Secret with the new credential.
3. Replace the existing Secret (e.g., with kubectl create secret and a new name).
4. New Pods use the new credential; existing Pods continue with the old until restart.
5. Restart the Pods to use the new credential.

The kubelet does not actively refresh credentials; the credential is cached at Pod start.

IRSA / Workload Identity for cloud registries

apiVersion: v1
kind: ServiceAccount
metadata:
  name: prod-app
  namespace: prod-app
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123:role/prod-app-ecr

IRSA (IAM Role for Service Accounts, AWS) or Workload Identity (GCP) or Managed Identity (Azure) provides cloud-native authentication:

• No static credentials. The IAM role is assumed via OIDC token exchange.
• No imagePullSecrets needed. The kubelet uses the IAM role to authenticate to ECR.
• Automatic rotation. The IAM role’s credentials are rotated by AWS.

For cloud registries, IRSA / Workload Identity is preferred over static credentials.

Quiz

The operational discipline

imagePullSecrets in production rest on five non-negotiable elements:

• Use dockerconfigjson Secret type. Modern format.
• Per-namespace Secrets. Credential isolation.
• Rotate credentials quarterly. Update Secret, restart Pods.
• Use IRSA / Workload Identity for cloud. No static credentials.
• Document the rotation procedure. In the runbook.

imagePullSecrets are how Pods authenticate to registries. The discipline is per-namespace Secrets, rotation, and cloud-native identity where possible.