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.

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

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

Você notará que o arquivo principal src/main.ts instancia um Stage do CDK chamado <namespace>-sandbox. Este estágio é destinado ao seu próprio desenvolvimento e testes.

src/main.ts

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

Você pode adicionar mais estágios, por exemplo, pode definir estágios beta e prod que implantam em ambientes separados:

src/main.ts

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

Um Stage define uma coleção de stacks que devem ser implantadas juntas para compor sua aplicação. Você pode instanciar quantas stacks quiser dentro de um estágio, por exemplo:

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 uma coleção de CDK Stacks que compõem sua aplicação
 */
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,
    });
  }
}

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:

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 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 da Sua Conta AWS

Se você está implantando uma aplicação CDK em uma conta AWS pela primeira vez, será necessário fazer o bootstrap primeiro.

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

Em seguida, use o comando cdk bootstrap:

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

Para mais detalhes, consulte a documentação 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 para implantações em pipelines CI/CD. Veja abaixo para detalhes.

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

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.

Também é possível 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 para implantações 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 deploy normal por garantir que a cloud-assembly pré-sintetizada seja implantada, em vez de sintetizar durante a execução. Isso ajuda a evitar problemas de não-determinismo devido a alterações em versões de pacotes, garantindo que cada estágio do pipeline use 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.