> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ArgoCD

> Connect ArgoCD to CloudThinker for GitOps operations and application management

Connect your ArgoCD instances to enable [Kai](/guide/agents/kai) (Kubernetes Engineer) to analyze deployments, manage applications, and troubleshoot GitOps workflows. ArgoCD authenticates with an **API token** — the setup varies between self-hosted instances and the Akuity Platform.

***

## Prerequisites

* An ArgoCD instance accessible from CloudThinker: self-hosted (default port `8888`) or managed via [Akuity Platform](https://akuity.cloud).
* **ArgoCD CLI** installed (`brew install argocd`); Akuity Platform also requires the [Akuity CLI](https://docs.akuity.io/akuity-platform/akuity-cli).
* Admin access to ArgoCD to enable the `apiKey` capability and generate a token.

***

## Setup

Select your ArgoCD platform:

<Tabs>
  <Tab title="Self-hosted ArgoCD">
    <Steps>
      <Step title="Get connection details">
        Ensure ArgoCD is running and accessible. Get your host IP address:

        ```bash theme={null}
        hostname -I | awk '{print $1}'
        ```
      </Step>

      <Step title="Generate an API token">
        Enable the `apiKey` capability and generate a token for the admin account:

        ```bash theme={null}
        kubectl -n argocd patch configmap argocd-cm --type merge -p '{"data":{"accounts.admin":"apiKey, login"}}'
        argocd login <host-ip>:8888 --username admin --password '<password>' --insecure
        argocd account generate-token --account admin --insecure
        ```
      </Step>

      <Step title="Add the connection in CloudThinker">
        Navigate to **Connections → ArgoCD** and enter:

        * **Base URL**: `https://<host-ip>:8888`
        * **API Token**: token from the previous step
        * **TLS Verification**: Disable
        * **Read-only Mode**: Enable

        Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Akuity Platform">
    <Steps>
      <Step title="Install CLIs">
        Install ArgoCD CLI:

        ```bash theme={null}
        brew install argocd
        ```

        Install Akuity CLI:

        ```bash theme={null}
        curl -sSL -o /tmp/akuity \
          "https://dl.akuity.io/akuity-cli/$(curl -sL https://dl.akuity.io/akuity-cli/stable.txt)/$(uname)/$(uname -m)/akuity"
        chmod +x /tmp/akuity
        sudo mv /tmp/akuity /usr/local/bin/akuity
        ```
      </Step>

      <Step title="Create an admin account">
        In the [Akuity Portal](https://akuity.cloud):

        1. Navigate to **Organization** → **API Keys** → click **Create API Key** (role: Owner).
        2. Under your ArgoCD instance → **Settings** → **System Accounts**.
        3. Click **Add Account** → name: `admin`.
        4. Enable both **login** and **apiKey** capabilities and set a password.
      </Step>

      <Step title="Generate an API token">
        Log in and generate a token:

        ```bash theme={null}
        argocd login <instance-id>.cd.akuity.cloud --grpc-web \
          --username admin --password '<your-password>'
        argocd account generate-token --account admin --grpc-web
        ```
      </Step>

      <Step title="Add the connection in CloudThinker">
        Navigate to **Connections → ArgoCD** and enter:

        * **Base URL**: `https://<instance-id>.cd.akuity.cloud`
        * **API Token**: token from the previous step
        * **TLS Verification**: Enable
        * **Read-only Mode**: Enable

        Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Connection details

| Field                | Description                                                               | Example                                                                             |
| -------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Base URL**         | ArgoCD server address                                                     | `https://192.168.1.100:8888` (self-hosted); `https://<id>.cd.akuity.cloud` (Akuity) |
| **API Token**        | Token generated for the ArgoCD admin account                              | —                                                                                   |
| **TLS Verification** | Enable for Akuity; disable for self-hosted with a self-signed certificate | —                                                                                   |
| **Read-only Mode**   | Enable to prevent unsanctioned writes                                     | —                                                                                   |

***

## Required permissions

Apply the following RBAC policy in ArgoCD to grant CloudThinker read-only access:

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    p, role:cloudthinker-readonly, applications, get, */*, allow
    p, role:cloudthinker-readonly, applications, list, */*, allow
    p, role:cloudthinker-readonly, repositories, get, *, allow
    p, role:cloudthinker-readonly, repositories, list, *, allow
    p, role:cloudthinker-readonly, clusters, get, *, allow
    p, role:cloudthinker-readonly, clusters, list, *, allow
    g, cloudthinker-readonly, role:cloudthinker-readonly
```

```bash theme={null}
kubectl apply -f argocd-rbac.yaml
```

<Tip>
  Follow least privilege: grant only `get` and `list` actions on applications, repositories, and clusters.
</Tip>

***

## Agent capabilities

Once connected, Kai can investigate and act on your ArgoCD applications.

| Capability              | Description                                        |
| ----------------------- | -------------------------------------------------- |
| **Application status**  | View sync status, health state, and last sync time |
| **Deployment analysis** | Identify out-of-sync and failed deployments        |
| **Repository insights** | Analyze Git repository state and commits           |
| **Health monitoring**   | Track application health across all apps           |
| **Sync operations**     | Trigger manual syncs — **requires approval**       |

### Verify the connection

```text theme={null}
@kai list all ArgoCD applications and show their sync and health status
```

### Example prompts

```text theme={null}
@kai show all out-of-sync ArgoCD applications and #report the details
@kai analyze deployment failures for the payment service and #recommend fixes
@kai check the health status of all applications in production
```

***

## Troubleshooting

<Accordion title="Cannot connect to ArgoCD server">
  For self-hosted instances, use the host IP address (not `localhost`) in the Base URL. If the server is behind a port-forward, run `kubectl port-forward svc/argocd-server -n argocd 8888:443 --address 0.0.0.0`. Check firewall rules if the host remains unreachable.
</Accordion>

<Accordion title="401 Unauthorized">
  Verify the API token is correct and that the admin account has both `login` and `apiKey` capabilities enabled. For self-hosted, confirm `argocd-cm` was patched; for Akuity, check the System Account capabilities in the portal.
</Accordion>

<Accordion title="Cannot generate API token">
  The `apiKey` capability is not enabled for the account. Run `argocd account get` to inspect the account's capabilities, then enable `apiKey` and retry.
</Accordion>

<Accordion title="TLS certificate errors">
  For self-hosted instances, disable TLS verification in the connection settings (equivalent to the `--insecure` CLI flag). For Akuity, TLS verification should remain enabled.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Read-only RBAC** — apply the `role:cloudthinker-readonly` policy in `argocd-rbac-cm` and enable read-only mode in the connection to prevent unsanctioned writes.
- **Token rotation** — rotate the ArgoCD API token periodically and update it in CloudThinker.

***

## Related

<CardGroup cols={2}>
  <Card title="Kai Agent" icon="dharmachakra" href="/guide/agents/kai">
    Kubernetes and GitOps agent
  </Card>

  <Card title="Kubernetes Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/kubernetes.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=7c03292954ff635a1994623a5c39971b" href="/guide/connections/kubernetes" width="24" height="24" data-path="images/icons/kubernetes.svg">
    Connect Kubernetes clusters
  </Card>
</CardGroup>