Infraestrutura CDK

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

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

Utilização

Gerar um Projeto de Infraestrutura

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

VSCode
CLI

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

pnpm nx g @aws/nx-plugin:ts#infra

yarn nx g @aws/nx-plugin:ts#infra

npx nx g @aws/nx-plugin:ts#infra

bunx nx g @aws/nx-plugin:ts#infra

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

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npx nx g @aws/nx-plugin:ts#infra --dry-run

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.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
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 stacks CDK para implantação
- Directorystacks Definições de stacks 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

Implementando sua Infraestrutura CDK

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

import * as cdk from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

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

    // Declare sua infraestrutura aqui
    new Bucket(this, 'MyBucket');
  }
}

Infraestrutura para APIs

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

Por exemplo, se você criou uma API tRPC chamada my-api, basta importar e instanciar o construct para adicionar toda a infraestrutura necessária:

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

Infraestrutura para Websites

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

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 declarar o website após quaisquer constructs de API para que a Configuração de Runtime 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 nx run <my-infra>:synth

yarn nx run <my-infra>:synth

npx nx run <my-infra>:synth

bunx nx run <my-infra>:synth

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

Preparando sua(s) Conta(s) AWS

Se você está implantando uma aplicação CDK em uma conta AWS pela primeira vez, será necessário preparar (bootstrap) a conta 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.

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

Em seguida, execute o target de deploy:

pnpm nx run <my-infra>:deploy --all

yarn nx run <my-infra>:deploy --all

npx nx run <my-infra>:deploy --all

bunx nx run <my-infra>:deploy --all

O comando acima implanta todas as stacks definidas em main.ts. Você pode querer implantar uma stack específica, especialmente se tiver configurado múltiplos estágios de uma aplicação:

pnpm nx run <my-infra>:deploy my-sandbox-stack

yarn nx run <my-infra>:deploy my-sandbox-stack

npx nx run <my-infra>:deploy my-sandbox-stack

bunx nx run <my-infra>:deploy my-sandbox-stack

Implantando na AWS em um Pipeline CI/CD

Use o target deploy-ci para implantações em pipelines CI/CD:

pnpm nx run <my-infra>:deploy-ci my-stack

yarn nx run <my-infra>:deploy-ci my-stack

npx nx run <my-infra>:deploy-ci my-stack

bunx nx run <my-infra>:deploy-ci my-stack

Este target difere do deploy normal por garantir que a cloud-assembly pré-sintetizada seja implantada, ao invés de sintetizar durante a execução. Isso evita problemas potenciais de não-determinismo devido a versões de pacotes, assegurando que todos os estágios do pipeline usem a mesma cloud-assembly.

Mais Informações

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