AWS

AWS wird über einen automatisierten Ablauf auf Basis einer CloudFormation-Vorlage verbunden. Polylane bekommt nie Schreibzugriff auf deine Infrastruktur: Der Stack vergibt nur eine schreibgeschützte Rolle, die Polylane kontoübergreifend annimmt.

Einrichtung

1. Gib deine 12-stellige AWS Account ID ein.
2. Wähle die AWS Region, die verbunden werden soll.
3. Klicke auf Deploy stack on AWS. Du wirst zur CloudFormation-Konsole weitergeleitet, die Vorlage ist bereits geladen.
4. Prüfe die Vorlage und klicke auf Create stack.
5. Der Stack legt eine IAM-Rolle mit Lesezugriff an, die Polylane annimmt.
6. Kehre zu Polylane zurück. Innerhalb weniger Minuten beginnt der Sync deiner Ressourcen.

Die CloudFormation-Vorlage ist offen: Du kannst genau prüfen, welche Berechtigungen vergeben werden, bevor du den Stack anlegst.

Berechtigungen

Die IAM-Rolle ist strikt schreibgeschützt:

• Die von AWS verwaltete Richtlinie ReadOnlyAccess
• Keine Berechtigungen zum Schreiben, Löschen oder Ändern
• Nur kontoübergreifende Annahme, aus dem AWS-Konto von Polylane

Alarme untersuchen

Beim Verbinden kannst du Polylane erlauben, die CloudWatch-Alarme im Konto zu abonnieren. Wenn ein Alarm auslöst, nimmt Polylane ihn auf und untersucht ihn automatisch. Das ist optional und lässt sich später ändern.

Verbindung trennen

Lösche den CloudFormation-Stack in deinem AWS-Konto. Damit werden die IAM-Rolle und alle anderen vom Stack angelegten Ressourcen entfernt. Du kannst das Konto auch in Polylane trennen, womit jeder Sync stoppt.

Der geführte Ablauf endet mit einem CloudFormation-Quick-Create-Link, den jemand in der AWS-Konsole öffnet. Wenn sich deine AWS-Konten nur über Code-Review und eine Pipeline ändern, ist niemand da, der ihn anklickt. Dieselbe Verbindung passt vollständig in einen CI-Job: Ein API-Aufruf erstellt die Verbindung und erzeugt eine CloudFormation-Vorlage, dein eigenes Tooling deployt die Vorlage, und der Stack registriert das Konto selbst bei Polylane.

Wenn du nur das Vorlagen-YAML willst, zeigt der Verbindungsdialog der Konsole es auch inline unter Advanced, mit Schaltflächen zum Kopieren und Herunterladen. Der Ablauf unten braucht überhaupt keine Konsole.

Voraussetzungen

• Ein Polylane-API-Schlüssel mit den Scopes cloud_accounts:write und cloud_accounts:read. Siehe API-Schlüssel und OAuth.
• Deine Workspace-ID, die mit ws_ beginnt. Lies sie mit demselben Schlüssel aus GET /v1/workspaces.
• AWS-Zugangsdaten in der Pipeline, die CloudFormation-Stacks deployen und IAM-Rollen in dem Konto anlegen können, das du verbindest.

Verbindung erstellen

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 ist die 12-stellige AWS-Konto-ID. regions listet die Regionen auf, die Polylane bei jedem Sync scannt; übergib null, um jede im Konto aktivierte Region zu scannen, aufgelöst bei jedem Sync. Zwei optionale Booleans, createMonitoringAlarms und subscribeToAlarms, steuern das unter Clouds beschriebene Alert-Verhalten und stehen standardmäßig auf true.

Die Antwort enthält alles, was der Rest des Ablaufs braucht:

