Migrate Self-Managed ArgoCD to ACK One GitOps-Container Service for Kubernetes(ACK)-阿里云帮助中心

This topic describes how to migrate a self-managed ArgoCD master cluster to ACK One.

Use onectl to migrate cluster Secrets, repository Secrets, and applications from a self-managed Argo CD master cluster to ACK One GitOps. The migration follows a three-stage sequence — clusters, then repositories, then applications — and runs alongside your existing Argo CD installation so live workloads remain unaffected throughout.

onectl retrieves kubeconfig files for both the Fleet instance and the Argo CD master cluster (identified by cluster ID) and saves them to the ~/.onectl/ directory. It then migrates cluster Secrets, repository Secrets, and applications to the target ACK One Fleet instance.

Before you start:

If the Argo CD master cluster is an on-premises cluster, connect it to a registered cluster first. For more information, see Create a registered cluster.
If you modified the ConfigMap of the Argo CD master cluster, update the corresponding configurations in the ACK One Fleet instance before migration.
If you added custom labels to cluster Secrets, configure those labels in the Argo CD UI in ACK One GitOps after migrating the cluster.
After migrating applications with onectl, delete them from the self-managed Argo CD master cluster using non-cascading deletion. This disconnects them from their current cluster without removing the underlying Kubernetes resources, allowing ACK One GitOps to take over management.

Migration overview

The migration proceeds through four steps:

Configure a RAM user for onectl — grant the required permissions and configure credentials.
Migrate clusters — attach clusters to the ACK One Fleet instance.
Migrate Git repository configurations — transfer repository Secrets to ACK One GitOps.
Migrate applications — move all or selected applications, then clean up from the source cluster.

Prerequisites

Before you begin, ensure that you have:

Activated ACK One with the multi-cluster management feature enabled. For more information, see Enable Fleet management.
Connected any on-premises cluster to a registered cluster. For more information, see Create a registered cluster.
Enabled GitOps for the Fleet instance and logged in to Argo CD using the Argo CD CLI. For more information, see Getting started with GitOps.
Obtained the Fleet ID and Cluster ID.
Installed the latest version of onectl.

Step 1: Configure a RAM user for onectl

onectl uses the AccessKey ID and AccessKey secret of a Resource Access Management (RAM) user to manage cloud resources. Grant the following permissions to the RAM user.

Grant the AliyunAdcpFullAccess permission. For more information, see Attach a system permission policy to a RAM user or RAM role.

Grant the AliyunCSReadOnly permission, or create a custom ACK policy with the following actions:

{
    "Action": [
        "cs:DescribeTemplates",
        "cs:DescribeTemplateAttribute",
        "cs:DescribeClusterUserKubeconfig"
    ],
    "Resource": [
        "*"
    ],
    "Effect": "Allow"
}

Grant administrator permissions to the self-managed Argo CD cluster. For more information, see Use RBAC to manage the operation permissions on resources in a cluster.

Run the following command and enter the AccessKey ID and AccessKey secret when prompted:

onectl configure

Expected output:

Configuring profile default ...
Access Key Id [*********************NaY]:
Access Key Secret [***************************HUd]:
Ram Username []:
Default Kubeconfig Path (default is ~/.kube/config) []:
Saving profile[default] ...
Done.

Step 2: Migrate clusters

Set the Fleet instance ID and Argo CD master cluster ID as environment variables. onectl uses these to retrieve and cache the corresponding kubeconfig files in the ~/.onectl/ directory.
```
export ACKONE_HUB_CLUSTER_ID=ccc47ca148d0147519f229bba********
export ARGOCD_CLUSTER_ID=ce4bb2004bb0e409eaa4c593d********
```
Migrate clusters using one of the following methods: Method 1: Use the ACK One console Associate the cluster (non-master cluster) of the self-managed Argo CD environment with the ACK One Fleet instance in the ACK One console. Method 2: Use onectl
1. Add the ack_cluster_id: <your ack cluster id> label to all cluster Secrets in the self-managed Argo CD master cluster. Use the Argo CD UI or kubectl to edit the Secrets.
2. Run the following command: ``shell onectl migrate clusters -n argocd `` > Note: If you added labels or annotations to cluster Secrets in the self-managed Argo CD environment, configure them in the Argo CD UI in ACK One GitOps after completing this step.

Step 3: Migrate Git repository configurations

Run the following command to migrate repository Secrets from the master cluster to ACK One GitOps:
```
onectl migrate repos -n argocd
```

Check migration status for all resources or a specific resource type:

# Query the status of all resource types
onectl migrate status -nargocd

# Query the status of a specific resource type
onectl migrate status clusters -nargocd
onectl migrate status repos -nargocd
onectl migrate status apps -nargocd

Expected output:

#################### Clusters Status ####################
All 1 clusters were attached successfully to ACK One ccc47****** !
CLUSTER       STATE    MESSAGE
ce4b******    Succeed

#################### Repositories Status ####################
All 1 repos were migrated successfully to ACK One ccc47****** !
STATE    REPO                                                        TYPE  NAME              MESSAGE
Succeed  https://github.com/AliyunContainerService/gitops-demo.git  git

