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

# Kubernetes

> Connect any Kubernetes-conformant cluster through a Traversal Connector for scoped, read-only kubectl investigations.

Traversal works with any Kubernetes-conformant cluster whose API is reachable through an associated Traversal Connector. Connecting Kubernetes lets Traversal inspect cluster events, logs, resource usage, and workload topology during investigations. Traversal uses scoped `kubectl` reads to understand cluster state and correlate it with your other telemetry.

## Read-only access and RBAC

Traversal passes Kubernetes credentials only to one bare, recognized read-only `kubectl` command. Supported operations cover resource reads and descriptions, bounded log retrieval, resource usage, events, API discovery, rollout status and history, and authorization checks.

Traversal rejects mutating operations, streaming or watch modes, plugins, wrappers, path-qualified binaries, pipes, redirects, shell chains and substitutions, credential or destination overrides, and output modes that read templates from files.

<Info>
  Kubernetes RBAC remains the authoritative permission boundary. Traversal's agent policies limit how the credentials can be used, while your RoleBindings, ClusterRoleBindings, or EKS access policy determine which cluster resources those credentials can read.
</Info>

Grant only the resources and namespaces Traversal needs. Do not grant access to secrets, `pods/exec`, port forwarding, write verbs, wildcards, or impersonation unless you intentionally want those capabilities.

## Before you start

Associate the Kubernetes integration with a Traversal Connector that can reach the cluster's Kubernetes API endpoint. Traversal reaches the API through that connector. This supports private endpoints and outbound-only connectivity without requiring inbound access to your environment.

The Connector validates the API server's certificate. If the certificate uses a private CA, add that CA to the Connector's upstream trust configuration. See [Set up the Traversal Connector](/setup/connector) and [Connector architecture](/architecture/connector).

## Choose a setup type

| Setup | Use it for | Authentication |
| - | - | - |
| [Standard Kubernetes](#standard-kubernetes) | Kubernetes-conformant clusters on any infrastructure or cloud provider | ServiceAccount TokenRequest or static bearer token |
| [AWS EKS](#aws-eks) | Amazon EKS clusters where you want a CloudFormation template to configure IAM and EKS access | Cross-account IAM with EKS-derived tokens |

Create one Kubernetes integration per cluster.

## Standard Kubernetes

Use this setup for any Kubernetes-conformant cluster. You provide the Kubernetes API endpoint and Kubernetes credentials directly.

Go to **Company Knowledge > Integrations**, select **Kubernetes**, and choose the standard cluster connection.

<Steps>
  <Step title="Enter the cluster endpoint">
    Enter a name for the cluster and its Kubernetes API server URL. You can also set an optional default namespace.

    Provide the API server's base64-encoded PEM CA bundle as **Certificate Authority Data**. Prefer a trusted CA over **Skip TLS Verification**, which disables server certificate verification.
  </Step>

  <Step title="Choose authentication">
    Choose one of these options:

    * **ServiceAccount TokenRequest** (recommended): Traversal uses a narrowly scoped requester credential to mint short-lived tokens for a target ServiceAccount. The target ServiceAccount's RBAC controls cluster access.
    * **Static Bearer Token**: Traversal uses a stored, long-lived ServiceAccount token. Use this only when your cluster cannot support the TokenRequest flow, and rotate the token according to your security policy.
  </Step>

  <Step title="Configure ServiceAccount TokenRequest">
    Skip this step if you selected **Static Bearer Token**.

    Create the target ServiceAccount and bind only the read permissions Traversal needs. Then add this rules fragment to a Role or ClusterRole for a separate requester identity, allowing it to create tokens for that specific target ServiceAccount:

    ```yaml theme={null}
    rules:
      - apiGroups: [""]
        resources: ["serviceaccounts/token"]
        resourceNames: ["traversal-agent-reader"]
        verbs: ["create"]
    ```

    Replace `traversal-agent-reader` with your target ServiceAccount name. Enter the target name, its namespace, and the requester bearer token in Traversal. You can also set a token audience and lifetime if your cluster requires them.
  </Step>
</Steps>

## AWS EKS

Use this setup for Amazon EKS. Traversal provides a CloudFormation template that configures cross-account IAM access and maps the role into the cluster with an EKS Access Entry. The associated Connector must be able to reach the EKS API endpoint that Traversal discovers.

Go to **Company Knowledge > Integrations**, select **Kubernetes**, and choose the AWS EKS cluster connection.

<Steps>
  <Step title="Download the CloudFormation template">
    Download the prefilled template from the Kubernetes integration form. It includes Traversal's AWS account ID and your unique external ID.
  </Step>

  <Step title="Deploy the stack">
    Deploy the template in the AWS account and region that host your EKS cluster. Set **ClusterName** to the exact EKS cluster name.

    Leave **RoleNameSuffix** blank when connecting one cluster in the account. Set a unique suffix only when deploying the template again for additional clusters in the same account, because IAM role names must be unique.

    The stack creates:

    * A cross-account IAM role guarded by your external ID
    * An EKS Access Entry for that role
    * A cluster-wide association with AWS's managed `AmazonAIOpsAssistantPolicy`
  </Step>

  <Step title="Configure the integration">
    When the stack finishes, copy its role ARN. In Traversal, enter:

    * **EKS Cluster Name**
    * **AWS Region**
    * **Role ARN**
    * **External ID**, if it is not already populated
    * An optional default namespace

    Select **AWS EKS (derived)** for authentication. Traversal assumes the role for a short session, discovers the cluster endpoint and CA, and mints a short-lived EKS token. No long-lived AWS access keys or manual CA entry are required. The Connector still validates the API server certificate using its upstream trust configuration.
  </Step>
</Steps>

<Tip>
  Repeat the stack deployment with a unique role suffix for each additional EKS cluster in the same AWS account.
</Tip>

## Example questions

* Which namespaces are using the most CPU and memory?
* Show recent warning events and identify the affected workloads.
* Which pods are crashing, and what do their recent and previous logs show?
* Map the Deployments, ReplicaSets, Pods, Services, and Ingresses for the checkout workload.

## More information

* [Kubernetes RBAC authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
* [ServiceAccount TokenRequest](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/)
* [EKS access policies](https://docs.aws.amazon.com/eks/latest/userguide/access-policies.html)


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