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

# Kubernetes

> Connect Kubernetes for pod inspection, cluster events, and deployment state during incidents

The Kubernetes integration gives sureops agents access to your cluster's API for pod and deployment inspection, log retrieval, event queries, and (with approval) remediation actions such as pod restarts and scaling operations.

***

## What this integration enables

* **Pod inspection** — agents read pod status, restart counts, resource utilization, and readiness state for affected services
* **Deployment state** — agents check current replica counts, rollout status, and recent rollout history
* **Cluster events** — agents query Kubernetes events correlated with incident timing to surface scheduling failures, OOM kills, and node pressure
* **Container logs** — agents retrieve container logs from affected pods for the incident time window
* **Remediation actions** — with explicit HITL approval, the resolution specialist can restart deployments, adjust replica counts, or trigger rollouts (always gated by Human-in-the-Loop, regardless of control mode)

***

## Prerequisites

* A Kubernetes cluster
* The `k8s-mcp` server running inside your cluster or accessible from sureops with an appropriate kubeconfig or service account token

***

## Setup

<Steps>
  <Step title="Stand up k8s-mcp">
    Deploy `k8s-mcp` inside your cluster (recommended) or on infrastructure with access to your cluster's API server. If you're using the sureops demo environment, `k8s-mcp` is already provisioned in-cluster — you can skip this step.

    For your own cluster, the sureops MCP setup guide provides a Helm chart for deploying `k8s-mcp` with a scoped service account. The service account needs read access to pods, deployments, events, and logs, plus optional exec/scale permissions for remediation.
  </Step>

  <Step title="Enter MCP endpoint and token">
    In sureops, go to **Settings → Integrations** and click **Connect** next to Kubernetes.

    Fill in:

    * **Kubernetes MCP Endpoint** — the URL of your running `k8s-mcp` server (e.g. `https://k8s-mcp.internal.company.com/mcp`)
    * **MCP Connection Token** — the bearer token used to authenticate sureops to your `k8s-mcp` deployment

    Click **Verify connection** to confirm sureops can reach the MCP server and list cluster resources.
  </Step>
</Steps>

***

## Required credentials

| Field                   | Required | Description                                                          |
| ----------------------- | -------- | -------------------------------------------------------------------- |
| Kubernetes MCP Endpoint | Yes      | URL of your running `k8s-mcp` server                                 |
| MCP Connection Token    | Yes      | Bearer token for authenticating sureops to your `k8s-mcp` deployment |

***

## Scoping k8s-mcp permissions

The level of access you grant `k8s-mcp` determines what sureops agents can do:

| Permission                            | Required for                            |
| ------------------------------------- | --------------------------------------- |
| `pods/list`, `pods/get`               | Pod inspection (diagnosis)              |
| `pods/log`                            | Container log retrieval (diagnosis)     |
| `events/list`                         | Cluster event queries (diagnosis)       |
| `deployments/list`, `deployments/get` | Deployment state (diagnosis)            |
| `deployments/scale`                   | Scaling actions (resolution — optional) |
| `pods/delete`                         | Pod restart (resolution — optional)     |

Grant only the permissions you want sureops to have. Read-only access (the first four rows) is sufficient for diagnosis-only use. Resolution actions require the additional scale and delete permissions.

***

## Common errors

| Error                  | Fix                                                                                                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "401 Unauthorized"     | The MCP connection token is incorrect or expired. Regenerate it and update both the `k8s-mcp` config and sureops.                                           |
| "403 Forbidden"        | The `k8s-mcp` service account lacks permission to access the requested resource. Review the service account's RBAC bindings and add the missing permission. |
| "Connection timed out" | Your `k8s-mcp` server is not reachable from sureops. If it's running in-cluster, check the service exposure configuration.                                  |
| "Namespace not found"  | The agent referenced a namespace that doesn't exist. Check that the namespace matches the service names and labels in your landscape.                       |

***

## Official documentation

* [Kubernetes RBAC documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
* [k8s-mcp on GitHub](https://github.com/strowger/k8s-mcp)