# Managing AWS Cloud Accounts with Terraform

## Overview

You can define your AWS Cloud Account integration in Terraform using the Panther [Terraform provider](https://registry.terraform.io/providers/panther-labs/panther/latest). AWS Cloud Accounts enable Panther's [Cloud Security Scanning](/cloud-scanning.md) capabilities to monitor cloud resource configurations for security compliance.

Other methods to create an AWS Cloud Account integration include [using the Panther REST API](/panther-developer-workflows/api/rest/cloud-accounts.md) directly and [manual creation in the Panther Console](/cloud-scanning.md#onboarding-a-cloud-account-in-the-panther-console).

## How to define your AWS Cloud Account in Terraform

The following sections outline how to define your AWS Cloud Account integration in HashiCorp Configuration Language (HCL).

### Prerequisites

* Before starting, ensure you have:
  * An API URL and token with the `Manage Cloud Security Sources` permission. This is required to complete [Step 2](#step-2-provide-values-for-the-defined-variables).
    * If needed, follow [these instructions for creating an API token in the Panther Console](/panther-developer-workflows/api.md#how-to-create-a-panther-api-token).
  * The IAM audit role deployed in your AWS account. Use the CloudFormation template generated by Panther (**Configure** > **Cloud Accounts** > **Connect an account**) to provision the role, then use its ARN in your Terraform configuration.

### Step 1: Define variables

* Define a `variables.tf` file with the Panther variables shown in the code block below.

```hcl
variable "panther_api_token" {
  description = "Panther API token"
  type        = string
  sensitive   = true
}

variable "panther_api_url" {
  description = "Panther API URL"
  type        = string
}

variable "integration_label" {
  description = "Display name for the AWS Cloud Account integration."
  type        = string
}

variable "aws_account_id" {
  description = "The 12-digit AWS account ID."
  type        = string
}

variable "audit_role" {
  description = "The IAM role ARN that Panther assumes to scan the AWS account."
  type        = string
}

// (Optional) Regions, resource types, and ARN regex patterns to exclude from scanning.
variable "region_ignore_list" {
  description = "AWS regions to exclude from scanning."
  type        = list(string)
  default     = []
}

variable "resource_type_ignore_list" {
  description = "Resource types to exclude from scanning (for example, AWS.S3.Bucket)."
  type        = list(string)
  default     = []
}

variable "resource_regex_ignore_list" {
  description = "Regex patterns matching resource ARNs to exclude from scanning."
  type        = list(string)
  default     = []
}
```

### Step 2: Provide values for the defined variables

* Add a `*.tfvars` file that assigns values to the variables you defined in Step 1. Note that to complete this section, you will need the API URL and token outlined in the [Prerequisites section](#prerequisites).
  * Your `panther_api_url` value should be your root API URL. This is either:
    * A [GraphQL API URL](/panther-developer-workflows/api/graphql.md#step-1-identify-your-panther-graphql-api-url) without the `/public/graphql` suffix
    * A [REST API URL](/panther-developer-workflows/api/rest.md#step-1-identify-your-panther-rest-api-url) as-is (REST URLs do not have a suffix after the root URL)

```hcl
panther_api_token          = "XXXXXXXXXX"
panther_api_url            = "https://your-panther-url/v1"
integration_label          = "production-aws"
aws_account_id             = "123456789012"
audit_role                 = "arn:aws:iam::123456789012:role/PantherAuditRole"
region_ignore_list         = ["us-west-1"]
resource_type_ignore_list  = ["AWS.KMS.Key"]
resource_regex_ignore_list = [".*-test-.*"]
```

### Step 3: Define the Terraform provider

* Add the [Panther](https://registry.terraform.io/providers/panther-labs/panther/latest) Terraform provider.

```hcl
terraform {
  required_providers {
    panther = {
      source  = "panther-labs/panther"
      version = "~> 0.2.11"
    }
  }
}
```

### Step 4: Define the Panther AWS Cloud Account resource

The following HCL configuration defines the AWS Cloud Account integration in Panther.

```hcl
provider "panther" {
  token = var.panther_api_token
  url   = var.panther_api_url
}

resource "panther_aws_cloud_account" "example" {
  integration_label = var.integration_label
  aws_account_id    = var.aws_account_id

  aws_scan_config = {
    audit_role = var.audit_role
  }

  region_ignore_list         = var.region_ignore_list
  resource_type_ignore_list  = var.resource_type_ignore_list
  resource_regex_ignore_list = var.resource_regex_ignore_list
}
```

{% hint style="info" %}
`aws_account_id` is immutable. Changing it after creation forces Terraform to destroy and recreate the resource.
{% endhint %}

## Resource reference

### `panther_aws_cloud_account`

#### Arguments

| Name                         | Type         | Required | Description                                                                                       |
| ---------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------- |
| `integration_label`          | string       | ✓        | Display name for the integration (alphanumeric, spaces, and hyphens only; maximum 36 characters). |
| `aws_account_id`             | string       | ✓        | The 12-digit AWS account ID. Immutable—changing this value forces resource replacement.           |
| `aws_scan_config`            | object       | ✓        | AWS scanning configuration. See [aws\_scan\_config](#aws_scan_config) below.                      |
| `region_ignore_list`         | list(string) | —        | AWS regions to exclude from scanning. Defaults to `[]`.                                           |
| `resource_type_ignore_list`  | list(string) | —        | Resource types to exclude from scanning (for example, `AWS.S3.Bucket`). Defaults to `[]`.         |
| `resource_regex_ignore_list` | list(string) | —        | Regex patterns matching resource ARNs to exclude from scanning. Defaults to `[]`.                 |

#### `aws_scan_config`

| Name         | Type   | Required | Description                                                    |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| `audit_role` | string | ✓        | The IAM role ARN that Panther assumes to scan the AWS account. |

#### Attributes

| Name | Type   | Description                                              |
| ---- | ------ | -------------------------------------------------------- |
| `id` | string | Panther integration ID (UUID) for the AWS Cloud Account. |

## Importing existing AWS Cloud Accounts

If you have existing AWS Cloud Accounts in Panther that you want to manage with Terraform, use `terraform import` with the integration ID. The integration ID is a UUID visible in the Panther Console URL when viewing the Cloud Account (**Configure** > **Cloud Accounts**).

```shell
terraform import panther_aws_cloud_account.example 12345678-1234-1234-1234-123456789012
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.panther.com/panther-developer-workflows/terraform/cloud-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.