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

# Deploy Plerion with Terraform

> Onboard a single AWS account to Plerion using a native Terraform template that provisions the IAM role and policies and registers the integration

With **[Terraform deployment](https://app.plerion.com/settings/integrations/add/AWS/AWSAccount)**, you can onboard a single AWS account to Plerion from your own Terraform. A generated template provisions the Plerion access role and its permissions policies as native Terraform resources in your state, and `terraform apply` registers the integration with Plerion for you. There is no CloudFormation stack in your account, and no role ARN to paste back into the console.

<Info>
  The template registers the integration by calling the Plerion API during `terraform apply`. No credential is involved. Plerion verifies the registration by assuming the role the template creates, using your tenant's external ID.
</Info>

***

## Before you start

* Terraform 1.5.0 or later. The template uses a `check` block to report a failed registration without blocking the rest of your apply.
* Credentials for the target AWS account, with permission to create IAM roles and policies.
* Access to the Plerion console to start onboarding and copy the values the template needs.

***

## Choose how CWPP scanning runs

Plerion enables Cloud Security Posture Management (CSPM) and Cloud Infrastructure Entitlement Management (CIEM) on every integration. Cloud Workload Protection Platform (CWPP) workload scanning is optional, and the Terraform flow provides three templates. Pick the one that matches the CWPP option you select in the console.

* **Same account** (`aws-integration.tf`): Plerion runs the CWPP scanning appliances inside the account you are onboarding. The template provisions the appliance role and instance profile. You set the appliance regions and networking in the console after applying. Choose this to keep scanning inside your own account.
* **Plerion-managed service account** (`aws-integration-plerion-managed.tf`): Plerion runs the scanning appliances in its own AWS accounts, so there is no appliance infrastructure or networking to manage in your account. You grant a cross-account role to the Plerion service account. See [Plerion-managed scanning](/guides/integrations/aws/managed-scanning/overview) for how managed scanning works.
* **Your own service account** (`aws-integration-service-account.tf`): Plerion runs the scanning appliances in one AWS account you own and nominate, and every account you onboard points at it. Scanning stays inside your organization, and no appliances run in the accounts being scanned. Set that account up first, with the templates in [Set up a service account with Terraform](#set-up-a-service-account-with-terraform).

To onboard with CSPM and CIEM only, use the same-account template (`aws-integration.tf`) and set `capabilities` to `CSPM`. No CWPP resources are provisioned.

***

## Steps to onboard with Terraform

<Steps>
  <Step title="Start an AWS account onboarding in Plerion">
    * Go to `Settings` > `Integrations`.
    * Next to **AWS account**, click the `+` button and choose `Add single AWS account`. You can also choose `Add single AWS account with Terraform` to go straight to the Terraform strategy.
  </Step>

  <Step title="Select your capabilities">
    * **CSPM** and **CIEM** are selected by default.
    * To include workload scanning, also select **CWPP**.
    * Click `Next`.
  </Step>

  <Step title="Select the Terraform deployment strategy">
    * On the **Deployment strategy** step, select **Terraform**.
    * If you selected CWPP, choose whether scanning runs in the **same account**, through a **Plerion-managed service account**, or in a **service account** you own. If you choose your own service account, pick it from the list.
    * Click `Next`.
  </Step>

  <Step title="Download the template">
    On the **Grant Plerion access** page, download the Terraform template into its own directory. The file is `aws-integration.tf` for same-account scanning, `aws-integration-plerion-managed.tf` for Plerion-managed scanning, or `aws-integration-service-account.tf` for scanning in your own service account.
  </Step>

  <Step title="Copy the values shown in the console">
    The page lists the values to pass to the template:

    * `plerion_api_url`
    * `plerion_account_id`
    * `tenant_id`
    * `external_id`
    * `service_account_id` (service account scanning, whether Plerion-managed or your own)
  </Step>

  <Step title="Apply the template">
    From the template directory, initialize and apply, passing the values from the console. `terraform apply` provisions the role and policies, then registers the integration with Plerion automatically.

    ```bash theme={"system"}
    terraform init
    terraform apply \
      -var 'plerion_api_url=<plerion_api_url>' \
      -var 'plerion_account_id=<plerion_account_id>' \
      -var 'tenant_id=<tenant_id>' \
      -var 'external_id=<external_id>'
    ```

    For either service account option, also pass `-var 'service_account_id=<service_account_id>'`. To onboard with CSPM and CIEM only, add `-var 'capabilities=CSPM'`.
  </Step>

  <Step title="Finish CWPP setup for same-account scanning">
    If you chose same-account CWPP, the template provisions the appliance role and instance profile, but the appliance regions and networking are specific to your VPC. In the console, open the integration's **Workload** tab, enable the appliance regions, and set the subnet and security group for each region.

    Neither service account option needs anything further here. Plerion-managed scanning is ready to use, and your own service account already carries its regions from when you set it up.
  </Step>

  <Step title="Confirm the integration">
    The account appears in your integrations list and Plerion starts the first scan. Track progress under `Settings` > `Integrations` > `Scans`, and view results in the **Compliance**, **Well-Architected**, and **Findings** dashboards.

    If the account belongs to an AWS organization that no other account in your tenant belongs to, Plerion holds it for approval instead of scanning it. See [Account approval](/guides/integrations/aws/aws-account/getting-started-with-aws-account#account-approval).
  </Step>
</Steps>

<Warning>
  If `terraform apply` reports that registration did not succeed, check `tenant_id` and `external_id` against the console and apply again.
</Warning>

***

## Template inputs

Pass these variables at apply time, or set them in a `.tfvars` file.

| Variable | Required | Default | Description |
| - | - | - | - |
| `plerion_api_url` | Yes | None | Plerion URL to register with, shown in the console. |
| `plerion_account_id` | Yes | None | Plerion AWS account ID, shown in the console. |
| `tenant_id` | Yes | None | Your Plerion tenant ID, shown in the console. Identifies the tenant the account registers into. |
| `external_id` | Yes | None | External ID for the cross-account access role, shown in the console. |
| `service_account_id` | Service account templates only | None | AWS account ID of the service account that runs scanning. Shown in the console: the Plerion-managed account for that template, or your own account for the service account template. |
| `integration_name` | No | Account alias | Display name for the integration in Plerion. Defaults to the AWS account's IAM alias, or the account ID if the account has none. |
| `capabilities` | No | `ALL` | Same-account template only. `ALL` enables CSPM, CIEM, and CWPP. `CSPM` enables CSPM and CIEM only, with no CWPP resources. |
| `kms_key_access_mode` | No | `ALL_KEYS` | `ALL_KEYS` grants access to all Key Management Service (KMS) keys except those tagged `PlerionAccess=Denied`. `SELECTED_KEYS` grants access only to keys tagged `PlerionAccess=Granted`. See [Provide Plerion access to KMS keys](/guides/integrations/aws/additional-aws-configurations/provide-plerion-access-to-kms-keys). |

***

## Set up a service account with Terraform

A service account is one AWS account you own that runs the scanning appliances for every account you onboard against it. The appliances stay inside your organization, and the accounts being scanned run no appliances of their own.

Set it up before you onboard any account that points at it. Two templates do the work. To get them and the token they need, start adding an AWS account in `Settings` > `Integrations`. On **Select capabilities**, keep CWPP selected, choose **Service account**, and select **Create a Service Account**. Then choose **Terraform** on the step that creates the AWS IAM roles.

<Steps>
  <Step title="Grant Plerion access to the service account">
    Apply `plerion-service-account.tf` in the account that will host the appliances. It creates the role Plerion assumes, the role the appliances run as, and its instance profile, then registers the account with Plerion as a service account.

    ```bash theme={"system"}
    terraform init
    terraform apply \
      -var 'plerion_api_url=<plerion_api_url>' \
      -var 'plerion_account_id=<plerion_account_id>' \
      -var 'external_id=<external_id>' \
      -var 'auth_token=<auth_token>'
    ```

    Note the `plerion_instance_profile_name` output. The region template needs it.
  </Step>

  <Step title="Add a scanning region">
    Apply `plerion-service-account-region.tf` once for each region you want to scan in, in the same account, with a separate Terraform state per region. It builds an isolated network for the appliances, an auto-scaling pool that grows and shrinks with the scan queue, and the key their snapshots are encrypted with, then tells Plerion where to find them.

    ```bash theme={"system"}
    terraform init
    terraform apply \
      -var 'plerion_api_url=<plerion_api_url>' \
      -var 'plerion_account_id=<plerion_account_id>' \
      -var 'auth_token=<auth_token>' \
      -var 'instance_profile_name=<plerion_instance_profile_name>'
    ```

    The region comes from your AWS provider configuration, so set `AWS_REGION` or a provider block to the region you are adding.
  </Step>

  <Step title="Onboard the accounts you want scanned">
    Each account is onboarded separately with `aws-integration-service-account.tf`, passing this account's ID as `service_account_id`. Follow [Steps to onboard with Terraform](#steps-to-onboard-with-terraform).
  </Step>
</Steps>

<Note>
  The appliances do not share a network with your workloads, so the address range the region template creates only has to avoid ranges you peer with. Change it with `vpc_cidr`, `public_subnet_cidr`, and `private_subnet_cidr` if the defaults overlap something you route to.
</Note>

<Warning>
  An AWS account runs one appliance fleet per region. If the account already hosts a Plerion service account deployed with CloudFormation, remove that stack before applying these templates in the same region.
</Warning>

### Service account template inputs

| Variable | Template | Required | Default | Description |
| - | - | - | - | - |
| `plerion_api_url` | Both | Yes | None | Plerion URL to register with, shown in the console. |
| `plerion_account_id` | Both | Yes | None | Plerion AWS account ID, shown in the console. |
| `auth_token` | Both | Yes | None | Short-lived token from the console that lets the account register. |
| `external_id` | Permissions | Yes | None | External ID for the cross-account role Plerion assumes, shown in the console. |
| `service_account_name` | Permissions | No | Account ID | Display name for the service account in Plerion. |
| `instance_profile_name` | Region | Yes | None | The `plerion_instance_profile_name` output of the permissions template. |
| `max_instance_limit` | Region | No | `10` | Most appliances that may run at once in this region. |
| `backlog_per_instance_limit` | Region | No | `10` | Queued scans per appliance before another appliance starts. |
| `appliance_instance_type_category` | Region | No | `ComputeOptimized` | `ComputeOptimized` for large environments, or `GeneralPurpose` for cost-focused deployments with modest performance. |
| `vpc_cidr` | Region | No | `10.0.0.0/16` | Address range for the appliance network. |
| `public_subnet_cidr` | Region | No | `10.0.0.0/21` | Address range for the public subnet that holds the NAT gateway. |
| `private_subnet_cidr` | Region | No | `10.0.32.0/19` | Address range for the private subnet the appliances run in. |
| `create_vpc_endpoint` | Region | No | `false` | Set to `true` when you scan instances built from AWS Marketplace AMIs, to reduce data transfer costs. |
| `create_autoscaling_service_linked_role` | Region | No | `true` | Creates the Auto Scaling service-linked role the appliance group runs as. Set to `false` to reuse one the account already has. |

***

## Keeping permissions up to date

Plerion extends the AWS permissions policies over time as detection coverage grows. A CloudFormation stack can update itself, but Terraform manages these resources in your own state, so you apply policy updates yourself. When Plerion releases a policy change, download the current template again and run `terraform apply`. Terraform updates the role and policies in place. Your integration keeps working on the existing permissions until you apply the update.

If you onboarded before Plerion removed the integration token, your first apply on the current template also needs two variable changes: drop `auth_token`, which the template no longer declares, and add `-var 'tenant_id=<tenant_id>'` from the **Grant Plerion access** page.

<Tip>
  The template onboards one account. To onboard several accounts you manage with Terraform, reuse it per account with standard Terraform patterns, such as a module with a per-account AWS provider configuration.
</Tip>


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