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

# Kubernetes

> Connect Kubernetes clusters to CloudThinker for workload analysis, resource optimization, and cluster operations

Connect your Kubernetes clusters to enable [Kai](/guide/agents/kai) to analyze workloads, optimize resources, and manage cluster operations.

Kubernetes connects via **cloud provider auto-discovery** (for EKS, GKE, and AKS) or a **service-account token** with cluster endpoint details for self-managed clusters.

***

## Prerequisites

Install Metrics Server before connecting — it is required for pod and node resource metrics:

```bash theme={null}
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
```

| Component              | Purpose                                        |
| ---------------------- | ---------------------------------------------- |
| **Metrics Server**     | Required for pod and node resource metrics     |
| **kube-state-metrics** | Enhanced cluster metrics (optional)            |
| **Network access**     | CloudThinker must reach the cluster API server |

### Supported platforms

| Platform         | Support             |
| ---------------- | ------------------- |
| **Amazon EKS**   | All versions        |
| **Google GKE**   | Standard, Autopilot |
| **Azure AKS**    | All versions        |
| **Self-managed** | Kubernetes 1.24+    |
| **Rancher**      | RKE, RKE2           |
| **OpenShift**    | 4.x                 |

***

## Setup

<Tabs>
  <Tab title="Via Cloud Provider (Recommended)">
    ### Auto-discovery from cloud connections

    If you've already connected AWS, GCP, or Azure, your managed Kubernetes clusters are automatically discovered.

    <Steps>
      <Step title="Connect cloud provider">
        Set up an [AWS](/guide/connections/aws), [GCP](/guide/connections/gcp), or [Azure](/guide/connections/azure) connection first.
      </Step>

      <Step title="Clusters auto-discovered">
        EKS, GKE, or AKS clusters appear automatically in CloudThinker. Select which clusters to enable for analysis. CloudThinker shows a **Connected** status for each enabled cluster.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Direct Kubeconfig">
    ### Manual setup with service account

    For self-managed clusters or additional access beyond what the cloud provider connection provides:

    <Steps>
      <Step title="Create a namespace (optional)">
        Create a dedicated namespace:

        ```yaml theme={null}
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cloudthinker
        ```
      </Step>

      <Step title="Create a service account">
        ```yaml theme={null}
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: cloudthinker-readonly
          namespace: cloudthinker
        ```
      </Step>

      <Step title="Create a ClusterRole">
        ```yaml theme={null}
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: cloudthinker-readonly
        rules:
        - apiGroups: [""]
          resources: ["*"]
          verbs: ["get", "list", "watch"]
        - apiGroups: ["apps", "extensions"]
          resources: ["*"]
          verbs: ["get", "list", "watch"]
        - apiGroups: ["autoscaling"]
          resources: ["*"]
          verbs: ["get", "list", "watch"]
        - apiGroups: ["metrics.k8s.io"]
          resources: ["pods", "nodes"]
          verbs: ["get", "list"]
        ```
      </Step>

      <Step title="Create a ClusterRoleBinding">
        ```yaml theme={null}
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: cloudthinker-readonly
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: cloudthinker-readonly
        subjects:
        - kind: ServiceAccount
          name: cloudthinker-readonly
          namespace: cloudthinker
        ```
      </Step>

      <Step title="Create a long-lived token">
        Starting from Kubernetes 1.24, create a Secret for long-lived tokens:

        ```yaml theme={null}
        apiVersion: v1
        kind: Secret
        metadata:
          name: cloudthinker-readonly-token
          namespace: cloudthinker
          annotations:
            kubernetes.io/service-account.name: cloudthinker-readonly
        type: kubernetes.io/service-account-token
        ```

        Apply with:

        ```bash theme={null}
        kubectl apply -f cloudthinker-token-secret.yaml
        ```
      </Step>

      <Step title="Retrieve the token">
        ```bash theme={null}
        kubectl get secret cloudthinker-readonly-token -n cloudthinker \
          -o jsonpath='{.data.token}' | base64 --decode
        ```
      </Step>

      <Step title="Get cluster info">
        Get your cluster endpoint:

        ```bash theme={null}
        kubectl cluster-info
        ```

        Extract the CA certificate:

        ```bash theme={null}
        kubectl get secret cloudthinker-readonly-token -n cloudthinker \
          -o jsonpath='{.data.ca\.crt}' | base64 --decode
        ```
      </Step>

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

        * Cluster API endpoint
        * Service account token
        * CA certificate (for self-signed clusters)

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

