AWS

连接AWS是一个基于CloudFormation模板的自动化流程。Polylane永远不会获得对你基础设施的写入权限：该栈只授予一个由Polylane跨账户扮演的只读角色。

设置

1. 输入你的12位AWS Account ID。
2. 选择要连接的AWS Region。
3. 点击Deploy stack on AWS。你会被重定向到已预加载模板的CloudFormation控制台。
4. 审阅模板并点击Create stack。
5. 该栈创建一个具有只读访问权限、由Polylane扮演的IAM角色。
6. 回到Polylane。几分钟内你的资源开始同步。

CloudFormation模板是公开的：你可以在创建栈之前准确审阅授予了哪些权限。

权限

该IAM角色严格只读：

• AWS托管的ReadOnlyAccess策略
• 没有写入、删除或修改权限
• 只能从Polylane的AWS账户跨账户扮演

调查警报

连接时你可以让Polylane订阅该账户中的CloudWatch Alarms。当警报触发时，Polylane会接收并自动调查它。这是可选的，之后可以更改。

断开连接

在你的AWS账户中删除CloudFormation栈。这会移除该IAM角色以及栈创建的其他所有资源。你也可以在Polylane中断开该账户，这会停止所有同步。

引导式流程的最后一步是一个由某人在AWS控制台中打开的CloudFormation快速创建链接。如果你的AWS账户只通过代码审查和流水线变更，那就没有人在那里点击它。同样的连接可以完全放进一个CI作业：一次API调用创建连接并生成CloudFormation模板，你自己的工具部署模板，然后栈自行向Polylane注册账户。

如果你只想要模板YAML，控制台的连接对话框也会在Advanced下内联显示它，带有Copy和Download按钮。下面的流程完全不需要控制台。

前提条件

• 一个具有cloud_accounts:write和cloud_accounts:read权限范围的Polylane API密钥。参见API密钥与OAuth。
• 你的工作区ID，以ws_开头。用同一个密钥从GET /v1/workspaces读取它。
• 流水线中能在你要连接的账户中部署CloudFormation栈并创建IAM角色的AWS凭据。

创建连接

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是12位的AWS账户ID。regions列出Polylane在每次同步中扫描的区域；传入null则扫描账户上启用的每个区域，在每次同步时解析。两个可选的布尔值createMonitoringAlarms和subscribeToAlarms控制Clouds中描述的告警行为，默认为true。

响应带有流程其余部分需要的一切：

{
  "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是为此连接生成的内联CloudFormation模板，所以作业可以直接把它写入文件。
• result.s3Url是指向同一模板的预签名链接。它在一小时后过期。
• result.region是要部署栈的区域。模板正是为这个区域生成的。
• result.url是引导式流程使用的控制台快速创建链接。在这里忽略它。

409意味着该账户已经连接。用PATCH /v1/cloud_accounts/{workspaceId}/{id}更改现有连接的区域，而不是重新连接。

把模板写入文件

把result.templateBody写入文件，或下载预签名链接：

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

模板到达时即可部署。它的ExternalParameter参数默认为为此连接生成的外部ID：它成为栈所创建角色上的sts:ExternalId条件，Polylane每次扮演该角色时都会出示同一个ID。原样部署生成的文件，不要改动参数默认值。外部ID被编辑过的栈能正常部署，但永远无法注册。

这个外部ID也是该文件值得按凭据处理的原因：把它留在流水线运行内部，而不是提交它或把它发布为构建产物。

如果预签名链接在你部署之前过期，再次调用连接端点获取新模板。在账户注册之前重复调用是安全的；之后它会返回409。

部署栈

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

使用第1步的region。CAPABILITY_IAM确认栈创建的IAM角色；角色本身没有命名，而命名的内联策略不需要CAPABILITY_NAMED_IAM，所以CAPABILITY_IAM就足够。

该栈创建Polylane扮演的角色（只读访问加上对polylane前缀资源的操作）、它的内联策略、一条写入新S3存储桶的CloudTrail跟踪、一个用于跟踪和警报通知的SNS主题，以及一个reporter自定义资源。reporter就是注册连接的东西：它在栈创建期间把角色ARN交给Polylane，所以没有需要配置的回调，也没有其他需要运行的东西。

用Terraform进行同样的部署：

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

把provider或provider别名指向第1步的region。用template_body引用保存的文件，而不是把s3Url交给template_url：预签名链接既活不过那一小时，也活不过你的下一次plan，所以在应用它的同一次运行中获取模板。

观察账户上线

一旦栈的reporter到达Polylane，账户就会出现，通常在栈完成后片刻。按它的自然键轮询，注册落地前返回404，之后返回200：

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

给循环一个截止时间，让失败的部署使作业失败而不是挂起。账户存在后，它的status字段跟踪第一次同步：注册时为new，资源流入时为syncing，第一次同步完成时为ready。

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'

从这里起，账户的行为与从控制台连接的账户完全一致：资源同步到拓扑中，Polylane自行运行它的第一次检查，账户页面逐渐填充。

从API断开连接

删除连接也会删除你账户中的CloudFormation栈。该调用需要cloud_accounts:delete权限范围：

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

角色、它的策略和CloudTrail S3存储桶带有DeletionPolicy: Retain，所以它们在栈删除后仍然保留。如果你想让AWS账户完全干净，请自行移除它们。