Amazon Web Services

In AWS, an Account maps to a credential able to authenticate against a given AWS account.


Whatever account you want to manage with AWS needs a few things configured before Spinnaker can manage it.

These steps assume that you will be naming this account ${MY_AWS_ACCOUNT} and is assigned region us-west-1.

Create a VPC

This is the VPC instances will be deployed to.

Navigate to Console > VPC.

  1. Select Start VPC wizard
  2. Select create a VPC with a Single Public Subnet
  3. Enter defaultvpc as the VPC name
  4. Enter as the Subnet name
  5. Select Create VPC

Create an EC2 Role

This is the role instances launched/deployed with Spinnaker will assume.

Navigate to Console > IAM > Roles.

  1. Select Create new role
  2. Select Amazon EC2
  3. Skip Attach policy and go directly to Next step
  4. Enter BaseIAMRole as the Role name
  5. Select Create role

Create an EC2 Key Pair

This is the key pair instances launched with Spinnaker will be configured with, allowing you to SSH into them if need-be.

Navigate to Console > EC2 > Key Pairs.

  1. Select Create key pair
  2. Enter ${MY_AWS_ACCOUNT}-keypair as the keypair name.
  3. Download the resulting ${MY_AWS_ACCOUNT}-keypair.pem, and run chmod 400 against the file

Adding an Account

There are two types of Accounts in the Spinnaker AWS provider; however, the distinction is not made in how they are configured using Halyard, but instead how they are configured in AWS.

  1. Managing accounts. There is always exactly one managing account, this account is what Spinnaker authenticates as, and if necessary, assumes roles in the managed accounts.
  2. Managed accounts. Every account that you want to modify resources in is a managed account. These will be configured to grant AssumeRole access to the managed account. This includes the managing account!

Configuring the Managing Account

Assume the managing account has 12-digit account id ${MANAGING_ACCOUNT_ID}, and there is at least one (optional) managed account with 12-digit account id ${MANAGED_ACCOUNT_ID}.

Now we will create a policy that allows the managing account to assume roles in each managed account.

Create the SpinnakerAssumeRolePolicy

Navigate to Console > IAM > Policies.

  1. Select Create policy
  2. Select Create your own policy
  3. Enter SpinnakerAssumeRolePolicy as the policy name
  4. Enter the following policy, subsituting all ${*} values and adding extra entries for your other managed accounts.
    "Version": "2012-10-17",
    "Statement": [{
        "Action": "sts:AssumeRole",
        "Resource": [
        "Effect": "Allow"

You can always add more accounts in the future by editing this policy.

Configure an Authentication mechanism

You can have Spinnaker authenticate via a user or role. If Spinnaker is running outside of EC2, you must use a user and access key/secret key pair. If Spinnaker is running inside of EC2, you may use your role on the instances Spinnaker is installed on. In either case, the user or role must have the SpinnakerAssumeRolePolicy attached, as well as the Amazon PowerUserAccess policy.

If you are authenticating as a user via an access key/secret key pair (${ACCESS_KEY_ID}/${SECRET_ACCESS_KEY}) you must run the following Halyard command:

hal config provider aws edit --access-key-id ${ACCESS_KEY_ID} \
    --secret-access-key # do not supply the key here, you will be prompted

In either case, record the ARN of the authentication mechanism (either arn:aws:iam::${MANAGED_ACCOUNT_ID}:role/<some role name> or arn:aws:iam::${MANAGED_ACCOUNT_ID}:user/<some user name>).

Configuring the Managed Account

These steps need to be carried out for the managing account as well.

First, we will create the role that will be assumed by our managing account.

Create the spinnakerManaged role

It is likely that you will want the instances created by Spinnaker to acquire an IAM role on startup. By default, this role is called BaseIAMRole, and was configured above. In order for instances to assume this role, you must grant them PassRole permission. To do so, create the following policy named SpinnakerPassRole, substituting for ${MANAGING_ACCOUNT_ID}:

    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [ "ec2:*" ],
        "Resource": "*"
        "Effect": "Allow",
        "Action": "iam:PassRole",
        "Resource": "arn:aws:iam::${MANAGING_ACCOUNT_ID}:role/BaseIAMRole"

Using the ARN of the managing account recorded above (as ${AUTH_ARN}), first create a role like so:

Navigate to Console > IAM > Roles.

  1. Select Create new role
  2. Select Amazon EC2
  3. Select PowerUserAccess and SpinnakerPassRole, and hit Continue
  4. Enter spinnakerManaged as the Role name
  5. Select Create role
  6. Navigate to the Trust relationships tab
  7. Select Edit trust relationship
  8. Enter the following trust relationship, substituting for the ${AUTH_ARN}
    "Version": "2012-10-17",
    "Statement": [{
        "Sid": "1",
        "Effect": "Allow",
        "Principal": {
            "AWS": "${AUTH_ARN}"
    "Action": "sts:AssumeRole"

Now add the account to the list of AWS accounts in Spinnaker using halyard:

$AWS_ACCOUNT_NAME={name for AWS account in Spinnaker, e.g. my-aws-account}

hal config provider aws account add $AWS_ACCOUNT_NAME \
    --account-id ${ACCOUNT_ID} \
    --assume-role role/spinnakerManaged

Now enable AWS

hal config provider aws enable

Advanced Account Settings

You can view the available configuration flags for AWS within the Halyard reference.