Connect to Akuity

This guide connects vCluster Platform to an Akuity-managed Argo CD instance. At the end you will have a connector that registers tenant clusters and control plane clusters with Akuity and provisions the Akuity agent inside each cluster automatically.

For a self-hosted Argo CD server, see Connect to Argo CD instead.

How the Akuity agent works

When you use an Akuity connector, Argo CD does not connect directly to your cluster's API server. Instead, Akuity uses a lightweight agent running inside each registered cluster that establishes an outbound connection to the Akuity control plane. The managed Akuity Argo CD instance communicates with the cluster through that persistent connection.

This means the cluster's API server does not need to be publicly reachable — the agent runs inside the cluster and connects outward — so private clusters are fully supported.

You do not install or manage the agent manually. When a cluster is registered with an Akuity connector, Platform:

1. Calls the Akuity API to register the cluster and retrieve the agent installation manifest.
2. Applies the manifest to the cluster. The agent is installed in its own namespace within the cluster.
3. Stores a hash of the applied manifest in a cluster annotation. If the manifest changes (for example, after an Akuity agent version update), Platform detects the drift and applies the updated manifest automatically.

When the integration is disabled or the connector is changed, Platform removes the agent namespace from the cluster and deregisters it from Akuity.

Prerequisites

• vCluster Platform running with admin access
• An Akuity organization with an active Argo CD instance
• An Akuity API key (see below)

Akuity API key permissions

The Akuity API key must have a custom role with the following permissions on the target Argo CD instance. The built-in Owner role satisfies all of these. For least-privilege access, create a custom role with only the permissions below.

Resource	Permission	Why
Argo CD Cluster	Get	Fetch cluster registration state and agent manifests
Argo CD Cluster	Create	Register new tenant clusters and control plane clusters
Argo CD Cluster	Update	Update cluster registration when connector or access key changes
Argo CD Cluster	Delete	Deregister clusters when the integration is disabled

See the Akuity API key documentation for instructions on creating an API key and attaching a custom role.

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. Enable the Use Akuity API toggle, then fill in:

   • Organization ID: your Akuity organization ID
   • Argo CD Instance: the Argo CD instance ID within your organization
   • API Key ID and API Key Secret: your Akuity API key credentials

5. In the Server URL field, enter the Akuity instance URL. The format is https://<akuityInstanceId>.cd.akuity.cloud/.

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

7. 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.

8. In the Agent Configuration section, select an Agent Size for the cluster workload. Optionally override Replicas and Memory for the argocd-repo-server (see Agent sizing below).

9. Click .

YAML

Set connectorType: "akuity" to use Akuity. Akuity supports two authentication methods for the Argo CD API, controlled by the authType field. Apply the Secret with kubectl apply.

Token

apiVersion: v1
kind: Secret
metadata:
  name: akuity-prod
  namespace: loft
  labels:
    loft.sh/connector-type: argocd
type: Opaque
stringData:
  connectorType: "akuity"
  authType: "token"
  server: "https://<akuity-instance-id>.cd.akuity.cloud/"
  token: "<argocd-api-token>"
  namespace: "argocd"
  insecure: "false"
  akuityOrgId: "<your-org-id>"
  akuityInstanceId: "<your-instance-id>"
  akuityApiKeyId: "<api-key-id>"
  akuityApiKeySecret: "<api-key-secret>"
  akuityAgentSize: "CLUSTER_SIZE_MEDIUM"
  akuityRepoServerReplicas: "1"
  akuityRepoServerMemory: "1Gi"

Basic auth

apiVersion: v1
kind: Secret
metadata:
  name: akuity-prod
  namespace: loft
  labels:
    loft.sh/connector-type: argocd
type: Opaque
stringData:
  connectorType: "akuity"
  authType: "basic"
  server: "https://<akuity-instance-id>.cd.akuity.cloud/"
  username: "<argocd-username>"
  password: "<argocd-password>"
  namespace: "argocd"
  insecure: "false"
  akuityOrgId: "<your-org-id>"
  akuityInstanceId: "<your-instance-id>"
  akuityApiKeyId: "<api-key-id>"
  akuityApiKeySecret: "<api-key-secret>"
  akuityAgentSize: "CLUSTER_SIZE_MEDIUM"
  akuityRepoServerReplicas: "1"
  akuityRepoServerMemory: "1Gi"

Field	Required	Description
connectorType	Yes	Must be "akuity"
authType	Yes	Argo CD authentication method: "token" or "basic"
server	Yes	Akuity instance URL. Format: https://<akuityInstanceId>.cd.akuity.cloud/
token	If authType is "token"	Argo CD API bearer token for the Akuity instance
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"
akuityOrgId	Yes	Akuity organization ID
akuityInstanceId	Yes	Argo CD instance ID within your Akuity organization
akuityApiKeyId	Yes	Akuity API key ID, used to register and manage clusters via the Akuity API
akuityApiKeySecret	Yes	Akuity API key secret
akuityAgentSize	No	Agent size profile: CLUSTER_SIZE_SMALL, CLUSTER_SIZE_MEDIUM (default), or CLUSTER_SIZE_LARGE. See Agent sizing.
akuityRepoServerReplicas	No	Override the argocd-repo-server replica count. See Agent sizing.
akuityRepoServerMemory	No	Override argocd-repo-server memory. Sets both requests and limits. See Agent sizing.

Agent sizing

Three fields in the connector Secret control how the Akuity agent is provisioned inside each registered cluster.

akuityAgentSize

This field is sent to the Akuity API when the cluster is registered and determines the overall resource profile of the agent as defined by Akuity. It is an Akuity-level concept, not a direct Kubernetes resource value — Akuity translates this into the appropriate CPU and memory requests for the agent workloads on its end.

Value	Recommended for
CLUSTER_SIZE_SMALL	Development or low-traffic clusters with few Applications
CLUSTER_SIZE_MEDIUM	General-purpose clusters (default)
CLUSTER_SIZE_LARGE	High-throughput clusters with many Applications or frequent syncs

akuityRepoServerReplicas and akuityRepoServerMemory

These fields let you override specific resource settings on the argocd-repo-server Deployment inside the cluster, independently of the size profile. Platform applies a kustomization patch to the agent manifest before installing it:

• akuityRepoServerReplicas sets spec.replicas on the argocd-repo-server Deployment.
• akuityRepoServerMemory sets both resources.requests.memory and resources.limits.memory to the same value on the argocd-repo-server container. Accepts standard Kubernetes memory quantity strings, for example "1Gi" or "512Mi".

Both fields are optional and independent of akuityAgentSize. Use them when the size profile alone does not give you the control you need over repo server memory or replica count.

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: akuity-prod

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: akuity-prod

When the VirtualClusterInstance reconciles, Platform registers the tenant cluster with Akuity, retrieves the agent manifest, and installs the agent into the cluster.

On a control plane cluster

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

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

Disabling the integration

Disabling the integration removes the cluster from Akuity, uninstalls the agent namespace from the cluster, 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.