Deploy Plerion with Terraform

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. No credential is involved. Plerion verifies the registration by assuming the role the template creates, using your tenant’s external ID.

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

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

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.

Select your capabilities

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

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.

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.

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)

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.

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

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.

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.

If terraform apply reports that registration did not succeed, check tenant_id and external_id against the console 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	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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Getting started

Administration

Integrations

Platform

Before you start

Choose how CWPP scanning runs

Steps to onboard with Terraform

Template inputs

Set up a service account with Terraform

Service account template inputs

Keeping permissions up to date

​Before you start

​Choose how CWPP scanning runs

​Steps to onboard with Terraform

​Template inputs

​Set up a service account with Terraform

​Service account template inputs

​Keeping permissions up to date

Before you start

Choose how CWPP scanning runs

Steps to onboard with Terraform

Template inputs

Set up a service account with Terraform

Service account template inputs

Keeping permissions up to date