What an Argo CD migration involves
A migration to Argo CD usually starts from one of three situations: an existing Flux installation that the team wants to replace, a CI pipeline that runs kubectl apply or helm upgrade commands against clusters, or another GitOps tool that no longer fits the operating model. Each starting point leaves a different amount of state behind. Flux-managed resources carry its labels and ownership metadata, scripted deploys often leave resources with no owner at all, and a CI pipeline may hold cluster credentials that the new design should stop using. Inventory these before choosing a cutover method.
Several things change. Argo CD takes ownership of live resources, so each Application must be pointed at the correct Git path and sync policy, and resources must be adopted without being recreated. Repository layout changes as well: teams commonly separate application source from environment configuration, and this decides who can approve what. Who triggers syncs also moves. In a scripted model, the pipeline pushes; in Argo CD, the controller pulls from Git and syncs on a policy that someone has to set, review and document.
Several things stay the same. The clusters, namespaces, workloads and their data remain where they are, and a well-run migration should not restart production services just to change the deployment tool. Confirm this with the owners of each workload before the work starts, including any Helm releases whose values files will move into Git.
In-house or partner is mostly a question of experience and scale. Teams that have already run Argo CD and Kubernetes in production often perform the cutover themselves, with a staged plan. Teams with many clusters, mixed tooling across Flux and scripts, or audit obligations for change history often bring in a partner for planning, adoption checks and a staged cutover. Ask any partner to show how they handle resource ownership during adoption and how each stage is verified and rolled back.
What the work includes
A fixed-scope migration is usually split into a small set of work packages, each with written deliverables. The list below shows what the migration covers and what you should receive at the end.
Current delivery inventory
We map every tool, pipeline, script, cluster, namespace and secret path that deploys workloads today, including Flux controllers, CI jobs running kubectl or Helm, and scheduled scripts. The output is an inventory that records owners, drift, manual steps and where credentials live, so cutover decisions rest on evidence rather than memory.
Target repository structure
We design the Git layout Argo CD will read, covering how environments, clusters, Helm charts, Kustomize overlays and plain manifests are separated. The design also states who may merge to each path and how repositories are referenced, since Argo CD 3.0 requires repository definitions as Kubernetes Secrets rather than argocd-cm entries.
Argo CD projects and RBAC
We define AppProjects that limit source repositories, destination clusters and namespaces for each team, then map group claims to RBAC roles. Confirm the target identity provider and group names early, because Dex-based RBAC in 3.0 keys on the federated_claims.user_id claim and update and delete rights apply only to the Application itself.
Adopting existing resources
We bring live workloads under Argo CD management without recreating them, which means matching existing object names, labels and ownership before the first sync. Annotation-based resource tracking is the default in current releases, so we test how it interacts with labels that Flux or scripts already set, and remove conflicting ownership markers in a planned order.
Cutover runbooks and rollback
We write per-application runbooks that define the freeze window, the order of Application syncs, the checks that confirm health and the exact steps to hand control back to the previous tool. Rollback is rehearsed on a non-production cluster, and the runbook names who decides to roll back and the evidence that triggers it.
Handover and operating notes
At close, you receive the inventory, target design, migrated Application definitions, cutover runbooks and operating notes covering upgrade cadence, admin account handling and how to add a cluster or repository. Confirm with us which of these are versioned in your Git repository and which are delivered as documents, so your team can maintain them after the engagement ends.
What drives cost and duration
Each row names one factor that moves the effort of an Argo CD migration up or down, why it matters, and what to do to keep it contained.
| Driver | Why it moves cost up | How to reduce it |
|---|---|---|
| Clusters and environments | Each cluster needs its own destination, credentials, network path and cutover window, and each environment repeats the adoption and verification work. | Start with one non-production cluster as the pilot, then group production clusters with similar configuration into the same waves. |
| Applications and Helm or Kustomize variants | Every application, overlay and Helm values combination must be mapped to an Argo CD Application and checked for a clean sync with no unexpected drift. | Inventory applications first, retire unused ones, and consolidate near-identical variants into shared bases or ApplicationSets. |
| Delivery tools and scripts to retire | Each Flux object, Jenkins job or deploy script that still writes to the cluster can fight Argo CD, so each must be found, replaced or disabled. | List every pipeline stage and script that calls kubectl, helm or flux, then retire them in the same wave as the application they deploy. |
| Repository history and secret locations | Mixed repositories, rewritten histories and secrets kept in CI variables or old manifests slow the repository restructuring and add review steps before anything is moved. | Decide the target repository layout early, keep history rather than rewriting it where possible, and confirm where each secret lives before moving any manifest. |
| Teams that own deployments | Each owning team needs its own project boundaries, review of its manifests and agreement on cutover dates, and coordination grows with the number of teams. | Name one owner per application and agree the cutover order with those owners before the pilot begins. |
| SSO and RBAC mapping | Existing group names, pipeline permissions and local accounts must be translated into Argo CD roles and tested, and a mismatch can block deployments or widen access. | Export current access from the identity provider and the old tools, map groups to roles in a short table, and test each role before cutover. |
| Compliance evidence needs | Assessors may expect records of who approved each change, how deployments were traced before and after cutover, and how the new access model was reviewed. | Ask your assessor which records they need, keep them from the pilot onward, and collect them as part of the cutover rather than afterward. |
| Existing Argo CD version | A new install needs full setup, while an Argo CD instance already in use may need a version upgrade and a review of its settings before any migration work. | Confirm the running version and its patch level with your team, and check whether it is among the three minor versions that still receive patches. |
Project phases and outputs
The sequence moves each workload from its current deployment tool to Argo CD in verified stages, so every application ends with one reconciler and a documented handover.
Inventory existing delivery and cluster state
DeployOpen maps every workload, the tool that deploys it, its Helm releases, Kustomize overlays, Flux objects, Jenkins jobs and scripts, and the credentials each one uses. The client receives an inventory register and a list of conflicts, such as two tools reconciling the same object. The step closes when each workload has one named owning tool and an accountable team.
Design target repository layout and projects
The team agrees the repository structure, whether app-of-apps or ApplicationSets, and the Argo CD Projects that bound source repositories, destination clusters and namespaces. Roles are mapped to delivery teams, and the default sync policy is set so automated sync applies only where the client has agreed. The client receives an approved design document and a repository skeleton.
Pilot adoption on a non-critical application
The team selects a low-risk application and commits manifests that match its live objects, then creates the Application with automated sync disabled. Before any sync, the team runs a diff, confirms Argo CD has written its tracking annotation, and confirms the old controller no longer reconciles those objects. Sync is enabled only when the diff is empty. The client receives a pilot runbook and evidence of the check.
Migrate clusters and teams in stages
Applications move in waves grouped by cluster or owning team, each using the adoption runbook from the pilot. Every wave has a documented rollback path and a diff review signed off by the application owner before sync is enabled. The client receives the wave plan and an adoption record for each application, and a wave closes when its applications report Synced and Healthy.
Run old and new tools in parallel
For each application, the old tool is disabled only after the Argo CD diff is clean, for example by suspending a Flux Kustomization or removing a Jenkins deploy stage. The rollback path stays available for the period the client agrees. The client receives a cutover log per application, and the step closes when Argo CD is the only reconciler for every migrated workload.
Decommission old controllers and scripts
The team removes retired Flux controllers, CI deploy jobs, kubectl and Helm scripts, deploy keys and stale service credentials, after checking that nothing still references them. Access is revoked and the removals are recorded. The client receives a decommissioning record and a list of revoked credentials, and the step closes when no old controller runs in the cluster.
Hand over runbooks and operating model
DeployOpen delivers runbooks for syncs, rollbacks, RBAC changes, repository contributions, backups and upgrades within the supported Argo CD minor versions. The client's team performs a supervised sync and rollback before handover is accepted. The client receives the documentation set and a handover record, and the step closes when the client team completes those tasks without assistance.
What stays in-house and what to outsource
This table compares migration work that application owners and the business usually keep, with work teams often outsource, and lists the skills each part needs so you can split the work deliberately.
| Migration part | Usually in-house or outsourced | Skills needed | Notes for the decision |
|---|---|---|---|
| Inventory of Flux, Jenkins and scripted deploys | Often outsourced | Kubernetes, Flux or Jenkins pipeline knowledge, shell scripting, change management | Needs a complete list of clusters, namespaces, scripts and credentials; partners can accelerate discovery but owners must confirm each entry. |
| Target Git repository design | Often outsourced | Git branching, Kustomize or Helm, Argo CD ApplicationSets, Kubernetes namespaces | Layout choices such as app-of-apps or ApplicationSets affect every later team; agree the design before anyone migrates workloads. |
| Argo CD projects and RBAC mapping | Shared | Argo CD RBAC, Kubernetes RBAC, identity provider group management | Platform engineers usually design the roles; application owners confirm which teams may sync which applications. |
| Adopting existing resources into Argo CD | Often outsourced | Kubernetes manifests, Helm or Kustomize, Argo CD sync and tracking settings | Test adoption in a non-production cluster first, since tracking changes can alter how resources are linked to applications. |
| Adoption tooling and migration scripts | Often outsourced | Scripting, Kubernetes API, Git automation | Scripts should be reviewed and retired after cutover, and the team should own them once the engagement ends. |
| Runbook drafting | Often outsourced, reviewed in-house | Operations writing, Argo CD operations, incident response | Drafts are a starting point; on-call engineers must rehearse each procedure before they rely on it. |
| Validating workloads per application | In-house | Application knowledge, Helm values, health checks, test suites | Only application owners know expected behavior, dependencies and acceptable downtime for their services. |
| Approving cutover windows and business sign-off | In-house | Change management, risk acceptance, service ownership | Accountable owners decide timing and accept risk; a partner can supply evidence and rollback plans for their review. |
What goes wrong and how to prevent it
Most failures in an Argo CD migration come from running two delivery tools at once, from ownership metadata that does not match, and from Argo CD 3.0 settings that carry over from older installs. Each risk below has a check to run before cutover.
Two controllers managing the same resources
During a parallel run, Flux or a CI script and Argo CD can both reconcile the same Deployment, Service or ConfigMap, and each reverts the other's changes. Assign every namespace and application to one controller before the first sync, and confirm in Git which tool owns each path. Watch the Argo CD diff view for fields that keep flipping between two values.
Pruning resources Argo CD does not own
Argo CD 3.0 tracks resources by annotation by default, but objects applied by Flux or scripts may carry only older labels. If Argo CD does not recognize them as its own and automated prune is enabled, a sync can delete live workloads. Keep prune off for migrated applications until a dry-run diff shows only expected changes.
Plain secrets committed to Git
Restructuring repositories often moves Kubernetes Secret manifests or Helm values containing credentials into the GitOps repository. Git history keeps those values even after the file is deleted. Scan the migrated repositories before the first commit, move credentials to an encrypted or externally sourced secrets approach, and rotate anything that was exposed.
Untrusted content in the repo-server
The repo-server runs Helm and Kustomize on repository content, so a chart, overlay or values file from an unvetted source can execute work or reach files outside its intended path. Migrated repositories often pull in vendored charts from third parties. Restrict repository sources to an approved list and confirm which out-of-tree file access controls your version provides.
Argo CD 3.0 repository and RBAC changes
Argo CD 3.0 removed repository definitions from argocd-cm, so repositories must be Kubernetes Secrets, and import scripts that write to the ConfigMap can leave repositories unreachable. RBAC also changed: update and delete apply only to the application itself, logs need an explicit logs get permission, and Dex-based rules use the federated_claims.user_id claim. Test each team's role after import.
HA sizing below three nodes
The Argo CD high availability manifests need at least three nodes because of pod anti-affinity rules. A migration onto a smaller cluster can leave replicas pending while the installation appears to work. Confirm node count and spread before the cutover plan is approved, and note that IPv6-only clusters are not supported.
How the work differs by starting point
Flux already keeps desired state in Git, so the scope is mapping its objects onto Argo CD Applications rather than rebuilding delivery from nothing. The main work is inventory and reconciliation behavior.
- Source objects: map each GitRepository, HelmRepository and OCI source to an Argo CD repository definition and its credentials.
- Workload objects: convert Kustomization and HelmRelease resources to Application or ApplicationSet definitions, keeping paths and values files identical.
- Ordering and pruning: record each dependsOn chain and prune setting, then confirm how Argo CD sync waves and prune behavior will reproduce them.
- Reconciliation timing: compare Flux intervals with Argo CD sync and refresh settings, so the cutover does not create surprise sync storms.
- Ownership handover: pause Flux per namespace, adopt resources, and remove the Flux controllers only after both tools show a clean state.
Pipelines that run kubectl or Helm imperatively keep their state in job history and runner logs, not in Git. The migration converts each pipeline step into declared state that Argo CD reconciles.
- Imperative steps: list every kubectl apply, patch and helm upgrade call and decide which becomes a manifest, a Helm values file or a Kustomize overlay.
- Pipeline split: keep image build and test in CI, and move only deployment into Git-driven sync, so CI no longer holds cluster credentials.
- Drift from manual runs: check for hotfixes applied outside the pipeline, since Argo CD will revert them unless they are committed first.
- Secrets paths: replace variables injected at deploy time with a secrets mechanism your team can reference from Git.
- Pipeline retirement: run both paths in parallel for a defined period and disable the old deploy stage only after sync results match.
Scripted deploys with no state record leave the team unsure what is actually running. Before any manifest is written, the work starts with an inventory built from the live clusters.
- Live inventory: list namespaces, workloads, services, ConfigMaps, Secrets references, CRDs and Helm releases on each cluster, and record their owners.
- Ownership decisions: classify each item as managed by Argo CD, managed by another tool, or to be retired, since some resources may have no owner at all.
- Repository design: create the Git layout from the inventory, not from the scripts, so the repository reflects what runs today.
- Adoption risk: adopting an existing resource can change its tracking metadata, so test adoption in a non-production cluster first.
- Evidence: keep the inventory and each sync result as the baseline for later drift checks and audit questions.
Teams on an older Argo CD version are upgrading within the same tool, so the risk lies in breaking changes and in leaving the supported range. Upgrades are staged rather than skipped.
- Support window: check the current minor releases, since only the three most recent minor versions receive patch releases, and plan a path into that range.
- Breaking changes: for 2.14 to 3.0, review that update and delete RBAC now applies only to the application itself and that logs access needs an explicit logs, get permission.
- Repository configuration: move any repositories defined in argocd-cm into Kubernetes Secrets, because 3.0 removed that configuration.
- Identity claims: update Dex-based RBAC that relies on older claims to use federated_claims.user_id.
- Tracking mode: annotation-based resource tracking is the default in 3.0, so confirm how existing label-tracked resources will behave before upgrading production.
In air-gapped or private registry environments, the migration depends on what the cluster can reach. Every Git source, chart and image Argo CD needs must be mirrored inside the network before cutover.
- Mirrored sources: list each Git repository, Helm chart repository, OCI artifact and container image referenced by manifests, and host it on internal infrastructure.
- Argo CD images: mirror the Argo CD component images and any tools the repo-server uses, since it runs Helm and Kustomize on repository content.
- Update path: plan how approved releases and patches are imported, so the internal mirror tracks the supported minor releases.
- Network policy: confirm which controllers, the repo-server and external identity providers need egress, and document any exceptions.
- Verification: test sync from the private mirror in a staging enclave before moving production sources.
What you need to provide
Before the migration starts, you need to give the implementation team read access to everything that currently delivers to your clusters: Flux resources or the Git repositories they reconcile, CI pipeline definitions, kubectl and Helm scripts, and the cluster configurations they target. Without the scripts, the team cannot tell which resources are deployed by hand, which are created by a CronJob or a pipeline stage, and which are managed by a controller that must be paused. Each application and each cluster also needs a named owner who can answer questions about expected state, approve the cutover and accept rollback decisions.
Three decisions should be made before any work begins: the repository layout (monorepo, per-team repositories or a hybrid), the tenancy model that maps teams to Argo CD projects, and the identity provider that Argo CD will use for single sign-on. Provide a test or staging cluster for the pilot, and confirm that its network path to your Git hosts and container registries matches production, since a pilot on a different network path hides real failures.
Agree on change windows with the people who run production change control. Confirm internally whether your change management policy requires a change record for each cutover step, whether adopting existing resources counts as a change, and whether any compliance evidence (for example, records of approved configuration changes) must be retained. These requirements are yours to confirm, not assumptions the team should make on your behalf.
Secret handling and access changes need named approvers from your security function before work starts. Moving repository credentials and cluster credentials into Argo CD, and changing who can sync or delete applications, both affect your access model. Ask your security lead to approve the secret storage approach and the RBAC changes in writing, and confirm who signs off on any change to admin access or service account permissions.
Frequently asked questions
Can our team migrate from Flux or Jenkins to Argo CD without outside help?
Yes, many teams do, provided they have someone who understands Kubernetes manifests, Git repository layout and their current delivery pipeline well enough to plan the cutover. Argo CD is licensed under Apache-2.0 and the project itself has no paid edition, so the software is not the barrier. The harder parts are usually adopting resources that already exist without triggering unwanted changes, restructuring repositories, and running two delivery tools side by side during a staged move. Ask whether your team has done a cutover like this before and who will own the rollback plan.
What drives the cost and effort of an Argo CD migration?
The main drivers are the number of clusters and applications, how far the current repositories and secrets handling differ from the layout Argo CD expects, how many teams and access rules are involved, and whether Flux, Jenkins scripts or Helm wrappers hold delivery logic that must be re-expressed. Cost is mostly people time: discovery, repository design, pilot cutover, staged migration and knowledge transfer. Ask for a fixed-scope quote that lists the clusters, applications and environments in scope, the deliverables for each phase, and what your team must supply. DeployOpen does not publish prices, and figures come only from a written scope.
How long does a migration take, and what sets the timeline?
Duration depends on scope rather than on a standard period. The timeline is set by the number of clusters and applications, the amount of inventory and dependency mapping needed, the readiness of your identity and access model, and how many change windows your organization allows for cutover. Teams with a small, well-documented estate and a clear target repository layout generally move faster than those with many undocumented scripts. Any specific duration will appear in the written scope and timeline agreed before work starts, and you should ask for it there.
Will existing workloads restart when we adopt them into Argo CD?
It depends on how the resources are adopted and how the manifests differ from what is running, so it should be checked before any cutover. Argo CD tracks resources, and the 2.14 to 3.0 upgrade notes state that annotation-based resource tracking is now the default, which changes how existing objects are recognized. Differences in labels, selectors or templates can cause rollouts, and a mismatch in tracking can cause Argo CD to prune or modify objects it did not previously manage. A good plan runs diff reviews in a non-production cluster, sets sync policies deliberately during adoption, and defines a rollback path before the first live sync.
Do we have to remove Flux or Jenkins on the first day?
No. A staged cutover normally runs old and new delivery paths side by side for a period, with each application or cluster moved only after its manifests and sync behavior have been verified. The key rule is that two controllers must not manage the same resources at once, so ownership of each application must be assigned clearly during the transition. Decommissioning Flux or the Jenkins jobs should happen after the last migrated application has run cleanly through its normal change process. Ask your provider to show the ownership map and the criteria for retiring each old path.
What must our team provide during the migration?
Your team typically supplies access to the clusters and Git repositories in scope, an inventory of current deployments and their owners, the identity provider details needed for SSO, and people who can approve repository changes and cutover windows. You will also need a named technical owner who can make decisions about manifest structure and rollback. Test clusters that mirror production are strongly recommended. Confirm the full list of inputs in the written scope, since responsibilities for secrets, network access and change approval differ between organizations.
How DeployOpen delivers this service
DeployOpen plans and carries out the move from Flux, CI-driven kubectl or Helm scripts, or another GitOps tool to Argo CD inside clusters and Git hosting you control. The work is scoped in writing first, then cut over in stages so each application's ownership and rollback path is clear before it moves.
How we scope
- Inventory every cluster, namespace, Helm release and script that currently applies manifests, and record who owns each one.
- Agree in writing which applications adopt existing resources and which are rebuilt, with the cutover order and rollback steps for each.
- Engagements are fixed-scope, so the written scope fixes deliverables and timelines before any migration work starts.
How we build
- Restructure the Git repositories into the layout Argo CD will read, separating app manifests from environment configuration.
- Adopt live resources into Argo CD Applications in a non-production cluster first, then confirm sync status and drift before moving production.
- Test the staged cutover, including pausing the old tool or pipeline so two controllers never fight over the same objects.
How we hand over
- Deliver the repository structure, Application and project definitions, and the cutover runbook with each stage's rollback steps.
- Document how repository credentials are stored as Kubernetes Secrets, and which old pipelines, controllers and scripts were retired.
- Walk your platform and application teams through daily sync, drift review and how new applications are onboarded.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Argo CD patch and minor releases follow a quarterly cadence with patch support for the three most recent minor versions, so an upgrade plan keeps you inside that window.
- Confirm with us in the quote which upgrade and test work sits in the initial scope and which moves to a retainer.
