> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/guides-and-examples/advanced-guides/how-to-configure-access-to-your-k8s-cluster.md).

# Configure access to your K8s cluster

Learn how to create access controls and view your cluster using kubectl, K9s, and eksctl

This document walks you through giving a user access to a Release EKS cluster, accessing the cluster, and viewing the cluster using K9s and `kubectl`.

## Definitions

* AWS: Amazon Web Services
* IAM: Identity and Access Management
* EKS: Elastic Kubernetes Service
* ARN: Amazon Resource Name

## How to add an IAM user to your self-hosted EKS cluster

### Prerequisites

To add an IAM user to your cluster, you will need the following:

* Administrator privileges to the EKS cluster.
* The ARN for the user you're granting access to (looks like `aws:arn:iam::ACCTID:user/USERNAME`).
* A kubeconfig file for the EKS cluster. If you do not have an existing kubeconfig file, generate one by following the steps in the [create the kubeconfig file](#create-the-kubeconfig-file) section below.

We recommend you [install K9s](https://github.com/derailed/k9s).

### Steps

You can grant a user access to a cluster in two ways: Using the K9s visual editor or the command line.

#### Using the K9s visual editor

1. Start up K9s and use the `:namespace` command to access the `kube-system` namespace as shown below:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-c3fe9b65d883cc64fc2d53d6ff9600cd2a34e3ac%2Fimage6.png?alt=media)

2. Use the `:configmap` command to access the `aws_auth` configuration:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-d2a64925d6f3ab7b88c1c770456bedf12b3596e0%2Fk9s_aws_auth.png?alt=media)

3. Find `aws_auth` and hit the `e` command to `edit` the file. Insert the user as shown below:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-910950fa6f89a5fd996c101a2cdab5653a93bbd7%2Fk9s_add_aws_user.png?alt=media)

4. Copy and paste the section outlined in red above to create a new user. Be careful to edit the ARN correctly to allow the user to access the system. In this example, the users are administrators, but you can consult the [documentation for Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/%23default-roles-and-role-bindings) to define default roles like viewers and ops users.
5. Save the file and then verify the changes by using the `d` (describe) command to view the document that was applied.

### Using the CLI

Follow the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) to complete the same procedure done visually above. The steps are the same:

1. Download the existing `aws_auth` configmap from the `kube-system` namespace.
2. Edit the `mapUsers` field and add the user.
3. Save the file.
4. Apply the changes to the cluster.
5. Verify the changes have been made.

## How to access the cluster

### Prerequisites

To access the cluster once you have been added to the configmap, you'll need:

* Your AWS IAM credentials for the account where the EKS cluster is running.
* The EKS cluster name and region.
* Command line utility `eksctl` installed. You can follow these [installation instructions](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html).
* Command line utility `kubectl` installed. You can follow these [installation instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl/).

We recommend you [install K9s](https://github.com/derailed/k9s).

### Steps

Once you have been added to the cluster configmap and you have the prerequisites installed, you can gain access to the cluster to view status and logs, and to perform other tasks you have permissions for.

#### Create the kubeconfig file

Have your AWS credentials available in configuration files, in your environment variables, or in named profiles.

Follow the steps in the AWS [configuration basics guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html). The `eksctl` binary respects the usual configuration directives that the AWS CLI uses. This document assumes the default credentials are available. If you wish to specify a set of credentials other than default, you will need to specify them appropriately.

Your credentials will authenticate you as a user or role in the account and region where the EKS cluster is available. You may have a user role configured in a different account and then assume a role in the EKS cluster account, or you may have a very complicated setup with [OAuth](https://oauth.net/2/) or [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) integrations, which is beyond the scope of this document.

To generate your kubeconfig file, type the following where your `eksctl` binary is available and your AWS credentials are specified by default:

```
eksctl utils write-kubeconfig --cluster CLUSTERNAME --region REGION
```

#### K9s instructions

We recommend that you use the K9s interface for visualization and viewing logs and status. Administrating the cluster from the K9s interface is also possible. Here are a few use cases we’ve found useful.

**View application namespaces**

You can use the `:namespaces` command and filter with the `/release` search to list applications running from Release environments as shown below:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-47a829298ca057269cd600e31c108d1c8ed734f8%2Fimage8%20\(3\)%20\(1\).png?alt=media)

**View pods for a Release environment**

You can then either click on a namespace or type the `:pods` command to view the applications in the Release environment as shown below:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-140f2604cd88d785ba386afc7145b52aaec64476%2Fimage1%20\(3\)%20\(1\).png~merged?alt=media)

**View logs for an application container in a Release environment**

You can use the `l` (or logs) command to view what is happening in your application:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-ab2a5c37445f4317018c2a19035facb012a92cc9%2Fk9s_view_logs.png?alt=media)

**Access the container system (if available)**

If you have sufficient privileges and configuration, use the `s` (or shell) command to enter the running container, if available:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e1182f297a4f2c63830027ea37af8a080f1bab30%2Fimage7%20\(2\)%20\(1\).png?alt=media)

**Exit K9s**

Use the familiar VI controls to `:quit` the K9s application:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-0a5d6740953b64b85d2306decf0739a942f4fbe8%2Fk9s_exit.png?alt=media)

#### CLI instructions

Use CLI commands to examine the state of the cluster, but we generally don't recommend using them to change settings or start or stop pods or services, as this should be handled by the Release website or CLI tool.

You can find great [kubectl documentation](https://kubernetes.io/docs/reference/kubectl/cheatsheet/) in the Kubernetes documentation.

**`kubectl get namespaces`**

Remember that a namespace in Kubernetes maps to a Release environment.

**`kubectl get pods -n RELEASEENV`**

Remember that a pod in Kubernetes maps to a Release service in the environment.

**`kubectl get logs RELEASESERVICE`**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/guides-and-examples/advanced-guides/how-to-configure-access-to-your-k8s-cluster.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.