Create IAM Role for EBS CSI Driver (AWS Only)¶

In this section you will create an IAM role for the service account that the Elastic Block Store (EBS) Container Storage Interface (CSI) driver will run with. EBS CSI driver will need this in order to have permissions to manage the lifecycle of EBS volumes for persistent volumes.

Fast Forward

If you are deploying EKF on Google Cloud or Azure, skip this guide and proceed to the What’s Next section.

Fast Forward

If you already have an IAM role for EBS CSI Driver, expand this box to fast-forward.

Go to your GitOps repository, inside your rok-tools management environment:

root@rok-tools:~# cd ~/ops/deployments
Restore the required context from previous sections:

root@rok-tools:~/ops/deployments# source <(cat deploy/env.{envvars-aws,eks-cluster})

root@rok-tools:~/ops/deployments# export AWS_DEFAULT_REGION EKS_CLUSTER
Specify the name of the IAM role for the EBS CSI driver:

root@rok-tools:~/ops/deployments# export IAM_EBS_CSI_DRIVER_ROLE=<ROLE>

Replace <ROLE> with the name of the IAM role for the EBS CSI driver, for example:

root@rok-tools:~/ops/deployments# export IAM_EBS_CSI_DRIVER_ROLE=rok-${AWS_DEFAULT_REGION?}\ > -${EKS_CLUSTER?}-ebs-csi-driver
Save your state:

root@rok-tools:~/ops/deployments# rok-j2 deploy/env.iam-ebs-csi-driver.j2 \ > -o deploy/env.iam-ebs-csi-driver
Commit your changes:

root@rok-tools:~/ops/deployments# git commit -am "Create IAM Role for EBS CSI Driver"
Proceed to the Verify section.

What You’ll Need ¶

A configured management environment.
Your clone of the Arrikto GitOps repository.
An existing EKS cluster.

Check Your Environment ¶

To create this role, you are going to deploy a CloudFormation stack. 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 the EBS CSI driver 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 IAM Role for EBS CSI Driver Automatically (preferred)¶

Create an IAM role for the EBS CSI driver by following the on-screen instructions on the rok-deploy user interface.

If rok-deploy is not already running, start it with:

root@rok-tools:~# rok-deploy --run-from iam-ebs-csi-driver

Proceed to the Summary section.

Option 2: Create IAM Role for EBS CSI Driver Manually ¶

If you want to create an IAM role for the EBS CSI driver manually, follow the instructions below.

Procedure ¶

Go to your GitOps repository, inside your rok-tools management environment:

root@rok-tools:~# cd ~/ops/deployments
Restore the required context from previous sections:

root@rok-tools:~/ops/deployments# source <(cat deploy/env.{envvars-aws,eks-cluster,\ > eks-identity})

root@rok-tools:~/ops/deployments# export AWS_ACCOUNT_ID AWS_DEFAULT_REGION \ > EKS_CLUSTER EKS_CLUSTER_OIDC
Specify the IAM role name and description for the EBS CSI driver:

root@rok-tools:~/ops/deployments# export IAM_EBS_CSI_DRIVER_ROLE=rok-${AWS_DEFAULT_REGION?}\ > -${EKS_CLUSTER?}-ebs-csi-driver

root@rok-tools:~/ops/deployments# export IAM_EBS_CSI_DRIVER_ROLE_DESC="EBS CSI Driver"
Verify that the IAM role name you specified is not longer than 64 characters:

root@rok-tools:~/ops/deployments# ((${#IAM_EBS_CSI_DRIVER_ROLE}<=64)) && echo OK || echo FAIL OK

Troubleshooting

The output of the command is FAIL

Go back to step 3 and specify a shorter name. Ensure the new name is not already in use.
Set the name of the CloudFormation stack you will deploy:

root@rok-tools:~/ops/deployments# export IAM_EBS_CSI_DRIVER_CF=rok-${AWS_DEFAULT_REGION?}\ > -${EKS_CLUSTER?}-ebs-csi-driver
Verify that the CloudFormation stack name you specified is not longer than 128 characters:

