How To: Use Kubernetes Registry Remapping to Redirect Bitnami Images to Bitnami Legacy as a Temporary Migration Mitigation

Starting August 28th, 2025, Bitnami is moving most older and versioned container images from the main Bitnami registry (docker.io/bitnami) to a legacy registry (docker.io/bitnamilegacy). This affects Helm charts, Kubernetes manifests, and other container deployments referencing Bitnami images.

Why Use Registry Remapping as a Temporary Mitigation?

• Immediate updates to all Helm charts and manifests can be complex due to nested dependencies or indirect image references.
• Without remapping, pods restarting or newly deployed may fail to pull images from the deprecated main registry.
• Registry remapping at the container runtime level transparently redirects image pulls to the new legacy registry, minimizing disruptions while you update charts and manifests over time.

Understanding Registry Remapping

Registry remapping configures your container runtime to automatically redirect image pull requests for one registry namespace to another. Specifically, requests for docker.io/bitnami images get redirected to docker.io/bitnamilegacy without needing to modify deployment manifests.

Correctly Configuring containerd with registry.redirects for Bitnami

Most Kubernetes clusters use containerd as the runtime.

You should create a drop-in redirect configuration file at:

/etc/containerd/conf.d/99-bitnami-legacy-redirect.toml

with the following content:

[plugins."io.containerd.grpc.v1.cri".registry.redirects."docker.io/bitnami"]
  to = "docker.io/bitnamilegacy"

This tells containerd to redirect any image requests from the Bitnami main registry to the legacy registry.

After adding the drop-in file, restart containerd to apply changes:

sudo systemctl restart containerd

This approach using registry.redirects is more explicit and appropriate than the mirrors approach.

Automating Registry Redirect Configuration Using a DaemonSet

Applying these changes to all nodes manually is cumbersome. To automate:

1. Use a ConfigMap that holds a shell script to create the redirect file safely.
2. Deploy a privileged DaemonSet that runs this script on every node and restarts containerd using nsenter.

Updated ConfigMap with robust remapping script:

apiVersion: v1
kind: ConfigMap
metadata:
  name: bitnami-remap-script
  namespace: kube-system
data:
  remap-bitnami.sh: |
    #!/bin/sh
    # This script applies a temporary registry redirect for Bitnami images via containerd
    set -e
    CONFIG_FILE="/etc/containerd/config.toml"
    HOST_CONFIG_DIR="/etc/containerd/conf.d"  # Drop-in config directory
    REMAP_CONFIG_FILE="${HOST_CONFIG_DIR}/99-bitnami-legacy-redirect.toml"
    REDIRECT_CONFIG='
[plugins."io.containerd.grpc.v1.cri".registry.redirects."docker.io/bitnami"]
  to = "docker.io/bitnamilegacy"
'
    mkdir -p "$HOST_CONFIG_DIR"
    if [ ! -f "$REMAP_CONFIG_FILE" ]; then
      echo "Creating containerd redirect config for Bitnami Legacy..."
      echo "${REDIRECT_CONFIG}" > "$REMAP_CONFIG_FILE"
      echo "Restarting containerd to apply changes..."
      nsenter --target 1 --mount --uts --ipc --net --pid -- systemctl restart containerd
      echo "Containerd restarted successfully."
    else
      echo "Bitnami redirect configuration already exists. No action taken."
    fi

DaemonSet manifest example:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: bitnami-registry-remap
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: bitnami-registry-remap
  template:
    metadata:
      labels:
        app: bitnami-registry-remap
    spec:
      hostPID: true
      restartPolicy: Always
      containers:
        - name: remap
          image: alpine:3.19
          securityContext:
            privileged: true
          command: ["/bin/sh", "/scripts/remap-bitnami.sh"]
          volumeMounts:
            - name: containerd-config
              mountPath: /etc/containerd
              readOnly: false
            - name: scripts
              mountPath: /scripts
      volumes:
        - name: containerd-config
          hostPath:
            path: /etc/containerd
        - name: scripts
          configMap:
            name: bitnami-remap-script
            defaultMode: 0700

Apply the ConfigMap and DaemonSet with:

kubectl apply -f bitnami-remap-cm.yaml
kubectl apply -f bitnami-remap-ds.yaml

Platform-Specific Considerations

Validating the Redirect

• Deploy pods referencing images under the docker.io/bitnami namespace.
• Confirm images successfully pull from docker.io/bitnamilegacy.
• Use kubectl describe pod and check containerd logs (journalctl -u containerd) on nodes.

Troubleshooting

• Containerd restart failure: Verify DaemonSet’s privileged access and writable mount on /etc/containerd. Use nsenter correctly.
• Config file missing or invalid: Shell into nodes, confirm the existence and correctness of /etc/containerd/conf.d/99-bitnami-legacy-redirect.toml.
• Image pulls still fail: Confirm images exist in docker.io/bitnamilegacy; check config syntax.
• On OpenShift or CRI-O: Registry redirects not supported; update manifests or use OpenShift config tools.
• DaemonSet lacks permissions: Managed services may block privileged DaemonSets; use node provisioning/custom images instead.

Summary

This registry remapping approach using registry.redirects in containerd with automated DaemonSet deployment is a robust, explicit, and cluster-wide temporary mitigation to keep Bitnami-dependent workloads running smoothly during the registry migration. It provides vital time to safely update Helm charts and manifests.