Skip to main content
With Terraform deployment, 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 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

1

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.
2

Select your capabilities

  • CSPM and CIEM are selected by default.
  • To include workload scanning, also select CWPP.
  • Click Next.
3

Select the Terraform deployment strategy

  • 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.
4

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, or aws-integration-plerion-managed.tf for Plerion-managed scanning.
5

Copy the values shown in the console

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
6

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.
For Plerion-managed scanning, also pass -var 'service_account_id=<service_account_id>'. To onboard with CSPM and CIEM only, add -var 'capabilities=CSPM'.
7

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. Plerion-managed scanning needs no further setup.
8

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.
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.

​
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.