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.
enableStageConfig	boolean		Enable centralized stage configuration (credentials, account, region) for multi-environment CDK deployments.

Resultado del generador

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

• Directoriosrc

  • main.ts Punto de entrada de la aplicación que instancia etapas CDK para despliegue
  • Directoriostages Definiciones de etapas CDK

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

Si estableces la opción enableStageConfig, el generador también crea dos paquetes compartidos para gestión centralizada de credenciales (si aún no existen):

• Directoriopackages/common

  • Directorioinfra-config Tipos de configuración de etapas y mapeos de credenciales

    • Directoriosrc

      • stages.types.ts Definiciones de tipos para credenciales y configuración de etapas
      • stages.config.ts Tus mapeos de etapa a credencial (edita esto)
      • index.ts Re-exportaciones para importar desde otros paquetes
  • Directorioscripts Scripts centralizados de despliegue/destrucción

    • Directoriosrc

      • infra-deploy.ts Script bin de despliegue
      • infra-destroy.ts Script bin de destrucción
      • Directoriostage-credentials/ Lógica compartida (búsqueda de credenciales, construcción de comandos CDK)

        • …

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

CDK usa Etapas para agrupar stacks que deben desplegarse juntos en un entorno específico. El src/main.ts generado crea una etapa sandbox para tu propio desarrollo y pruebas:

src/main.ts

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

La propiedad env indica a CDK en qué cuenta y región de AWS desplegar. CDK_DEFAULT_ACCOUNT y CDK_DEFAULT_REGION son resueltos automáticamente por el CLI de CDK desde tus credenciales AWS activas. Consulta la documentación de entornos CDK para más detalles.

Si generaste con enableStageConfig, el main.ts lee la cuenta y región desde un archivo de configuración centralizado, recurriendo a variables de entorno cuando no hay configuración establecida:

src/main.ts (con enableStageConfig)

import stagesConfig from ':my-scope/common-infra-config';

const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
const sandboxConfig = projectStages['my-app-sandbox'];

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

Puedes agregar más etapas para desplegar en diferentes entornos. Por ejemplo, etapas beta y prod dirigidas a cuentas AWS separadas:

src/main.ts

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

Una Etapa agrupa uno o más stacks. Puedes agregar tantos stacks como necesites dentro de una etapa:

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

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

Configuración de credenciales de etapas

Nota

Esta sección aplica cuando generas con enableStageConfig. Sin ella, el generador produce una configuración más simple donde gestionas las credenciales AWS tú mismo (por ejemplo, exportando AWS_PROFILE antes de desplegar).

Cuando tienes múltiples etapas dirigidas a diferentes cuentas AWS, gestionar credenciales manualmente puede ser propenso a errores, especialmente a medida que crece el número de etapas.

La opción enableStageConfig resuelve esto generando dos paquetes compartidos:

• packages/common/infra-config — Un único archivo de configuración donde mapeas cada etapa a sus credenciales AWS, cuenta y región. Es importable desde cualquier paquete en tu workspace, por lo que tu main.ts de CDK puede leer cuenta y región desde la misma fuente de verdad.
• packages/common/scripts — Comandos infra-deploy e infra-destroy que envuelven CDK con resolución automática de credenciales. Cuando ejecutas deploy, el script lee la configuración, establece las variables de entorno AWS correctas para el proceso hijo de CDK, y ejecuta cdk deploy. Tu entorno de shell nunca se modifica.

Configurando credenciales

Edita packages/common/infra-config/src/stages.config.ts para mapear tus etapas a credenciales AWS:

packages/common/infra-config/src/stages.config.ts

import type { StagesConfig } from './stages.types.js';

const config: StagesConfig = {
  projects: {
    // La clave es la ruta del proyecto relativa a la raíz del workspace.
    // Esto coincide con la ruta en project.json y en comandos de despliegue.
    'packages/infra': {
      stages: {
        // Los nombres de etapas deben coincidir con los identificadores de etapa CDK en main.ts
        // (el primer argumento a `new ApplicationStage(app, 'my-app-dev', ...)`).
        'my-app-dev': {
          credentials: { type: 'profile', profile: 'dev-account' },
          region: 'us-east-1',
        },
        'my-app-prod': {
          credentials: {
            type: 'assumeRole',
            assumeRole: 'arn:aws:iam::123456789012:role/DeployRole',
          },
          region: 'us-west-2',
          account: '123456789012',
        },
      },
    },
  },
  shared: {
    // Las etapas compartidas están disponibles para todos los proyectos de infraestructura.
    // Las entradas específicas de proyecto tienen prioridad sobre las compartidas.
    stages: {
      sandbox: {
        credentials: { type: 'profile', profile: 'personal-sandbox' },
        region: 'us-east-1',
      },
    },
  },
};

