.. _eks_access_role:

=========================
Using the EKS Access Role
=========================

What is the Access Role?
------------------------
By EKS default, only the IAM entity that creates an EKS cluster is given ``system:masters`` permission. To add other IAM users to your clusters you must manually add them to the cluster's ``aws-auth`` ConfigMap (see `this guide <https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html>`_). However, k9 has automated this process.

* As part of ``k9 create cluster`` an IAM role is created inside of the EKS CloudFormation stack named {{clusterName}}-eks-access-role.
* Next, k9 will edit the ``aws-auth`` ConfigMap to associate the eks-access-role ARN with a kubernetes user. user name: ``eks-access-role-user``
* Then, k9 creates a ClusterRole with full access to all resources. name: ``eks-access-ClusterRole``
* Finally, k9 creates a ClusterRoleBinding to associate the user from ``aws-auth`` with the new ClusterRole. name: ``eks-access-ClusterRoleBinding``

This means that once a user assumes the access role and connects to the cluster, they will have full access to all resources.

Assuming the Role
-----------------
First, the entity (user or another role) who wishes to assume the access role must be added to the eks-access-role's trust policy. This must be done manually through the AWS console by someone with permissions to edit IAM resources.

Add the entity's ARN to the Trust Policy:

::

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        // add an entry like below
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "<ASSUMING_ENTITY_ARN>"
            },
            "Action": "sts:AssumeRole",
            "Condition": {}
        }
        ]
    }

If a role is assuming the access role, you may need to add an inline policy to that role allowing it to assume the access role.

::

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::<ACCESS_ROLE_ARN>"
        }
        ]
    }

AWS cli command to assume the role.

::

    aws sts assume-role --role-arn "<ACCESS_ROLE_ARN>" --role-session-name <SESSION_NAME>

Connect to the cluster

::

    aws eks update-kubeconfig --name <CLUSTER_NAME> --role-arn <eks-access-role-arn>

Now kubectl commands should have full access permissions.

Running k9 using a cluster access role
--------------------------------------

In order to run k9 commands as an IAM entity other than the one used to create the clusters, you must configure your access to the clusters. Add the current IAM entity ARN to each cluster's trust policy, as describe above. Then run

::

    k9 configure access -n clusterName

This command creates an entry in the ``aws-auth`` ConfigMap, associating the current IAM identity with the ``eks-access-role-user``. After configuring access to all clusters, k9 can be run normally.

Source Code
-----------

.. autofunction:: k9.cluster_init.create_access_role