Infraestructura de CDK

AWS CDK es un framework para definir infraestructura en la nube mediante código y aprovisionarla 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 con CFN Guard.

Uso

Generar un proyecto de infraestructura

Puedes generar un nuevo proyecto de infraestructura de dos formas:

VSCode

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
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra

yarn

yarn nx g @aws/nx-plugin:ts#infra

npm

npx nx g @aws/nx-plugin:ts#infra

bun

bunx nx g @aws/nx-plugin:ts#infra

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --dry-run

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 etapas CDK para desplegar
  • Directorystages Definiciones de etapas CDK

    • application-stage.ts Define una colección de stacks para desplegar en una etapa
  • Directorystacks Definiciones de stacks 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 construcción

Consejo

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

Implementando tu infraestructura CDK

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

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

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

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

Etapas y stacks

Notarás que el archivo principal src/main.ts instancia una Etapa CDK llamada <namespace>-sandbox. Esta etapa está destinada a tus propias pruebas y desarrollo.

src/main.ts

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

Puedes agregar más etapas, por ejemplo podrías definir etapas beta y prod que se desplieguen en entornos separados:

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // cuenta beta
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // cuenta prod
    region: 'us-west-2',
  },
});

Una Etapa define una colección de stacks que deben desplegarse juntos para formar tu aplicación. Puedes instanciar tantos stacks como quieras dentro de una etapa, por ejemplo:

src/stages/application-stage.ts

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * Define una colección de stacks CDK que componen tu aplicación
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

Infraestructura para APIs

Si has usado los generadores tRPC API o FastAPI, 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 importa e instancia el constructo para agregar 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);

    // Agrega infraestructura para tu API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

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);

    // Agrega 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.

Síntesis de 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:

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

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

Preparación de cuentas AWS

Si es la primera vez que despliegas una aplicación CDK en una cuenta AWS, necesitarás prepararla primero.

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

Luego, puedes usar el comando cdk bootstrap:

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

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

Despliegue en AWS

Después de una construcción, puedes desplegar tu infraestructura en AWS usando el objetivo deploy.

Precaución

Usa el objetivo deploy-ci si despliegas en un pipeline CI/CD. Ver más abajo para detalles.

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

Luego, ejecuta el objetivo de despliegue:

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

Consejo

El comando anterior despliega todos los stacks de la etapa <my-infra>-sandbox. Puedes especificar otras etapas siempre que estén definidas en main.ts.

También puedes desplegar stacks individuales especificando su nombre completo, por ejemplo:

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

Despliegue en AWS mediante CI/CD

Usa el objetivo deploy-ci si despliegas en AWS como parte de un pipeline CI/CD.

pnpm

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn

yarn nx run <my-infra>:deploy-ci my-stage/*

npm

npx nx run <my-infra>:deploy-ci my-stage/*

bun

bunx nx run <my-infra>:deploy-ci my-stage/*

Este objetivo difiere ligeramente del objetivo deploy regular en que asegura que se despliegue un cloud-assembly pre-sintetizado, en lugar de sintetizarlo sobre la marcha. Esto ayuda a evitar problemas de no-determinismo por cambios en versiones de paquetes, garantizando que cada etapa del pipeline use el mismo cloud-assembly.

Eliminación de infraestructura AWS

Usa el objetivo destroy para eliminar tus recursos:

pnpm

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

Más información

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