***

## Connection details

The kubeconfig format CloudThinker uses for direct connections:

```yaml theme={null}
apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority-data: <base64-encoded-ca-cert>
    server: https://your-cluster-endpoint:6443
  name: your-cluster
contexts:
- context:
    cluster: your-cluster
    user: cloudthinker-readonly
  name: cloudthinker-context
current-context: cloudthinker-context
users:
- name: cloudthinker-readonly
  user:
    token: <your-service-account-token>
```

***

## Required permissions

### Minimum (read-only)

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cloudthinker-readonly
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "services", "namespaces", "events", "configmaps"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
  resources: ["pods", "nodes"]
  verbs: ["get", "list"]
```

### Recommended (full analysis)

```yaml theme={null}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cloudthinker-full-analysis
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "services", "namespaces", "events", "configmaps", "secrets", "persistentvolumeclaims", "resourcequotas", "limitranges", "replicationcontrollers"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs", "cronjobs"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["networking.k8s.io"]
  resources: ["ingresses", "networkpolicies"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["metrics.k8s.io"]
  resources: ["pods", "nodes"]
  verbs: ["get", "list"]
```

<Tip>
  Start with the minimum ClusterRole and expand to the full-analysis role only when you need the broader capability set. Never grant write verbs — get, list, and watch are sufficient for all Kai capabilities.
</Tip>

***

## Agent capabilities

Once connected, [Kai](/guide/agents/kai) can inspect and optimize your cluster.

| Capability                | Description                                  |
| ------------------------- | -------------------------------------------- |
| **Resource analysis**     | Pod CPU/memory usage, requests vs limits     |
| **Node health**           | Node status, capacity, allocatable resources |
| **Workload optimization** | Right-sizing recommendations, HPA tuning     |
| **Troubleshooting**       | CrashLoopBackOff, OOMKilled, pending pods    |
| **Security audit**        | RBAC review, pod security, network policies  |

### Verify the connection

```text theme={null}
@kai check the cluster connection and list all namespaces and node count
```

### Example prompts

```text theme={null}
@kai analyze pod resource utilization in the production namespace and #report the top CPU and memory consumers
@kai investigate crash loops in the payment service and #recommend a fix
@kai check node resource pressure across the cluster and #alert if any node is near capacity
```

***

## Troubleshooting

<Accordion title="Cannot connect to cluster">
  Verify the API server endpoint is accessible from the internet. Check that firewall rules and security groups allow CloudThinker's IPs. For private clusters, set up VPN or bastion access and confirm the API server certificate is valid.
</Accordion>

<Accordion title="Unauthorized errors">
  Verify the service account token is correct. Check that the ClusterRoleBinding is applied and that the token hasn't expired. Confirm the service account exists in the correct namespace.
</Accordion>

<Accordion title="No metrics data">
  Verify Metrics Server is installed by running `kubectl top nodes`. Check that Metrics Server pods are running and that the `metrics.k8s.io` API is available.
</Accordion>

<Accordion title="Missing namespaces">
  Verify the ClusterRole includes namespace list permission. Check if RBAC restricts access to certain namespaces and confirm the service account binding is cluster-wide.
</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 access** — never grant write verbs to the CloudThinker service account; get, list, and watch are sufficient for all agent capabilities.
- **Namespace isolation** — keep the service account in a dedicated namespace (e.g., `cloudthinker`) to simplify auditing and revocation.

***

## Related

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

  <Card title="AWS Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/aws.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=45d526a3e9345214c0345f277da2e829" href="/guide/connections/aws" width="24" height="24" data-path="images/icons/aws.svg">
    Connect AWS for EKS auto-discovery
  </Card>
</CardGroup>