export default config;

Cuando despliegas, por ejemplo:

pnpm

pnpm nx run infra:deploy my-app-dev/*

yarn

yarn nx run infra:deploy my-app-dev/*

npm

npx nx run infra:deploy my-app-dev/*

bun

bunx nx run infra:deploy my-app-dev/*

El script de despliegue:

1. Extrae el nombre de etapa my-app-dev de los argumentos del comando
2. Busca credenciales en la configuración: primero bajo projects['packages/infra'], luego bajo shared
3. Si las encuentra, establece AWS_PROFILE (o asume el rol IAM) solo para el proceso hijo de CDK
4. Si no las encuentra, recurre a las credenciales AWS que estén en tu entorno

Esto significa que los flujos de trabajo existentes sin ninguna configuración continúan funcionando — el script solo aplica credenciales cuando encuentra una entrada coincidente.

Tipos de credenciales

Se admiten dos estrategias de credenciales:

• profile — Usa un perfil AWS CLI nombrado de ~/.aws/config. El script establece AWS_PROFILE para el proceso CDK.
• assumeRole — Llama a STS AssumeRole con el ARN del rol especificado y pasa las credenciales temporales a CDK. Opcionalmente puedes especificar un profile como credenciales fuente para la llamada AssumeRole, un externalId para políticas de confianza entre cuentas, y una sessionDuration en segundos.

Cuenta y región

Cada configuración de etapa incluye una region requerida y una account opcional:

• region (requerida) — La región AWS donde desplegar (por ejemplo, us-east-1, eu-west-2).
• account (opcional) — El ID de cuenta AWS. Si se omite, CDK lo infiere de las credenciales activas en tiempo de despliegue. Consulta la documentación de entornos CDK sobre cómo CDK resuelve cuenta y región.

El main.ts generado lee estos valores de la configuración para que la síntesis y despliegue de CDK usen la misma configuración de entorno:

src/main.ts

const sandboxConfig = projectStages['my-app-sandbox'];
new ApplicationStage(app, 'my-app-sandbox', {
  env: {
    account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
    region: sandboxConfig?.region ?? process.env.CDK_DEFAULT_REGION,
  },
});

Etapas compartidas vs específicas de proyecto

Las etapas compartidas (bajo shared.stages) aplican a cualquier proyecto de infraestructura en el workspace. Esto es útil cuando múltiples proyectos despliegan a la misma cuenta sandbox — defines las credenciales una vez en lugar de repetirlas para cada proyecto.

Las etapas específicas de proyecto (bajo projects['packages/infra'].stages) solo aplican a ese proyecto. Cuando ambas existen para el mismo nombre de etapa, la entrada específica de proyecto tiene prioridad.

Consejo

Recomendamos hacer commit de stages.config.ts para que el equipo comparta una única fuente de verdad para las credenciales de etapas. Si contiene nombres de perfiles personales, puedes agregarlo a .gitignore y usar una anulación local en su lugar.

Infraestructura para APIs

Si has usado 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 importa e instancia el constructo para agregar toda la infraestructura necesaria para desplegarla:

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 en tu infraestructura 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á ser preparada. El proceso de preparación crea los recursos que CDK necesita para gestionar despliegues (un bucket S3 para assets, roles IAM, etc.).

Primero, asegúrate de tener credenciales configuradas para tu cuenta AWS.

Luego, ejecuta el comando bootstrap para cada cuenta y región donde planees desplegar:

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

Para más detalles, consulta la documentación de preparació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 si despliegas en un pipeline CI/CD. Ver más abajo para más detalles.

Primero, asegúrate de tener credenciales AWS configuradas. Si generaste con enableStageConfig y has configurado credenciales de etapas en packages/common/infra-config/src/stages.config.ts, el comando de despliegue resolverá y aplicará automáticamente las credenciales correctas para la etapa objetivo. De lo contrario, asegúrate de que tus credenciales AWS estén establecidas en tu entorno (por ejemplo, mediante AWS_PROFILE o variables de entorno). Consulta la documentación de credenciales AWS para las opciones disponibles.

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 el nombre completo del stack, 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 si estás desplegando 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 despliega un cloud assembly pre-sintetizado en lugar de sintetizar al vuelo. Esto evita potencial no-determinismo por cambios en versiones de paquetes, garantizando que cada etapa del pipeline despliegue usando 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.