AWS

Подключение AWS: это автоматизированный процесс на основе шаблона CloudFormation. Polylane никогда не получает доступ на запись к вашей инфраструктуре: стек выдаёт только роль с правами на чтение, которую Polylane принимает кросс-аккаунтно.

Настройка

1. Введите ваш 12-значный AWS Account ID.
2. Выберите AWS Region для подключения.
3. Нажмите Deploy stack on AWS. Вы будете перенаправлены в консоль CloudFormation с уже загруженным шаблоном.
4. Просмотрите шаблон и нажмите Create stack.
5. Стек создаёт IAM-роль с доступом только на чтение, которую принимает Polylane.
6. Вернитесь в Polylane. Через несколько минут ваши ресурсы начнут синхронизироваться.

Шаблон CloudFormation открыт: вы можете проверить, какие именно разрешения выдаются, прежде чем создавать стек.

Разрешения

IAM-роль строго ограничена чтением:

• Управляемая AWS политика ReadOnlyAccess
• Никаких разрешений на запись, удаление или изменение
• Только кросс-аккаунтное принятие роли из AWS-аккаунта Polylane

Расследование алармов

При подключении вы можете разрешить Polylane подписаться на CloudWatch Alarms в аккаунте. Когда аларм срабатывает, Polylane подхватывает его и расследует автоматически. Это необязательно и может быть изменено позже.

Отключение

Удалите стек CloudFormation в вашем AWS-аккаунте. Это удалит IAM-роль и все остальные ресурсы, созданные стеком. Вы также можете отключить аккаунт в Polylane, что остановит всю синхронизацию.

Пошаговый процесс заканчивается ссылкой быстрого создания CloudFormation, которую кто-то открывает в консоли AWS. Если ваши AWS-аккаунты меняются только через код-ревью и пайплайн, нажимать на неё некому. То же подключение целиком помещается в CI-задание: один вызов API создаёт подключение и генерирует шаблон CloudFormation, ваши собственные инструменты деплоят шаблон, и стек сам регистрирует аккаунт в Polylane.

Если вам нужен только YAML шаблона, диалог подключения в консоли также показывает его в разделе Advanced с кнопками Copy и Download. Процесс ниже вообще не требует консоли.

Требования

• API-ключ Polylane с областями cloud_accounts:write и cloud_accounts:read. См. API-ключи и OAuth.
• ID вашего рабочего пространства, который начинается с ws_. Прочитайте его из GET /v1/workspaces тем же ключом.
• Учётные данные AWS в пайплайне, которые могут деплоить стеки CloudFormation и создавать IAM-роли в подключаемом аккаунте.

Создайте подключение

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-значный ID AWS-аккаунта. regions перечисляет регионы, которые Polylane сканирует при каждой синхронизации; передайте null, чтобы сканировать каждый регион, включённый в аккаунте, с разрешением при каждой синхронизации. Два необязательных булевых поля, createMonitoringAlarms и subscribeToAlarms, управляют поведением алертов, описанным на странице Облака, и по умолчанию равны 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

Используйте region из шага 1. CAPABILITY_IAM подтверждает IAM-роль, которую создаёт стек; сама роль без имени, а именованная inline-политика не требует CAPABILITY_NAMED_IAM, поэтому CAPABILITY_IAM достаточно.

Стек создаёт роль, которую принимает Polylane (доступ на чтение плюс операции над ресурсами с префиксом polylane), её inline-политику, трейл CloudTrail, пишущий в новый бакет S3, SNS-топик для уведомлений трейла и алармов и пользовательский ресурс-репортёр. Репортёр и регистрирует подключение: он передаёт Polylane ARN роли во время создания стека, так что не нужно настраивать колбэк и запускать что-либо ещё.

Тот же деплой из Terraform:

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

Направьте провайдер или алиас провайдера на region из шага 1. Ссылайтесь на сохранённый файл через template_body, а не передавайте s3Url в template_url: предподписанная ссылка не переживёт ни час, ни ваш следующий plan, поэтому получайте шаблон в том же запуске, который его применяет.

Дождитесь появления аккаунта

Аккаунт появляется, когда репортёр стека достигает 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"

Роль, её политика и бакет S3 CloudTrail несут DeletionPolicy: Retain, поэтому переживают удаление стека. Удалите их сами, если хотите полностью очистить AWS-аккаунт.