AWS

Collegare AWS è un flusso automatizzato basato su un template CloudFormation. Polylane non ottiene mai accesso in scrittura alla tua infrastruttura: lo stack concede soltanto un ruolo in sola lettura che Polylane assume cross-account.

Configurazione

1. Inserisci il tuo AWS Account ID a 12 cifre.
2. Seleziona la AWS Region da collegare.
3. Fai clic su Deploy stack on AWS. Vieni reindirizzato alla console CloudFormation con il template già caricato.
4. Rivedi il template e fai clic su Create stack.
5. Lo stack crea un ruolo IAM con accesso in sola lettura che Polylane assume.
6. Torna in Polylane. Entro pochi minuti le tue risorse iniziano a sincronizzarsi.

Il template CloudFormation è aperto: puoi verificare esattamente quali permessi vengono concessi prima di creare lo stack.

Permessi

Il ruolo IAM è strettamente in sola lettura:

• La policy ReadOnlyAccess gestita da AWS
• Nessun permesso di scrittura, eliminazione o modifica
• Assunzione solo cross-account, dall'account AWS di Polylane

Indagare gli allarmi

Durante il collegamento puoi lasciare che Polylane si iscriva ai CloudWatch Alarms dell'account. Quando un allarme scatta, Polylane lo raccoglie e lo indaga automaticamente. È facoltativo e può essere cambiato in seguito.

Scollegamento

Elimina lo stack CloudFormation nel tuo account AWS. Questo rimuove il ruolo IAM e ogni altra risorsa creata dallo stack. Puoi anche scollegare l'account da Polylane, il che interrompe ogni sincronizzazione.

Il flusso guidato termina con un link di creazione rapida CloudFormation che qualcuno apre nella console AWS. Se i tuoi account AWS cambiano solo tramite code review e una pipeline, non c'è nessuno a fare clic. Lo stesso collegamento sta interamente in un job CI: una chiamata API crea il collegamento e genera un template CloudFormation, i tuoi strumenti deployano il template e lo stack registra da solo l'account presso Polylane.

Se vuoi solo lo YAML del template, anche la finestra di collegamento della console lo mostra inline sotto Advanced, con i pulsanti Copy e Download. Il flusso qui sotto non ha bisogno della console.

Prerequisiti

• Una chiave API Polylane con gli scope cloud_accounts:write e cloud_accounts:read. Vedi Chiavi API e OAuth.
• L'ID del tuo workspace, che inizia con ws_. Leggilo da GET /v1/workspaces con la stessa chiave.
• Credenziali AWS nella pipeline in grado di deployare stack CloudFormation e creare ruoli IAM nell'account che stai collegando.

Crea il collegamento

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 è l'ID a 12 cifre dell'account AWS. regions elenca le regioni che Polylane analizza a ogni sincronizzazione; passa null per analizzare ogni regione abilitata sull'account, risolta a ogni sincronizzazione. Due booleani facoltativi, createMonitoringAlarms e subscribeToAlarms, controllano il comportamento degli alert descritto in Cloud e valgono true per impostazione predefinita.

La risposta contiene tutto ciò che serve al resto del flusso:

{
  "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 è il template CloudFormation generato per questo collegamento, inline, così un job può scriverlo direttamente in un file.
• result.s3Url è un link presigned allo stesso template. Scade dopo un'ora.
• result.region è la regione in cui deployare lo stack. Il template è generato esattamente per questa regione.
• result.url è il link di creazione rapida nella console che usa il flusso guidato. Qui ignoralo.

Un 409 significa che l'account è già collegato. Cambia le regioni di un collegamento esistente con PATCH /v1/cloud_accounts/{workspaceId}/{id} invece di ricollegare.

Scrivi il template in un file

Scrivi result.templateBody in un file, oppure scarica il link presigned:

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

Il template arriva pronto per il deploy. Il suo parametro ExternalParameter ha come valore predefinito un ID esterno generato per questo collegamento: diventa la condizione sts:ExternalId sul ruolo che lo stack crea, e Polylane presenta lo stesso ID ogni volta che assume quel ruolo. Deploya il file esattamente com'è stato generato e lascia intatti i valori predefiniti dei parametri. Uno stack con un ID esterno modificato viene deployato senza problemi ma non potrà mai registrarsi.

Quell'ID esterno è anche il motivo per cui il file merita di essere trattato come una credenziale: tienilo dentro l'esecuzione della pipeline invece di committarlo o pubblicarlo come artefatto di build.

Se il link presigned scade prima del deploy, richiama l'endpoint di collegamento per un template nuovo. Ripetere la chiamata è sicuro finché l'account non si registra; dopo restituisce un 409.

Deploya lo stack

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

Usa la region del passo 1. CAPABILITY_IAM riconosce il ruolo IAM che lo stack crea; il ruolo stesso non ha nome, e una inline policy con nome non richiede CAPABILITY_NAMED_IAM, quindi CAPABILITY_IAM è sufficiente.

Lo stack crea il ruolo che Polylane assume (accesso in sola lettura più operazioni sulle risorse con prefisso polylane), la sua inline policy, un trail CloudTrail che scrive in un nuovo bucket S3, un topic SNS per le notifiche del trail e degli allarmi e una custom resource di reporting. Il reporter è ciò che registra il collegamento: consegna a Polylane l'ARN del ruolo mentre lo stack viene creato, quindi non c'è nessun callback da configurare e nient'altro da eseguire.

Lo stesso deploy da Terraform:

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

Punta il provider, o un alias del provider, alla region del passo 1. Fai riferimento al file salvato con template_body invece di passare s3Url a template_url: il link presigned non sopravvive né all'ora né al tuo prossimo plan, quindi recupera il template nella stessa esecuzione che lo applica.

Osserva l'account andare online

L'account compare quando il reporter dello stack raggiunge Polylane, normalmente pochi istanti dopo il completamento dello stack. Interrogalo tramite la sua chiave naturale, che restituisce 404 finché la registrazione non arriva e 200 dopo:

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

Dai al ciclo una scadenza, così un deploy fallito fa fallire il job invece di bloccarlo. Una volta che l'account esiste, il suo campo status segue la prima sincronizzazione: new alla registrazione, syncing mentre le risorse arrivano, ready quando la prima sincronizzazione è completa.

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'

Da qui l'account si comporta esattamente come uno collegato dalla console: le risorse si sincronizzano nella topologia, Polylane esegue da solo il suo primo controllo e la pagina dell'account si riempie.

Scollega dall'API

Eliminare il collegamento elimina anche lo stack CloudFormation nel tuo account. La chiamata richiede lo 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"

Il ruolo, la sua policy e il bucket S3 di CloudTrail hanno DeletionPolicy: Retain, quindi sopravvivono all'eliminazione dello stack. Rimuovili tu se vuoi l'account AWS completamente pulito.