Create a Role with AWS CLI - Complete Guide

avatar

Borislav Hadzhiev

Sun Sep 19 20217 min read

Table of Contents #

  1. Create an IAM role with AWS CLI
  2. Attach an Inline Policy to an IAM role with AWS CLI
  3. Attach a Managed Policy to an IAM role with AWS CLI
  4. Update a Role's Inline Policies with AWS CLI
  5. Update a Role's Managed Policies with AWS CLI
  6. Delete an Inline Policy of a Role with AWS CLI
  7. Delete a Managed Policy of a Role with AWS CLI

Create an IAM role with AWS CLI #

An IAM role is a collection of policies, that grant specific permissions to access AWS resources.

Before we create the role, we must define a trust policy for it. The trust policy specifies which IAM entities (accounts, users, roles, services) can assume the role.

In our case we will create a role that is to be assumed by the lambda service. Let's create a trust policy that allows lambda to assume the role. Create a file called trust-policy.json:

trust-policy.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

To create an IAM role, open your terminal in the directory where trust-policy.json is stored and use the create-role command.

shell
aws iam create-role --role-name role-example --assume-role-policy-document file://trust-policy.json

create role aws cli

When passing local files as --parameters to an AWS CLI command, prefix human-readable files with file:// and binary (non human-readable) files with fileb://.

Attach an Inline Policy to an IAM role with AWS CLI #

At this point our role can be assumed by the lambda service, but it does not grant any permissions.

To grant permissions to an IAM role we must attach a policy to the role.

IAM policies define specific permissions needed to access AWS resources and can be associated with roles, users or groups.

To attach an inline policy to an IAM role, we have to:

  1. write and store the policy in a json file on the local file system
  2. run the AWS CLI put-role-policy command

This is an example inline policy that grants permissions to List* and GetItem actions on all dynamodb tables. Save the contents of the policy in a file named read-dynamodb.json:

read-dynamodb.json
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "dynamodb:List*", "dynamodb:GetItem" ], "Effect": "Allow", "Resource": "*" } ] }
It is a best practice to allocate the least permissions that enable you to get the job done. Generally using * characters makes the policies too broad and grants more permissions than necessary.

The next step is to attach the policy to our IAM role. Open your terminal in the directory where the read-dynamodb.json file is stored and run the put-role-policy command:

shell
aws iam put-role-policy --role-name role-example --policy-name read-dynamodb --policy-document file://read-dynamodb.json

attach inline policy to role

Let's verify that the inline policy is successfully attached to the role, by running the list-role-policies command:

shell
aws iam list-role-policies --role-name role-example

inline policy attached to role

Inline policies have a on-to-one relationship with the Principal (role, user or group). This means that if we delete the IAM role, the inline policy also gets deleted.

Attach a Managed Policy to an IAM role with AWS CLI #

Managed policies in are of 2 types:

  • AWS managed policies - created and managed by AWS. They aim to provide permissions for the most common use cases.
  • Customer managed policies - created and managed by the user. Like AWS managed policies, they can be reused and attached to multiple principal entities, as opposed to inline policies.

Let's attach an AWS managed policy that grants read and write permissions to access the CloudWatch service to our role.

To attach an AWS managed policy to an IAM role with the AWS CLI, use the attach-role-policy command.

shell
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole --role-name role-example

attach aws managed policy to role

To verify the AWS managed policy has been successfully attached to an IAM role, run the list-attached-role-policies command.

shell
aws iam list-attached-role-policies --role-name role-example

list managed policies of role

To attach a customer managed policy to an IAM role with the AWS CLI, we have to:

  1. Create the managed policy and take note of the policy's arn
  2. Use the attach-role-policy command to attach the policy to the role

Let's create a customer managed policy, that grants S3 read permissions to all buckets in the account.

Store the following json into a file called read-s3.json:

read-s3.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:Get*", "s3:List*" ], "Resource": "*" } ] }

To create the customer managed policy, open your terminal in the directory where you stored the read-s3.json file and run the create-policy command:

shell
aws iam create-policy --policy-name read-s3 --policy-document file://read-s3.json

create customer managed policy

Copy and paste the role ARN into a notepad, because we will need it when attaching the policy to our role.

To attach a customer managed policy to an IAM role, using the AWS CLI, run the attach-role-policy command.

shell
aws iam attach-role-policy --policy-arn YOUR_POLICY_ARN --role-name role-example

attach customer managed policy to role

To verify the customer managed policy has been successfully attached to the IAM role, run the list-attach-role-policies command.

shell
aws iam list-attached-role-policies --role-name role-example

list all managed policies of role

Update a Role's Inline Policies with AWS CLI #

To update a role's inline policy using the AWS CLI, we have to know the name of the inline policy. Let's get the name by running the list-role-policies command:

shell
aws iam list-role-policies --role-name role-example

