Cluster API - Argo CD

Overview

The Cluster Service API manages Kubernetes cluster configurations. Clusters represent deployment targets for Applications and must be registered with Argo CD before use. Base Path: /api/v1/clusters gRPC Service: cluster.ClusterService

Cluster Resource

A Cluster represents a Kubernetes cluster that can be used as an Application destination.

Cluster Spec

string

required

Kubernetes API server URL

server: https://kubernetes.default.svc  # In-cluster
server: https://1.2.3.4:6443           # External cluster

string

Cluster name (unique identifier, alternative to server)

name: prod-us-east-1

ClusterConfig

required

Authentication and connection configuration

Show ClusterConfig fields

string

Bearer token for authentication

TLSClientConfig

TLS certificate configuration

insecure: Skip TLS verification
caData: Base64-encoded CA certificate
certData: Base64-encoded client certificate
keyData: Base64-encoded client key

AWSAuthConfig

AWS IAM authentication configuration

ExecProviderConfig

External credential provider configuration

string[]

Allowed namespaces (empty = all namespaces)

boolean

Whether Argo CD can manage cluster-scoped resources

string

Project that owns this cluster

map[string]string

Labels for cluster selection in ApplicationSets

map[string]string

Cluster annotations

Example Cluster

apiVersion: v1
kind: Secret
metadata:
  name: prod-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: prod-us-east-1
  server: https://prod-cluster.example.com
  config: |
    {
      "bearerToken": "<token>",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64-ca-cert>"
      }
    }
  namespaces: production,staging
  clusterResources: "true"
  project: production
data:
  labels: |
    env: production
    region: us-east-1

API Operations

List Clusters

Retrieve a list of registered clusters.

GET /api/v1/clusters

string

Filter by server URL

string

Filter by cluster name

curl https://argocd-server/api/v1/clusters \
  -H "Authorization: Bearer $TOKEN"

import clusterpkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/cluster"

clusterClient := clusterpkg.NewClusterServiceClient(conn)
clusters, err := clusterClient.List(ctx, &clusterpkg.ClusterQuery{})

import requests

response = requests.get(
    "https://argocd-server/api/v1/clusters",
    headers={"Authorization": f"Bearer {token}"}
)
clusters = response.json()

Response:

{
  "items": [
    {
      "server": "https://kubernetes.default.svc",
      "name": "in-cluster",
      "config": {
        "tlsClientConfig": {
          "insecure": false
        }
      },
      "connectionState": {
        "status": "Successful",
        "message": "cluster is reachable"
      },
      "serverVersion": "1.28",
      "info": {
        "serverVersion": "1.28.3",
        "applicationsCount": 5
      }
    }
  ]
}

Get Cluster

Retrieve a specific cluster by server URL or name.

GET /api/v1/clusters/{id.value}

string

required

Cluster server URL or name (URL-encoded)

string

Identifier type: “server” (default) or “name”

SERVER=$(echo -n "https://kubernetes.default.svc" | jq -sRr @uri)
curl "https://argocd-server/api/v1/clusters/${SERVER}" \
  -H "Authorization: Bearer $TOKEN"

curl "https://argocd-server/api/v1/clusters/prod-us-east-1?id.type=name" \
  -H "Authorization: Bearer $TOKEN"

cluster, err := clusterClient.Get(ctx, &clusterpkg.ClusterQuery{
    Id: &clusterpkg.ClusterID{
        Type:  "name",
        Value: "prod-us-east-1",
    },
})

Create Cluster

POST /api/v1/clusters

Cluster

required

Complete Cluster configuration

boolean

Update if already exists (default: false)

curl -X POST https://argocd-server/api/v1/clusters \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "https://prod-cluster.example.com",
    "name": "prod-us-east-1",
    "config": {
      "bearerToken": "eyJhbGc...",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "LS0tLS1CRUdJTi..."
      }
    },
    "namespaces": ["production", "staging"],
    "labels": {
      "env": "production",
      "region": "us-east-1"
    }
  }'

