Create EKS Cluster IAM Role¶
EKS clusters interact with multiple AWS APIs and services to manage cloud resources. To grant Amazon EKS sufficient permissions to perform these actions, you need to create an IAM role. This guide will guide you through creating this role for your cluster using AWS CloudFormation and GitOps.
Fast Forward
If you already have an IAM role for your cluster, expand this box to fast-forward.
Specify the name of the IAM role for your cluster. Replace
<CLUSTER_ROLE>
with your cluster role name:root@rok-tools:~# export EKS_IAM_CLUSTER_ROLE=<CLUSTER_ROLE>Go to your GitOps repository, inside your
rok-tools
management environment:root@rok-tools:~# cd ~/ops/deploymentsSave your state:
root@rok-tools:~/ops/deployments# j2 deploy/env.eks-iam-cluster.j2 \ > -o deploy/env.eks-iam-clusterCommit your changes:
root@rok-tools:~/ops/deployments# git commit -am "Create EKS Cluster IAM Role"Proceed to the Verify section.
See also
Choose one of the following options to create an IAM role for your cluster:
- Option 1: Create EKS Cluster IAM Role Automatically (preferred).
- Option 2: Create EKS Cluster IAM Role Manually.
Overview
What You’ll Need¶
- A configured management environment.
- Your clone of the Arrikto GitOps repository.
Check Your Environment¶
When working with AWS CloudFormation stacks to manage resources, not only do you need sufficient permissions on AWS CloudFormation, but also on the underlying resources that are defined in the template.
In order to create an IAM role with proper IAM policies attached to it for your EKS cluster using AWS CloudFormation you need permissions for the following actions:
- Deploy AWS CloudFormation stacks.
- Create IAM roles.
- Attach managed IAM policies to IAM roles.
Note
If you do not have the above permissions, contact your AWS administrator to grant sufficient permissions to your IAM user or deploy the below AWS CloudFormation stack for you.
Option 1: Create EKS Cluster IAM Role Automatically (preferred)¶
Create an IAM role for your cluster by following the on-screen instructions on
the rok-deploy
user interface.
If rok-deploy
is not already running, start it with:
Proceed to the Summary section.
Option 2: Create EKS Cluster IAM Role Manually¶
If you want to create an IAM role for your cluster manually, follow the instructions below.
Procedure¶
Go to your GitOps repository, inside your
rok-tools
management environment:root@rok-tools:~# cd ~/ops/deploymentsSet the name for the EKS cluster IAM role:
root@rok-tools:~/ops/deployments# export EKS_IAM_CLUSTER_ROLE=eksClusterRoleSet the name of the CloudFormation stack you will deploy:
root@rok-tools:~/ops/deployments# export EKS_IAM_CLUSTER_CF=eksClusterRoleGenerate an AWS CloudFormation stack:
root@rok-tools:~/ops/deployments# j2 rok/eks/eks-cluster-iam-role.yaml.j2 \ > -o rok/eks/eks-cluster-iam-role.yamlAlternatively, download the
eks-cluster-iam-role.yaml
AWS CloudFormation Template provided below and use it locally.eks-cluster-iam-role.yaml.j21 AWSTemplateFormatVersion: "2010-09-09" 2 3 Description: Amazon EKS - Cluster Role 4-25 4 5 Metadata: 6 Rok::StackName: {{EKS_IAM_CLUSTER_CF}} 7 8 Resources: 9 eksClusterRole: 10 Type: AWS::IAM::Role 11 Properties: 12 AssumeRolePolicyDocument: 13 Version: '2012-10-17' 14 Statement: 15 - Effect: Allow 16 Principal: 17 Service: 18 - eks.amazonaws.com 19 Action: 20 - sts:AssumeRole 21 ManagedPolicyArns: 22 - arn:aws:iam::aws:policy/AmazonEKSClusterPolicy 23 RoleName: {{EKS_IAM_CLUSTER_ROLE}} 24 25 Outputs: 26 RoleArn: 27 Description: The role that Amazon EKS will use to create AWS resources for Kubernetes clusters 28 Value: !GetAtt eksClusterRole.Arn Save your state:
root@rok-tools:~/ops/deployments# j2 deploy/env.eks-iam-cluster.j2 \ > -o deploy/env.eks-iam-clusterCommit your changes:
root@rok-tools:~/ops/deployments# git commit -am "Create EKS Cluster IAM Role"Deploy the AWS CloudFormation stack to create the EKS cluster IAM role and wait for it to complete successfully:
root@rok-tools:~/ops/deployments# aws cloudformation deploy \ > --stack-name ${EKS_IAM_CLUSTER_CF?} \ > --template-file rok/eks/eks-cluster-iam-role.yaml \ > --capabilities CAPABILITY_NAMED_IAM Waiting for changeset to be created.. Waiting for stack create/update to complete Successfully created/updated stack - eksClusterRoleTroubleshooting
AccessDenied
If the above command fails with an error message similar to the following:
An error occurred (AccessDenied) when calling the DescribeStacks operation: User: arn:aws:iam::123456789012:user/user is not authorized to perform: cloudformation:DescribeStacks on resource: arn:aws:cloudformation:us-east-1:123456789012:stack/eksClusterRole/*it means that your IAM user does not have sufficient permissions to perform an action necessary to deploy an AWS CloudFormation stack.
To proceed, Check Your Environment and contact your AWS administrator to grant sufficient permissions to your IAM user or deploy the AWS CloudFormation stack for you.
Failed to create/update the stack
If the above command fails with an error message similar to the following:
Failed to create/update the stack. Run the following command to fetch the list of events leading up to the failure aws cloudformation describe-stack-events --stack-name eksClusterRoledescribe the events of the CloudFormation stack to identify the root cause of the failure:
root@rok-tools:~/ops/deployments# aws cloudformation describe-stack-events --stack-name ${EKS_IAM_CLUSTER_ROLE?}A stack event like the following:
{ "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/eksClusterRole/599bc930-7b3f-11eb-ac1c-029efe3a90a0", "EventId": "eksClusterRole-CREATE_FAILED-2021-03-02T10:09:27.457Z", "StackName": "eksClusterRole", "LogicalResourceId": "eksClusterRole", "PhysicalResourceId": "", "ResourceType": "AWS::IAM::Role", "Timestamp": "2021-03-02T10:09:27.457000+00:00", "ResourceStatus": "CREATE_FAILED", "ResourceStatusReason": "eksClusterRole already exists", "ResourceProperties": "{\"ManagedPolicyArns\":[\"arn:aws:iam::aws:policy/AmazonEKSClusterPolicy\"],\"RoleName\":\"eksClusterRole\",\"AssumeRolePolicyDocument\":{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":[\"sts:AssumeRole\"],\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"eks.amazonaws.com\"]}}]}}" }means that one or more resources that the AWS CloudFormation stack defines already exist, leading to name conflicts.
To proceed, use the existing role, assuming it has the right policies attached, or create a new one by changing the variable’s value in step 2 and following the rest of the guide.
A stack event like the following:
{ "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/eksClusterRole/415eef80-7b46-11eb-b047-06980f530fec", "EventId": "eksClusterRole-CREATE_FAILED-2021-03-02T10:58:54.216Z", "StackName": "eksClusterRole", "LogicalResourceId": "eksClusterRole", "PhysicalResourceId": "", "ResourceType": "AWS::IAM::Role", "Timestamp": "2021-03-02T10:58:54.216000+00:00", "ResourceStatus": "CREATE_FAILED", "ResourceStatusReason": "API: iam:CreateRole User: arn:aws:iam::123456789012:user/user is not authorized to perform: iam:CreateRole on resource: arn:aws:iam::123456789012:role/eksClusterRole", "ResourceProperties": "{\"ManagedPolicyArns\":[\"arn:aws:iam::aws:policy/AmazonEKSClusterPolicy\"],\"RoleName\":\"eksClusterRole\",\"AssumeRolePolicyDocument\":{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":[\"sts:AssumeRole\"],\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"eks.amazonaws.com\"]}}]}}" }means that your IAM user does not have sufficient permissions to create the resources that the AWS CloudFormation stack defines.
To proceed, Check Your Environment and contact your AWS administrator to grant your IAM user sufficient permissions or deploy the AWS CloudFormation stack for you.
ValidationError
If the above command fails with an error message similar to the following:
An error occurred (ValidationError) when calling the CreateChangeSet operation: Stack:arn:aws:cloudformation:us-east-1:123456789012:stack/eksClusterRole/671606f0-eb2b-11eb-8afb-0217413c9ed2 is in ROLLBACK_COMPLETE state and can not be updated.delete the stack and deploy it again.
Verify¶
Go to your GitOps repository, inside your
rok-tools
management environment:root@rok-tools:~# cd ~/ops/deploymentsRestore the required context from previous sections:
root@rok-tools:~/ops/deployments# source <(cat deploy/env.eks-iam-cluster)root@rok-tools:~/ops/deployments# export EKS_IAM_CLUSTER_ROLEVerify that the EKS cluster IAM role exists:
root@rok-tools:~/ops/deployments# aws iam get-role \ > --role-name ${EKS_IAM_CLUSTER_ROLE?} \ > --query Role.RoleName \ > --output text && echo OK eksClusterRole OKVerify that your EKS cluster IAM role has the
AmazonEKSClusterPolicy
policy attached:root@rok-tools:~/ops/deployments# POLICIES=$(aws iam list-attached-role-policies \ > --role-name ${EKS_IAM_CLUSTER_ROLE?} \ > --query 'length(AttachedPolicies[? > PolicyArn==`arn:aws:iam::aws:policy/AmazonEKSClusterPolicy`])') && \ > ((POLICIES==1)) && \ > echo OK || \ > echo FAIL OK
Summary¶
You have successfully created an IAM role for your new EKS cluster using AWS CloudFormation and GitOps.
What’s Next¶
The next step is to create an IAM role for the nodes of your new EKS cluster.