¿Cómo utilizo la interfaz AwsSdkCall para realizar una llamada a AWS SDK desde un proyecto de CDK?

Descripción corta

Puedes utilizar las llamadas del AWS Software Development Kit (AWS SDK) para los siguientes escenarios de despliegue de pilas:

• Para recuperar las configuraciones de forma dinámica al crear y actualizar una pila.
• Para recuperar los atributos de los recursos que AWS CloudFormation no admite en los valores devueltos.
• Para realizar pequeños parches o cambios de configuración que AWS CloudFormation no admite.

Puedes activar llamadas a AWS SDK en diferentes eventos de operación de pila de CloudFormation, como Create, Delete o Update. No necesitas configurar el acceso ni las herramientas para tu canalización de despliegue para realizar llamadas a AWS SDK. AWS CDK configura la versión ejecutable de AWS SDK. Puedes personalizar y limitar el acceso a la función de AWS Lambda detrás del recurso personalizado.

Resolución

Nota: Los siguientes ejemplos utilizan TypeScript. Asegúrate de usar sintaxis específicas del lenguaje de programación que estés usando.

Para realizar una llamada a AWS SDK mediante AwsSdkCall, utiliza los siguientes parámetros:

1. En Service (Servicio) utiliza el servicio de AWS al que deseas llamar. Los valores distinguen entre mayúsculas y minúsculas.
2. En Action (Acción), usa la API o la llamada a la acción que quieras realizar. Por lo general, sigue un patrón camel case, y los valores distinguen entre mayúsculas y minúsculas.
3. En Parameters (Parámetros), usa los parámetros opcionales que pasas al realizar la API o la llamada a la acción. Puedes declarar los parámetros como una variable y, a continuación, pasarlos a la interfaz como un objeto JSON para la carga útil de la API. Para obtener más información, consulta AWS SDK for JavaScript (AWS SDK para JavaScript).

Ejemplo 1: Recupera las configuraciones de forma dinámica

En el siguiente ejemplo, se recupera un ID de imagen de máquina del Almacén de parámetros de AWS Systems Manager durante la creación de la pila. En él se muestra cómo hacer referencia a la respuesta de la llamada a la API con el método getResponseField mediante la notación de puntos para navegar por la estructura de respuestas del SDK:

import * as cdk from "aws-cdk-lib/core";
import { Construct } from "constructs";
import * as cr from "aws-cdk-lib/custom-resources";

export class Example1Stack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const getAmiId = new cr.AwsCustomResource(this, "GetAMIId", {
      onCreate: {
        service: "SSM",
        action: "getParameter",
        parameters: {
          Name: "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64",
        },
        physicalResourceId: cr.PhysicalResourceId.of("get-ami-id"),
        },
        policy: cr.AwsCustomResourcePolicy.fromSdkCalls({
         resources: cr.AwsCustomResourcePolicy.ANY_RESOURCE,
        }),
     });

     new cdk.CfnOutput(this, "ImageId", {
        value: getAmiId.getResponseField("Parameter.Value"),
     });
    }
}

Ejemplo 2: Recuperación de atributos de recursos no disponibles en CloudFormation

CloudFormation no expone todos los atributos de los recursos a través de Fn::GetAtt. Si CloudFormation no devuelve el valor que necesitas, utiliza una llamada al SDK para recuperarlo directamente de la API de servicio. Este método también te permite recuperar los recursos que existen fuera de CloudFormation y sus atributos que no has almacenado en las exportaciones de pilas, los parámetros de SSM o Secrets Manager.

Por ejemplo, AWS::Organizations::Organization expone Id y ManagementAccountId como valores de retorno, pero CloudFormation no crea la mayoría de las organizaciones. Una llamada del SDK a describeOrganization te permite recuperar estos valores de una cuenta de miembro sin necesidad de incluir la organización como parte de tu pila.

import * as cdk from "aws-cdk-lib/core";
import { Construct } from "constructs";
import * as cr from "aws-cdk-lib/custom-resources";

