Infraestrutura CDK

AWS CDK é um framework para definir infraestrutura em nuvem em código e provisioná-la através do AWS CloudFormation.

O gerador de infraestrutura TypeScript cria uma aplicação de infraestrutura AWS CDK escrita em TypeScript. A aplicação gerada inclui práticas recomendadas de segurança através de verificações de segurança do Checkov.

Uso

Gerar um Projeto de Infraestrutura

Você pode gerar um novo projeto de infraestrutura de duas maneiras:

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#infra
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	O nome da aplicação.
directory	string	packages	O diretório da nova aplicação.
subDirectory	string	-	O subdiretório onde o projeto é colocado. Por padrão, este é o nome do projeto.
stageConfig	boolean		Habilita configuração centralizada de estágio (credenciais, conta, região) para implantações CDK em múltiplos ambientes.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador criará a seguinte estrutura de projeto no diretório <directory>/<name>:

• Directorysrc

  • main.ts Application entry point instantiating CDK stages to deploy
  • Directorystages CDK Stage definitions

    • application-stage.ts Defines a collection of stacks to deploy in a stage
  • Directorystacks CDK Stack definitions

    • application-stack.ts Main application stack
• cdk.json CDK configuration
• package.json Project manifest defining the project’s package name and dependencies
• project.json Project configuration and build targets
• checkov.yml Checkov configuration file

Se você definir a opção stageConfig, o gerador também cria dois pacotes compartilhados para gerenciamento centralizado de credenciais (se eles ainda não existirem):

• Directorypackages/common

  • Directoryinfra-config Stage configuration types and credential mappings

    • Directorysrc

      • stages.types.ts Type definitions for stage credentials and config
      • stages.config.ts Your stage-to-credential mappings (edit this)
      • index.ts Re-exports for importing from other packages
  • Directoryscripts Centralized deploy/destroy scripts

    • Directorysrc

      • infra-deploy.ts Deploy bin script
      • infra-destroy.ts Destroy bin script
      • Directorystage-credentials/ Shared logic (credential lookup, CDK command building)

        • …

Recursos do Projeto TypeScript

Sua infraestrutura é um projeto TypeScript, então você pode consultar a documentação do projeto TypeScript para mais detalhes sobre seu uso geral.

Implementando sua Infraestrutura CDK

Você pode começar a escrever sua infraestrutura CDK dentro de src/stacks/application-stack.ts, por exemplo:

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

    // Declare your infrastructure here
    new Bucket(this, 'MyBucket');
  }
}

Stages e Stacks

O CDK usa Stages para agrupar stacks que devem ser implantados juntos em um ambiente específico. O src/main.ts gerado cria um stage sandbox para seu próprio desenvolvimento e testes:

src/main.ts

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

// Define other instances of stages, such as beta and prod, below

A propriedade env informa ao CDK em qual conta AWS e região implantar. CDK_DEFAULT_ACCOUNT e CDK_DEFAULT_REGION são resolvidos automaticamente pela CLI do CDK a partir de suas credenciais AWS ativas. Consulte a documentação de ambientes do CDK para mais detalhes.

O stage sandbox é aquele que o target deploy-sandbox implanta.

Se você gerou com stageConfig, o main.ts lê a conta e região de um arquivo de configuração centralizado, recorrendo a variáveis de ambiente quando nenhuma configuração está definida:

src/main.ts (with stageConfig)

import { resolveStage } from '@my-scope/common-infra-config';

// Looks up the stage under this project (packages/infra), falling back to
// shared stages. Returns undefined when no config exists for the stage.
const sandboxConfig = resolveStage('packages/infra', '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,
  },
});

Você pode adicionar mais stages para implantar em diferentes ambientes. Por exemplo, stages beta e prod direcionados a contas 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',
  },
});

Um Stage agrupa um ou mais stacks. Você pode adicionar quantos stacks precisar dentro de um stage:

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

Configuração de Credenciais de Stage

Configuração em Stages

Esta seção se aplica quando você gera com stageConfig. Sem ela, o gerador produz uma configuração mais simples onde você gerencia as credenciais AWS por conta própria (por exemplo, exportando AWS_PROFILE antes de implantar).

Quando você tem múltiplos stages direcionados a diferentes contas AWS, gerenciar credenciais manualmente pode ser propenso a erros, especialmente à medida que o número de stages cresce.

A opção stageConfig resolve isso gerando dois pacotes compartilhados:

• packages/common/infra-config — Um único arquivo de configuração onde você mapeia cada stage para suas credenciais AWS, conta e região. Isso é importável de qualquer pacote em seu workspace, então seu main.ts do CDK pode ler conta e região da mesma fonte de verdade.
• packages/common/scripts — Comandos infra-deploy e infra-destroy que envolvem o CDK com resolução automática de credenciais. Quando você executa deploy, o script lê a configuração, define as variáveis de ambiente AWS corretas para o processo filho do CDK e executa cdk deploy. Seu ambiente de shell nunca é modificado.

Configurando Credenciais

