Connect to Argo CD

This guide connects vCluster Platform to a self-hosted Argo CD server. At the end you will have a connector that registers tenant clusters and control plane clusters with Argo CD automatically.

For Akuity-managed Argo CD, see Connect to Akuity instead.

Prerequisites

• vCluster Platform running with admin access
• A self-hosted Argo CD server reachable from the Platform namespace

Argo CD API token permissions

The API token you provide in the connector must have the following RBAC permissions. Create a dedicated role in your Argo CD argocd-rbac-cm ConfigMap and generate a token for it:

policy.csv: |
  p, role:vcluster-platform, clusters, get, *, allow
  p, role:vcluster-platform, clusters, create, *, allow
  p, role:vcluster-platform, clusters, update, *, allow
  p, role:vcluster-platform, clusters, delete, *, allow
  p, role:vcluster-platform, applications, get, */*, allow
  p, role:vcluster-platform, applications, create, */*, allow
  p, role:vcluster-platform, applications, update, */*, allow
  p, role:vcluster-platform, applications, delete, */*, allow
  p, role:vcluster-platform, applications, sync, */*, allow

Resource	Actions	Why
clusters	get, create, update, delete	Register and deregister tenant clusters and control plane clusters
applications	get, create, update, delete, sync	Create and sync Argo CD Applications across all projects (*/*). sync is required to stop in-progress sync operations when deleting a tenant cluster with installed apps

Step 1: Create a connector

Platform UI

1. Go to Infrastructure > Connectors and select the Argo CD tab.

2. Click .

3. In the Display name field, enter a human-readable name for the connector. The Argo CD Connector ID is auto-generated from the display name and is used to reference this connector from clusters.

4. In the Server URL field, enter the URL of your Argo CD server.

5. If Argo CD is installed in a namespace other than argocd, update the Argo CD Namespace field.

6. Select an authentication method and fill in the credentials:

   • Authenticate with Argo CD API token: paste your token in the Argo CD API Token field.
   • Authenticate with username / password: fill in Username and Password.

7. Click .

YAML

Argo CD supports two authentication methods. If token is set, the controller uses bearer token authentication. Otherwise it falls back to username and password. Apply the Secret with kubectl apply.

Token

apiVersion: v1
kind: Secret
metadata:
  name: argocd-main
  namespace: loft
  labels:
    loft.sh/connector-type: argocd
type: Opaque
stringData:
  server: "https://argocd.example.com"
  token: "<argocd-api-token>"
  namespace: "argocd"
  insecure: "false"

Basic auth

apiVersion: v1
kind: Secret
metadata:
  name: argocd-main
  namespace: loft
  labels:
    loft.sh/connector-type: argocd
type: Opaque
stringData:
  server: "https://argocd.example.com"
  username: "<argocd-username>"
  password: "<argocd-password>"
  namespace: "argocd"
  insecure: "false"

Field	Required	Description
server	Yes	Full URL of the Argo CD API server
token	If set, bearer token authentication is used	Argo CD API bearer token
username	Required when token is not set	Argo CD username
password	Required when token is not set	Argo CD password
namespace	No	Namespace where Argo CD is installed. Defaults to argocd
insecure	No	Set to "true" to skip TLS verification. Defaults to "false"
caData	No	Base64-encoded CA certificate for custom TLS verification

Step 2: Enable the connector on a cluster

On a tenant cluster

Add the integrations.argoCD block to the tenant cluster's vcluster.yaml. The connector field references the Secret name from Step 1.

integrations:
  argoCD:
    enabled: true
    connector: argocd-main

The connector can also be set directly in the VirtualClusterInstance manifest:

apiVersion: management.loft.sh/v1
kind: VirtualClusterInstance
metadata:
  name: app-dev
  namespace: p-team-a
spec:
  template:
    metadata:
      name: vcluster
    helmRelease:
      values: |
        integrations:
          argoCD:
            enabled: true
            connector: argocd-main

When the VirtualClusterInstance reconciles, Platform registers the tenant cluster with Argo CD using the Platform proxy as the API server endpoint and a scoped access key as the bearer token.

On a control plane cluster

Connecting a cluster to Platform creates a Cluster object for it. Add spec.argoCD to that existing object instead of applying a new manifest.

Find the object's name:

kubectl get clusters.management.loft.sh

When Platform runs in the same cluster it manages, that cluster's object is typically named loft-cluster.

Patch it in place:

kubectl patch clusters.management.loft.sh <cluster-name> --type merge \
  -p '{"spec":{"argoCD":{"enabled":true,"connector":"argocd-main"}}}'

If you manage the object through GitOps, add argoCD alongside its existing fields instead:

apiVersion: management.loft.sh/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  # existing connection method: spec.local, spec.networkPeer, or spec.config
  argoCD:
    enabled: true
    connector: argocd-main

A Cluster manifest fails validation unless it targets an existing object or already sets one of spec.local, spec.networkPeer, or spec.config. Applying only spec.argoCD on its own returns spec.config: Required value: spec.config or spec.local or spec.networkPeer is required.

Disabling the integration

Disabling the integration removes the cluster from Argo CD and deletes every ArgoCDApplication object Platform generated for it from deploy.argoCD.applications, including ones with target: host. This is a cascading delete. Argo CD also removes the Kubernetes resources those Applications were managing, not just the Application registration. This applies whether the integration is configured using vcluster.yaml, a VirtualClusterInstance manifest, or a Cluster object. Standalone ArgoCDApplication objects you created directly, including ones using spec.destination.cluster, keep their CR when you disable the integration alone. Once the destination's connector stops resolving, Platform still deletes the standalone object's remote Argo CD Application the same way, cascading to the workloads it managed, and marks the CR's Synced condition False until the cluster registers again. Re-enabling the integration reconciles it again; you don't have to recreate it. Deleting the tenant cluster itself deletes every ArgoCDApplication targeting it, whether standalone or not, along with the workloads those applications managed.

The Platform UI keeps these two settings in order. The guided vcluster.yaml editor only shows the Applications section once the integration is enabled with a connector, and disabling the integration through the UI prompts you to confirm removing any configured applications, stripping them from deploy.argoCD.applications as part of the disable.

Editing vcluster.yaml directly doesn't enforce that order. Entries in deploy.argoCD.applications stay inert until the integration is enabled with a connector, and disabling directly doesn't remove them from the file. They just stop producing ArgoCDApplication objects until you re-enable the integration.

Next step

With the connector enabled, you can declare Argo CD Applications in your tenant cluster or control plane cluster configuration. See Deploy applications.