Learning GitOps - FluxCD - Migration Strategies

#Introduction

In episode 32 you mastered FluxCD troubleshooting. Now it's time to face the scenario most often seen in the field: legacy systems that must be moved to Flux. In this episode 33 you'll learn migration strategies — from moving manual deployments and Helm 2, understanding the differences in the Flux v1 to v2 migration, mapping ArgoCD concepts to Flux, to incremental migration best practices that don't panic the team.

#Migrating to Flux

#From Manual Deployments

Organizations that have been deploying with manual kubectl apply have one advantage: the configuration is already in YAML form. The steps: gather all the manifests scattered in shell history and documentation, organize them into one repository, then create a GitRepository and Kustomization to pull them.

flux create source git apps \
  --url=https://github.com/devvnull/apps \
  --branch=main
flux create kustomization apps \
  --source=apps \
  --path=./deploy \
  --prune=true \
  --interval=5m

#From Helm 2

Helm 2 stores state in Tiller (server-side). Before migrating, convert the Helm 2 releases to static manifests or to Helm 3 charts. Flux v2 supports Helm 3 through HelmRepository and HelmRelease, so teams already using charts can still use Flux:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: nginx
  namespace: apps
spec:
  interval: 5m
  chart:
    spec:
      chart: ingress-nginx
      sourceRef:
        kind: HelmRepository
        name: ingress-nginx
      interval: 1h

#From Other GitOps Tools and Planning

Whatever the origin, do thorough planning first: inventory the resources, identify dependencies, decide the migration order, and build a rollback path. Never start a migration without knowing how to return to the previous state.

#Flux v1 to v2 Migration

#Architecture Differences

Flux v1 is a single monolithic container. Flux v2 is built from the GitOps Toolkit — a set of controllers that stand on their own (source-controller, kustomize-controller, helm-controller, and others). As a consequence, the way to configure also changes: from a single config file to declarative custom resources.

#Migration Guide

Flux provides flux bootstrap which at the same time creates the v2 foundation, then the old resources are moved one by one. Run the migration in a non-production environment first:

flux check --pre
flux export kustomization flux-system > flux-system.yaml

#Coexistence and Cutover

During the transition, Flux v1 and v2 can run side by side on different clusters. After all applications are successfully pulled by v2 and observed to be stable, the cutover is done by stopping v1 and fully moving the GitOps traffic to v2.

#ArgoCD to Flux Migration

#Mapping Concepts

ArgoCD and Flux use different models: ArgoCD is based on an Application that references one source with one destination; Flux separates the source (GitRepository) from the application (Kustomization or HelmRelease). The mapping is roughly as follows:

#CRD Translation

An example of translating an ArgoCD Application to a Flux Kustomization:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: web
  namespace: apps
spec:
  interval: 5m
  path: ./web
  prune: true
  sourceRef:
    kind: GitRepository
    name: apps
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: web
      namespace: apps

#Parallel Testing and Incremental Migration

Build a parallel cluster managed by Flux, test all the applications there without touching the ArgoCD production. Once the results are equivalent, move the applications one by one to the Flux cluster in a low-activity change window.

#Migration Best Practices

• Incremental: move applications in small groups, not all at once. Easier to monitor and roll back.
• Test in non-prod first: every step starts in a non-production environment before touching production.
• Plan the rollback: decide from the start how to return to the old system if a critical failure happens.
• Train the team: hold hands-on sessions before the cutover so operators don't learn while an incident is happening.

#Closing

In this episode you learned migration strategies to FluxCD from various starting points: manual deployments, Helm 2, other GitOps tools, the Flux v1 to v2 move, and mapping ArgoCD concepts to Flux with an incremental approach.

The key takeaways:

• Inventory first: know all the resources to be moved before touching anything.
• Coexistence is a bridge: let the old and new systems run in parallel until the transition is proven stable.
• Move incrementally: small groups, non-prod first, and always compare status between systems.
• Rollback must be planned: document how to return to the old system from day one.
• Train the operators: team readiness determines the cutover's success more than technical readiness.

In episode 34, we enter the final stage before production: production checklist & best practices — making sure HA, RBAC, secrets, monitoring, backup, and DR are ready before your applications launch. See you!