AWS

Conectar a AWS é um fluxo automatizado baseado em um template do CloudFormation. O Polylane nunca recebe acesso de escrita à sua infraestrutura: o stack concede apenas uma função somente leitura que o Polylane assume entre contas.

Configuração

1. Informe o AWS Account ID de 12 dígitos.
2. Selecione a AWS Region a conectar.
3. Clique em Deploy stack on AWS. Você é redirecionado ao console do CloudFormation com o template já carregado.
4. Revise o template e clique em Create stack.
5. O stack cria uma função IAM com acesso somente leitura que o Polylane assume.
6. Volte ao Polylane. Em poucos minutos seus recursos começam a sincronizar.

O template do CloudFormation é aberto: você pode revisar exatamente quais permissões são concedidas antes de criar o stack.

Permissões

A função IAM é estritamente somente leitura:

• A política ReadOnlyAccess gerenciada pela AWS
• Nenhuma permissão de escrita, exclusão ou modificação
• Assunção apenas entre contas, a partir da conta AWS do Polylane

Investigar alarmes

Ao conectar, você pode permitir que o Polylane se inscreva nos CloudWatch Alarms da conta. Quando um alarme dispara, o Polylane o captura e investiga automaticamente. Isso é opcional e pode ser alterado depois.

Desconectar

Exclua o stack do CloudFormation na sua conta AWS. Isso remove a função IAM e todos os outros recursos que o stack criou. Você também pode desconectar a conta no Polylane, o que interrompe toda a sincronização.

O fluxo guiado termina com um link de criação rápida do CloudFormation que alguém abre no console da AWS. Se as suas contas AWS só mudam por revisão de código e por uma pipeline, não há ninguém ali para clicar nele. A mesma conexão cabe inteiramente em um job de CI: uma chamada de API cria a conexão e gera um template do CloudFormation, sua própria ferramenta implanta o template, e o stack registra a conta no Polylane por conta própria.

Se você só quiser o YAML do template, o diálogo de conexão do console também o mostra inline em Advanced, com botões Copy e Download. O fluxo abaixo não precisa de console nenhum.

Pré-requisitos

• Uma chave de API do Polylane com os escopos cloud_accounts:write e cloud_accounts:read. Veja Chaves de API e OAuth.
• O ID do seu workspace, que começa com ws_. Leia-o em GET /v1/workspaces com a mesma chave.
• Credenciais AWS na pipeline que possam implantar stacks do CloudFormation e criar funções IAM na conta que você está conectando.

Criar a conexão

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 é o ID de 12 dígitos da conta AWS. regions lista as regiões que o Polylane varre em cada sincronização; passe null para varrer todas as regiões habilitadas na conta, resolvidas a cada sincronização. Dois booleanos opcionais, createMonitoringAlarms e subscribeToAlarms, controlam o comportamento de alertas descrito em Clouds e têm true como padrão.

A resposta traz tudo o que o restante do fluxo precisa:

{
  "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 é o template do CloudFormation gerado para esta conexão, inline, para que um job possa gravá-lo direto em um arquivo.
• result.s3Url é um link pré-assinado para o mesmo template. Ele expira em uma hora.
• result.region é a região onde implantar o stack. O template é gerado exatamente para essa região.
• result.url é o link de criação rápida do console que o fluxo guiado usa. Ignore-o aqui.

Um 409 significa que a conta já está conectada. Altere as regiões de uma conexão existente com PATCH /v1/cloud_accounts/{workspaceId}/{id} em vez de reconectar.

Gravar o template em um arquivo

Grave result.templateBody em um arquivo, ou baixe o link pré-assinado:

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

O template chega pronto para implantar. Seu parâmetro ExternalParameter tem como padrão um ID externo gerado para esta conexão: ele se torna a condição sts:ExternalId na função que o stack cria, e o Polylane apresenta o mesmo ID toda vez que assume essa função. Implante o arquivo exatamente como gerado e deixe os padrões dos parâmetros em paz. Um stack com um ID externo editado implanta normalmente, mas nunca consegue se registrar.

Esse ID externo também é o motivo pelo qual o arquivo merece tratamento de credencial: mantenha-o dentro da execução da pipeline em vez de commitá-lo ou publicá-lo como artefato de build.

Se o link pré-assinado expirar antes de você implantar, chame o endpoint de conexão de novo para obter um template novo. Repetir a chamada é seguro até a conta se registrar; depois disso ela retorna um 409.

Implantar o stack

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

Use a region do passo 1. CAPABILITY_IAM reconhece a função IAM que o stack cria; a função em si não tem nome, e uma política inline nomeada não exige CAPABILITY_NAMED_IAM, então CAPABILITY_IAM basta.

O stack cria a função que o Polylane assume (acesso somente leitura mais operações em recursos com prefixo polylane), sua política inline, uma trilha do CloudTrail gravando em um novo bucket S3, um tópico SNS para notificações de trilha e de alarmes, e um custom resource reporter. O reporter é o que registra a conexão: ele entrega ao Polylane o ARN da função enquanto o stack está sendo criado, então não há callback para configurar nem nada mais para executar.

O mesmo deploy a partir do Terraform:

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

Aponte o provider, ou um alias de provider, para a region do passo 1. Referencie o arquivo salvo com template_body em vez de entregar s3Url a template_url: o link pré-assinado não sobrevive nem à hora nem ao seu próximo plan, então busque o template na mesma execução que o aplica.

Acompanhar a conta ficar online

A conta aparece assim que o reporter do stack alcança o Polylane, normalmente instantes depois de o stack concluir. Consulte-a pela sua chave natural, que retorna 404 até o registro chegar e 200 depois:

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

Dê um prazo ao loop para que um deploy com falha faça o job falhar em vez de travá-lo. Quando a conta existir, seu campo status acompanha a primeira sincronização: new no registro, syncing enquanto os recursos chegam, ready quando a primeira sincronização termina.

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'

A partir daqui a conta se comporta exatamente como uma conectada pelo console: os recursos sincronizam para a topologia, o Polylane executa sua primeira verificação por conta própria, e a página da conta se preenche.

Desconectar pela API

Excluir a conexão também exclui o stack do CloudFormation na sua conta. A chamada precisa do escopo 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"

A função, sua política e o bucket S3 do CloudTrail carregam DeletionPolicy: Retain, então sobrevivem à exclusão do stack. Remova-os você mesmo se quiser a conta AWS totalmente limpa.