IAM Roles for Secondary Accounts

When the Aviatrix Controller go through the initial Onboarding process, a primary access account is created. Using the primary access account the Controller can launch gateways and build connectivity in the VPCs that belong to this account.

If the Controller needs to build connectivity in AWS accounts that are different from the Controller instance’s AWS account, secondary access accounts need to be created.

To create a secondary access account on the Controller, you need to first create IAM roles, policies and establish trust relationship to the primary AWS account.

Follow the steps below to create IAM roles and policies for the secondary access account.

(If you like to customize the conditions of the policies published by Aviatrix, consult this link.)

Setup by CloudFormation template

This is the preferred approach.

  1. Login to AWS Management Console with secondary account credential in any region.

  2. Go to CloudFormation service.

  3. Click Create new stack or Create Stack


  4. Select Specify an Amazon S3 template and copy and paste this URL https://s3-us-west-2.amazonaws.com/aviatrix-cloudformation-templates/aviatrix-secondary-account-iam.json to the field.


  5. Click Next.

  6. Populate the Stack name. For example, Aviatrix-for-marketing.

  7. Enter the Aviatrix Controller’s AWS account number.

  8. Click Next.

  9. We recommend you to enable stack termination protection during stack creation time to prevent accidental deletion, as shown below, then click Next.


  10. Click the checkbox next to “I acknowledge that AWS CloudFormation ...” and then click Create. When the stack creation completes, the secondary account IAM roles and policies are all set.


  11. Done.

Setup Manually

This is not a recommended approach as it takes longer time and error prone.

1. Create two IAM custom policies

1.1 Create “aviatrix-assume-role-policy”:

  • Log in in to AWS managment console with secondary AWS account.
  • Go to Services -> IAM -> Policies -> Create Policy -> Create Your Own Policy
  • Enter the policy name, aviatrix-assume-role-policy , copy and paste the policy text from this link.
  • Click Valid Policy to validate the policy.
  • Click Create Policy button.

1.2 Create “aviatrix-app-policy”:

  • Log in to AWS console with your own account.
  • Go to Services -> IAM -> Policies -> Create Policy -> Create Your Own Policy
  • Enter the policy name, aviatrix-app-policy , copy and paste the policy provided by this link into “Policy Document” section. In this example, the policy name is “aviatrix-app-policy”, as shown below.
  • Click Create Policy button.

2. Create Two IAM Roles

2.1 Create “aviatrix-role-ec2” role

The role name MUST be exactly “aviatrix-role-ec2”.

  • Go to AWS console -> IAM service -> Roles -> Create role


  • Select AWS Service -> EC2 -> EC2 -> Next: Permissions


  • Search Policy aviatrix-assume-role-policy, then select this policy. Click “Next Review”


  • Enter Role name aviatrix-role-ec2 (must be exact) then click [Create]
  • Search/Check the role. You should see something like this for Role ARN: arn:aws:iam::575xxxxxx729:role/aviatrix-role-ec2


  • Make a note of the above Role ARN string, it will be used for setup Aviatrix Cloud Account later

2.2 Create “aviatrix-role-app” role

This role is to be assumed by a granted AWS account. The Aviatrix controller acquires the “assume role” capability authorized by its “aviatrix-role-ec2” role. It then assumes to this service role that is granted by its own AWS account or other AWS accounts to perform AWS APIs.

  • Go to AWS console -> IAM service -> Roles -> Create Role
  • Select “Another AWS account”, and enter your AWS account ID, then Click [Next:Permissions]


  • Select aviatrix-app-policy IAM policy, then click [Next: Review]

  • Enter a Role Name, in this case aviatrix-role-app . Click “Create role”

  • You should see something like this for Role ARN: arn:aws:iam::575xxxxxx729:role/aviatrix-role-app

  • Make a note of the above Role ARN string, it will be used to setup Aviatrix access account later.


2.3 Establish trust relationship with primary account

Grant the primary (Controller) AWS account access to the aviatrix-role-app in the this secondary account

  1. AWS console -> IAM service -> Roles > aviatrix-role-app

  2. Click Trust Relationships > Edit Trust Relationship

  3. Edit the trust relationship as follow


  4. Remember you need to enter both primary account number and secondary account number

  5. Click Update Trust Policy