Infraestructura de CDK

AWS CDK es un marco 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 de Checkov.

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.
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 despliegue
  • 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 compilación
• checkov.yml Archivo de configuración de Checkov

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 en 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 desarrollo y pruebas propias.

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 para definir entornos beta y prod que se desplieguen en ambientes 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 desees 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.

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 a CloudFormation. Esto también puede ejecutarse independientemente 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.

Pruebas de seguridad

Se agrega un objetivo checkov a tu proyecto que ejecuta verificaciones de seguridad usando Checkov.

pnpm

pnpm nx run <my-infra>:checkov

yarn

yarn nx run <my-infra>:checkov

npm

npx nx run <my-infra>:checkov

bun

bunx nx run <my-infra>:checkov

Encontrarás los resultados de las pruebas de seguridad en la carpeta raíz dist, bajo dist/packages/<my-infra-project>/checkov.

Nota

Checkov se ejecuta usando uvx, por lo que necesitarás instalar uv si aún no lo has hecho.

Precaución

Algunas reglas de Checkov están suprimidas por defecto mediante el archivo checkov.yml. Se recomienda revisarlas según tu caso de uso.

Suprimir verificaciones de Checkov

Puede haber instancias donde quieras suprimir ciertas reglas en recursos. Puedes hacerlo de dos formas:

Suprimir una regla en un constructo específico

import { suppressRules } from ':my-scope/common-constructs';

// Suprime CKV_AWS_XXX para el constructo dado
suppressRules(construct, ['CKV_AWS_XXX'], 'Motivo');

Suprimir una regla en un constructo descendiente

import { suppressRules } from ':my-scope/common-constructs';

// Suprime CKV_AWS_XXX para el constructo o cualquier descendiente si es una instancia de Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Motivo', (construct) => construct instanceof Bucket);

Preparando tu(s) cuenta(s) AWS

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

Primero, asegúrate de tener credenciales configuradas 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.

Desplegando en AWS

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

Precaución

Usa el objetivo deploy-ci para despliegues en pipelines CI/CD. Ver más abajo.

Primero, asegúrate de tener credenciales configuradas 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

Desplegando en AWS en un pipeline CI/CD

Usa el objetivo deploy-ci para despliegues en pipelines 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 deploy regular en que asegura el despliegue de cloud-assembly pre-sintetizado, en lugar de sintetizar durante el despliegue. 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.

Eliminando 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 Referencia de API.