IAM Roles for Secondary Access Accounts

When the Aviatrix Controller goes through the initial Onboarding process, the 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 recommended approach.

  1. Click the Secondary account link to create secondary account credential and build trust to the Controller account.

  2. If you have not logged in, you will be prompted to login to AWS with secondary account.

  3. Once login, you should be already in the CloudFormation page. Note the CloudFormation is already loaded.

  4. Click Next.

  5. You can change the default Stack name. For example, Aviatrix-prod-account.

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

  7. Click Next.

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


  9. 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.


  10. Done.

Setup Secondary Account IAM 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


If you are using this manual process to setup primary access account (Controller’s account), you do not need to establish a trust relationship. Skip this step.

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