Edite packages/common/infra-config/src/stages.config.ts para mapear seus stages para credenciais AWS:

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

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

const config: StagesConfig = {
  projects: {
    // The key is the project path relative to the workspace root.
    // This matches the path in project.json and in deploy commands.
    'packages/infra': {
      stages: {
        // Stage names must match the CDK stage identifiers in main.ts
        // (the first argument to `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: {
    // Shared stages are available to all infra projects.
    // Project-specific entries take priority over shared ones.
    stages: {
      sandbox: {
        credentials: { type: 'profile', profile: 'personal-sandbox' },
        region: 'us-east-1',
      },
    },
  },
};

export default config;

Quando você implanta, por exemplo:

pnpm

pnpm nx deploy infra my-app-dev/*

yarn

yarn nx deploy infra my-app-dev/*

npm

npx nx deploy infra my-app-dev/*

bun

bunx nx deploy infra my-app-dev/*

O script de implantação:

1. Extrai o nome do stage my-app-dev dos argumentos do comando
2. Procura credenciais na configuração: primeiro em projects['packages/infra'], depois em shared
3. Se encontrado, define AWS_PROFILE (ou assume a função IAM) apenas para o processo filho do CDK
4. Se não encontrado, recorre a quaisquer credenciais AWS que estejam em seu ambiente

Isso significa que fluxos de trabalho existentes sem nenhuma configuração continuam a funcionar — o script só aplica credenciais quando encontra uma entrada correspondente.

Tipos de Credenciais

Duas estratégias de credenciais são suportadas:

• profile — Usa um perfil da AWS CLI nomeado de ~/.aws/config. O script define AWS_PROFILE para o processo CDK.
• assumeRole — Chama STS AssumeRole com o ARN da função especificado e passa as credenciais temporárias para o CDK. Você pode opcionalmente especificar um profile como as credenciais de origem para a chamada AssumeRole, um externalId para políticas de confiança entre contas e um sessionDuration em segundos.

Conta e Região

Cada configuração de stage inclui uma region obrigatória e uma account opcional:

• region (obrigatória) — A região AWS para implantar (por exemplo, us-east-1, eu-west-2).
• account (opcional) — O ID da conta AWS. Se omitido, o CDK infere das credenciais ativas no momento da implantação. Consulte a documentação de ambientes do CDK para saber como o CDK resolve conta e região.

O main.ts gerado lê esses valores da configuração para que a síntese e implantação do CDK usem as mesmas configurações de ambiente:

src/main.ts

const sandboxConfig = resolveStage('packages/infra', '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,
  },
});

Stages Compartilhados vs Específicos de Projeto

Stages compartilhados (em shared.stages) se aplicam a qualquer projeto de infraestrutura no workspace. Isso é útil quando múltiplos projetos implantam na mesma conta sandbox — você define as credenciais uma vez em vez de repeti-las para cada projeto.

Stages específicos de projeto (em projects['packages/infra'].stages) se aplicam apenas a esse projeto. Quando ambos existem para o mesmo nome de stage, a entrada específica do projeto tem prioridade.

Commit da Configuração de Stage

Recomendamos fazer commit de stages.config.ts para que a equipe compartilhe uma única fonte de verdade para credenciais de stage. Se contiver nomes de perfis pessoais, você pode adicioná-lo ao .gitignore e usar uma substituição local.

Infraestrutura de API

Se você usou os geradores de API tRPC ou FastAPI para criar APIs, você notará que já tem alguns constructs disponíveis em packages/common/constructs para implantá-los.

Se, por exemplo, você criou uma API tRPC chamada my-api, você pode simplesmente importar e instanciar o construct para adicionar toda a infraestrutura necessária para implantá-la:

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from '@my-scope/common-constructs';

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

    // Add infrastructure for your API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Infraestrutura de Website

Se você usou o gerador de Website React, você notará que já tem um construct em packages/common/constructs para implantá-lo. Por exemplo:

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from '@my-scope/common-constructs';

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

    // Add infrastructure for your website
    new MyWebsite(this, 'MyWebsite');
  }
}

Construct de Website CDK

Com o CDK, o construct de website pode ser declarado em qualquer ponto do seu stack — a configuração de runtime é resolvida preguiçosamente no momento da síntese. Para Terraform, certifique-se de que o módulo de website tenha depends_on apropriado para módulos que adicionam à Configuração de Runtime.

Sintetizando sua Infraestrutura

Como parte do seu target build, além de executar os targets padrão de compilação, lint e teste, seu projeto de infraestrutura é sintetizado para CloudFormation. Isso também pode ser executado de forma independente, executando o target synth:

pnpm

pnpm nx synth <my-infra>

yarn

yarn nx synth <my-infra>

npm

npx nx synth <my-infra>

bun

bunx nx synth <my-infra>

Você encontrará seu cloud assembly sintetizado na pasta raiz dist, em dist/packages/<my-infra-project>/cdk.out.

Testes de Segurança

Um target checkov é adicionado ao seu projeto que executa verificações de segurança em sua infraestrutura usando Checkov.

pnpm

pnpm nx checkov <my-infra>

yarn

yarn nx checkov <my-infra>

npm

npx nx checkov <my-infra>

bun

bunx nx checkov <my-infra>

Você encontrará os resultados dos testes de segurança na pasta raiz dist, em dist/packages/<my-infra-project>/checkov.

Checkov via UV

O Checkov é executado usando uvx, então você precisará instalar o uv se ainda não o fez.

Regras do Checkov Suprimidas

Algumas regras do Checkov são suprimidas por padrão através do arquivo checkov.yml. É recomendado que você as revise com base no seu caso de uso.

Suprimindo Verificações do Checkov

Pode haver casos em que você queira suprimir certas regras em recursos. Você pode fazer isso de duas maneiras:

Suprimir uma regra em um construct específico

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

// suppresses the CKV_AWS_XXX for the given construct.
suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');

Suprimir uma regra em um construct descendente

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

// Supresses the CKV_AWS_XXX for the construct or any of its descendants if it is an instance of Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);

Fazendo Bootstrap de sua(s) Conta(s) AWS

Se você está implantando uma aplicação CDK em uma Conta AWS pela primeira vez, ela precisará passar por bootstrap. O bootstrap cria os recursos que o CDK precisa para gerenciar implantações (um bucket S3 para assets, funções IAM, etc.).

Primeiro, certifique-se de que você configurou credenciais para sua conta AWS.

Em seguida, execute o comando bootstrap para cada conta e região que você planeja implantar:

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

Para mais detalhes, consulte a documentação de bootstrap do CDK.

Implantando na AWS

Seu projeto tem três targets de implantação, cada um adequado para uma situação diferente:

Target	Use para
deploy-sandbox	Implantar seu próprio stage sandbox durante o desenvolvimento. Nenhum argumento de stage necessário.
deploy	Implantar qualquer stage, nomeando o stage ou stacks que você deseja.
deploy-ci	Implantar a partir de um pipeline CI/CD, usando um cloud assembly pré-sintetizado.

Primeiro, certifique-se de ter credenciais AWS configuradas. Se você gerou com stageConfig e configurou credenciais de stage em packages/common/infra-config/src/stages.config.ts, o comando deploy resolverá e aplicará automaticamente as credenciais corretas para o stage de destino. Caso contrário, certifique-se de que suas credenciais AWS estejam definidas em seu ambiente (por exemplo, via AWS_PROFILE ou variáveis de ambiente). Consulte a documentação de credenciais AWS para as opções disponíveis.

Implantando seu Stage Sandbox

O target deploy-sandbox implanta o stage sandbox que main.ts declara, então você não precisa lembrar seu nome de stage:

pnpm

pnpm nx deploy-sandbox <my-infra>

yarn

yarn nx deploy-sandbox <my-infra>

npm

npx nx deploy-sandbox <my-infra>

bun

bunx nx deploy-sandbox <my-infra>

Esta é a maneira mais rápida de ter sua própria cópia da aplicação rodando na AWS enquanto você desenvolve.

Modo Express para Implantações Mais Rápidas

Os targets de implantação aguardam a estabilização completa dos recursos por padrão, favorecendo consistência em vez de velocidade. Para acelerar a iteração durante o desenvolvimento, opte pelo modo express do CloudFormation passando a flag --express do CDK:

pnpm

pnpm nx deploy-sandbox <my-infra> --express

yarn

yarn nx deploy-sandbox <my-infra> --express

npm

npx nx deploy-sandbox <my-infra> --express

bun

bunx nx deploy-sandbox <my-infra> --express

O modo express termina assim que a configuração do recurso é confirmada como aplicada, em vez de esperar pela estabilização completa, com a propagação continuando em segundo plano, para ciclos de iteração significativamente mais rápidos. É destinado para desenvolvimento e iteração.

Implantando um Stage Específico

O target deploy implanta qualquer stage ou stacks que você nomear. Use-o para stages diferentes do seu sandbox, ou para implantar um único stack:

pnpm

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

yarn

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

npm

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

bun

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

Você pode especificar qualquer stage desde que esteja definido em main.ts. Para implantar um stack individual, forneça o nome completo do stack:

pnpm

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

yarn

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

npm

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

bun

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

Implantando na AWS em um Pipeline CI/CD

Use o target deploy-ci se você está implantando na AWS como parte de um pipeline CI/CD.

pnpm

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

yarn

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

npm

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

bun

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

Este target difere ligeiramente do target deploy regular, pois implanta um cloud assembly pré-sintetizado em vez de sintetizar em tempo real. Isso evita potencial não-determinismo de mudanças de versão de pacotes, garantindo que cada estágio do pipeline implante usando o mesmo cloud assembly.

Desmontando Infraestrutura AWS

Use o target destroy para desmontar seus recursos:

pnpm

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

yarn

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

npm

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

bun

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

Mais Informações

Para mais informações sobre o CDK, consulte o Guia do Desenvolvedor CDK e a Referência da API.