#################### Applications Status ####################
-------------------- Git/Helm Applications --------------------
Total 'Git/Helm' type applications: 1, success to migrate: 0, pending to migrate: 1
STATE    NAME       NAMESPACE  CLUSTER  STATUS  HEALTH  REPO  PATH  TARGET  MESSAGE
Pending  app-git-2  argocd                                                  application has not been migrated to ACK One ccc47******

-------------------- Template Applications --------------------
STATE    NAME            NAMESPACE  TEMPLATEID                            TEMPLATEPATH  MESSAGE

Step 4: Migrate applications

Migrate all applications

Run the following command to migrate all applications at once:

onectl migrate apps -n argocd --all

Expected output:

Applications in source cluster (ArgoCD or AppCenter cluster):
NAME            NAMESPACE  TYPE      TEMPLATEID
app-git-2       argocd     Git/Helm
will be migrated to ACK One ccc47******. Please checking the source cluster and ACK One cluster. Are you sure to migrate the Applications?  [Y/n] y

Total 1 applications will be migrated to ACK One ccc47****** ...
-------------------- Git/Helm Applications --------------------
Application argocd/app-git-2 was migrated succeessfully.
All 1 'Git/Helm' type applications has been migrated successfully o ACK One ccc47******.
STATE    NAME       NAMESPACE  CLUSTER                     STATUS  HEALTH   REPO                                     PATH                        TARGET  MESSAGE
Succeed  app-git-2  argocd     https://172.16.**.**:6443  Synced  Healthy  git@github.com:**/gitops-demo.git  manifests/helm/echo-server  main

-------------------- Template Applications --------------------
No 'Template' type applications need to be migrated.

Migrate selected applications

To migrate one or more specific applications, run:

onectl migrate apps ${app1Name} -n argocd
# Replace ${app1Name} with the name of the application to migrate.

Expected output:

Applications in source cluster (ArgoCD or AppCenter cluster):
NAME       NAMESPACE  TYPE      TEMPLATEID
app-git-2  argocd     Git/Helm
will be migrated to ACK One ccc47******. Please checking the source cluster and ACK One cluster. Are you sure to migrate the Applications?  [Y/n] y

Total 1 applications will be migrated to ACK One ccc47****** ...
-------------------- Git/Helm Applications --------------------
Application argocd/app-git-2 was migrated succeessfully.
All 1 'Git/Helm' type applications has been migrated successfully o ACK One ccc47ca148d0147519f229bbaea2963b6.
STATE    NAME       NAMESPACE  CLUSTER                     STATUS  HEALTH   REPO                                     PATH                        TARGET  MESSAGE
Succeed  app-git-2  argocd     https://172.16.**.**:6443   Synced  Healthy  git@github.com:**/gitops-demo.git  manifests/helm/echo-server  main

-------------------- Template Applications --------------------
No 'Template' type applications need to be migrated.

Remove applications from the source cluster

After confirming that applications are running correctly in ACK One GitOps, remove them from the self-managed Argo CD master cluster using non-cascading deletion.

Warning

Always include --cascade=false. Without it, Kubernetes deletes the resources managed by the application, which affects your running workloads.

kubectl --kubeconfig ${ARGOCD_CLUSTER_KUBECONFIG_PATH} delete app ${appName} -n argocd --cascade=false

FAQ

The CONNECTION STATUS of a repository added to ACK One GitOps shows Failed

The most likely cause is a network connectivity issue between the ACK One Fleet instance and the repository host. Connect to the ACK One Fleet instance and check the logs:

kubectl -nargocd get pod

kubectl -nargocd logs argocd-server-xx -c argocd-repo-server

If the logs contain context deadline exceeded (Client.Timeout exceeded while awaiting headers), the Fleet instance cannot reach the repository over the Internet. Verify that an Internet NAT gateway is configured in the virtual private cloud (VPC) used by the Fleet instance:

Log in to the ACK One console. In the left-side navigation pane, choose Fleet > Fleet Information.
Click the Basic Information tab. Find the VPC field and click the link to open the VPC details page.
On the VPC page, click the Resource Management tab and check the Access to Internet section.

What containers are included in argocd-server?

Container name	Description
`argocd-server`	The API server for Argo CD. Exposes APIs to the web UI, CLI, and CI/CD systems.
`argocd-application-controller`	A Kubernetes controller that coordinates application and project resources and syncs application state from the Git repository to the cluster.
`argocd-applicationset-controller`	Coordinates ApplicationSets across clusters. An ApplicationSet creates and deploys applications to multiple clusters.
`argocd-repo-server`	Interacts with Git repositories to generate and return Kubernetes manifests.
`redis`	Provides a caching layer for Argo CD to reduce requests to the Kubernetes API server and Git repository server.
`dex`	Handles authentication with external OpenID Connect (OIDC) providers. You can also use other tools.
`argocd-image-updater`	Detects changes to container images for Kubernetes workloads managed by Argo CD (such as Deployments) and automatically updates them to the latest version.