# 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)!