Roles vs Profiles

Qaz has two very important stack keywords necessary for Cross-Account or Cross-Region deployments, these are role and profile. It can be tricky knowing when to use which and also if it's safe to mix the two in one configuration file. This article will look at these two in depth.

Profiles

The profile keyword allows you to select a particular profile as defined in your AWS Config or Credentials file. The profile can be passed in using the -p or --profile flags or set per stack within config, the later being utilised when doing Multi-Account/Region deployments.

For example:

Globally Declared

$ qaz deploy stack --profile=myprofile

If no profile is specified for the stack it will be deployed using the credentials set for myprofile.

Set Per-Stack

stacks:
  stackA:
    profile: my-profile-a

  stackB:
    profile: my-profile-b

For the above, stackA would be deployed using the credentials set for my-profile-a while stackB would use those set for my-profile-b. This would effectively deploy both stacks simultaneously on potentially different accounts.

While this mechanism would function just fine on an EC2, it's hardly ideal to configure credentials on an Instance. That's where Roles come in.

Roles

An IAM role is similar to a user, in that it is an AWS identity with permission policies that determine what the identity can and cannot do in AWS. However, instead of being uniquely associated with one person, a role is intended to be assumable by anyone or anything that is explicitly allowed. More on AWS Roles here

In the same way profiles can be specified per stack, roles can also be specified. To do this, you will need to have your RoleARN.

stacks:
  stackA:
    role: arn:aws:iam::9999999999:role/role-a

  stackB:
    role: arn:aws:iam::9999999999:role/role-b

Given the above, Qaz will switchrole to arn:aws:iam::9999999999:role/role-a and deploy stackA using those credentials, simultaneously, stackB will be deployed using arn:aws:iam::9999999999:role/role-b.

When to Use What...

• If you're using Qaz on a workstation it is recommended that you use profiles and configure roles in your aws config/credentials files. In so doing, you not only have the ability to deploy Cloudformation via Qaz but also the AWS CLI tools and other SDKs will have access to those credentials.

• If you're running Qaz on an EC2 Instance, roles are recommended as long as the EC2 has the necessary access to switchroles.

• If you have some roles but don't want to put them in AWS Config/credentials files, you can specify the roles in your Qaz configuration file. Then when calling that config, you specify the source profile for the roles. For example, given the Qaz role configuration above, if the source profile to switch to those roles on my local machine was lab, I would call that configuration using qaz deploy stack --profile=lab

Note: It is not recommended having both role and profile specified for a single stack and may result in access failures.