# Add Kubernetes Cluster

Source: https://docs.ops0.com/docs/kubernetes/add-cluster

Connect a Kubernetes cluster to ops0 for monitoring, incident detection, and pod management.

## Connection Methods

ops0 agent (Recommended)

Outbound-only connection. Install agent in cluster for full features.

Direct Connection

Connect via kubeconfig or cloud provider credentials.

## Add Cluster Wizard

1. **Name** - Enter display name and optional description

2. **Provider** - Select EKS, GKE, AKS, or Self-managed

3. **Credentials** - Provide provider-specific authentication

4. **Connect** - Test and establish connection

---

## AWS EKS

### EKS Required Fields

| Field | Description |
|-------|-------------|
| **AWS Integration** | Select from configured integrations |
| **Region** | AWS region (e.g., us-east-1) |
| **Cluster Name** | EKS cluster name from AWS |

### IAM Permissions

The AWS integration IAM role requires:

```json
{
  "Effect": "Allow",
  "Action": [
    "eks:DescribeCluster",
    "eks:ListClusters"
  ],
  "Resource": "*"
}
```

Additionally, the IAM role must be mapped in the cluster's `aws-auth` ConfigMap for Kubernetes API access.

---

## Google GKE

### GKE Required Fields

| Field | Description |
|-------|-------------|
| **Project ID** | GCP project containing the cluster |
| **Cluster Name** | GKE cluster name |
| **Location** | Region or zone (e.g., us-central1) |
| **Service Account JSON** | GCP service account key |

### Service Account Roles

Create a service account with these roles:

| Role | Purpose |
|------|---------|
| `roles/container.clusterViewer` | View cluster and workloads |
| `roles/container.developer` | Pod exec and log access |

---

## Azure AKS

### AKS Required Fields

| Field | Description |
|-------|-------------|
| **Subscription ID** | Azure subscription ID |
| **Resource Group** | Resource group containing cluster |
| **Cluster Name** | AKS cluster name |
| **Tenant ID** | Azure AD tenant ID |
| **Client ID** | Service principal application ID |
| **Client Secret** | Service principal secret |

### Service Principal

The service principal needs `Azure Kubernetes Service Cluster User Role` or equivalent RBAC permissions.

---

## Self-Managed Clusters

For any Kubernetes cluster (on-prem, k3s, kind, etc.) accessible via kubeconfig.

### Self-Managed Cluster Required Fields

| Field | Description |
|-------|-------------|
| **Kubeconfig** | Full kubeconfig YAML content |

### Getting Your Kubeconfig

```bash
# Full config (all contexts)
cat ~/.kube/config

# Single cluster, flattened
kubectl config view --minify --flatten
```

### Requirements

- API server must be reachable from ops0
- Valid credentials (token, certificate, or exec auth)
- Appropriate RBAC permissions

---

## Install ops0 agent

The ops0 agent enables real-time features without opening inbound connections to your cluster.

### Why ops0 agent?

Outbound Only

No ingress rules or public endpoints needed

Real-time Logs

Stream container logs live

Pod Exec

Terminal access to containers

Metrics

CPU and memory utilization

### Installation via Helm

After connecting your cluster, install the agent:

```bash
helm repo add ops0 https://charts.ops0.io
helm repo update

helm install ops0-agent ops0/ops0-agent \
  --namespace ops0-system \
  --create-namespace \
  --set token=YOUR_CLUSTER_TOKEN \
  --set endpoint=https://api.ops0.io
```

The token is provided in the ops0 UI after adding the cluster. Click **Install ops0 agent** on the cluster detail page to copy the complete command.

### Verify Installation

```bash
kubectl get pods -n ops0-system
```

Once the agent pod is running, the cluster status in ops0 changes to **Connected**.

---

## Required RBAC

