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

# Kubernetes

> Connect your Kubernetes clusters to Kestrel for real-time incident detection, traffic visibility, and AI-powered operations

The Kestrel Operator is a lightweight Kubernetes agent that connects your clusters to the Kestrel AI platform. It streams resource metadata, events, logs, and network traffic telemetry over mTLS — enabling 24/7 real-time incident detection, AI-powered workflows, and an infrastructure copilot without any changes to your existing applications.

## Prerequisites

* Kubernetes cluster (v1.24+)
* `kubectl` configured with cluster admin access
* `helm` CLI (v3.0+)
* A Kestrel AI account with **Organization Admin** role
* Network connectivity to `grpc.platform.usekestrel.ai:443`

## Setup

**1. Generate operator credentials**

1. Log in to the [Kestrel AI Dashboard](https://platform.usekestrel.ai)
2. Navigate to **Integrations → Kubernetes**
3. Click **Generate New Credential**
4. Set a **Cluster Name** (e.g., `production-cluster`) — alphanumeric, dots, dashes, and underscores only
5. Choose your **Flow Collection Source** (Cilium L3/L4 or Istio L7)
6. Choose your **Metrics Source** (Kubernetes Metrics Server, OpenTelemetry, or Datadog)
7. Optionally enable **Safe-Apply Permissions** for AI-powered resource management

**2. Download the Helm values file**

Click **Download** to save the pre-configured values file:

```
kestrel-ai-operator-values-<cluster-name>.yaml
```

**3. Deploy with Helm**

```bash theme={null}
helm install kestrel-operator \
  oci://ghcr.io/kestrelai/charts/kestrel-operator \
  --version latest \
  --namespace kestrel-ai \
  --create-namespace \
  -f kestrel-ai-operator-values-<cluster-name>.yaml
```

**4. Verify installation**

Check pod status:

```bash theme={null}
kubectl get pods -n kestrel-ai -l app=kestrel-operator
```

Expected output:

```
NAME                               READY   STATUS    RESTARTS   AGE
kestrel-operator-xxxxxxxxx-xxxxx   1/1     Running   0          1m
```

Then confirm the cluster shows as **Connected** (green badge) in **Integrations → Kubernetes**.

> [!NOTE]
>
> The operator token automatically renews every 24 hours. No manual rotation is required.

## Flow Collection Sources

> [tab] Cilium (L3/L4)
>
> Collects Layer 3/4 network flows from Cilium CNI via Hubble Relay. This is the default — no extra configuration needed if Cilium is your CNI.

> [tab] Istio (L7)
>
> Collects Layer 7 HTTP/gRPC access logs from Envoy proxies via Istio's Access Log Service. Requires registering Kestrel as an Istio extension provider — see the [Configuration Reference](#istio-configuration) below.

## How It's Used

### In Workflows

**Trigger blocks:**

* **Deployment Replicas Failing** — fires when a Deployment cannot reach its desired replica count
* **Nodes Unavailable** — fires when one or more cluster nodes become NotReady
* **Pod CrashLoopBackOff** — fires when a pod enters a CrashLoopBackOff restart cycle
* **Pod ImagePullBackOff** — fires when a pod cannot pull its container image
* **Pod OOMKilled** — fires when a container is terminated due to an out-of-memory condition
* **Pods Failing** — fires when pods transition to a failed state
* **Pods Restarting** — fires when pods exceed a restart count threshold
* **StatefulSet Replicas Failing** — fires when a StatefulSet cannot reach its desired replica count
* **Node Memory Pressure** — fires when a node reports a MemoryPressure condition
* **Node Disk Pressure** — fires when a node reports a DiskPressure condition
* **DaemonSet Failing** — fires when a DaemonSet has unavailable pods
* **Any Kubernetes Incident** — fires on any Kubernetes incident detected by Kestrel

Kubernetes operations (kubectl commands, resource scaling, rolling restarts, network policy application, safe-apply YAML changes) are provided by Kestrel's built-in action blocks and are available in any workflow alongside these triggers.

Example: A workflow triggers on Pod CrashLoopBackOff, runs an AI root cause analysis, applies a fix via safe-apply, and notifies the namespace owner on Slack.

### In Incident Response

* **24/7 real-time detection** from Kubernetes events, pod logs, node conditions, and network telemetry
* **Automated root cause analysis** correlating events, metrics, logs, and network flows
* **YAML fix generation** with one-click GitOps deployment via connected GitHub/GitLab repos
* **Causal PR detection** — identifies recent deployments that may have caused the incident

### In Cloud AI Copilot

* Ask questions about any connected cluster: `What pods are crashing in production?`
* Query metrics and resource utilization: `Show memory usage for the payments namespace`
* Generate and apply Kubernetes resources through conversational AI
* Use the `/kestrel` Slack command for quick cluster queries

## Configuration Reference

### Helm Values

#### Authentication

| Key | Type | Default | Description |
| - | - | - | - |
| `auth.token` | string | `""` | JWT token (generated in dashboard) |
| `server.host` | string | `grpc.platform.usekestrel.ai` | gRPC endpoint |
| `server.port` | integer | `443` | gRPC port |

#### Cilium

| Key | Type | Default | Description |
| - | - | - | - |
| `operator.cilium.disableFlows` | boolean | `false` | Disable Cilium flow collection |
| `operator.cilium.hubble.tls.forceDisable` | boolean | `false` | Disable TLS for Hubble connections |

#### Istio Configuration

| Key | Type | Default | Description |
| - | - | - | - |
| `operator.istio.enabled` | boolean | `false` | Enable Istio ALS for L7 flows |
| `operator.istio.alsPort` | integer | `8080` | ALS gRPC server port |

When enabling Istio, register Kestrel as an extension provider in your Istio mesh config:

```yaml theme={null}
meshConfig:
  extensionProviders:
    - name: kestrel-operator-als
      envoyHttpAls:
        service: kestrel-operator-als.kestrel-ai.svc.cluster.local
        port: 8080
    - name: kestrel-operator-als-tcp
      envoyTcpAls:
        service: kestrel-operator-als.kestrel-ai.svc.cluster.local
        port: 8080
```

#### Metrics Source

| Key | Type | Default | Description |
| - | - | - | - |
| `operator.otel.enabled` | boolean | `false` | Enable OpenTelemetry metrics receiver |
| `operator.otel.receiverPort` | integer | `4317` | OTLP gRPC receiver port |
| `operator.datadog.enabled` | boolean | `false` | Enable Datadog metrics integration |
| `operator.datadog.namespace` | string | `"datadog"` | Namespace where Datadog is deployed |

#### Safe-Apply

| Key | Type | Default | Description |
| - | - | - | - |
| `operator.safeApply.enabled` | boolean | `false` | Grant RBAC permissions for applying approved changes |

> [!WARNING]
>
> Safe-Apply permissions allow the operator to create, update, and delete Kubernetes resources. Only enable if you plan to use AI-powered resource management features.

### Quick Configuration Examples

**Cilium with Datadog metrics:**

```yaml theme={null}
auth:
  token: "your-token-here"
operator:
  cluster:
    id: "cluster-uuid"
    name: "production-cluster"
  datadog:
    enabled: true
    namespace: "datadog"
```

**Istio with OpenTelemetry metrics:**

```yaml theme={null}
auth:
  token: "your-token-here"
operator:
  cluster:
    id: "cluster-uuid"
    name: "production-cluster"
  cilium:
    disableFlows: true
  istio:
    enabled: true
    alsPort: 8080
  otel:
    enabled: true
```

## Managing Clusters

### Multiple Clusters

Connect multiple clusters to a single Kestrel organization. Generate a unique credential for each cluster and deploy the operator with its specific token.

> [!NOTE]
>
> Your subscription tier determines the maximum number of clusters. Contact [hello@usekestrel.ai](mailto:hello@usekestrel.ai) to upgrade.

### Updating

```bash theme={null}
helm upgrade kestrel-operator \
  oci://ghcr.io/kestrelai/charts/kestrel-operator \
  --version latest \
  --namespace kestrel-ai \
  -f kestrel-ai-operator-values-<cluster-name>.yaml
```

### Uninstalling

```bash theme={null}
helm uninstall kestrel-operator -n kestrel-ai
```

Then revoke the credential in **Integrations → Kubernetes** by clicking the delete icon next to your cluster.

### Connection Status

| Status | Meaning |
| - | - |
| **Connected** (Green) | Actively sending data |
| **Offline** (Gray) | Previously connected, currently offline |
| **Pending** (Red) | Never connected with this token |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.