root@rok-tools:~/ops/deployments# ((${#IAM_EBS_CSI_DRIVER_CF}<=128)) && echo OK || echo FAIL OK

Troubleshooting

The output of the command is FAIL

Go back to step 5 and specify a shorter name. Ensure the new name is not already in use.

Generate the AWS CloudFormation stack:

root@rok-tools:~/ops/deployments# j2 rok/eks/ebs-csi-driver-role.yaml.j2 \
> -o rok/eks/ebs-csi-driver-role.yaml

Alternatively, download the ebs-csi-driver-role CloudFormation template provided below and use it locally.

ebs-csi-driver-role.yaml.j2

1AWSTemplateFormatVersion: '2010-09-09'
2
3Description: EBS CSI Driver IAM Role
4-23
4
5Metadata:
Rok::StackName: {{IAM_EBS_CSI_DRIVER_CF}}
7
8Resources:
EBSCSIDriverRole:
  Type: AWS::IAM::Role
  Properties:
    RoleName: {{IAM_EBS_CSI_DRIVER_ROLE}}
    AssumeRolePolicyDocument:
      Version: '2012-10-17'
      Statement:
        - Effect: Allow
          Principal:
            Federated: arn:aws:iam::{{AWS_ACCOUNT_ID}}:oidc-provider/{{EKS_CLUSTER_OIDC}}
          Action: sts:AssumeRoleWithWebIdentity
          Condition:
            StringEquals:
              {{EKS_CLUSTER_OIDC}}:aud: sts.amazonaws.com
              {{EKS_CLUSTER_OIDC}}:sub: system:serviceaccount:kube-system:ebs-csi-controller-sa
    Description: {{IAM_EBS_CSI_DRIVER_ROLE_DESC}}
    ManagedPolicyArns:
      - arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy

Save your state:

root@rok-tools:~/ops/deployments# rok-j2 deploy/env.iam-ebs-csi-driver.j2 \ > -o deploy/env.iam-ebs-csi-driver
Commit your changes:

root@rok-tools:~/ops/deployments# git commit -am "Create IAM Role for EBS CSI Driver"
Deploy the CloudFormation stack:

root@rok-tools:~/ops/deployments# aws cloudformation deploy \ > --stack-name ${IAM_EBS_CSI_DRIVER_CF?} \ > --template-file rok/eks/ebs-csi-driver-role.yaml \ > --capabilities CAPABILITY_NAMED_IAM Waiting for changeset to be created.. Waiting for stack create/update to complete Successfully created/updated stack - rok-us-west-2-arrikto-cluster-ebs-csi-driver
Troubleshooting
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-west-2:123456789012:stack/rok-us-west-2-arrikto-cluster-ebs-csi-driver

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 rok-us-west-2-arrikto-cluster-ebs-csi-driver

describe 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 ${IAM_EBS_CSI_DRIVER_CF?}

A stack event like the following:

{ "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/rok-us-west-2-arrikto-cluster-ebs-csi-driver/599bc930-7b3f-11eb-ac1c-029efe3a90a0", "EventId": "EBSCSIDriverRole-CREATE_FAILED-2021-03-02T10:09:27.457Z", "StackName": "rok-us-west-2-arrikto-cluster-ebs-csi-driver", "LogicalResourceId": "EBSCSIDriverRole", "PhysicalResourceId": "", "ResourceType": "AWS::IAM::Role", "Timestamp": "2021-03-02T10:09:27.457000+00:00", "ResourceStatus": "CREATE_FAILED", "ResourceStatusReason": "rok-us-west-2-arrikto-cluster-ebs-csi-driver already exists", "ResourceProperties": "{\"ManagedPolicyArns\":[\"arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy\"],\"RoleName\":\"rok-us-west-2-arrikto-cluster-ebs-csi-driver\",\"Description\":\"EBS CSI Driver\",\"AssumeRolePolicyDocument\":{\"Version\":\"2012-10-17\",\"Statement\":[{\"Condition\":{\"StringEquals\":{\"oidc.eks.us-west-2.amazonaws.com/id/352A7999E682D224D5A47B738D375237:aud\":\"sts.amazonaws.com\",\"oidc.eks.us-west-2.amazonaws.com/id/352A7999E682D224D5A47B738D375237:sub\":\"system:serviceaccount:kube-system:ebs-csi-controller-sa\"}},\"Action\":\"sts:AssumeRoleWithWebIdentity\",\"Effect\":\"Allow\",\"Principal\":{\"Federated\":\"arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-west-2.amazonaws.com/id/352A7999E682D224D5A47B738D375237\"}}]}}" }

