Infraestrutura CDK

O 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 do Checkov.

Utilização

Gerar um Projeto de Infraestrutura

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

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

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	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.

Saída do Gerador

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

• Directorysrc

  • main.ts Ponto de entrada da aplicação que instancia estágios do CDK para implantação
  • Directorystages Definições de estágios do CDK

    • application-stage.ts Define uma coleção de stacks para implantar em um estágio
  • Directorystacks Definições de stacks do CDK

    • application-stack.ts Stack principal da aplicação
• cdk.json Configuração do CDK
• project.json Configuração do projeto e targets de build
• checkov.yml Arquivo de configuração do Checkov

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

• Directorypackages/common

  • Directoryinfra-config Tipos de configuração de estágio e mapeamentos de credenciais

    • Directorysrc

      • stages.types.ts Definições de tipos para credenciais e configuração de estágios
      • stages.config.ts Seus mapeamentos de estágio para credenciais (edite este arquivo)
      • index.ts Re-exportações para importar de outros pacotes
  • Directoryscripts Scripts centralizados de deploy/destroy

    • Directorysrc

      • infra-deploy.ts Script bin de deploy
      • infra-destroy.ts Script bin de destroy
      • Directorystage-credentials/ Lógica compartilhada (busca de credenciais, construção de comandos CDK)

        • …

Dica

Sua infraestrutura é um projeto TypeScript, portanto você pode consultar a documentação de projetos TypeScript para detalhes gerais de utilização.

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 sua infraestrutura aqui
    new Bucket(this, 'MyBucket');
  }
}

Estágios e Stacks

O CDK usa Stages para agrupar stacks que devem ser implantadas juntas em um ambiente específico. O src/main.ts gerado cria um estágio 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,
  },
});

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 pelo CDK CLI a partir de suas credenciais AWS ativas. Consulte a documentação de ambientes do CDK para mais detalhes.

Se você gerou com enableStageConfig, o main.ts lê 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 (com 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,
  },
});

Você pode adicionar mais estágios para implantar em diferentes ambientes. Por exemplo, estágios 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 uma ou mais stacks. Você pode adicionar quantas stacks precisar dentro de um estágio:

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 Estágio

Nota

Esta seção se aplica quando você gera com enableStageConfig. 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 estágios direcionados a diferentes contas AWS, gerenciar credenciais manualmente pode ser propenso a erros, especialmente à medida que o número de estágios cresce.

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

• packages/common/infra-config — Um único arquivo de configuração onde você mapeia cada estágio para suas credenciais AWS, conta e região. Este arquivo pode ser importado de qualquer pacote no 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 encapsulam 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 shell nunca é modificado.

Configurando Credenciais

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

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

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

