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

Resource	Actions	Why
clusters	get, create, update, delete	Register and deregister tenant clusters and control plane clusters
applications	get, create, update, delete	Create and sync Argo CD Applications across all projects (*/*)

Step 1: Create a connector

Platform UI

1. Click Connectors and select the Argo CD tab.

2. Click .

3. In the Display name field, enter a human-readable name for the connector. The ArgoCD 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, controlled by the authType field. 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:
  authType: "token"
  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:
  authType: "basic"
  server: "https://argocd.example.com"
  username: "<argocd-username>"
  password: "<argocd-password>"
  namespace: "argocd"
  insecure: "false"

Field	Required	Description
authType	Yes	Authentication method: "token" or "basic"
server	Yes	Full URL of the Argo CD API server
token	If authType is "token"	Argo CD API bearer token
username	If authType is "basic"	Argo CD username
password	If authType is "basic"	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
    spec:
      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

To register a control plane cluster with Argo CD, add spec.argoCD to the Cluster object:

apiVersion: management.loft.sh/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  argoCD:
    enabled: true
    connector: argocd-main

Disabling the integration

Disabling the integration removes the cluster from Argo CD and deletes all ArgoCDApplication objects managed by Platform. This applies whether the integration is configured via vcluster.yaml, a VirtualClusterInstance manifest, or a Cluster object. Any applications deployed by the integration will be removed from Argo CD.

Next step

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