Migrating from Bitnami to CleanStart Images

Last updated: April 2026

Overview

CleanStart images are distroless, FIPS-compliant replacements for Bitnami container images. Rather than requiring you to rewrite your Helm charts, CleanStart provides values overlay files that you apply on top of existing Bitnami charts. Your Kubernetes structure (RBAC, StatefulSets, Services) stays unchanged.

How It Works

Bitnami charts assume images contain a shell and CLI tools (e.g., mongosh, valkey-cli, redis-cli). Bitnami health probes use exec to call these tools. CleanStart images are distroless -- no shell, no CLI tools at runtime -- so these probes must be converted to TCP or HTTP socket probes.

CleanStart provides two things to make migration seamless:

1. Values overlay files -- YAML files that override the image reference, security context, and probes for a specific Bitnami chart.
2. Probe conversion script -- A Python utility (fix-bitnami-probes.py) that auto-generates probe overrides for any Bitnami chart.

Quick Migration

Step 1: Get the Overlay File

Pre-built overlays are available for common applications:

Step 2: Deploy with Overlay

helm install mongodb bitnami/mongodb \  -f your-values.yaml \  -f mongodb-clnstrt-values.yaml

The CleanStart overlay is applied last, overriding the image source, security context, and health probes while preserving your custom configuration.

Step 3: Verify

kubectl get pods -l app.kubernetes.io/name=mongodbkubectl describe pod <pod-name>  # Check image and probe configuration

What the Overlay Changes

Each overlay makes three categories of changes:

Image Source

Replaces the Bitnami registry with CleanStart:

image:  registry: gcr.io/clean-image-build  repository: mongodb  tag: "8.0.6-r0"

Security Context

Enforces CleanStart hardening defaults:

podSecurityContext:  runAsUser: 65532  runAsGroup: 65532  fsGroup: 65532  runAsNonRoot: truecontainerSecurityContext:  readOnlyRootFilesystem: true  allowPrivilegeEscalation: false  capabilities:    drop: ["ALL"]

CleanStart images run as UID 65532 (user clnstrt) instead of Bitnami's UID 1001.

Health Probes

Converts exec probes to TCP socket probes:

# Bitnami default (won't work -- no shell)livenessProbe:  exec:    command: ["mongosh", "--eval", "db.adminCommand('ping')"] # CleanStart overridelivenessProbe:  tcpSocket:    port: mongodb  initialDelaySeconds: 30  periodSeconds: 10

TCP probes verify the port is accepting connections. For deeper health checks (replication status, query capability), deploy a sidecar with diagnostic tools or use the CleanStart debug image variant with kubectl debug.

Generating Overlays for Other Charts

For Bitnami charts without a pre-built overlay, use the probe conversion script:

python fix-bitnami-probes.py \  --chart bitnami/postgresql \  --output postgresql-clnstrt-values.yaml

This scans the chart's default values for exec probes and generates TCP/HTTP replacements. Review the output before deploying -- some applications may need HTTP health endpoints instead of TCP sockets.

Key Differences from Bitnami

Troubleshooting

Pods crash with permission errors -- The UID changed from 1001 to 65532. Ensure persistent volumes have correct ownership. You may need an initContainer to chown existing data directories.

Probes failing after migration -- Verify the probe port name matches the service definition. Check kubectl describe pod for probe configuration details.

Application can't write to filesystem -- CleanStart enforces read-only root filesystem. Add writable paths via emptyDir volumes for /tmp, /var/run, or application-specific data directories.