Skip to main content

Migrating from Open-Source Argo CD

The Akuity Platform automates the deployment of the upstream version of Argo CD, but packages it in a unique hybrid architecture that significantly improves performance and scalability. However, the API, CLI, UI, and CRDs will be no different than open-source Argo CD.

The main considerations during a migration to an Argo CD instance on the Akuity Platform will come down to implementation details.


Sign up for a free 14-day trial of the Akuity Platform!


Applications Targeting the in-cluster Destination

When running the open-source Argo CD, it’s common to deploy resources into the same cluster that Argo CD is running in. This is known as the in-cluster destination (or the server URL https://kubernetes.default.svc).

On the Akuity Platform, in-cluster refers to the control plane hosting your Argo CD instance. You can only deploy Application, ApplicationSet, and AppProject resources to this destination (see the Declarative Management).

When migrating to the Akuity Platform, any cluster that Argo CD will manage resources in will be connected by deploying the Akuity Agent into it. This means Applications that were targeting the in-cluster destination to deploy resources other than Application, ApplicationSet, and AppProject, will now need to target a named cluster.

For example, this Application was targeting the in-cluster destination:

kind: Application
name: guestbook
project: default
repoURL: ''
path: guestbook
targetRevision: HEAD
namespace: default
name: in-cluster # <--
automated: {}

While migrating to the Akuity Platform, the cluster was connected using the agent and was given the name my-cluster. So the of the Application will need to be changed from in-cluster to my-cluster.

namespace: default
-- name: in-cluster
++ name: my-cluster

It’s recommended to use the over the destination.server as it provides greater flexibility (since a server URL using an IP address or generated FQDN can change if a cluster is recreated, but the name will remain the same) and improves the readability of the Application destination (the name will match that of the cluster name used when provisioning the Akuity Agent).

Application’s used for the App of Apps pattern (i.e. that deploy other Application resources) can continue to target the in-cluster destination. However, any child Applications that target the in-cluster destination will need to be updated to target the connected cluster by name (or server URL).

Resource Tracking Method

The Akuity Platform takes advantage of the annotation resource tracking method. On first sync of an Application with existing resources, Argo CD will add the annotation and if the original Argo CD instance used the default label or annotation+label methods, it will remove the label.

On the original instance, if it still has the Application and is monitoring those resources, the Application will show as out-of-sync with a diff for the annotation and label.

Resource Tracking Diff

To avoid this, update the original instance to use the annotation resource tracking method prior to switching to the Akuity Platform.

Non-cascading Deletion of Applications

When removing Applications from the original Argo CD instance, it's important to use the non-cascading propagation policy to ensure the Application is deleted without pruning the resources managed by it.

Step-by-Step Guide to an Active-Active Migration

This guide will cover how to do an Active-Active migration from an open-source Argo CD installation to an instance on the Akuity Platform. The goal is to have both instances in the cluster as Applications are moved over incrementally. Then the original Argo CD instance is torn down without any impact to the running workloads.

Your specific implementation of Argo CD may vary from the assumptions of the guide. It's highly recommended to start with the lowest-impact Applications to ensure that there are no unexpected side effects.

To start off, let's assume you have Argo CD running in the argocd namespace of the managed cluster.

% k get deploy -n argocd
argocd-applicationset-controller 1/1 1 1 14d
argocd-dex-server 1/1 1 1 14d
argocd-notifications-controller 1/1 1 1 14d
argocd-redis 1/1 1 1 14d
argocd-repo-server 1/1 1 1 14d
argocd-server 1/1 1 1 14d

After creating an Argo CD instance on the Akuity Platform of the same version as the original installation, install the Akuity Agent into the akuity namespace of the same cluster.


The Akuity Agent is intentionally installed in a separate namespace (akuity) from the Argo CD installation (argocd) because they both create resources with the same names. For example, both will create an argocd-repo-server Deployment.

% k get deploy -n akuity
akuity-agent 2/2 2 2 82s
argocd-application-controller 1/1 1 1 82s
argocd-applicationset-controller 0/0 0 0 82s
argocd-image-updater 0/0 0 0 82s
argocd-notifications-controller 1/1 1 1 82s
argocd-redis 1/1 1 1 81s
argocd-repo-server 2/2 2 2 81s

Now, on the Akuity Platform Argo CD instance, create the same Application as on the original instance. If the original destination was in-cluster, make sure to update the (or destination.server) to reflect the new cluster. At this point, both instances will be monitoring and managing the resources for the Application.

On the original Argo CD instance, delete the Application using the non-cascading propagation policy.

At this point, the Akuity Platform Argo CD instance will manage the Application and it’s resources.