AWS

Connecting AWS is an automated flow based on a CloudFormation template. Polylane never gets write access to your infrastructure: the stack only grants a read-only role that Polylane assumes cross-account.

Setup

1. Enter your 12-digit AWS Account ID.
2. Select the AWS Region to connect.
3. Click Deploy stack on AWS. You are redirected to the CloudFormation console with the template pre-loaded.
4. Review the template and click Create stack.
5. The stack creates an IAM role with read-only access that Polylane assumes.
6. Return to Polylane. Within minutes your resources start syncing.

The CloudFormation template is open: you can review exactly which permissions are granted before you create the stack.

Permissions

The IAM role is strictly read-only:

• The AWS-managed ReadOnlyAccess policy
• No write, delete, or modify permissions
• Cross-account assumption only, from Polylane's AWS account

Investigate alarms

When connecting you can let Polylane subscribe to the CloudWatch Alarms in the account. When an alarm fires, Polylane picks it up and investigates it automatically. This is optional and can be changed later.

Disconnecting

Delete the CloudFormation stack in your AWS account. That removes the IAM role and every other resource the stack created. You can also disconnect the account from Polylane, which stops all syncing.

The guided flow ends with a CloudFormation quick-create link that someone opens in the AWS console. If your AWS accounts only change through code review and a pipeline, nobody is there to click it. The same connection fits entirely in a CI job: one API call creates the connection and generates a CloudFormation template, your own tooling deploys the template, and the stack registers the account with Polylane by itself.

If you only want the template YAML, the console's connect dialog also shows it inline under Advanced, with Copy and Download buttons. The flow below needs no console at all.

Prerequisites

• A Polylane API key with the cloud_accounts:write and cloud_accounts:read scopes. See API keys and OAuth.
• Your workspace ID, which starts with ws_. Read it from GET /v1/workspaces with the same key.
• AWS credentials in the pipeline that can deploy CloudFormation stacks and create IAM roles in the account you are connecting.

Create the connection

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "workspaceId": "ws_0abc123",
    "account": "123456789012",
    "regions": ["us-east-1", "eu-west-1"]
  }'

account is the 12-digit AWS account ID. regions lists the regions Polylane scans on each sync; pass null to scan every region enabled on the account, resolved at each sync. Two optional booleans, createMonitoringAlarms and subscribeToAlarms, control the alert behavior described on Clouds and default to true.

The response carries everything the rest of the flow needs:

{
  "success": true,
  "result": {
    "provider": "aws",
    "url": "https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?...",
    "s3Url": "https://....s3.amazonaws.com/...?X-Amz-Expires=3600&...",
    "region": "us-east-1",
    "templateBody": "Description: This template creates the resources necessary for Polylane to observe your AWS Account\n..."
  }
}

• result.templateBody is the CloudFormation template generated for this connection, inline, so a job can write it straight to a file.
• result.s3Url is a presigned link to the same template. It expires after one hour.
• result.region is the region to deploy the stack in. The template is generated for exactly this region.
• result.url is the console quick-create link the guided flow uses. Ignore it here.

A 409 means the account is already connected. Change an existing connection's regions with PATCH /v1/cloud_accounts/{workspaceId}/{id} instead of reconnecting.

Write the template to a file

Write result.templateBody to a file, or download the presigned link:

curl -o polylane-connector.yaml "<result.s3Url>"

The template arrives ready to deploy. Its ExternalParameter parameter defaults to an external ID generated for this connection: it becomes the sts:ExternalId condition on the role the stack creates, and Polylane presents the same ID every time it assumes that role. Deploy the file exactly as generated and leave the parameter defaults alone. A stack with an edited external ID deploys fine but can never register.

That external ID is also why the file deserves credential handling: keep it inside the pipeline run rather than committing it or publishing it as a build artifact.

If the presigned link expires before you deploy, call the connect endpoint again for a fresh template. Repeating the call is safe until the account registers; after that it returns a 409.

Deploy the stack

aws cloudformation deploy \
  --stack-name PolylaneConnector \
  --template-file polylane-connector.yaml \
  --capabilities CAPABILITY_IAM \
  --region us-east-1

Use the region from step 1. CAPABILITY_IAM acknowledges the IAM role the stack creates; the role itself is unnamed, and a named inline policy does not require CAPABILITY_NAMED_IAM, so CAPABILITY_IAM suffices.

The stack creates the role Polylane assumes (read-only access plus operations on polylane-prefixed resources), its inline policy, a CloudTrail trail writing to a new S3 bucket, an SNS topic for trail and alarm notifications, and a reporter custom resource. The reporter is what registers the connection: it hands Polylane the role ARN while the stack is being created, so there is no callback to configure and nothing else to run.

The same deploy from Terraform:

resource "aws_cloudformation_stack" "polylane_connector" {
  name          = "PolylaneConnector"
  template_body = file("${path.module}/polylane-connector.yaml")
  capabilities  = ["CAPABILITY_IAM"]
}

Point the provider, or a provider alias, at the region from step 1. Reference the saved file with template_body rather than handing s3Url to template_url: the presigned link outlives neither the hour nor your next plan, so fetch the template in the same run that applies it.

Watch the account come online

The account appears once the stack's reporter reaches Polylane, normally moments after the stack completes. Poll it by its natural key, which returns 404 until registration lands and 200 after:

until curl -sf "https://api.polylane.com/v1/cloud_accounts/ws_0abc123/aws/123456789012/us-east-1" \
  -H "x-api-key: $POLYLANE_API_KEY" > /dev/null; do
  sleep 15
done

Give the loop a deadline so a failed deploy fails the job instead of hanging it. Once the account exists, its status field tracks the first sync: new on registration, syncing while resources stream in, ready when the first sync completes.

curl -s "https://api.polylane.com/v1/cloud_accounts/ws_0abc123/aws/123456789012/us-east-1" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status'

From here the account behaves exactly like one connected from the console: resources sync into the topology, Polylane runs its first check on its own, and the account page fills in.

Disconnect from the API

Deleting the connection also deletes the CloudFormation stack in your account. The call needs the cloud_accounts:delete scope:

curl -X DELETE https://api.polylane.com/v1/cloud_accounts/ws_0abc123/<cloud-account-id> \
  -H "x-api-key: $POLYLANE_API_KEY"

The role, its policy, and the CloudTrail S3 bucket carry DeletionPolicy: Retain, so they survive the stack deletion. Remove them yourself if you want the AWS account fully clean.