# Kubernetes

## Introduction

The SAML.to [Command Line Interface](https://github.com/saml-to/cli) or [Assume AWS Role Action](https://github.com/saml-to/assume-aws-role-action) can be used for authentication to the Kubernetes Control Plane and be used with any tool that supports a `kubeconfig` file (such as `kubectl`, `helm`, `k9s`, etc.).

This document will detail how to use SAML.to to authenticate to the Kubernetes Control Plane for Tokenless authentication.

{% hint style="info" %}
This page is focused for AWS EKS, however if you've manually provisioned your own cluster, you'll need to first set up the [AWS IAM Authenticator](https://github.com/kubernetes-sigs/aws-iam-authenticator) on your Kubernetes cluster.
{% endhint %}

## Prerequisites

* [SAML.to has been Installed](https://docs.saml.to/installation) to your GitHub Organization or User Account
* [A role (with a SAML.to Trust Relationship)](https://docs.saml.to/configuration/service-providers/aws-federated-roles/adding-roles) that will be used to access Kubernetes
  * Grant yourself access in `saml-to.yml` for Testing purposes
  * At a minimum, allow the role the `eks:DescribeCluster` permission 
* A Kubernetes Cluster and the ability to run `kubectl` commands on it

## Create a Kubernetes Admin Role

Create a `kubernetes-admin` role (or whatever name you prefer) that has a [Trust Relationship to SAML.to](https://docs.saml.to/configuration/service-providers/aws-federated-roles/adding-roles).

At a minimum, the role needs permission to `eks:DescribeCluster`:

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "eks:DescribeCluster",
      "Resource": "arn:aws:eks:*:*:cluster/*"
    }
  ]
}
```

Then, in `saml-to.yml`, grant access to GitHub Users to assume that role:

```
      - name: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
        ...
        users:
          github:
            - SOME_GITHUB_USERNAME
            - ANOTHER_GITHUB_USERNAME
```

Ensure the role is functional:

```
$(saml-to assume kubernetes-admin)
aws eks describe-cluster --name THE_CLUSTER_NAME [--region THE_CLUSTER_REGION]
```

## Edit the Config Map

{% hint style="warning" %}
For brevity, these instructions will detail on how to map an IAM role to the `system:masters` group for full administrative control over Kubernetes.

In Kubernetes best practices, it is not recommended to grant access to `system:masters` .

Any group configuration is supported. Refer to the Kubernetes documentation for details on creating/using Cluster Roles and Cluster Role Bindings.
{% endhint %}

If the system was provisioned by AWS EKS, you should have an `aws-auth` ConfigMap in the `kube-system` namespace:

```
kubectl edit -n kube-system configmap/aws-auth
```

Add a section to `mapRoles` allowing the desired role access to the `system:masters` group:

<pre><code><strong>    - groups:
</strong><strong>        - system:masters
</strong><strong>      rolearn: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
</strong>      username: kubernetes-admin
</code></pre>

## Connect to Kubernetes Using the Role

### With The SAML.to CLI

<details>

<summary>Optional: Create or Update <code>.kubeconfig</code></summary>

Using the [SAML.to CLI](https://github.com/saml-to/cli) with the `--headless` flag will update your Terminal Session with temporary AWS Session Tokens:

```
$(saml-to assume kubernetes-admin --headless)
```

```
aws eks update-kubeconfig --name THE_CLUSTER_NAME
kbectl set-context THE_CLUSTER_ARN
```

</details>

Run `saml-to` before `kubectl` commands as you normally would:

```
$(saml-to assume kubernetes-admin --headless)
kubectl get all -A
```

Kubernetes will do the rest of the work and map the active role in the Terminal Session to a group permission level as defined in `mapRoles`!

{% hint style="info" %}
Running `$(saml-to ...)` before **every** Kubectl command is **unnecessary**.&#x20;

The credentials will stay valid in your Terminal Session for how-ever long is defined in `saml-to.yml` the property value of `https://aws.amazon.com/SAML/Attributes/SessionDuration`, which defaults to 1 hour.

If the session expires, simply run the `saml-to assume ... --headless` command again!
{% endhint %}

### Within GitHub Actions

A repository can also be granted access to the role. In your user's or organizations `saml-to.yml`, grant access for the Repository to gain access to the role:

```
      - name: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
        ...
        repos:
          github:
            - name: THE_REPO_NAME
            - name: SOME_OTHER_ORG/SOME_OTHER_REPO
```

Then, in the GitHub action, use the [Assume AWS Role Action](https://github.com/saml-to/assume-aws-role-action) to assume the role:

```
      - name: Assume Role
        uses: saml-to/assume-aws-role-action@v1
        with:
          role: arn:aws::YOUR_ACCOUNT_ID:role/kubernetes-admin
          region: THE_CLUSTER_REGION
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Login to Kubernetes
        run: aws eks update-kubeconfig --name THE_CLUSTER_NAME
        
      - name: Run a Kubernetes Command
        run: kubectl apply -f some-manifest.yaml
```

## Questions/Comments/Issues?

[Contact us](https://saml.to/contact)!


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.saml.to/configuration/service-providers/aws-federated-roles/assuming-roles/kubernetes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.