Set up IAM roles

In this part, you’ll use the bootstrap user credentials created earlier to create some IAM roles that can be used for further examples. You’ll do this by creating an unprivileged IAM user, with credentials, that will be used to run the code by assuming IAM roles. You will then apply a stack (provided for you, but of course you’ll look over the code before applying it) which will create IAM roles, and give your unprivileged user the right to assume those roles.

This is all done in the name of good security hygiene. AWS has documentation that explains how assuming a role works.

(1) Create an unprivileged user

Create a user (for example, cloudspin_user) in the IAM console. Do not add the user to any groups, and don’t give it console access. Create an API access key and secret key for the user.

(1.1) Add the unprivileged user to the AWS credentials file

In file: ~/.aws/credentials:

[cloudspin_user]
aws_access_key_id = AKIA........
aws_secret_access_key = xxxxxxxxxxx

(2) Apply the IAM role stack

(2.1) Configure the IAM role stack

Create a file 00-iam-roles/stack-instance-local.yaml (you can copy 00-iam-roles/stack-instance-local-example.yaml as a starter), and edit it:

instance:
  group: YOURNAME_sandbox (1)

parameters:
  stack_manager_users:
    - YOUR_UNPRIVILEGED_IAM_USER_NAME (2)

terraform_backend:
  bucket: statebucket-cloudspin-examples-XXXXXXXXXXXX (3)
  profile: YOUR_BOOTSTRAP_PROFILE (4)

resources:
  aws_profile: YOUR_BOOTSTRAP_PROFILE (4)

This may be the same as the value you set for your statebucket in the previous page.
This is the name of the unprivileged IAM user you created in the steps above in this page.
This should be the name of the bucket created in the previous page.
This is the profile in your ~/.aws/credentials file that you used for bootstrapping the statebucket. So these credentials have enough privileges to create IAM roles without needing to assume a role.

(2.2) Apply the iam-roles stack

The first time you do this, you’ll need to initialize the tooling in the stack project folder 00-iam-roles:

bundle install

Now you can plan the stack and make sure you’re happy with what it will do:

rake plan

Then run the thing:

rake up

(2.3) What happened?

This should have created three IAM roles in your AWS account:

Table 1. Table IAM Roles
spin_role-cloudspin_examples-account	Used to manage IAM roles, policies, etc.
spin_role-cloudspin_examples-delivery	Used to manage resources that support delivery, e.g. pipelines, S3 buckets, etc.
spin_role-cloudspin_examples-manager	Used to manage basic stacks

(3) Switch over to using the managed IAM roles

In the steps above you used a privileged "bootstrap" IAM user to apply the stack. But the point of creating the IAM roles is so you can use "assume role" rather than using the privileged account.

Add an assume-role profile to the file ~/.aws/config:

[profile assume-cloudspin_examples-account]
role_arn = arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/spin_role-cloudspin_examples-account
source_profile = cloudspin_user (1)

This is the profile for the unprivileged user you added to ~/.aws/credentials earlier on this page.

Then in your local configuration file ./stack-instance-local.yaml, replace the bootstrap profile configuration with the configuration that will assume the newly created IAM role instead:

terraform_backend:
  bucket: statebucket-cloudspin-examples-XXXXXXXXXXXX
  profile: YOUR_UNPRIVILEGED_PROFILE (1)
  role_arn: arn:aws:iam::XXXXXXXXXXXX:role/spin_role-cloudspin_examples-account (2)

resources:
  aws_profile: YOUR_UNPRIVILEGED_PROFILE (1)
  assume_role_profile: assume-cloudspin_examples-account (3)
  assume_role_arn: arn:aws:iam::XXXXXXXXXXXX:role/spin_role-cloudspin_examples-account (4)

The profile for the unprivileged user you added to ~/.aws/credentials earlier on this page.
The ARN for the profile to assume for write access to the S3 statebucket.
The name of the profile in your ~/.aws/config, as described above, which indicates the role terraform should assume to manage infrastructure.
The ARN for the profile terraform should assume.

At the moment, these examples use a highly privileged role for both of these things. These should be split out - a role that has just enough permissions for the S3 statebucket, and another role that has more specific permissions for this particular project.

(3.1) Testing it

We need a nice spec for this. A rough way to test is to run rake plan, expecting it will show that nothing will be changed.

Create IAM roles