AWS

Connecting AWS is an automated flow based on a CloudFormation template. The stack creates an IAM role that Polylane assumes cross-account. The role can read your account and change the resources that Polylane creates. It can also change, mute or unmute any CloudWatch alarm in the account. Polylane uses this access only as described below.

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 the IAM role 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 has these permissions:

• The AWS-managed ReadOnlyAccess policy. The role cannot read S3 objects or DynamoDB items, except in the S3 bucket of the stack.
• Changes to the resources that Polylane creates: Lambda functions, SNS topics, CloudWatch dashboards and CloudWatch alarms with names that start with polylane- or Polylane-, and the CloudTrail trail and S3 bucket of the stack.
• Tags on resources, and an EKS access entry for the role itself, so that it can read your Kubernetes clusters.
• Write access to every CloudWatch alarm in the account. The role can create or replace an alarm (PutMetricAlarm replaces the full alarm configuration) and mute or unmute an alarm. Polylane uses this access only to add or remove its alert topic when you let it investigate your alarms (see below), and to mute or unmute an alarm when you ask it to. The role cannot delete an alarm that Polylane did not create.

Polylane assumes the role from its AWS account with an external ID that is unique to your connection.

Investigate alarms

When you connect, you can let Polylane investigate the CloudWatch alarms in the account. When an alarm fires, Polylane gets the notification and investigates it automatically.

To do this, Polylane adds its alert topic to the actions of each alarm, and to each alarm that you create later. The alarm keeps its threshold and its other actions. When this option is off, Polylane does not add its topic to your alarms.

Disconnecting

Delete the CloudFormation stack in your AWS account. The IAM role, its policy, and the CloudTrail S3 bucket stay after the stack is deleted. Delete them yourself to remove all access. 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.