means that the IAM role that the AWS CloudFormation stack defines already exist, leading to name conflicts.

To proceed, go back to step 3, specify a different name for resources that already exist, and follow the rest of the guide.

A stack event like the following:

{ "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/rok-us-west-2-arrikto-cluster-ebs-csi-driver/415eef80-7b46-11eb-b047-06980f530fec", "EventId": "EBSCSIDriverRole-CREATE_FAILED-2021-03-02T10:58:54.216Z", "StackName": "rok-us-west-2-arrikto-cluster-ebs-csi-driver", "LogicalResourceId": "EBSCSIDriverRole", "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/rok-us-west-2-arrikto-cluster-ebs-csi-driver", "ResourceProperties": "{\"ManagedPolicyArns\":[\"arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy\"],\"RoleName\":\"rok-us-west-2-arrikto-cluster-ebs-csi-driver\",\"Description\":\"EBS CSI Driver\",\"AssumeRolePolicyDocument\":{\"Version\":\"2012-10-17\",\"Statement\":[{\"Condition\":{\"StringEquals\":{\"oidc.eks.us-west-2.amazonaws.com/id/352A7999E682D224D5A47B738D375237:aud\":\"sts.amazonaws.com\",\"oidc.eks.us-west-2.amazonaws.com/id/352A7999E682D224D5A47B738D375237:sub\":\"system:serviceaccount:kube-system:ebs-csi-controller-sa\"}},\"Action\":\"sts:AssumeRoleWithWebIdentity\",\"Effect\":\"Allow\",\"Principal\":{\"Federated\":\"arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-west-2.amazonaws.com/id/352A7999E682D224D5A47B738D375237\"}}]}}" }

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-west-2:123456789012:stack/rok-us-west-2-arrikto-cluster-ebs-csi-driver/671606f0-eb2b-11eb-8afb-0217413c9ed2 is in ROLLBACK_COMPLETE state and can not be updated.

delete the stack and deploy it again.
Mark your progress:

root@rok-tools:~/ops/deployments# export DATE=$(date -u "+%Y-%m-%dT%H.%M.%SZ")

root@rok-tools:~/ops/deployments# git tag \ > -a deploy/${DATE?}/release-2.0/iam-ebs-csi-driver \ > -m "Create IAM Role for EBS CSI Driver"

Verify ¶

Go to your GitOps repository, inside your rok-tools management environment:

root@rok-tools:~# cd ~/ops/deployments
Restore the required context from previous sections:

root@rok-tools:~/ops/deployments# source deploy/env.iam-ebs-csi-driver

root@rok-tools:~/ops/deployments# export IAM_EBS_CSI_DRIVER_ROLE
Verify that the IAM role exists:

root@rok-tools:~/ops/deployments# aws iam get-role \ > --role-name ${IAM_EBS_CSI_DRIVER_ROLE?} >/dev/null \ > && echo OK OK
Verify that the IAM role has the AmazonEBSCSIDriverPolicy policy attached:

root@rok-tools:~/ops/deployments# POLICIES=$(aws iam list-attached-role-policies \ > --role-name ${IAM_EBS_CSI_DRIVER_ROLE?} \ > --query "length(AttachedPolicies[?PolicyArn=='arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy'])") \ > && ((POLICIES==1)) \ > && echo OK \ > || echo FAIL OK

Summary ¶

You have successfully created the IAM role for the EBS CSI driver.

What’s Next ¶

The next step is to deploy the EBS CSI driver.

Deploy EBS CSI Driver (AWS Only)