> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-feat-new-runbook-parameters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes EKS

> Manage Kubernetes resources through kubectl commands or native API access. This integration supports both CLI-based workflows and direct interaction with the Kubernetes API for full cluster control.

export const ConnectionTemplate = ({config}) => {
  const defaultConfig = {
    name: "Connection",
    description: "Connection description",
    coverImage: "",
    features: {
      tlsTerminationProxy: {
        native: false,
        oneOff: false
      },
      audit: {
        native: false,
        oneOff: false
      },
      dataMaskingGoogleDLP: {
        native: false,
        oneOff: false
      },
      dataMaskingMSPresidio: {
        native: false,
        oneOff: false
      },
      guardrails: {
        native: false,
        oneOff: false
      },
      credentialsOffload: {
        native: false,
        oneOff: false
      },
      interactiveAccess: {
        native: false,
        oneOff: false
      }
    }
  };
  const finalConfig = Object.assign({}, defaultConfig, config);
  const renderIcon = enabled => {
    return enabled ? <Icon icon="check" /> : <Icon icon="xmark" />;
  };
  return <div>
      <h2>Before you start</h2>
      <p>To get the most out of this guide, you will need to:</p>
      <ul>
        <li>Either <a href="https://use.hoop.dev">create an account in our managed instance</a> or <a href="/getting-started/installation/overview">deploy your own hoop.dev instance</a></li>
        <li>You must be your account administrator to perform the following commands</li>
      </ul>

      {finalConfig.requirements && <>
          <h2>Requirements</h2>
          <p>{finalConfig.requirements.description}</p>
          {finalConfig.requirements.items && <ul>
            {finalConfig.requirements.items.map(item => <li>{item}</li>)}
          </ul>}
        </>}

      <h2>Features</h2>
      <p>The table below outlines the features available for this type of connection.</p>

      <ul>
        <li><strong>Native</strong> - Accessible via a native connection using hoop as proxy protocol to the resource.</li>
        <li><strong>One Off</strong> - This term refers to accessing the resource from Hoop Web Console.</li>
      </ul>

      <table>
        <thead>
          <tr>
            <th>Feature</th>
            <th>Native</th>
            <th>One Off</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>TLS Termination Proxy</td>
            <td>{renderIcon(finalConfig.features?.tlsTerminationProxy?.native)}</td>
            <td>{renderIcon(finalConfig.features?.tlsTerminationProxy?.oneOff)}</td>
            <td>The local proxy terminates the connection with TLS, enabling the connection with the remote server to be TLS encrypted.</td>
          </tr>
          <tr>
            <td>Audit</td>
            <td>{renderIcon(finalConfig.features?.audit?.native)}</td>
            <td>{renderIcon(finalConfig.features?.audit?.oneOff)}</td>
            <td>The gateway stores and audits the queries being issued by the client.</td>
          </tr>
          <tr>
            <td>Data Masking (Google DLP)</td>
            <td>{renderIcon(finalConfig.features?.dataMaskingGoogleDLP?.native)}</td>
            <td>{renderIcon(finalConfig.features?.dataMaskingGoogleDLP?.oneOff)}</td>
            <td>A policy can be enabled to mask sensitive fields dynamically when performing queries in the database.</td>
          </tr>
          <tr>
            <td>Data Masking (MS Presidio)</td>
            <td>{renderIcon(finalConfig.features?.dataMaskingMSPresidio?.native)}</td>
            <td>{renderIcon(finalConfig.features?.dataMaskingMSPresidio?.oneOff)}</td>
            <td>A policy can be enabled to mask sensitive fields dynamically when performing queries in the database.</td>
          </tr>
          <tr>
            <td>Guardrails</td>
            <td>{renderIcon(finalConfig.features?.guardrails?.native)}</td>
            <td>{renderIcon(finalConfig.features?.guardrails?.oneOff)}</td>
            <td>An intelligent layer of protection with smart access controls and monitoring mechanisms.</td>
          </tr>
          <tr>
            <td>Credentials Offload</td>
            <td>{renderIcon(finalConfig.features?.credentialsOffload?.native)}</td>
            <td>{renderIcon(finalConfig.features?.credentialsOffload?.oneOff)}</td>
            <td>The user authenticates via SSO instead of using database credentials.</td>
          </tr>
          <tr>
            <td>Interactive Access</td>
            <td>{renderIcon(finalConfig.features?.interactiveAccess?.native)}</td>
            <td>{renderIcon(finalConfig.features?.interactiveAccess?.oneOff)}</td>
            <td>Interactive access is available when using an IDE or connecting via a terminal to perform analysis exploration.</td>
          </tr>
        </tbody>
      </table>

      {finalConfig.resourceConfiguration?.credentials && <>
      <h2>Configuration</h2>
      <table>
        <thead>
          <tr>
            <th>Name</th>
            <th>Type</th>
            <th>Required</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          {Object.entries(finalConfig.resourceConfiguration.credentials).map(([key, credential]) => {
    if (typeof credential === 'string' || credential.hidden) return null;
    return <tr key={key}>
                <td>{credential.name}</td>
                <td>{credential.type}</td>
                <td>{credential.required ? 'yes' : 'no'}</td>
                <td>
                  {credential.description?.split(/(\[[^\]]+\]\([^)]+\))/).map((part, index) => {
      const linkMatch = part.match(/\[([^\]]+)\]\(([^)]+)\)/);
      if (linkMatch) {
        return <a key={index} href={linkMatch[2]} target="_blank" rel="noopener noreferrer">{linkMatch[1]}</a>;
      }
      return part;
    })}
                </td>
              </tr>;
  }).filter(Boolean)}
        </tbody>
      </table>
      </>}
    </div>;
};

