Cluster API

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

server

string

required

Kubernetes API server URL

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

name

string

Cluster name (unique identifier, alternative to server)

name: prod-us-east-1

config

ClusterConfig

required

Authentication and connection configuration

Show ClusterConfig fields

bearerToken

string

Bearer token for authentication

tlsClientConfig

TLSClientConfig

TLS certificate configuration

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

awsAuthConfig

AWSAuthConfig

AWS IAM authentication configuration

execProviderConfig

ExecProviderConfig

External credential provider configuration

namespaces

string[]

Allowed namespaces (empty = all namespaces)

clusterResources

boolean

Whether Argo CD can manage cluster-scoped resources

project

string

Project that owns this cluster

labels

map[string]string

Labels for cluster selection in ApplicationSets

annotations

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

server

string

Filter by server URL

name

string

Filter by cluster name

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

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}

id.value

string

required

Cluster server URL or name (URL-encoded)

id.type

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"

Create Cluster

POST /api/v1/clusters

cluster

Cluster

required

Complete Cluster configuration

upsert

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"
    }
  }'

Update Cluster

Update an existing cluster configuration.

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

id.value

string

required

Cluster server URL or name (URL-encoded)

cluster

Cluster

required

Updated Cluster configuration

updatedFields

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}

id.value

string

required

Cluster server URL or name (URL-encoded)

id.type

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"

Cluster Operations

Rotate Auth

Rotate the bearer token for a cluster.

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

id.value

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

id.value

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

Resources

gRPC Services

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

Build docs developers (and LLMs) love

Overview

Resources

gRPC Services

​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

Build docs developers (and LLMs) love

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