> ## 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 Cloud Accounts to Aviatrix Cloud with Terraform

> Onboard your first AWS, Azure, or GCP cloud account to Aviatrix PaaS using the avxcloud_cloud_account resource and the aviatrixsystems/avxcloud provider.

Onboarding a cloud account is the first step in Aviatrix Cloud. It connects your
existing AWS, Azure, or GCP account to your Fabric and is required before you
can manage networks.

<Note>
  Complete [Configure the Aviatrix Cloud Terraform
  Provider](/docs/cloud/platform-administration/terraform/terraform-getting-started)
  before following this guide.
</Note>

For all `avxcloud_cloud_account` arguments, see the
[provider documentation on the Terraform Registry](https://registry.terraform.io/providers/AviatrixSystems/avxcloud/latest/docs/resources/cloud_account).

## Step 1: Add Variables and Define the Cloud Account

Add to `variables.tf`:

```hcl theme={null}
variable "fabric_name" {
  description = "Name of the Aviatrix Cloud Fabric to onboard the account to."
  type        = string
}

variable "cloud_account_name" {
  description = "Display name for the onboarded cloud account."
  type        = string
}
```

Add to `terraform.tfvars`:

```hcl theme={null}
fabric_name        = "your-fabric-name"
cloud_account_name = "your-cloud-account-name"
```

Select your cloud provider. Add its variables to `variables.tf`, the resource to
`main.tf`, and the values to `terraform.tfvars`.

<Tabs>
  <Tab title="AWS">
    Add to `variables.tf`:

    ```hcl theme={null}
    variable "aws_account_number" {
      description = "12-digit AWS account number."
      type        = string
    }

    variable "aws_assumed_role_arn" {
      description = "ARN of the IAM role that Aviatrix assumes in your AWS account."
      type        = string
    }
    ```

    Add to `main.tf`:

    ```hcl theme={null}
    resource "avxcloud_cloud_account" "account" {
      fabric       = var.fabric_name
      display_name = var.cloud_account_name

      aws = {
        account_number = var.aws_account_number

        token_info = {
          assumed_role_arn = var.aws_assumed_role_arn
        }
      }
    }
    ```

    Add to `terraform.tfvars`:

    ```hcl theme={null}
    aws_account_number   = "123456789012"
    aws_assumed_role_arn = "arn:aws:iam::123456789012:role/aviatrix-platform-app"
    ```
  </Tab>

  <Tab title="Azure">
    Add to `variables.tf`:

    ```hcl theme={null}
    variable "azure_subscription_id" {
      description = "Azure subscription ID."
      type        = string
    }

    variable "azure_directory_id" {
      description = "Azure AD tenant (directory) ID."
      type        = string
    }

    variable "azure_application_id" {
      description = "Service principal application (client) ID."
      type        = string
    }

    variable "azure_application_key" {
      description = "Service principal application key (client secret)."
      type        = string
      sensitive   = true
    }
    ```

    Add to `main.tf`:

    ```hcl theme={null}
    resource "avxcloud_cloud_account" "account" {
      fabric       = var.fabric_name
      display_name = var.cloud_account_name

      azure = {
        subscription_id = var.azure_subscription_id
        directory_id    = var.azure_directory_id
        application_id  = var.azure_application_id

        credentials = {
          application_key = var.azure_application_key
        }
      }
    }
    ```

    Add to `terraform.tfvars`:

    ```hcl theme={null}
    azure_subscription_id = "00000000-0000-0000-0000-000000000000"
    azure_directory_id    = "11111111-1111-1111-1111-111111111111"
    azure_application_id  = "22222222-2222-2222-2222-222222222222"
    ```
  </Tab>

  <Tab title="GCP">
    Add to `variables.tf`:

    ```hcl theme={null}
    variable "gcp_project_id" {
      description = "GCP project ID."
      type        = string
    }
    ```

    Add to `main.tf`. The `credential_json` value is the contents of a GCP
    service account key file in your working directory. Update the filename `gcp-service-account.json` to
    match your key file:

    ```hcl theme={null}
    resource "avxcloud_cloud_account" "account" {
      fabric       = var.fabric_name
      display_name = var.cloud_account_name

      gcp = {
        project_id = var.gcp_project_id

        credentials = {
          credential_json = file("${path.module}/gcp-service-account.json")
        }
      }
    }
    ```

    Add to `terraform.tfvars`:

    ```hcl theme={null}
    gcp_project_id = "my-gcp-project"
    ```
  </Tab>
</Tabs>

## Step 2: Apply Your Configuration

To preview and apply your configuration, follow these steps:

1. Open a terminal window and navigate to your working directory.

2. Optionally, format and validate your configuration:

   ```bash theme={null}
   terraform fmt
   terraform validate
   ```

3. To initialize the Terraform configuration and download the provider from the
   public registry, run the following command:

   ```bash theme={null}
   terraform init
   ```

4. To preview the changes, run the following command:

   ```bash theme={null}
   terraform plan
   ```

5. To apply the changes, run the following command:

   ```bash theme={null}
   terraform apply
   ```

6. After the apply completes, verify that the cloud account appears in the
   Aviatrix Cloud console under **Cloud Resources > Cloud Accounts**.

## Outputs (Optional)

To print the name assigned to the cloud account after apply, add the following
to `outputs.tf`:

```hcl theme={null}
output "cloud_account_name" {
  description = "Name assigned to the onboarded cloud account."
  value       = avxcloud_cloud_account.account.name
}
```

## Troubleshooting

<Expandable title="Provider and API connectivity">
  | Symptom | Resolution |
  | - | - |
  | `terraform init` cannot find or download the provider | Confirm the `source` is `aviatrixsystems/avxcloud` and that your workstation can reach the public Terraform Registry. |
  | Authentication fails or the API access key is rejected | Confirm `api_access_key` is set and current. API access keys can expire — regenerate the key in the Aviatrix Cloud console and update your `terraform.tfvars` or environment variable. |
  | Cannot reach `https://api.cloud.aviatrix.com` | Check connectivity, proxy, and firewall rules from the machine running Terraform. |
  | TLS or certificate errors | Confirm your local trust store and network proxy configuration are correct. Contact Aviatrix support to resolve certificate issues against the Aviatrix Cloud endpoint. |

  <Warning>For provider errors, TLS problems, or other production issues contact Aviatrix support.</Warning>
</Expandable>

<Expandable title="avxcloud_cloud_account apply failures">
  | Symptom | Resolution |
  | - | - |
  | `terraform validate` or `terraform plan` reports an undefined variable | Confirm every `var.<name>` reference has a matching `variable` block in `variables.tf` and a value in `terraform.tfvars` or a `TF_VAR_<name>` environment variable. |
  | Error referencing `fabric` or invalid Fabric | Set `fabric` to the exact Fabric name in your Aviatrix Cloud account. Copy the name from the Aviatrix Cloud console if needed. |
  | `terraform apply` succeeds but the account does not appear in the console | Confirm you are signed in to the correct Fabric. Check **Cloud Resources > Cloud Accounts**. Wait a few minutes and refresh the page. |
  | Cloud account already exists | Import the existing account into Terraform state, or remove the duplicate from the console before re-applying. Do not onboard the same cloud subscription, project, or AWS account twice. |
</Expandable>

<Expandable title="Cloud-Related Errors">
  <Expandable title="AWS">
    | Symptom | Resolution |
    | - | - |
    | IAM role assumption or permission denied during apply | Confirm `aws_assumed_role_arn` matches the `aviatrix-platform-app` role ARN in your AWS account (for example, `arn:aws:iam::123456789012:role/aviatrix-platform-app`). The role must exist and trust Aviatrix. See [Onboard Your AWS Cloud Account](/docs/cloud/platform-administration/onboard-offboard/aws-cloud-account-onboard). |
    | Invalid AWS account number | `aws.account_number` must be the 12-digit AWS account ID with no hyphens. |
    | Onboarding fails after stack or role setup issues | If you used CloudFormation to create the IAM role, review stack events in AWS and fix failed resources. See [Troubleshoot AWS Onboarding Issues](/docs/cloud/platform-administration/onboard-offboard/aws-cloud-onboard-troubleshoot). |
  </Expandable>

  <Expandable title="Azure">
    | Symptom | Resolution |
    | - | - |
    | Authentication or authorization error during apply | Confirm `azure_subscription_id`, `azure_directory_id`, and `azure_application_id` match your service principal. Verify the client secret is set via `TF_VAR_azure_application_key` or `terraform.tfvars`. |
    | Expired or invalid application key | Regenerate the service principal secret in Azure AD and update `TF_VAR_azure_application_key`. |
    | Insufficient permissions | Confirm the service principal has the permissions required to onboard the subscription. See [Onboard Your Microsoft Azure Cloud Account](/docs/cloud/platform-administration/onboard-offboard/azure-cloud-account-onboard). |
  </Expandable>

  <Expandable title="GCP">
    | Symptom | Resolution |
    | - | - |
    | Cannot read service account key file | Confirm the JSON key file path in `file("${path.module}/gcp-service-account.json")` exists in your Terraform working directory and matches your key filename. |
    | Invalid `gcp_project_id` | Use the GCP project ID, not the project name or number. |
    | Permission denied during apply | Confirm the service account has the roles required to onboard the project. |
  </Expandable>
</Expandable>

## Related Topics

* [Configure the Aviatrix Cloud Terraform Provider](/docs/cloud/platform-administration/terraform/terraform-getting-started)
* [Onboard Your AWS Cloud Account](/docs/cloud/platform-administration/onboard-offboard/aws-cloud-account-onboard)


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