> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard Your AWS Cloud Account

> Aviatrix PaaS cloud account onboard

After signing up with Aviatrix Cloud Network Security Platform-as-a-Service
(Aviatrix PaaS), you need to connect your cloud accounts with the Aviatrix PaaS
console. The onboarding process creates the AWS roles and resources required for
the Aviatrix console to monitor and manage your AWS network.

You can easily onboard your AWS account in the Aviatrix console by using the
provided CloudFormation template.

Alternatively, you can onboard your account using your AWS key and secret.

[Onboard Your AWS Account By Using CloudFormation](#onboard-your-aws-account-by-using-cloudformation)

* Recommended for production environments

[Onboard Your AWS Account By Using a Key and Secret](#onboard-your-aws-account-by-using-a-key-and-secret)

* Recommended only for test environments

## Onboard Your AWS Account By Using CloudFormation

The CloudFormation template creates the required IAM roles and policies in AWS
that allow Aviatrix to manage your cloud network. These include the following:

* *aviatrix-platform-app* role
* `aviatrix-role-ec2-<long-id>` role
* *aviatrix-platform-app-policy* policy

To view the privileges granted by the CloudFormation template, see
[AWS IAM Privileges for Aviatrix PaaS Onboarding](/docs/cloud/platform-administration/onboard-offboard/aws-onboard-iam-privileges).

To onboard an AWS cloud account, do the following:

1. In the Aviatrix PaaS console, go to *Cloud Resources > Cloud Accounts* and
   click *+Cloud Account*.
2. Enter an Account Name and click *AWS*.
3. Select *AWS IAM Role* and *CloudFormation Script*.
4. Click *Launch CloudFormation*. The AWS *CloudFormation quick create stack*
   template opens.
5. In the template, you can optionally modify the stack name and IAM role or
   leave them with their default settings.
   <Warning>
     Do not modify the AviatrixPrincipalArn. This is the IAM role owned by
     Aviatrix and permitted to assume the aviatrix-platform-app role.
   </Warning>

<img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-onboard-cf-template.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=faba40ab11c60f25c80f73459246e26f" alt="aws-onboard-cf-template" width="641" height="556" data-path="docs/cloud/images/aws-onboard-cf-template.png" />

6. Under Capabilities, click the acknowledgment and then click *Create stack*.
7. On AWS *CloudFormation > Stacks > Events*, watch the *Status* column for
   CREATE\_COMPLETE to display. Refresh the list periodically to see updates.

<Frame>
  <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-onboard-cf.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=b64d1bed747eac9ce07acd842991bcd0" alt="aws-onboard-cf" style={{ maxHeight: "600px", width: "auto" }} width="2854" height="1288" data-path="docs/cloud/images/aws-onboard-cf.png" />
</Frame>

8. When creation completes, click the *Outputs* tab and copy the *Value* for
   *AviatrixRoleAppARN*. This is the ARN in the format
   `arn:aws:iam::<account-id>:role/aviatrix-platform-app`.

<img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-onboard-cf-outputs.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=a4254ea6f62baf10dc35d53726c1ebca" alt="aws-onboard-cf-outputs" width="1154" height="478" data-path="docs/cloud/images/aws-onboard-cf-outputs.png" />

<Tip>
  The ARN can also be viewed at IAM > Roles by clicking the
  aviatrix-platform-app role.
</Tip>

9. Return to the Aviatrix *Onboard Cloud Account* dialog box, paste the value
   into the field *AWS Role ARN*, and click *Next*. You will see a Discovering
   Cloud Resources message that changes to a success message after a minute or two.
10. Click *Close*. 11. Verify that the new cloud account displays in the list on
    *Cloud Accounts > Overview*.

*Next Step*: Onboard your VPCs or VNets.

The CloudFormation template creates the required IAM roles and policies in AWS
that allow Aviatrix to manage your cloud network. Using CloudFormation is the
recommended method for onboarding Aviatrix PaaS.

<Warning>
  In the CloudFormation template, do not modify the AviatrixPrincipalArn. This
  is the IAM role owned by Aviatrix and permitted to assume the
  aviatrix-platform-app role.
</Warning>

When template creation starts, the AWS CloudFormation page displays to *Stacks >
Events*. When creation completes, you need to copy the *Value* for
*AviatrixRoleAppARN* from the *Outputs* tab and paste it in the Aviatrix
*Onboard Cloud Account* dialog box.

## Onboard Your AWS Account By Using a Key and Secret

Your Aviatrix ID will be used with your AWS key and secret so that Aviatrix PaaS
can perform actions on your behalf.

<Note>
  Onboarding with a key and secret is recommended for test environments only,
  not for production.
</Note>

*Prerequisite*

You must already have an AWS key and secret before onboarding your AWS account.
If you do not have permission to create credentials in AWS, contact your IAM
administrator.

<Warning>
  The Access Secret is only displayed when it is originally created. If you
  create a new key and secret for onboarding AWS, be sure to keep a copy of the
  secret in a secure place for future use.
</Warning>

To onboard your AWS account in the Aviatrix PaaS console, do the following.

1. Go to *Cloud Resources > Cloud Accounts* and click *+Cloud Account*.
2. Enter a unique Account Name and click *AWS*.
3. Select *AWS Key/Secret*.
4. Enter the *Access Key ID* and *Access Secret* for your AWS account.
5. Enter your AWS *Account Number*.
6. Click *Next*.
7. Verify that the new cloud account displays in the list on *Cloud Accounts >
   Overview*.

*Next Step*: Onboard your VPCs or VNets

## Troubleshoot AWS Onboarding Issues

If onboarding fails, the AWS CloudFormation stack shows failures in the Status
column and the final status should display ROLLBACK\_COMPLETE.

Before trying to onboard your AWS account again, you must remove the
CloudFormation template, two IAM roles, and a policy created in AWS by the
template.

1. In *AWS console*, go to *CloudFormation > Stacks*.
   <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-offboard-cf-stacks.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=541fafad63f1aea562805b2ae4b8c47a" alt="screenshot of AWS cloudformation stacks page" width="1110" height="215" data-path="docs/cloud/images/aws-offboard-cf-stacks.png" />

2. Select the failed stack. The default name is *aviatrix-onboard-aws*, but the
   name could have been modified.

3. In the pane that displays to the right, click the *Events* tab.
   <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-offboard-cf-stack-select.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=862f945f307ba840eb48e98144439ac0" alt="screenshot of AWS cloudformation events tab" width="1308" height="428" data-path="docs/cloud/images/aws-offboard-cf-stack-select.png" />

4. Scroll through the *Events* table and look for messages in the *Status
   reason* column. Examples of some root cause descriptions:
   <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-offboard-cf-status-sg.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=621c68ae224fa4d2d0e33e4ac930c139" alt="screenshot of AWS cloudformation events with security group error" width="989" height="541" data-path="docs/cloud/images/aws-offboard-cf-status-sg.png" />
   <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-offboard-cf-status-rules.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=c3335c9de309853d4aa3d8b2957035d7" alt="screenshot of AWS cloudformation events with rules and policy errors" width="966" height="562" data-path="docs/cloud/images/aws-offboard-cf-status-rules.png" />

5. Resolve the issues mentioned. If the problem is due to existing roles or
   policies, you will resolve those in the following steps.

6. Click *Delete* to permanently remove the failed stack.

7. Read the AWS warning and click *Delete*. Stack status changes to
   DELETE\_COMPLETE after several seconds. If you refresh the Stacks pane, the
   stack name disappears.

8. To remove the roles, go to AWS *IAM > Access Management > Roles* and select
   and delete the following:

* *aviatrix-platform-app*
* `aviatrix-role-ec2-<long-id>`
  <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-offboard-roles-delete.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=1a2da1e496fa083121985b690cd6678a" alt="screenshot of aws roles page" width="908" height="363" data-path="docs/cloud/images/aws-offboard-roles-delete.png" />

9. To remove the policy, go to *Access Management > Policies* and then search
   for and delete the following:

* *aviatrix-platform-app-policy*
  <img src="https://mintcdn.com/aviatrix-14b37c43/EV0VWzgSoSn4nUA6/docs/cloud/images/aws-offboard-policy-delete.png?fit=max&auto=format&n=EV0VWzgSoSn4nUA6&q=85&s=3b68a9536a7b1b4abaaf7e94c318cd1f" alt="screenshot of aws roles page" width="1032" height="351" data-path="docs/cloud/images/aws-offboard-policy-delete.png" />

You can now onboard the same account in the Aviatrix PaaS console, if you choose
to do so.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.