{
  "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 ist die für diese Verbindung erzeugte CloudFormation-Vorlage, inline, ein Job kann sie also direkt in eine Datei schreiben.
• result.s3Url ist ein vorsignierter Link auf dieselbe Vorlage. Er läuft nach einer Stunde ab.
• result.region ist die Region, in der der Stack deployt werden soll. Die Vorlage ist genau für diese Region erzeugt.
• result.url ist der Quick-Create-Link der Konsole, den der geführte Ablauf verwendet. Ignoriere ihn hier.

Ein 409 bedeutet, dass das Konto bereits verbunden ist. Ändere die Regionen einer bestehenden Verbindung mit PATCH /v1/cloud_accounts/{workspaceId}/{id}, statt neu zu verbinden.

Vorlage in eine Datei schreiben

Schreibe result.templateBody in eine Datei oder lade den vorsignierten Link herunter:

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

Die Vorlage kommt bereit zum Deployen an. Ihr Parameter ExternalParameter steht standardmäßig auf einer für diese Verbindung erzeugten externen ID: Sie wird zur Bedingung sts:ExternalId auf der Rolle, die der Stack anlegt, und Polylane legt dieselbe ID jedes Mal vor, wenn es diese Rolle annimmt. Deploye die Datei genau so, wie sie erzeugt wurde, und lass die Parameter-Standardwerte unangetastet. Ein Stack mit geänderter externer ID lässt sich problemlos deployen, kann sich aber nie registrieren.

Diese externe ID ist auch der Grund, warum die Datei wie Zugangsdaten behandelt gehört: Halte sie innerhalb des Pipeline-Laufs, statt sie zu committen oder als Build-Artefakt zu veröffentlichen.

Wenn der vorsignierte Link abläuft, bevor du deployst, rufe den Verbindungsendpunkt erneut auf, um eine frische Vorlage zu bekommen. Den Aufruf zu wiederholen ist sicher, bis sich das Konto registriert; danach liefert er einen 409.

Stack deployen

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

Verwende die region aus Schritt 1. CAPABILITY_IAM bestätigt die IAM-Rolle, die der Stack anlegt; die Rolle selbst ist unbenannt, und eine benannte Inline-Richtlinie erfordert kein CAPABILITY_NAMED_IAM, CAPABILITY_IAM reicht also.

Der Stack legt die Rolle an, die Polylane annimmt (Lesezugriff plus Operationen auf Ressourcen mit dem Präfix polylane), ihre Inline-Richtlinie, einen CloudTrail-Trail, der in einen neuen S3-Bucket schreibt, ein SNS-Topic für Trail- und Alarmbenachrichtigungen und eine Reporter-Custom-Resource. Der Reporter ist es, der die Verbindung registriert: Er übergibt Polylane den Rollen-ARN, während der Stack angelegt wird, es gibt also keinen Callback zu konfigurieren und nichts weiter auszuführen.

Derselbe Deploy aus Terraform:

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

Richte den Provider oder einen Provider-Alias auf die region aus Schritt 1. Referenziere die gespeicherte Datei mit template_body, statt s3Url an template_url zu übergeben: Der vorsignierte Link überlebt weder die Stunde noch deinen nächsten Plan, hole die Vorlage also in demselben Lauf, der sie anwendet.

Zusehen, wie das Konto online geht

Das Konto erscheint, sobald der Reporter des Stacks Polylane erreicht, normalerweise Augenblicke nach Abschluss des Stacks. Frage es über seinen natürlichen Schlüssel ab, der 404 liefert, bis die Registrierung eintrifft, und danach 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

Gib der Schleife eine Frist, damit ein fehlgeschlagener Deploy den Job fehlschlagen lässt, statt ihn hängen zu lassen. Sobald das Konto existiert, verfolgt sein Feld status den ersten Sync: new bei der Registrierung, syncing, während Ressourcen einlaufen, ready, wenn der erste Sync abgeschlossen ist.

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'

Von hier an verhält sich das Konto genau wie eines, das aus der Konsole verbunden wurde: Ressourcen werden in die Topologie synchronisiert, Polylane führt seinen ersten Check von selbst aus, und die Kontoseite füllt sich.

Über die API trennen

Das Löschen der Verbindung löscht auch den CloudFormation-Stack in deinem Konto. Der Aufruf braucht den Scope 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"

Die Rolle, ihre Richtlinie und der CloudTrail-S3-Bucket tragen DeletionPolicy: Retain, sie überleben die Stack-Löschung also. Entferne sie selbst, wenn du das AWS-Konto vollständig sauber haben willst.