<ConnectionTemplate
  config={{
"id": "kubernetes-eks",
"name": "Kubernetes EKS",
"description": "Manage Kubernetes resources through kubectl commands or native API access. This integration supports both CLI-based workflows and direct interaction with the Kubernetes API for full cluster control.",
"category": "cloud-services",
"icon-name": "kubernetes",
"tags": [
"containers",
"cli",
"aws"
],
"overview": {
"description": "Manage Kubernetes resources through kubectl commands or native API access. This integration supports both CLI-based workflows and direct interaction with the Kubernetes API for full cluster control."
},
"setupGuide": {
"accessMethods": {
  "webapp": true,
  "cli": true,
  "runbooks": true
}
},
"resourceConfiguration": {
"credentials": [
  {
    "type": "env-var",
    "required": false,
    "name": "KUBERNETES_CLUSTER_URL",
    "description": "The Kubernetes API Server URL. Defaults to in cluster value\nhttps://kubernetes.default.svc.cluster.local",
    "placeholder": "e.g.: https://kubernetes.default.svc.cluster.local"
  },
  {
    "type": "env-var",
    "required": false,
    "name": "KUBERNETES_INSECURE_SKIP_VERIFY",
    "description": "Controls whether a client verifies the server's certificate chain\nand host name. If is true, it accepts any certificate presented by the\nserver and any host name in that certificate. Defaults to false.",
    "placeholder": "false"
  },
  {
    "type": "env-var",
    "required": true,
    "name": "EKS_CLUSTER",
    "description": "The name of the EKS cluster",
    "placeholder": "my-eks-cluster"
  },
  {
    "type": "env-var",
    "required": false,
    "name": "EKS_AWS_REGION",
    "description": "The AWS Region associated with the cluster. If none is provided, \nread the env AWS_REGION from the agent.",
    "placeholder": "us-east-1"
  },
  {
    "type": "env-var",
    "required": "required",
    "name": "EKS_ROLE_ARN",
    "description": "The ARN of the role to assume when connecting to the EKS cluster. If\nnone is provided, the agent's IAM role will be used.",
    "placeholder": "arn:aws:iam::123456789012:role/MyEKSRole"
  },
  {
    "type": "env-var",
    "required": false,
    "name": "EKS_BINDING_USER_ROLE",
    "description": "The name assigned to the session when assuming a role. Use this field to dynamically map Kubernetes role bindings by specifying it as a subject in RoleBinding or ClusterRoleBinding resources.",
    "placeholder": "developer-group or"
  }
],
"type": "custom",
"subtype": "kubernetes-eks",
"command": [
  "bash"
]
},
"features": {
"tlsTerminationProxy": {
  "native": true,
  "oneOff": true
},
"audit": {
  "native": true,
  "oneOff": true
},
"dataMaskingGoogleDLP": {
  "native": false,
  "oneOff": false
},
"dataMaskingMSPresidio": {
  "native": true,
  "oneOff": true
},
"guardrails": {
  "native": true,
  "oneOff": true
},
"credentialsOffload": {
  "native": true,
  "oneOff": true
},
"interactiveAccess": {
  "native": true,
  "oneOff": true
}
},
"documentationConfig": {
"path": "quickstart/cloud-services/kubernetes/kubernetes-eks"
}
}}
/>

## EKS Access Setup

This guide explains how to enable access to an EKS cluster using AWS IAM roles
and Kubernetes RBAC.

### Role X and Role Y

* Role X: the Hoop agent's runtime identity (EC2, IRSA, or injected credentials)
* Role Y: the IAM role used only to authenticate to EKS

The Hoop agent uses Role X to assume Role Y and generate the EKS token.

### Step 1 — Create IAM Role Y

Create a role that represents the Kubernetes identity (Role Y). Use a clear
name like `arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-access-role`.

Example trust policy (allow Role X to assume Role Y):

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<role-x>"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

### Step 2 — Allow AssumeRole (Role X -> Role Y)

Attach a policy to Role X:

```json theme={null}
{
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-access-role"
}
```

### Step 3 — Create the EKS Access Entry

```sh theme={null}
aws eks create-access-entry \
  --cluster-name <cluster-name> \
  --principal-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-access-role \
  --type STANDARD \
  --username "eks-access-role:{{SessionNameRaw}}"
```

The username template becomes the Kubernetes username that RBAC evaluates.

### Step 4 — Create the Kubernetes ClusterRoleBinding

```sh theme={null}
kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks-access-role-cluster-admin
subjects:
- kind: User
  name: eks-access-role:developers
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
EOF
```

`roleRef` points to the Kubernetes role that will be granted. You can replace
`cluster-admin` with a least-privilege `ClusterRole` or use a namespace-scoped
`Role` and `RoleBinding` if you do not need cluster-wide access.

You can create multiple bindings for different groups or users. For example,
bind `eks-access-role:developers` to a read-only role and
`eks-access-role:admins` to an admin role.

The `developers` suffix is the session name value. It can represent a user,
group, or role binding name as long as it matches your RBAC subject.

### Configure the Hoop agent to assume Role Y

<img src="https://mintcdn.com/hoopdev-feat-new-runbook-parameters/9UvCrBcG2bkKisqL/images/quickstarts/kubeeks.png?fit=max&auto=format&n=9UvCrBcG2bkKisqL&q=85&s=1effebfc91afef07af77089f6b10aa4c" alt="Kubernetes EKS credentials configuration" width="748" height="1219" data-path="images/quickstarts/kubeeks.png" />

In the Hoop UI, select the `Kubernetes EKS` connection and set:

* `EKS_ROLE_ARN` to `arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-access-role`
* `EKS_BINDING_USER_ROLE` to your binding name (for example `developers`)

Save the configuration and reload the connection so the agent picks up the
new values.