For full ops0 functionality, apply this ClusterRole:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ops0-reader
rules:
  # Core resources
  - apiGroups: [""]
    resources:
      - pods
      - pods/log
      - services
      - namespaces
      - nodes
      - events
    verbs: ["get", "list", "watch"]

  # Workload resources
  - apiGroups: ["apps"]
    resources:
      - deployments
      - replicasets
      - statefulsets
      - daemonsets
    verbs: ["get", "list", "watch"]

  # Terminal access (optional)
  - apiGroups: [""]
    resources: ["pods/exec"]
    verbs: ["create"]
```

Bind this role to your service account or user.

---

## Troubleshooting

Unable to Connect

Check firewall rules and security groups. Verify the API server endpoint is reachable. For private clusters, ensure network path exists.

Access Denied

Verify RBAC permissions. For EKS, check aws-auth ConfigMap. For GKE, verify service account roles. Regenerate credentials if expired.

Certificate Error

Ensure CA certificate is included in kubeconfig. For self-signed certs, the CA must be trusted or explicitly provided.

Timeout

Network latency or cluster overload. Try again or check cluster health. Large clusters may take longer to enumerate resources.

## After Connection

Once connected, you can:

- **View cluster overview** - Node count, pod status, resource usage
- **Monitor incidents** - Auto-detected CrashLoops, OOM, failures
- **Browse pods** - Filter by namespace, view details
- **Access logs** - Stream container output in real-time
- **Open terminals** - Exec into running containers

---

## Example: Adding an EKS Cluster

### Wizard Configuration

**Step 1: Name**
```
Display Name:   production-eks
Description:    Production EKS cluster in us-east-1
```

**Step 2: Provider**
```
Provider:       AWS EKS
```

**Step 3: Credentials**
```
AWS Integration:  AWS Production (123456789012)
Region:           us-east-1
Cluster Name:     production-cluster
```

**Step 4: Connect**
```
Testing connection to production-cluster...
✓ AWS credentials valid
✓ EKS cluster found
✓ Kubernetes API accessible
✓ RBAC permissions verified

Connection successful!
```

### Install ops0 agent After Connection

After connection, the UI shows the Helm command:

```bash
# Add ops0 Helm repository
helm repo add ops0 https://charts.ops0.io
helm repo update

# Install ops0 agent
helm install ops0-agent ops0/ops0-agent \
  --namespace ops0-system \
  --create-namespace \
  --set token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  --set endpoint=https://api.ops0.io \
  --set clusterName=production-eks
```

### Verify Agent Status

```bash
$ kubectl get pods -n ops0-system

NAME                          READY   STATUS    RESTARTS   AGE
ops0-agent-7b8f9c6d5-xk2lp    1/1     Running   0          30s

$ kubectl logs -n ops0-system ops0-agent-7b8f9c6d5-xk2lp

2024-01-15T10:30:00Z INFO  Starting ops0 agent v2.1.0
2024-01-15T10:30:01Z INFO  Connected to ops0 API
2024-01-15T10:30:02Z INFO  Cluster registered: production-eks
2024-01-15T10:30:02Z INFO  Starting metrics collection
2024-01-15T10:30:02Z INFO  Starting event watcher
2024-01-15T10:30:03Z INFO  Agent ready, awaiting commands
```

### Result in ops0 UI

```
Cluster: production-eks
Status:  Connected ✓

Connection Details:
─────────────────────────────────────
Method:         ops0 agent
Agent Version:  v2.1.0
Last Heartbeat: 2 seconds ago
Features:       Logs, Exec, Metrics, Events
```

---

## Incident Monitoring Settings

After adding a cluster, configure how ops0 monitors it for incidents. Navigate to the cluster → **⋮ menu → Monitoring Settings**.

| Setting | Description |
|---------|-------------|
| **Incident Monitoring** | Toggle to enable or disable automatic incident detection for this cluster |
| **Scan Interval** | How often ops0 scans for new incidents (minutes). Default: 5 minutes. Range: 1–60 minutes. |

Incident monitoring runs in the background and detects CrashLoopBackOff, OOMKilled, ImagePullBackOff, failed deployments, and node NotReady conditions automatically. Reducing the scan interval gives faster detection but increases API calls to the cluster.

Disable incident monitoring temporarily if a cluster is under maintenance and you want to suppress expected alerts.