Saltearse al contenido
@aws/nx-plugin
Blog

Infraestructura CDK

AWS CDK es un framework para definir infraestructura en la nube mediante código y provisionarla a través de AWS CloudFormation.

El generador de infraestructura TypeScript crea una aplicación de infraestructura AWS CDK escrita en TypeScript. La aplicación generada incluye mejores prácticas de seguridad mediante verificaciones de CFN Guard.

Uso

Generar un proyecto de infraestructura

Puedes generar un nuevo proyecto de infraestructura de dos formas:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#infra
  5. Complete los parámetros requeridos
    • Haga clic en Generate

    Opciones

    Parámetro Tipo Predeterminado Descripción
    name Requerido string - The name of the application.
    ruleSet string aws_prototyping Rule set to validate your AWS resources with.
    directory string packages The directory of the new application.

    Resultado del generador

    El generador creará la siguiente estructura de proyecto en el directorio <directory>/<name>:

    • Directorysrc
      • main.ts Punto de entrada de la aplicación que instancia los stacks de CDK a desplegar
      • Directorystacks Definiciones de stacks de CDK
        • application-stack.ts Stack principal de la aplicación
    • cdk.json Configuración de CDK
    • project.json Configuración del proyecto y objetivos de build

    Tu infraestructura es un proyecto TypeScript, por lo que puedes consultar la documentación de proyectos TypeScript para obtener más detalles sobre su uso general.

    Implementando tu infraestructura CDK

    Puedes comenzar a escribir tu infraestructura CDK en src/stacks/application-stack.ts, por ejemplo:

    src/stacks/application-stack.ts
    import * as cdk from 'aws-cdk-lib';
    import { Bucket } from 'aws-cdk-lib/aws-s3'
    import { Construct } from 'constructs';
    

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

        // Declara tu infraestructura aquí
        new Bucket(this, 'MyBucket');
      }
    }

    Infraestructura para API

    Si has utilizado los generadores tRPC API o FastAPI para crear APIs, notarás que ya tienes algunos constructos disponibles en packages/common/constructs para desplegarlos.

    Si, por ejemplo, creaste una API tRPC llamada my-api, simplemente puedes importar e instanciar el constructo para añadir toda la infraestructura necesaria:

    src/stacks/application-stack.ts
    import * as cdk from 'aws-cdk-lib';
    import { Construct } from 'constructs';
    import { MyApi } from ':my-scope/common-constructs';
    

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

        // Añade infraestructura para tu API
        new MyApi(this, 'MyApi');
      }
    }

    Infraestructura para sitios web

    Si has usado el generador sitio web CloudScape, notarás que ya tienes un constructo en packages/common/constructs para desplegarlo. Por ejemplo:

    src/stacks/application-stack.ts
    import * as cdk from 'aws-cdk-lib';
    import { Construct } from 'constructs';
    import { MyWebsite } from ':my-scope/common-constructs';
    

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

        // Añade infraestructura para tu sitio web
        new MyWebsite(this, 'MyWebsite');
      }
    }

    Es importante asegurarse de que el sitio web se declare después de cualquier constructo de API para que la Configuración en Tiempo de Ejecución del sitio web incluya toda la configuración de las APIs.

    Sintetizando tu infraestructura

    Como parte de tu objetivo build, además de ejecutar los objetivos predeterminados de compilación, lint y pruebas, tu proyecto de infraestructura se sintetiza en CloudFormation. Esto también puede ejecutarse de forma independiente mediante el objetivo synth:

    Terminal window
    pnpm nx run <my-infra>:synth

    Encontrarás tu cloud assembly sintetizado en la carpeta dist raíz, bajo dist/packages/<my-infra-project>/cdk.out.

    Bootstrapping de tu(s) cuenta(s) AWS

    Si estás desplegando una aplicación CDK en una cuenta AWS por primera vez, necesitarás hacer bootstrap primero.

    Primero, asegúrate de haber configurado credenciales para tu cuenta AWS.

    Luego, puedes usar el comando cdk bootstrap:

    Ventana de terminal
    npx cdk bootstrap aws://<account-id>/<region>

    Para más detalles, consulta la documentación de CDK.

    Despliegue en AWS

    Después de un build, puedes desplegar tu infraestructura en AWS usando el objetivo deploy.

    :::precaución Utiliza el objetivo deploy-ci si desplegas en un pipeline de CI/CD. Ver más detalles abajo. :::

    Primero, asegúrate de haber configurado credenciales para tu cuenta AWS.

    Luego, ejecuta el objetivo deploy:

    Terminal window
    pnpm nx run <my-infra>:deploy --all

    El comando anterior despliega todos los stacks definidos en main.ts. Puedes querer apuntar a un stack individual, especialmente si has configurado múltiples etapas de una aplicación:

    Terminal window
    pnpm nx run <my-infra>:deploy my-sandbox-stack

    Despliegue en AWS en un pipeline de CI/CD

    Utiliza el objetivo deploy-ci si estás desplegando en AWS como parte de un pipeline de CI/CD.

    Terminal window
    pnpm nx run <my-infra>:deploy-ci my-stack

    Este objetivo difiere ligeramente del objetivo deploy regular en que asegura que se despliegue una cloud-assembly pre-sintetizada, en lugar de sintetizarla sobre la marcha. Esto ayuda a evitar posibles problemas de no determinismo debido a cambios en versiones de paquetes, garantizando que cada etapa del pipeline despliegue usando la misma cloud-assembly.

    Más información

    Para más información sobre CDK, consulta la Guía para desarrolladores de CDK y la Referencia de API.