inline policy attached to role

Let's remove the List* action from our read-dynamodb.json. Update the file to look like:

read-dynamodb.json
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "dynamodb:GetItem" ], "Effect": "Allow", "Resource": "*" } ] }

Now open your terminal in the directory where the read-dynamodb.json file is stored and execute the put role policy command to update the inline policy attached to the role:

shell
aws iam put-role-policy --role-name role-example --policy-name read-dynamodb --policy-document file://read-dynamodb.json

update inline policy of role

To verify the inline policy of the role has been updated, run the get role policy command:

shell
aws iam get-role-policy --role-name role-example --policy-name read-dynamodb

verify inline policy updated

The output of the command shows that the List* action has successfully been removed from the inline policy.

Update a Role's Managed Policies with AWS CLI #

We can only update customer managed AWS Policies.

To update a customer managed policy with AWS CLI, we have to:

  1. Get the ARN of the policy
  2. update the json file that stores the contents of the customer managed policy
  3. update the policy by running the create policy version command

Let's get the ARN of the customer managed policy, that's attached to our role, by running the list-attached-role-policies command:

shell
aws iam list-attached-role-policies --role-name role-example

list all managed policies of role

Copy and paste the policy ARN of the read-s3 policy to a notepad.

Let's update the contents of the read-s3.json file to delete the List* action:

read-s3.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:Get*" ], "Resource": "*" } ] }

Open your terminal in the directory where you stored the read-s3.json file and execute the create-policy-version command to update the managed policy:

shell
aws iam create-policy-version --policy-arn "YOUR_S3_POLICY_ARN" --policy-document file://read-s3.json --set-as-default

update customer managed policy

The --set-as-default parameter specifies that the policy's version should be set as default and applied to all IAM users, groups, and roles that the policy is attached to.

The output shows that the policy's VersionId is v2 after the update.

We can use the policy's ARN and VersionId to verify that the customer managed policy has been updated successfully:

verify customer policy updated

The output of the get-policy-version command shows that the List* action has been successfully removed from the policy.

Delete an Inline Policy of a Role with AWS CLI #

To delete an inline policy attached to an IAM role with AWS CLI, we have to:

  1. Get the name of the inline policy
  2. run the delete-role-policy command

Let's list the names of the inline policies attached to our IAM role:

shell
aws iam list-role-policies --role-name role-example

inline policy attached to role

And finally let's delete the read-dynamodb inline policy from the role, by using the delete-role-policy command:

shell
aws iam delete-role-policy --role-name role-example --policy-name read-dynamodb

delete inline policy from role

To verify the inline policy has been deleted from the role, run the list-role-policies command again:

shell
aws iam list-role-policies --role-name role-example

list inline policies empty

Delete a Managed Policy of a Role with AWS CLI #

The process of deleting a customer managed policy is a lot more complicated than with inline policies.

That's because, customer managed policies:

  1. Can be attached to multiple users, groups and roles.
  2. Can have multiple versions, which have to be deleted.

The process of deleting a customer managed policy with AWS CLI consists of the following steps:

  1. Detach the policy from all users, groups and roles
  2. Delete all versions of the policy
  3. Delete the policy

Let's grab the ARN of the managed policy we're trying to delete by running the list-attached-role-policies command:

shell
aws iam list-attached-role-policies --role-name role-example

list all managed policies of role

Copy the PolicyArn of the read-s3 managed policy and store it in a notepad.

The next step is to list all users, roles and groups that the managed policy is attached to, by running the list-entities-for-policy command:

shell
aws iam list-entities-for-policy --policy-arn "YOUR_S3_POLICY_ARN"

list entities for policy

The output shows that the policy is only attached to the role-example role.

Let's detach the customer managed policy from the role by using the detach-role-policy command:

shell
aws iam detach-role-policy --role-name role-example --policy-arn "YOUR_S3_POLICY_ARN"

detach managed policy from role

The next step is to delete all versions of the policy other than the default version. The default version is automatically deleted when the managed policy is deleted.

shell
aws iam list-policy-versions --policy-arn "YOUR_S3_POLICY_ARN"

list policy versions

The output from the command shows that v2 of the policy is the default (the one we can't delete). So let's delete v1 of the customer managed policy, by running the delete-policy-version command.

shell
aws iam delete-policy-version --policy-arn "YOUR_S3_POLICY_ARN" --version-id v1

delete policy version

To delete a customer managed policy with AWS CLI, use the delete-policy command.

shell
aws iam delete-policy --policy-arn "YOUR_S3_POLICY_ARN"

delete customer managed policy

If we run the list-attached-role-policies command we can see that the only managed policy attached to our IAM role is the AWS managed policy:

shell
aws iam list-attached-role-policies --role-name role-example

list managed policies after delete

Further Reading #

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee