> ## 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.
The template registers the integration by calling the Plerion API during `terraform apply`, using a short-lived token you generate in the console. Generate the token immediately before you apply.
***
## 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 generate an integration token.
***
## 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 two 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.
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
* 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.
* **CSPM** and **CIEM** are selected by default.
* To include workload scanning, also select **CWPP**.
* Click `Next`.
* On the **Deployment strategy** step, select **Terraform**.
* If you selected CWPP, choose whether scanning runs in the **same account** or through a **Plerion-managed service account**.
* Click `Next`.
On the **Grant Plerion access** page, download the Terraform template into its own directory. The file is `aws-integration.tf` for same-account scanning, or `aws-integration-plerion-managed.tf` for Plerion-managed scanning.
The page lists the values to pass to the template:
* `plerion_api_url`
* `plerion_account_id`
* `external_id`
* `service_account_id` (Plerion-managed scanning only)
* `auth_token`, the short-lived integration token
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=https://au.api.plerion.com' \
-var 'plerion_account_id=' \
-var 'external_id=' \
-var 'auth_token='
```
For Plerion-managed scanning, also pass `-var 'service_account_id='`. To onboard with CSPM and CIEM only, add `-var 'capabilities=CSPM'`.
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. Plerion-managed scanning needs no further setup.
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.
The integration token is short-lived. If `terraform apply` reports that registration did not succeed, return to the **Grant Plerion access** page for a fresh token and apply again.
***
## Template inputs
Pass these variables at apply time, or set them in a `.tfvars` file.
| Variable | Required | Default | Description |
| --------------------- | ----------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plerion_api_url` | Yes | None | Base URL of the Plerion API to register with, shown in the console (for example `https://au.api.plerion.com`). |
| `plerion_account_id` | Yes | None | Plerion AWS account ID, shown in the console. |
| `external_id` | Yes | None | External ID for the cross-account access role, shown in the console. |
| `auth_token` | Yes | None | Short-lived integration token from the console. Marked sensitive. |
| `service_account_id` | Plerion-managed template only | None | AWS account ID of the Plerion-managed service account, shown in the console. |
| `integration_name` | No | AWS account ID | Display name for the integration in Plerion. |
| `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). |
***
## 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.
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.