AWS

Conectar AWS es un flujo automatizado basado en una plantilla de CloudFormation. Polylane nunca obtiene acceso de escritura a tu infraestructura: el stack solo concede un rol de solo lectura que Polylane asume entre cuentas.

Configuración

1. Introduce tu AWS Account ID de 12 dígitos.
2. Selecciona la AWS Region que quieres conectar.
3. Haz clic en Deploy stack on AWS. Se te redirige a la consola de CloudFormation con la plantilla ya cargada.
4. Revisa la plantilla y haz clic en Create stack.
5. El stack crea un rol de IAM con acceso de solo lectura que Polylane asume.
6. Vuelve a Polylane. En cuestión de minutos tus recursos empiezan a sincronizarse.

La plantilla de CloudFormation es abierta: puedes revisar exactamente qué permisos se conceden antes de crear el stack.

Permisos

El rol de IAM es estrictamente de solo lectura:

• La política ReadOnlyAccess gestionada por AWS
• Sin permisos de escritura, eliminación ni modificación
• Solo asunción entre cuentas, desde la cuenta de AWS de Polylane

Investigar alarmas

Al conectar puedes permitir que Polylane se suscriba a las alarmas de CloudWatch de la cuenta. Cuando una alarma se dispara, Polylane la recoge y la investiga automáticamente. Es opcional y se puede cambiar más adelante.

Desconexión

Elimina el stack de CloudFormation en tu cuenta de AWS. Eso elimina el rol de IAM y todos los demás recursos que creó el stack. También puedes desconectar la cuenta desde Polylane, lo que detiene toda la sincronización.

El flujo guiado termina con un enlace de creación rápida de CloudFormation que alguien abre en la consola de AWS. Si tus cuentas de AWS solo cambian mediante revisión de código y un pipeline, no hay nadie ahí para hacer clic. La misma conexión cabe por completo en un trabajo de CI: una llamada a la API crea la conexión y genera una plantilla de CloudFormation, tus propias herramientas despliegan la plantilla, y el stack registra la cuenta en Polylane por sí solo.

Si solo quieres el YAML de la plantilla, el diálogo de conexión de la consola también lo muestra inline en Advanced, con botones de Copy y Download. El flujo de abajo no necesita consola en absoluto.

Requisitos previos

• Una clave de API de Polylane con los scopes cloud_accounts:write y cloud_accounts:read. Consulta Claves de API y OAuth.
• El ID de tu espacio de trabajo, que empieza por ws_. Léelo desde GET /v1/workspaces con la misma clave.
• Credenciales de AWS en el pipeline que puedan desplegar stacks de CloudFormation y crear roles de IAM en la cuenta que estás conectando.

Crear la conexión

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 es el ID de cuenta de AWS de 12 dígitos. regions lista las regiones que Polylane escanea en cada sincronización; pasa null para escanear todas las regiones habilitadas en la cuenta, resueltas en cada sincronización. Dos booleanos opcionales, createMonitoringAlarms y subscribeToAlarms, controlan el comportamiento de alertas descrito en Clouds y valen true por defecto.

La respuesta lleva todo lo que necesita el resto del flujo:

{
  "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 es la plantilla de CloudFormation generada para esta conexión, inline, así que un trabajo puede escribirla directamente en un archivo.
• result.s3Url es un enlace prefirmado a la misma plantilla. Expira al cabo de una hora.
• result.region es la región en la que desplegar el stack. La plantilla se genera exactamente para esta región.
• result.url es el enlace de creación rápida de la consola que usa el flujo guiado. Ignóralo aquí.

Un 409 significa que la cuenta ya está conectada. Cambia las regiones de una conexión existente con PATCH /v1/cloud_accounts/{workspaceId}/{id} en lugar de reconectar.

Escribir la plantilla en un archivo

Escribe result.templateBody en un archivo, o descarga el enlace prefirmado:

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

La plantilla llega lista para desplegar. Su parámetro ExternalParameter toma por defecto un ID externo generado para esta conexión: se convierte en la condición sts:ExternalId del rol que crea el stack, y Polylane presenta el mismo ID cada vez que asume ese rol. Despliega el archivo exactamente como se generó y deja intactos los valores por defecto de los parámetros. Un stack con un ID externo editado se despliega sin problemas pero nunca puede registrarse.

Ese ID externo es también la razón por la que el archivo merece el tratamiento de una credencial: mantenlo dentro de la ejecución del pipeline en lugar de hacerle commit o publicarlo como artefacto de compilación.

Si el enlace prefirmado expira antes de que despliegues, llama de nuevo al endpoint de conexión para obtener una plantilla nueva. Repetir la llamada es seguro hasta que la cuenta se registra; después devuelve un 409.

Desplegar el stack

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

Usa la region del paso 1. CAPABILITY_IAM reconoce el rol de IAM que crea el stack; el rol en sí no tiene nombre, y una política inline con nombre no requiere CAPABILITY_NAMED_IAM, así que CAPABILITY_IAM basta.

El stack crea el rol que Polylane asume (acceso de solo lectura más operaciones sobre recursos con prefijo polylane), su política inline, un trail de CloudTrail que escribe en un bucket de S3 nuevo, un tema de SNS para notificaciones del trail y de alarmas, y un recurso personalizado reporter. El reporter es lo que registra la conexión: entrega a Polylane el ARN del rol mientras el stack se está creando, así que no hay callback que configurar ni nada más que ejecutar.

El mismo despliegue desde Terraform:

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

Apunta el provider, o un alias del provider, a la region del paso 1. Referencia el archivo guardado con template_body en lugar de pasar s3Url a template_url: el enlace prefirmado no sobrevive ni a la hora ni a tu siguiente plan, así que obtén la plantilla en la misma ejecución que la aplica.

Ver cómo la cuenta entra en línea

La cuenta aparece cuando el reporter del stack alcanza Polylane, normalmente instantes después de que el stack se complete. Consúltala por su clave natural, que devuelve 404 hasta que el registro llega y 200 después:

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

Dale al bucle un plazo límite para que un despliegue fallido haga fallar el trabajo en lugar de dejarlo colgado. Una vez que la cuenta existe, su campo status sigue la primera sincronización: new al registrarse, syncing mientras los recursos van llegando, ready cuando la primera sincronización 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 de aquí la cuenta se comporta exactamente como una conectada desde la consola: los recursos se sincronizan en la topología, Polylane ejecuta su primera comprobación por sí solo y la página de la cuenta se va rellenando.

Desconectar desde la API

Eliminar la conexión también elimina el stack de CloudFormation en tu cuenta. La llamada necesita el 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"

El rol, su política y el bucket de S3 de CloudTrail llevan DeletionPolicy: Retain, así que sobreviven a la eliminación del stack. Elimínalos tú mismo si quieres dejar la cuenta de AWS completamente limpia.