Image registry overview — pull, push, cache, and security

Image registries are central to Kubernetes; every Pod pulls an image. This lesson walks the pull mechanics, the registry types, the cache, the security, and the discipline.

The image pull flow

flowchart LR
    A[Pod scheduled] --> B[kubelet]
    B --> C{Image already cached?}
    C -->|Yes| D[Use cached image]
    C -->|No| E[Check imagePullSecrets]
    E -->|No secret| F[Pull anonymously]
    E -->|Has secret| G[Authenticate]
    G --> H[Pull from registry]
    F --> H
    H --> I[Pull layers]
    I --> J[Store in kubelet cache]
    J --> K[Start container]

The pull flow:

1. The kubelet receives a Pod to run.
2. It checks the kubelet’s local cache.
3. If not cached, it checks for imagePullSecrets.
4. It authenticates with the registry (or pulls anonymously).
5. It pulls the image layers.
6. It stores the layers in the kubelet cache.
7. It starts the container.

imagePullPolicy

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
        - name: app
          image: myapp:1.2.3
          imagePullPolicy: IfNotPresent  # pull only if missing

The policies:

• Always. Always pull the image, even if cached. Default for :latest and untagged images.
• IfNotPresent. Pull only if not in the kubelet cache. Default for tagged images.
• Never. Never pull; use the local image only. Rare; useful for offline scenarios.

For production, IfNotPresent with explicit tags is the recommended pattern.

The registry types

flowchart LR
    A[Registry types] --> B["Public: Docker Hub"]
    A --> C["Private: Harbor, Quay"]
    A --> D["Cloud: ECR, GCR, ACR"]
    B --> B1["Anchore, Clair"]
    C --> C1[On-prem control]
    D --> D1[Managed; IAM integration]

The registry types:

• Public. Docker Hub, Quay.io. Free for public images; rate-limited for anonymous pulls.
• Private. Harbor (CNCF), Quay (Red Hat), distribution (Docker registry). On-prem control; vulnerability scanning built in.
• Cloud. AWS ECR, Google GCR/Artifact Registry, Azure ACR. Managed; IAM integration.

Most production deployments use a private or cloud registry, not Docker Hub directly.

imagePullSecrets

apiVersion: v1
kind: Secret
metadata:
  name: my-registry-creds
  namespace: prod-app
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      imagePullSecrets:
        - name: my-registry-creds
      containers:
        - name: app
          image: registry.example.com/myapp:1.2.3

The imagePullSecrets:

• Secret type. kubernetes.io/dockerconfigjson for Docker registry credentials.
• Pod spec. imagePullSecrets lists the Secrets to use for authentication.
• The kubelet uses the credentials to authenticate with the registry.

Registry cache

flowchart LR
    A[kubelet] -->|pull| B["Registry cache: distribution"]
    B -->|cache miss| C[Upstream registry]
    C -->|return layers| B
    B -->|return layers| A
    B -->|cache hit| A

A registry cache (pull-through proxy) reduces load on the upstream registry and improves pull performance:

• distribution. Docker’s pull-through cache.
• Harbor. CNCF registry with caching.
• kube-fledged. kubelet-level cache.

The cache is deployed as a Deployment in the cluster; Pods are configured to pull from the cache instead of the upstream.

Quiz

The operational discipline

Image registries in production rest on five non-negotiable elements:

• Use a private or cloud registry. Not Docker Hub directly.
• Pin image tags. No :latest in production.
• imagePullSecrets for authentication. For private registries.
• Registry cache for performance. Pull-through proxy.
• Image signing and scanning. cosign, Trivy, Grype.

Image registries are the source of application code. The discipline is private registries, pinned tags, and signed images.