cluster, err := clusterClient.Create(ctx, &clusterpkg.ClusterCreateRequest{
    Cluster: &v1alpha1.Cluster{
        Server: "https://prod-cluster.example.com",
        Name:   "prod-us-east-1",
        Config: v1alpha1.ClusterConfig{
            BearerToken: "eyJhbGc...",
            TLSClientConfig: v1alpha1.TLSClientConfig{
                Insecure: false,
                CAData:   []byte("-----BEGIN CERTIFICATE-----..."),
            },
        },
        Namespaces: []string{"production", "staging"},
        Labels: map[string]string{
            "env":    "production",
            "region": "us-east-1",
        },
    },
    Upsert: false,
})

# Using argocd CLI to add cluster from kubeconfig
argocd cluster add prod-context \
  --name prod-us-east-1 \
  --label env=production \
  --label region=us-east-1

Update Cluster

Update an existing cluster configuration.

PUT /api/v1/clusters/{id.value}

string

required

Cluster server URL or name (URL-encoded)

Cluster

required

Updated Cluster configuration

string[]

List of fields to update (empty = update all)

Example:

curl -X PUT "https://argocd-server/api/v1/clusters/prod-us-east-1?id.type=name" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "cluster": {
      "server": "https://prod-cluster.example.com",
      "name": "prod-us-east-1",
      "labels": {
        "env": "production",
        "region": "us-east-1",
        "tier": "critical"
      }
    },
    "updatedFields": ["labels"]
  }'

Delete Cluster

Remove a cluster from Argo CD.

DELETE /api/v1/clusters/{id.value}

string

required

Cluster server URL or name (URL-encoded)

string

Identifier type: “server” or “name”

Deleting a cluster does not affect the actual Kubernetes cluster, only Argo CD’s registration of it. Applications deployed to the cluster will remain.

curl -X DELETE "https://argocd-server/api/v1/clusters/prod-us-east-1?id.type=name" \
  -H "Authorization: Bearer $TOKEN"

_, err := clusterClient.Delete(ctx, &clusterpkg.ClusterQuery{
    Id: &clusterpkg.ClusterID{
        Type:  "name",
        Value: "prod-us-east-1",
    },
})

Cluster Operations

Rotate Auth

Rotate the bearer token for a cluster.

POST /api/v1/clusters/{id.value}/rotate-auth

string

required

Cluster server URL or name

This operation creates a new service account token and updates the cluster configuration. The old token remains valid for a grace period.

Example:

curl -X POST "https://argocd-server/api/v1/clusters/prod-us-east-1/rotate-auth?id.type=name" \
  -H "Authorization: Bearer $TOKEN"

Invalidate Cache

Clear cached cluster information and force reconnection.

POST /api/v1/clusters/{id.value}/invalidate-cache

string

required

Cluster server URL or name

Example:

curl -X POST "https://argocd-server/api/v1/clusters/prod-us-east-1/invalidate-cache?id.type=name" \
  -H "Authorization: Bearer $TOKEN"

Authentication Methods

Bearer Token Authentication

Most common method using a Kubernetes service account token.

{
  "config": {
    "bearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii...",
    "tlsClientConfig": {
      "caData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
    }
  }
}

TLS Client Certificate

Authenticate using client certificates.

{
  "config": {
    "tlsClientConfig": {
      "caData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
      "certData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
      "keyData": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVkt..."
    }
  }
}

AWS EKS Authentication

For Amazon EKS clusters.

{
  "config": {
    "awsAuthConfig": {
      "clusterName": "prod-cluster",
      "roleARN": "arn:aws:iam::123456789012:role/ArgoCDClusterRole"
    }
  }
}

External Credential Provider

Use exec-based credential plugins.