const config: StagesConfig = {
  projects: {
    // A chave é o caminho do projeto relativo à raiz do workspace.
    // Isso corresponde ao caminho em project.json e nos comandos de deploy.
    'packages/infra': {
      stages: {
        // Os nomes dos estágios devem corresponder aos identificadores de estágio do CDK em main.ts
        // (o primeiro argumento para `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: {
    // Estágios compartilhados estão disponíveis para todos os projetos de infraestrutura.
    // Entradas específicas de projeto têm prioridade sobre as compartilhadas.
    stages: {
      sandbox: {
        credentials: { type: 'profile', profile: 'personal-sandbox' },
        region: 'us-east-1',
      },
    },
  },
};

export default config;

Quando você implanta, por exemplo:

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/*

O script de deploy:

1. Extrai o nome do estágio my-app-dev dos argumentos do comando
2. Busca credenciais na configuração: primeiro em projects['packages/infra'], depois em shared
3. Se encontrado, define AWS_PROFILE (ou assume a role IAM) apenas para o processo filho do CDK
4. Se não encontrado, recorre às credenciais AWS que estiverem no seu ambiente

Isso significa que workflows existentes sem qualquer 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 AWS CLI nomeado de ~/.aws/config. O script define AWS_PROFILE para o processo CDK.
• assumeRole — Chama STS AssumeRole com o ARN da role especificado e passa as credenciais temporárias para o CDK. Você pode opcionalmente especificar um profile como credenciais de origem para a chamada AssumeRole, um externalId para políticas de confiança entre contas e uma sessionDuration em segundos.

Conta e Região

Cada configuração de estágio 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 o 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 = 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,
  },
});

Estágios Compartilhados vs Específicos de Projeto

Estágios 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.

Estágios específicos de projeto (em projects['packages/infra'].stages) aplicam-se apenas àquele projeto. Quando ambos existem para o mesmo nome de estágio, a entrada específica de projeto tem prioridade.

Dica

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

Infraestrutura de API

Se você usou os geradores tRPC API ou FastAPI para criar APIs, 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, pode simplesmente importar e instanciar o construct para adicionar toda a infraestrutura necessária para implantá-la:

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

    // Adicione infraestrutura para sua API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Infraestrutura de Website

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

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

    // Adicione infraestrutura para seu website
    new MyWebsite(this, 'MyWebsite');
  }
}

É importante garantir que o website seja declarado após quaisquer constructs de API para que o Runtime Config do website inclua todas as configurações de API.

Sintetizando sua Infraestrutura

Como parte do target build, além de executar os targets padrão de compilação, lint e testes, seu projeto de infraestrutura é sintetizado para CloudFormation. Isso também pode ser executado separadamente através do target 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

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

Testes de Segurança

Um target checkov é adicionado ao seu projeto para executar verificações de segurança na sua infraestrutura usando o 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

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

Nota

O Checkov é executado usando uvx, portanto você precisa instalar o uv caso ainda não tenha.

Cuidado

Algumas regras do Checkov são suprimidas por padrão via arquivo checkov.yml. Recomenda-se revisá-las com base no seu caso de uso.

Suprimindo Verificações do Checkov

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

Suprimir uma regra em um construct específico

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

// suprime a CKV_AWS_XXX para o construct especificado
suppressRules(construct, ['CKV_AWS_XXX'], 'Motivo');

Suprimir uma regra em um construct descendente

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

// Suprime a CKV_AWS_XXX para o construct ou quaisquer descendentes se for uma instância de Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Motivo', (construct) => construct instanceof Bucket);

Bootstrapping das Suas Contas AWS

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

Primeiro, certifique-se de ter configurado credenciais para sua conta AWS.

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

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

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

Implantando na AWS

Após um build, você pode implantar sua infraestrutura na AWS usando o target deploy.

Cuidado

Use o target deploy-ci se estiver implantando em um pipeline CI/CD. Veja abaixo para mais detalhes.

Primeiro, certifique-se de ter credenciais AWS configuradas. Se você gerou com enableStageConfig e configurou credenciais de estágio em packages/common/infra-config/src/stages.config.ts, o comando deploy resolverá e aplicará automaticamente as credenciais corretas para o estágio alvo. Caso contrário, certifique-se de que suas credenciais AWS estejam definidas no 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.

Em seguida, execute o target deploy:

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/*

Dica

O comando acima implanta todas as stacks do estágio <my-infra>-sandbox. Você pode especificar outros estágios desde que estejam definidos em main.ts.

Você também pode implantar stacks individuais especificando o nome completo da stack, por exemplo:

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

Implantando na AWS em um Pipeline CI/CD

Use o target deploy-ci se estiver implantando na AWS como parte de um 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 target difere ligeiramente do target deploy normal por implantar uma cloud assembly pré-sintetizada em vez de sintetizar em tempo de execução. Isso evita potencial não-determinismo de mudanças em versões de pacotes, garantindo que cada estágio do pipeline implante usando a mesma cloud assembly.

Removendo Infraestrutura AWS

Use o target destroy para remover seus 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/*

Mais Informações

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