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

# Kubernetes

> Let ewake read pods, events, logs, and deployment state from your cluster during incidents — read-only, with no inbound ports.

<Info>
  **What you'll get:** during an incident, ewake can inspect your cluster — list
  pods, read their status and events, pull (and `--previous`) container logs, and
  see deployment state — to root-cause failures like `CrashLoopBackOff`,
  `OOMKilled`, `ImagePullBackOff`, and unschedulable pods. Access is **read-only**.
</Info>

***

## How it works

You run a read-only [Kubernetes MCP server](https://github.com/containers/kubernetes-mcp-server)
inside your cluster and expose it over a tunnel of your choice. ewake connects to
that endpoint — with whatever headers you specify — and reads pods, events, logs,
and deployments on demand.

ewake never needs inbound access: the tunnel dials out, so no ports are opened into
your cluster. And it only ever reads — the server runs `--read-only`, bound to a
read-only `view` role.

```mermaid theme={null}
flowchart LR
  A["ewake agent"] -->|"request headers (your auth)"| B["your tunnel<br/>(Cloudflare, ngrok, …)"]
  B -->|"outbound — no inbound ports"| C["kubernetes-mcp-server<br/>(--read-only)"]
  C -->|"read-only RBAC (view)"| D["cluster API server"]
```

***

## Configuration

<Steps>
  <Step title="Run a read-only MCP server in your cluster">
    Deploy the open-source
    [`kubernetes-mcp-server`](https://github.com/containers/kubernetes-mcp-server)
    however you prefer — Helm, plain manifests, or an existing deployment. Two
    things matter:

    * **Read-only server** — start it with `--read-only` (optionally
      `--toolsets core,config`).
    * **Read-only ServiceAccount** — bind it to the built-in `view` ClusterRole,
      which excludes Secrets and all write verbs.

    <Warning>
      Don't grant the server a write-capable role. The `view` ClusterRole is what
      keeps ewake read-only and blocks access to Secrets.
    </Warning>
  </Step>

  <Step title="Expose it through a tunnel">
    Put the server behind an **outbound** tunnel so ewake can reach it without any
    inbound ports — for example
    [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/),
    [ngrok](https://ngrok.com/), or any equivalent. Protect the public endpoint with
    whatever your tunnel offers (a Cloudflare Access service token, an ngrok auth
    header, etc.).

    Your endpoint URL is the public tunnel hostname plus the MCP path, e.g.
    `https://k8s-mcp.yourcompany.com/mcp`.
  </Step>

  <Step title="Connect it in ewake">
    In your dashboard, go to **Integrations → Infrastructure → Kubernetes →
    Connect**, then enter:

    | Field               | Value                                                                     |
    | ------------------- | ------------------------------------------------------------------------- |
    | **MCP Server URL**  | Your tunnel URL, e.g. `https://k8s-mcp.yourcompany.com/mcp`               |
    | **Request headers** | Whatever your endpoint requires (see below). Values are stored encrypted. |

    Headers depend on how you protected the endpoint:

    * **Cloudflare Access service token** → two headers: `CF-Access-Client-Id` and `CF-Access-Client-Secret`.
    * **Bearer / ngrok** → e.g. `Authorization: Bearer <token>`.
    * **No auth** → leave it empty.

    <img src="https://mintcdn.com/ewakeai/AOgKYQT1rTMrK_ZB/images/integrations/infrastructure/kubernetes/connect-modal.png?fit=max&auto=format&n=AOgKYQT1rTMrK_ZB&q=85&s=e9a7712e1d17cec652470470ea7fdd27" alt="Connect to Kubernetes modal in ewake" style={{ maxHeight: "320px", objectFit: "cover", objectPosition: "top", borderRadius: "8px" }} width="600" height="694" data-path="images/integrations/infrastructure/kubernetes/connect-modal.png" />
  </Step>

  <Step title="Test and save">
    Click **Test connection** — ewake connects through the tunnel and lists the
    read-only tools to confirm the URL and headers work. Then click **Save**.

    <Check>
      Kubernetes is connected. ewake can now read pods, events, logs, and
      deployment state during incidents.
    </Check>
  </Step>
</Steps>

***

## What ewake can and can't do

<CardGroup cols={2}>
  <Card title="Can (read-only)" icon="eye">
    List and describe pods, deployments, nodes, and events; read current and
    previous container logs; inspect non-secret config.
  </Card>

  <Card title="Can't (blocked)" icon="ban">
    Create, edit, delete, scale, or `exec` into anything. Read Secrets. Open any
    inbound port into your cluster.
  </Card>
</CardGroup>

<Note>
  ewake observes your cluster **on demand** during an investigation — it does not
  continuously watch or store cluster state.
</Note>