Helm to Flux Migrator

Seamlessly migrate your Helm releases to FluxCD GitOps-managed HelmReleases. Extract, convert, and deploy with confidence.

Get Started Documentation

Streamlined GitOps Migration

Transition from traditional Helm deployments to FluxCD with automated tooling

🔄

Automatic Conversion

Extracts all Helm releases and converts them to FluxCD HelmRelease format automatically.

📁

Best Practice Structure

Generates output following FluxCD's recommended directory structure with Kustomizations.

🤖

AI-Powered Detection

Uses Claude AI to find official Helm chart repositories when not detected from FluxCD.

📈

Export & Compare

Export manifests and compare deployments before/after changes for validation.

Quick Start

Get up and running in minutes with simple commands

Installation
git clone https://github.com/starburst997/helm-to-flux
cd helm-to-flux
chmod +x *.sh
Convert a Single Release
# Basic usage
./convert.sh ingress-nginx ingress-nginx

# With cluster and output directory
./convert.sh --cluster production --output-dir my-gitops ingress-nginx ingress-nginx
Convert All Releases
# Discover and convert all Helm releases across all namespaces
./all.sh

# Specify cluster name for production
./all.sh --cluster production --output-dir my-gitops
Export & Compare Manifests
# Export current state
./export-all.sh export-before

# Make changes to your cluster...

# Export new state and compare
./export-all.sh export-after
./compare-exports.sh export-before export-after

Output Structure

FluxCD-compatible directory layout following GitOps best practices 

clusters/
├── my_cluster/                     # Cluster-specific Kustomizations
│   ├── infrastructure/
│   │   ├── ingress-nginx.yaml     # Kustomization
│   │   └── cert-manager.yaml
│   └── apps/
│       ├── myapp.yaml
│       └── another-app.yaml
└── resources/
    └── my_cluster/
        ├── infrastructure/
        │   ├── ingress-nginx/
        │   │   └── helm.yaml          # HelmRepo + HelmRelease
        │   └── cert-manager/
        │       └── helm.yaml
        └── apps/
            ├── myapp/
            │   └── helm.yaml
            └── another-app/
                └── helm.yaml

Command Reference

Complete options for all scripts

convert.sh

--cluster CLUSTER_NAME
Name of the target cluster
Default: my_cluster
--output-dir OUTPUT_DIR
Root output directory
Default: clusters
--allow-overwrite
Allow overwriting existing files
Default: disabled
<RELEASE> <NAMESPACE>
Helm release name and Kubernetes namespace (required)

all.sh

--cluster CLUSTER_NAME
Name of the target cluster
Default: my_cluster
--output-dir OUTPUT_DIR
Root output directory
Default: clusters
--allow-overwrite
Allow overwriting existing files
Default: disabled

export-all.sh

[OUTPUT_DIR]
Output directory for exported manifests
Default: export

compare-exports.sh

<EXPORT_DIR_1>
First export directory (required)
<EXPORT_DIR_2>
Second export directory (required)
Returns exit code 0 if identical, 1 if different

Migration Workflow

Recommended approach for a seamless transition

1

Test in Development

Run the migration in a dev cluster first using ./all.sh --cluster dev

2

Review Generated Files

Inspect Kustomizations and HelmReleases before committing to ensure correctness.

3

Gradual Production Migration

Migrate one release at a time in production using ./convert.sh

4

Commit & Push

Add generated files to your GitOps repository and push to trigger FluxCD reconciliation.

5

Verify State

Run flux get kustomizations and flux get helmreleases -A to verify success.

6

Clean Up

Once verified, remove original Helm releases with helm uninstall

Prerequisites

Required tools for running the migrator

helm

Helm CLI

kubectl

Kubernetes CLI

jq

JSON processor

yq

YAML processor

claudeoptional

AI repository detection