export class Example2Stack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const orgInfo = new cr.AwsCustomResource(this, "DescribeOrg", {
      onCreate: {
        service: "Organizations",
        action: "describeOrganization",
        physicalResourceId: cr.PhysicalResourceId.of("describe-org"),
        outputPaths: ["Organization.Id", "Organization.MasterAccountId"],
      },
      policy: cr.AwsCustomResourcePolicy.fromSdkCalls({
        resources: cr.AwsCustomResourcePolicy.ANY_RESOURCE,
      }),
    });

    new cdk.CfnOutput(this, "OrgId", {
      value: orgInfo.getResponseField("Organization.Id"),
    });

    new cdk.CfnOutput(this, "ManagementAccountId", {
      value: orgInfo.getResponseField("Organization.MasterAccountId"),
    });
  }
}

Nota: El ejemplo usa outputPaths para restringir la respuesta solo a los campos necesarios. Esto evita alcanzar el límite de respuesta de CloudFormation de 4096 bytes.

Ejemplo 3: realizar cambios de configuración no compatibles con CloudFormation

Algunas operaciones no tienen ningún recurso o propiedad de CloudFormation correspondiente. Por ejemplo, CloudFormation puede crear una tabla de DynamoDB, pero no puede insertar elementos en ella. Para resolver este problema, utiliza AwsSdkCall para sembrar los datos iniciales en el momento del despliegue.

El siguiente ejemplo usa onCreate, por lo que solo inserta el elemento cuando se crea la pila por primera vez. Para actualizar también el elemento en las actualizaciones de la pila, agrega la misma llamada a onUpdate.

import * as cdk from "aws-cdk-lib/core";
import { Construct } from "constructs";
import * as cr from "aws-cdk-lib/custom-resources";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";

export class Example3Stack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, "ConfigTable", {
      partitionKey: { name: "PK", type: dynamodb.AttributeType.STRING },
    });

    new cr.AwsCustomResource(this, "SeedData", {
      onCreate: {
        service: "DynamoDB",
        action: "putItem",
        parameters: {
          TableName: table.tableName,
          Item: {
            PK: { S: "CONFIG" },
            version: { S: "1.0" },
            enabled: { BOOL: true },
          },
        },
        physicalResourceId: cr.PhysicalResourceId.of("seed-data"),
      },
      policy: cr.AwsCustomResourcePolicy.fromSdkCalls({
        resources: [table.tableArn],
      }),
    });
  }
}

Gestión de escenarios de permisos complejos

La propiedad policy otorga permisos a la función de Lambda detrás del recurso personalizado. El uso de fromSdkCalls() traduce automáticamente cada llamada a la API en los permisos de IAM correspondientes. Cuando sea posible, asigna los permisos a ARN de recursos específicos en lugar de usar ANY_RESOURCE (ejemplo 3).

En algunos casos, es posible que fromSdkCalls() no genere todos los permisos necesarios. Por ejemplo, si la tabla de DynamoDB del ejemplo 3 usa una clave de KMS administrada por el cliente, fromSdkCalls() solo genera dynamodb:PutItem y no agrega ningún permiso de KMS. El despliegue fallará porque DynamoDB requiere kms:Encrypt, kms:Decrypt y kms:GenerateDataKey para escribir elementos en una tabla cifrada. Puedes usar fromStatements() para especificar los permisos exactos.

Por ejemplo:

import * as cdk from "aws-cdk-lib/core";
import { Construct } from "constructs";
import * as cr from "aws-cdk-lib/custom-resources";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as kms from "aws-cdk-lib/aws-kms";
import * as iam from "aws-cdk-lib/aws-iam";

export class Example4Stack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const encryptionKey = new kms.Key(this, "TableKey");

    const table = new dynamodb.Table(this, "ConfigTable", {
      partitionKey: { name: "PK", type: dynamodb.AttributeType.STRING },
      encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED,
      encryptionKey,
    });

    new cr.AwsCustomResource(this, "SeedData", {
      onCreate: {
        service: "DynamoDB",
        action: "putItem",
        parameters: {
          TableName: table.tableName,
          Item: {
            PK: { S: "CONFIG" },
            version: { S: "1.0" },
            enabled: { BOOL: true },
          },
        },
        physicalResourceId: cr.PhysicalResourceId.of("seed-data"),
      },
      policy: cr.AwsCustomResourcePolicy.fromStatements([
        new iam.PolicyStatement({
          actions: ["dynamodb:PutItem"],
          resources: [table.tableArn],
        }),
        new iam.PolicyStatement({
          actions: ["kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey"],
          resources: [encryptionKey.keyArn],
        }),
      ]),
    });
  }
}