Este é o Guia do Desenvolvedor AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Seu primeiro AWS CDK aplicativo
Comece a usar o AWS Cloud Development Kit (AWS CDK) criando seu primeiro aplicativo CDK.
Antes de iniciar este tutorial, recomendamos que você conclua o seguinte:
-
Consulte O que é o AWS CDK? para obter uma introdução ao AWS CDK.
-
Veja Aprenda os AWS CDK principais conceitos para aprender os principais conceitos do AWS CDK.
-
Siga os pré-requisitos e as etapas de AWS CDK configuração em. Começando com o AWS CDK
Tópicos
- Sobre este tutorial
- Etapa 1: criar o aplicativo
- Etapa 2: criar o aplicativo
- Etapa 3: liste as pilhas no aplicativo
- Etapa 4: Adicionar um bucket do Amazon S3
- Etapa 5: sintetizar um modelo AWS CloudFormation
- Etapa 6: implantar sua pilha
- Etapa 7: modifique seu aplicativo
- Etapa 8: Destruindo os recursos do aplicativo
- Próximas etapas
Sobre este tutorial
Neste tutorial, você criará e implantará um AWS CDK aplicativo simples. Esse aplicativo contém uma pilha com um único recurso de bucket do Amazon Simple Storage Service (Amazon S3). Por meio deste tutorial, você aprenderá o seguinte:
-
A estrutura de um AWS CDK projeto.
-
Como criar um AWS CDK aplicativo.
-
Como usar a AWS Construct Library para definir aplicativos, pilhas e AWS recursos.
-
Como usar o CDK CLI para sintetizar, diferenciar, implantar e excluir seu aplicativo CDK.
-
Como modificar e reimplantar seu aplicativo CDK para atualizar seus recursos implantados.
O fluxo de trabalho de AWS CDK desenvolvimento padrão consiste nas seguintes etapas:
-
Crie seu AWS CDK aplicativo — Aqui, você usará um modelo fornecido pelo CDKCLI.
-
Defina suas pilhas e recursos — Use construções para definir suas pilhas e AWS recursos em seu aplicativo.
-
Crie seu aplicativo — Essa etapa é opcional. O CDK executa CLI automaticamente essa etapa, se necessário. É recomendável realizar essa etapa para identificar erros de sintaxe e tipo.
-
Sintetize suas pilhas — Essa etapa cria um AWS CloudFormation modelo para cada pilha em seu aplicativo. Essa etapa é útil para identificar erros lógicos nos AWS recursos definidos.
-
Implante seu aplicativo — implante em seu AWS ambiente usando AWS CloudFormation para provisionar seus recursos. Durante a implantação, você identificará quaisquer problemas de permissão com seu aplicativo.
Por meio de um fluxo de trabalho típico, você voltará e repetirá as etapas anteriores para modificar ou depurar seu aplicativo.
Recomendamos que você use o controle de versão para seus AWS CDK projetos.
Etapa 1: criar o aplicativo
Um aplicativo CDK deve estar em seu próprio diretório, com suas próprias dependências de módulos locais. Em sua máquina de desenvolvimento, crie um novo diretório. Veja a seguir um exemplo que cria um novo hello-cdk
diretório:
$
mkdir hello-cdk
$
cd hello-cdk
Importante
Certifique-se de nomear o diretório do seu projetohello-cdk
, exatamente como mostrado aqui. O modelo do AWS CDK projeto usa o nome do diretório para nomear as coisas no código gerado. Se você usar um nome diferente, o código deste tutorial não funcionará.
Em seguida, a partir do seu novo diretório, inicialize o aplicativo usando o cdk init comando. Especifique o app
modelo e sua linguagem de programação preferida com a --language
opção. Veja um exemplo a seguir:
O cdk init
comando cria vários arquivos e pastas dentro do hello-cdk
diretório para ajudar você a organizar o código-fonte do seu AWS CDK aplicativo. Coletivamente, isso é chamado de seu AWS CDK
projeto. Reserve um momento para explorar o projeto CDK.
Se você Git instalou, cada projeto que você cria usando também cdk init
é inicializado como um Git repositório.
Etapa 2: criar o aplicativo
Na maioria dos ambientes de programação, você cria ou compila o código depois de fazer alterações. Isso não é necessário com o, AWS CDK pois o CDK CLI executará essa etapa automaticamente. No entanto, você ainda pode criar manualmente quando quiser detectar erros de sintaxe e tipo. Veja um exemplo a seguir:
Etapa 3: liste as pilhas no aplicativo
Verifique se seu aplicativo foi criado corretamente listando as pilhas em seu aplicativo. Execute o seguinte:
$
cdk ls
A saída deve ser exibidaHelloCdkStack
. Se você não ver essa saída, verifique se você está no diretório de trabalho correto do seu projeto e tente novamente. Se você ainda não vê sua pilha, repita Etapa 1: criar o aplicativo e tente novamente.
Etapa 4: Adicionar um bucket do Amazon S3
Neste momento, seu aplicativo CDK contém uma única pilha. Em seguida, você definirá um recurso de bucket do Amazon Simple Storage Service (Amazon S3) dentro da sua pilha. Para fazer isso, você importará e usará a construção Bucket
L2 da Construct Library. AWS
Modifique seu aplicativo CDK importando a Bucket
construção e definindo seu recurso de bucket do Amazon S3. Veja um exemplo a seguir:
Vamos dar uma olhada mais de perto na Bucket
construção. Como todas as construções, a Bucket
classe usa três parâmetros:
-
escopo — Define a
Stack
classe como a mãe daBucket
construção. Todas as construções que definem AWS recursos são criadas dentro do escopo de uma pilha. Você pode definir construções dentro de construções, criando uma hierarquia (árvore). Aqui, e na maioria dos casos, o escopo éthis
(self
emPython). -
Id — O ID lógico do
Bucket
dentro do seu AWS CDK aplicativo. Esse ID, mais um hash baseado na localização do bucket na pilha, identifica exclusivamente o bucket durante a implantação. AWS CDK Também faz referência a esse ID quando você atualiza a construção em seu aplicativo e reimplanta para atualizar o recurso implantado. Aqui, sua identificação lógica éMyFirstBucket
. Os buckets também podem ter um nome, especificado com abucketName
propriedade. Isso é diferente do ID lógico. -
props — Um pacote de valores que define as propriedades do bucket. Aqui você definiu a
versioned
propriedade comotrue
, que permite o controle de versão dos arquivos no bucket.Os adereços são representados de forma diferente nos idiomas suportados pelo AWS CDK.
-
In TypeScript and JavaScript,
props
é um único argumento e você passa um objeto contendo as propriedades desejadas. -
Em Python, os adereços são passados como argumentos de palavras-chave.
-
Em Java, um Builder é fornecido para passar os adereços. Existem dois: um para
BucketProps
e um segundo para permitir que vocêBucket
construa a construção e seu objeto de adereços em uma única etapa. Esse código usa o último. -
Em C#, você instancia um
BucketProps
objeto usando um inicializador de objetos e o passa como o terceiro parâmetro.
Se os adereços de uma construção forem opcionais, você poderá omitir totalmente o
props
parâmetro. -
Todas as construções usam esses mesmos três argumentos, então é fácil se manter orientado à medida que você aprende sobre novos. E, como era de se esperar, você pode subclassificar qualquer construção para estendê-la de acordo com suas necessidades ou se quiser alterar seus padrões.
Etapa 5: sintetizar um modelo AWS CloudFormation
Sintetize um AWS CloudFormation modelo para o aplicativo, da seguinte forma:
$
cdk synth
Se seu aplicativo contiver mais de uma pilha, você deverá especificar quais pilhas sintetizar. Como seu aplicativo contém uma única pilha, o CDK detecta CLI automaticamente a pilha para sintetizar.
Se você não executarcdk synth
, o CDK CLI executará automaticamente essa etapa quando você implantar. No entanto, recomendamos que você execute essa etapa antes de cada implantação.
dica
Se você receber um erro como--app is required ...
, verifique o diretório no qual você está executando os CLI comandos do CDK. Você deve estar no diretório principal do seu aplicativo.
O cdk synth
comando executa seu aplicativo. Isso cria um AWS CloudFormation modelo para cada pilha no seu aplicativo. O CDK CLI exibirá uma versão em formato YAML do seu modelo na linha de comando e salvará uma versão em formato JSON do seu modelo no diretório. cdk.out
Veja a seguir um trecho da saída da linha de comando que mostra o bucket sendo definido no AWS CloudFormation modelo:
Resources: MyFirstBucketB8884501: Type: AWS::S3::Bucket Properties: VersioningConfiguration: Status: Enabled UpdateReplacePolicy: Retain DeletionPolicy: Retain Metadata: #...
nota
Cada modelo gerado contém um AWS::CDK::Metadata
recurso por padrão. A AWS CDK equipe usa esses metadados para obter informações sobre o AWS CDK uso e encontrar maneiras de melhorá-lo. Para obter detalhes, incluindo como optar por não receber relatórios de versão, consulteRelatórios de versão.
O modelo gerado pode ser implantado por meio do AWS CloudFormation console ou de qualquer ferramenta AWS CloudFormation de implantação. Você também pode usar o CDK CLI para implantar. Na próxima etapa, você usa o CDK CLI para implantar.
Etapa 6: implantar sua pilha
Para implantar sua pilha de CDK para AWS CloudFormation usar o CDKCLI, execute o seguinte:
$
cdk deploy
Importante
Você deve executar uma única inicialização do seu AWS ambiente antes da implantação. Para obter instruções, consulte Bootstrap em seu ambiente.
Da mesma formacdk synth
, você não precisa especificar a AWS CDK pilha, pois o aplicativo contém uma única pilha.
Se seu código tiver implicações de segurança, o CDK CLI produzirá um resumo. Você precisará confirmá-los para continuar com a implantação. O aplicativo deste tutorial não tem essas implicações.
Após a execuçãocdk deploy
, o CDK CLI exibe informações de progresso à medida que sua pilha é implantada. Quando terminar, você pode acessar o AWS CloudFormation consoleHelloCdkStack
pilha. Você também pode acessar o console do Amazon S3 para visualizar seu MyFirstBucket
recurso.
Parabéns! Você implantou sua primeira pilha usando o. AWS CDK Em seguida, você modificará seu aplicativo e o reimplantará para atualizar seu recurso.
Etapa 7: modifique seu aplicativo
Nesta etapa, você modificará seu bucket do Amazon S3 configurando-o para ser excluído automaticamente quando sua pilha for excluída. Essa modificação envolve a alteração da RemovalPolicy
propriedade do bucket. Você também configurará a autoDeleteObjects
propriedade para configurar o CDK CLI para excluir objetos do bucket antes de destruí-lo. Por padrão, AWS CloudFormation não exclui buckets do Amazon S3 que contêm objetos.
Use o exemplo a seguir para modificar seu recurso:
Atualmente, suas alterações de código não fizeram nenhuma atualização direta em seu recurso de bucket do Amazon S3 implantado. Seu código define o estado desejado do seu recurso. Para modificar seu recurso implantado, você usará o CDK CLI para sintetizar o estado desejado em um novo modelo. AWS CloudFormation Em seguida, você implantará seu novo AWS CloudFormation modelo como um conjunto de alterações. Os conjuntos de alterações fazem somente as alterações necessárias para alcançar o novo estado desejado.
Para ver essas alterações, use o cdk diff
comando. Execute o seguinte:
$
cdk diff
O CDK CLI consulta sua Conta da AWS conta para obter o AWS CloudFormation modelo mais recente para a pilha. HelloCdkStack
Em seguida, ele compara o modelo mais recente com o modelo que acabou de sintetizar do seu aplicativo. A saída deve ser a seguinte.
Stack HelloCdkStack IAM Statement Changes ┌───┬──────────────────────────────┬────────┬──────────────────────────────┬──────────────────────────────┬───────────┐ │ │ Resource │ Effect │ Action │ Principal │ Condition │ ├───┼──────────────────────────────┼────────┼──────────────────────────────┼──────────────────────────────┼───────────┤ │ + │ ${Custom::S3AutoDeleteObject │ Allow │ sts:AssumeRole │ Service:lambda.amazonaws.com │ │ │ │ sCustomResourceProvider/Role │ │ │ │ │ │ │ .Arn} │ │ │ │ │ ├───┼──────────────────────────────┼────────┼──────────────────────────────┼──────────────────────────────┼───────────┤ │ + │ ${MyFirstBucket.Arn} │ Allow │ s3:DeleteObject* │ AWS:${Custom::S3AutoDeleteOb │ │ │ │ ${MyFirstBucket.Arn}/* │ │ s3:GetBucket* │ jectsCustomResourceProvider/ │ │ │ │ │ │ s3:GetObject* │ Role.Arn} │ │ │ │ │ │ s3:List* │ │ │ └───┴──────────────────────────────┴────────┴──────────────────────────────┴──────────────────────────────┴───────────┘ IAM Policy Changes ┌───┬────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────┐ │ │ Resource │ Managed Policy ARN │ ├───┼────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤ │ + │ ${Custom::S3AutoDeleteObjectsCustomResourceProvider/Ro │ {"Fn::Sub":"arn:${AWS::Partition}:iam::aws:policy/serv │ │ │ le} │ ice-role/AWSLambdaBasicExecutionRole"} │ └───┴────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘ (NOTE: There may be security-related changes not in this list. See https://github.com/aws/aws-cdk/issues/1299) Parameters [+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3Bucket AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3BucketBF7A7F3F: {"Type":"String","Description":"S3 bucket for asset \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""} [+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3VersionKey AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3VersionKeyFAF93626: {"Type":"String","Description":"S3 key for asset version \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""} [+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/ArtifactHash AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392ArtifactHashE56CD69A: {"Type":"String","Description":"Artifact hash for asset \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""} Resources [+] AWS::S3::BucketPolicy MyFirstBucket/Policy MyFirstBucketPolicy3243DEFD [+] Custom::S3AutoDeleteObjects MyFirstBucket/AutoDeleteObjectsCustomResource MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E [+] AWS::IAM::Role Custom::S3AutoDeleteObjectsCustomResourceProvider/Role CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092 [+] AWS::Lambda::Function Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F [~] AWS::S3::Bucket MyFirstBucket MyFirstBucketB8884501 ├─ [~] DeletionPolicy │ ├─ [-] Retain │ └─ [+] Delete └─ [~] UpdateReplacePolicy ├─ [-] Retain └─ [+] Delete
Essa diferença tem quatro seções:
-
Alterações na declaração do IAM e na política do IAM — Essas alterações de permissão existem porque você define a
AutoDeleteObjects
propriedade no seu bucket do Amazon S3. O recurso de exclusão automática usa um recurso personalizado para excluir os objetos no bucket antes que o próprio bucket seja excluído. Os objetos do IAM concedem ao código do recurso personalizado acesso ao bucket. -
Parâmetros — O AWS CDK usa essas entradas para localizar o ativo da AWS Lambda função para o recurso personalizado.
-
Recursos — Os recursos novos e alterados nessa pilha. Podemos ver os objetos IAM mencionados anteriormente, o recurso personalizado e a função Lambda associada sendo adicionados. Também podemos ver que o bucket
DeletionPolicy
e osUpdateReplacePolicy
atributos estão sendo atualizados. Isso permite que o bucket seja excluído junto com a pilha e substituído por um novo.
Você pode notar que especificamos RemovalPolicy
em nosso AWS CDK aplicativo, mas obtivemos uma DeletionPolicy
propriedade no AWS CloudFormation modelo resultante. Isso ocorre porque o AWS CDK usa um nome diferente para a propriedade. O AWS CDK
padrão é reter o bucket quando a pilha é excluída, enquanto o AWS CloudFormation padrão é excluí-la. Para ter mais informações, consulte Políticas de remoção.
Para ver seu novo AWS CloudFormation modelo, você pode executarcdk synth. Ao fazer algumas alterações em seu aplicativo CDK, seu novo AWS CloudFormation modelo agora inclui muitas linhas de código adicionais em comparação com o AWS CloudFormation modelo original.
Em seguida, implante seu aplicativo executando o seguinte:
$
cdk deploy
Ele AWS CDK informará você sobre as mudanças na política de segurança que já vimos no diff. Entre y para aprovar as alterações e implantar a pilha atualizada. O CDK CLI implantará sua pilha para fazer as alterações desejadas. Veja a seguir um exemplo de saída:
HelloCdkStack: deploying... [0%] start: Publishing 4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392:current [100%] success: Published 4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392:current HelloCdkStack: creating CloudFormation changeset... 0/5 | 4:32:31 PM | UPDATE_IN_PROGRESS | AWS::CloudFormation::Stack | HelloCdkStack User Initiated 0/5 | 4:32:36 PM | CREATE_IN_PROGRESS | AWS::IAM::Role | Custom::S3AutoDeleteObjectsCustomResourceProvider/Role (CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092) 1/5 | 4:32:36 PM | UPDATE_COMPLETE | AWS::S3::Bucket | MyFirstBucket (MyFirstBucketB8884501) 1/5 | 4:32:36 PM | CREATE_IN_PROGRESS | AWS::IAM::Role | Custom::S3AutoDeleteObjectsCustomResourceProvider/Role (CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092) Resource creation Initiated 3/5 | 4:32:54 PM | CREATE_COMPLETE | AWS::IAM::Role | Custom::S3AutoDeleteObjectsCustomResourceProvider/Role (CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092) 3/5 | 4:32:56 PM | CREATE_IN_PROGRESS | AWS::Lambda::Function | Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler (CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F) 3/5 | 4:32:56 PM | CREATE_IN_PROGRESS | AWS::S3::BucketPolicy | MyFirstBucket/Policy (MyFirstBucketPolicy3243DEFD) 3/5 | 4:32:56 PM | CREATE_IN_PROGRESS | AWS::Lambda::Function | Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler (CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F) Resource creation Initiated 3/5 | 4:32:57 PM | CREATE_COMPLETE | AWS::Lambda::Function | Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler (CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F) 3/5 | 4:32:57 PM | CREATE_IN_PROGRESS | AWS::S3::BucketPolicy | MyFirstBucket/Policy (MyFirstBucketPolicy3243DEFD) Resource creation Initiated 4/5 | 4:32:57 PM | CREATE_COMPLETE | AWS::S3::BucketPolicy | MyFirstBucket/Policy (MyFirstBucketPolicy3243DEFD) 4/5 | 4:32:59 PM | CREATE_IN_PROGRESS | Custom::S3AutoDeleteObjects | MyFirstBucket/AutoDeleteObjectsCustomResource/Default (MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E) 5/5 | 4:33:06 PM | CREATE_IN_PROGRESS | Custom::S3AutoDeleteObjects | MyFirstBucket/AutoDeleteObjectsCustomResource/Default (MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E) Resource creation Initiated 5/5 | 4:33:06 PM | CREATE_COMPLETE | Custom::S3AutoDeleteObjects | MyFirstBucket/AutoDeleteObjectsCustomResource/Default (MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E) 5/5 | 4:33:08 PM | UPDATE_COMPLETE_CLEA | AWS::CloudFormation::Stack | HelloCdkStack 6/5 | 4:33:09 PM | UPDATE_COMPLETE | AWS::CloudFormation::Stack | HelloCdkStack ✅ HelloCdkStack Stack ARN: arn:aws:cloudformation:REGION:ACCOUNT:stack/HelloCdkStack/UNIQUE-ID
Etapa 8: Destruindo os recursos do aplicativo
Agora que você concluiu este tutorial, pode excluir a AWS CloudFormation pilha implantada e todos os recursos associados a ela. Essa é uma boa prática para minimizar custos desnecessários e manter seu ambiente limpo. Execute o seguinte:
$
cdk destroy
Entre y para aprovar as alterações e excluir sua pilha.
nota
Se você não alterasse o intervaloRemovalPolicy
, a exclusão da pilha seria concluída com êxito, mas o intervalo ficaria órfão (não mais associado à pilha).
Próximas etapas
Parabéns! Você concluiu este tutorial e usou o AWS CDK para criar, modificar e excluir recursos no Nuvem AWS. Agora você está pronto para começar a usar AWS CDK o.
Para saber mais sobre como usar o AWS CDK em sua linguagem de programação preferida, consulteTrabalhando com o AWS CDK em linguagens de programação suportadas.
Para obter recursos adicionais, consulte o seguinte:
-
Experimente o CDK Workshop
para um tour mais aprofundado envolvendo um projeto mais complexo. -
Mergulhe mais fundo em conceitos como Ambientes do Ativos PermissõesContexto de runtime,,Parâmetros,, Personalizando construções da Construct Library AWS e.
-
Consulte a referência da API para começar a explorar as construções de CDK disponíveis para seus serviços favoritos AWS .
-
Visite o Construct Hub
para descobrir construções criadas por AWS e outros. -
Explore exemplos
de uso do AWS CDK.
AWS CDK É um projeto de código aberto. Para contribuir, consulte Contribuindo para AWS Cloud Development Kit (AWS CDK)