{
  "config": {
    "execProviderConfig": {
      "command": "aws-iam-authenticator",
      "args": ["token", "-i", "prod-cluster"],
      "env": {
        "AWS_PROFILE": "production"
      },
      "apiVersion": "client.authentication.k8s.io/v1beta1"
    }
  }
}

Connection State

Clusters report their connection status:

{
  "connectionState": {
    "status": "Successful",
    "message": "cluster is reachable",
    "attemptedAt": "2024-03-04T12:00:00Z"
  },
  "serverVersion": "1.28.3",
  "info": {
    "serverVersion": "1.28.3",
    "applicationsCount": 12,
    "cacheInfo": {
      "resourcesCount": 1534,
      "apisCount": 42
    }
  }
}

Status Values:

Successful: Cluster is reachable and authenticated
Failed: Connection or authentication failed
Unknown: Status not yet determined

Cluster Labels

Labels are used by ApplicationSet generators to select clusters.

Setting Labels

{
  "labels": {
    "env": "production",
    "region": "us-east-1",
    "cloud": "aws",
    "tier": "critical"
  }
}

Using Labels in ApplicationSets

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          env: production
        matchExpressions:
        - key: region
          operator: In
          values: [us-east-1, us-west-2]
  template:
    # ...

Namespace Restrictions

Limit which namespaces Argo CD can access:

{
  "namespaces": [
    "production",
    "staging",
    "argocd"
  ]
}

Empty list = all namespaces accessible.

Security Best Practices

Use Dedicated Service Accounts

Create dedicated service accounts with minimal permissions for Argo CD.

kubectl create serviceaccount argocd-manager -n kube-system
kubectl create clusterrolebinding argocd-manager-binding \
  --clusterrole=cluster-admin \
  --serviceaccount=kube-system:argocd-manager

Enable TLS Verification

Always verify TLS certificates in production:

{
  "tlsClientConfig": {
    "insecure": false,
    "caData": "<base64-ca-cert>"
  }
}

Rotate Credentials Regularly

Use the rotate-auth endpoint to refresh tokens periodically.

Restrict Cluster Resources

Set clusterResources: false if cluster-scoped access isn’t needed.

Use Namespace Restrictions

Limit accessible namespaces to reduce attack surface.

In-Cluster vs External

In-Cluster

Argo CD’s own cluster:

server: https://kubernetes.default.svc
name: in-cluster

Automatically registered
Uses in-cluster service account
Cannot be deleted

External Clusters

Remote clusters:

server: https://external-cluster.example.com:6443
name: prod-cluster

Must be explicitly registered
Requires authentication configuration
Can be added via CLI or API

Next Steps

Application API

Deploy applications to clusters

ApplicationSet API

Use cluster generators

Project API

Configure cluster destinations in projects

​Overview

​Cluster Resource

​Cluster Spec

​Example Cluster

​API Operations

​List Clusters

​Get Cluster

​Create Cluster

​Update Cluster

​Delete Cluster

​Cluster Operations

​Rotate Auth

​Invalidate Cache

​Authentication Methods

​Bearer Token Authentication

​TLS Client Certificate

​AWS EKS Authentication

​External Credential Provider

​Connection State

​Cluster Labels

​Setting Labels

​Using Labels in ApplicationSets

​Namespace Restrictions

​Security Best Practices

​In-Cluster vs External

​In-Cluster

​External Clusters

​Next Steps

Application API

ApplicationSet API

Project API

Overview

Cluster Resource

Cluster Spec

Example Cluster

API Operations

List Clusters

Get Cluster

Create Cluster

Update Cluster

Delete Cluster

Cluster Operations

Rotate Auth

Invalidate Cache

Authentication Methods

Bearer Token Authentication

TLS Client Certificate

AWS EKS Authentication

External Credential Provider

Connection State

Cluster Labels

Setting Labels

Using Labels in ApplicationSets

Namespace Restrictions

Security Best Practices

In-Cluster vs External

In-Cluster

External Clusters

Next Steps