Este é o Guia do desenvolvedor do 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á.
Tutorial: Crie seu primeiro aplicativo AWS CDK
Comece a usar o AWS Cloud Development Kit (AWS CDK) usando a AWS CDK Command Line Interface (AWS CDK CLI) para desenvolver seu primeiro aplicativo CDK, inicializar seu ambiente e implantar AWS seu aplicativo nele. AWS
Pré-requisitos
Antes de iniciar este tutorial, conclua todas as etapas de configuração em Introdução ao AWS CDK.
Sobre este tutorial
Neste tutorial, você criará e implantará um aplicativo simples AWS usando o AWS CDK. O aplicativo consiste em uma função AWS Lambda que retorna uma Hello World!
mensagem quando invocada. A função será invocada por meio de um URL de função do Lambda que serve como um endpoint HTTP(S) dedicado para sua função do Lambda.
Usando este tutorial, você fará o seguinte:
-
Crie seu projeto — Crie um projeto CDK usando o comando CDK CLI.
cdk init
-
Configure seu AWS ambiente — configure o AWS ambiente no qual você implantará seu aplicativo.
-
Inicialize seu AWS ambiente — Prepare seu AWS ambiente para implantação inicializando-o usando o comando CDK CLI.
cdk bootstrap
-
Desenvolva seu aplicativo — Use construções da AWS Construct Library para definir sua função Lambda e os recursos de URL da função Lambda.
-
Prepare seu aplicativo para implantação — Use a CLI do CDK para criar seu aplicativo e AWS CloudFormation sintetizar um modelo.
-
Implante seu aplicativo — Use o comando CDK
cdk deploy
CLI para implantar seu aplicativo e AWS provisionar seus recursos. -
Interaja com seu aplicativo — Interaja com sua função AWS Lambda implantada invocando-a e recebendo uma resposta.
-
Modifique sua aplicação — Modifique sua função do Lambda e implante para implementar suas alterações.
-
Exclua seu aplicativo — exclua todos os recursos que você criou usando o comando CDK
cdk destroy
CLI.
Etapa 1: Criar seu projeto CDK
Nesta etapa, você cria um novo projeto CDK. Um projeto CDK deve estar em seu próprio diretório, com suas próprias dependências de módulos locais.
- Para criar um projeto CDK
-
-
Em um diretório inicial de sua escolha, crie e navegue até um diretório chamado
hello-cdk
:$ mkdir hello-cdk && cd hello-cdk
Importante
Certifique-se de nomear o diretório do seu projeto
hello-cdk
, exatamente como mostrado aqui. A CLI do CDK usa esse nome de diretório para nomear coisas dentro do seu código CDK. Se você escolher outro nome de diretório, você terá problemas durante este tutorial. -
No
hello-cdk
diretório, inicialize um novo projeto CDK usando o comando CDK CLIcdk init
. Especifique o modeloapp
e sua linguagem de programação preferida com a opção--language
:
-
O comando cdk init
cria uma estrutura de arquivos e pastas dentro do diretório hello-cdk
para ajudar a organizar o código-fonte da sua aplicação CDK. Essa estrutura de arquivos e pastas é chamada de projeto CDK. Reserve um momento para explorar seu projeto CDK.
Se você instalou o Git, cada projeto que você cria usando também cdk init
é inicializado como um repositório Git.
Durante a inicialização do projeto, a CLI do CDK cria um aplicativo CDK contendo uma única pilha de CDK. A instância da aplicação CDK é criada usando o constructo App
. A seguir está uma parte desse código do seu arquivo de aplicação CDK:
A pilha CDK é criada usando o constructo Stack
. A seguir está uma parte desse código do seu arquivo de pilha CDK:
Etapa 2: configurar seu AWS ambiente
Nesta etapa, você configura o AWS ambiente para sua pilha de CDK. Ao fazer isso, você especifica em qual ambiente sua pilha de CDK será implantada.
Primeiro, determine o AWS ambiente que você deseja usar. Um AWS ambiente consiste em uma AWS conta e uma AWS região.
Ao usar a AWS CLI para configurar as credenciais de segurança em sua máquina local, você pode usar a AWS CLI para obter informações de AWS ambiente para um perfil específico.
- Para usar a AWS CLI para obter o ID da sua conta AWS
-
-
Execute o seguinte comando da AWS CLI para obter o ID da AWS conta do seu
default
perfil:$ aws sts get-caller-identity --query "Account" --output text
-
Se você preferir usar um perfil nomeado, forneça o nome do seu perfil usando a opção
--profile
:$ aws sts get-caller-identity --profile your-profile-name --query "Account" --output text
-
- Para usar a AWS CLI para obter sua região AWS
-
-
Execute o seguinte comando da AWS CLI para obter a região que você configurou para seu
default
perfil:$ aws configure get region
-
Se você preferir usar um perfil nomeado, forneça o nome do seu perfil usando a opção
--profile
:$ aws configure get region --profile your-profile-name
-
Em seguida, você configurará o AWS ambiente para sua pilha de CDK modificando a HelloCdkStack
instância no arquivo do aplicativo. Neste tutorial, você codificará as informações do seu AWS ambiente. Isso é recomendado para ambientes de produção. Para obter informações sobre outras formas de configurar ambientes, consulte Configurar ambientes para uso com o AWS CDK.
- Para configurar o ambiente para sua pilha de CDK
-
-
No seu arquivo da aplicação, use a propriedade
env
do constructoStack
para configurar seu ambiente. Veja um exemplo a seguir:
-
Etapa 3: inicialize seu ambiente AWS
Nesta etapa, você inicializa o AWS ambiente que você configurou na etapa anterior. Isso prepara seu ambiente para implantações de CDK.
Para inicializar seu ambiente, execute o seguinte a partir da raiz do seu projeto CDK:
$ cdk bootstrap
Ao inicializar a partir da raiz do seu projeto CDK, você não precisa fornecer nenhuma informação adicional. A CLI do CDK obtém informações do ambiente do seu projeto. Ao inicializar fora de um projeto CDK, você deve fornecer informações do ambiente com o comando cdk bootstrap
. Para obter mais informações, consulte Bootstrap do seu ambiente para uso com o AWS CDK.
Etapa 4: compilar sua aplicação do CDK
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 a CLI do CDK executará automaticamente essa etapa. No entanto, você ainda pode criar manualmente quando quiser detectar erros de sintaxe e tipo. Veja um exemplo a seguir:
Etapa 5: listar as pilhas de CDK em sua aplicação
Neste momento, você deve ter uma aplicação CDK contendo uma única pilha de CDK. Para verificar, use o comando CDK cdk list
CLI para exibir suas pilhas. A saída deve exibir uma única pilha chamada HelloCdkStack
:
$ cdk list HelloCdkStack
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 a Etapa 1: Crie seu projeto CDK e tente novamente.
Etapa 6: definir sua função do Lambda
Nesta etapa, você importa o aws_lambda
módulo da AWS Construct Library e usa a construção Function
L2.
Modifique seu arquivo de pilha CDK da seguinte forma:
Vamos dar uma olhada mais de perto na Function
construção. Como todos os constructos, a classe Function
usa três parâmetros:
-
escopo — Define sua instância
Stack
como pai do constructoFunction
. Todas as construções que definem AWS recursos são criadas dentro do escopo de uma pilha. Você pode definir constructos dentro de constructos, criando uma hierarquia (árvore). Aqui, e na maioria dos casos, o escopo éthis
(self
em Python). -
Id — O ID de construção do
Function
dentro do seu aplicativo AWS CDK. Esse ID, mais um hash baseado na localização da função na pilha, identifica de forma exclusiva a função durante a implantação. O AWS CDK também faz referência a essa ID quando você atualiza a construção em seu aplicativo e reimplanta para atualizar o recurso implantado. Aqui, seu ID de constructo éHelloWorldFunction
. As funções também podem ter um nome, especificado com a propriedadefunctionName
. Isto é diferente do ID do constructo. -
props — Um pacote de valores que define as propriedades da função. Aqui você define as propriedades
runtime
,handler
ecode
.Os adereços são representados de forma diferente nas linguagens suportadas 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 o
FunctionProps
e um segundo para oFunction
para permitir que você construa o constructo e seu objeto de props em uma única etapa. Esse código usa o último. -
Em C#, você instancia um
FunctionProps
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 constructo para estendê-lo de acordo com suas necessidades ou se quiser alterar seus padrões.
Etapa 7: Definir seu URL da função do Lambda
Nesta etapa, você usa o método auxiliar addFunctionUrl
do constructo Function
para definir o URL de uma função do Lambda. Para gerar o valor dessa URL na implantação, você criará uma AWS CloudFormation saída usando a CfnOutput
construção.
Adicione o seguinte ao seu arquivo de pilha CDK:
Atenção
Para manter esse tutorial simples, o URL da função do Lambda é definido sem autenticação. Quando implantado, isso cria um endpoint acessível ao público que pode ser usado para invocar sua função. Ao concluir este tutorial, siga a Etapa 12: Excluir seu aplicativo para excluir esses recursos.
Etapa 8: sintetizar um modelo CloudFormation
Nesta etapa, você se prepara para a implantação sintetizando um CloudFormation modelo com o comando CLI cdk synth
do CDK. Esse comando executa a validação básica do seu código CDK, executa seu aplicativo CDK e gera um CloudFormation modelo da sua pilha de CDK.
Se sua aplicação contiver mais de uma pilha, você deverá especificar quais pilhas sintetizar. Como seu aplicativo contém uma única pilha, a CLI do CDK detecta automaticamente a pilha para sintetizar.
Se você não sintetizar um modelo, a CLI do CDK executará automaticamente essa etapa quando você implantar. No entanto, recomendamos executar essa etapa antes de cada implantação para verificar se há erros de síntese.
Antes de sintetizar um modelo, você pode, opcionalmente, criar sua aplicação para capturar erros de sintaxe e de tipo. Para obter instruções, consulte Etapa 4: criar seu aplicativo CDK.
Para sintetizar um CloudFormation modelo, execute o seguinte a partir da raiz do seu projeto:
$ cdk synth
nota
Se você receber um erro como o seguinte, verifique se você está no diretório hello-cdk
e tente novamente:
--app is required either in command-line, in cdk.json or in ~/.cdk.json
Se for bem-sucedida, a CLI do CDK exibirá YAML
um modelo CloudFormation —formatado e salvará JSON
um modelo stdout
—formatado no diretório do seu projeto. cdk.out
Veja a seguir um exemplo de saída do CloudFormation modelo:
Resources: HelloWorldFunctionServiceRole<unique-identifier>: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Statement: - Action: sts:AssumeRole Effect: Allow Principal: Service: lambda.amazonaws.com Version: "2012-10-17" ManagedPolicyArns: - Fn::Join: - "" - - "arn:" - Ref: AWS::Partition - :iam::aws:policy/service-role/AWSLambdaBasicExecutionRole Metadata: aws:cdk:path: HelloCdkStack/HelloWorldFunction/ServiceRole/Resource HelloWorldFunction<unique-identifier>: Type: AWS::Lambda::Function Properties: Code: ZipFile: " \ exports.handler = async function(event) { \ return { \ statusCode: 200, \ body: JSON.stringify('Hello World!'), \ }; \ }; \ " Handler: index.handler Role: Fn::GetAtt: - HelloWorldFunctionServiceRole<unique-identifier> - Arn Runtime: nodejs20.x DependsOn: - HelloWorldFunctionServiceRole<unique-identifier> Metadata: aws:cdk:path: HelloCdkStack/HelloWorldFunction/Resource HelloWorldFunctionFunctionUrl<unique-identifier>: Type: AWS::Lambda::Url Properties: AuthType: NONE TargetFunctionArn: Fn::GetAtt: - HelloWorldFunction<unique-identifier> - Arn Metadata: aws:cdk:path: HelloCdkStack/HelloWorldFunction/FunctionUrl/Resource HelloWorldFunctioninvokefunctionurl<unique-identifier>: Type: AWS::Lambda::Permission Properties: Action: lambda:InvokeFunctionUrl FunctionName: Fn::GetAtt: - HelloWorldFunction<unique-identifier> - Arn FunctionUrlAuthType: NONE Principal: "*" Metadata: aws:cdk:path: HelloCdkStack/HelloWorldFunction/invoke-function-url CDKMetadata: Type: AWS::CDK::Metadata Properties: Analytics: v2:deflate64:<unique-identifier> Metadata: aws:cdk:path: HelloCdkStack/CDKMetadata/Default Condition: CDKMetadataAvailable Outputs: myFunctionUrlOutput: Value: Fn::GetAtt: - HelloWorldFunctionFunctionUrl<unique-identifier> - FunctionUrl Parameters: BootstrapVersion: Type: AWS::SSM::Parameter::Value<String> Default: /cdk-bootstrap/<unique-identifier>/version Description: Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip] Rules: CheckBootstrapVersion: Assertions: - Assert: Fn::Not: - Fn::Contains: - - "1" - "2" - "3" - "4" - "5" - Ref: BootstrapVersion AssertDescription: CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI.
nota
Cada modelo gerado contém um recurso AWS::CDK::Metadata
por padrão. A equipe do AWS CDK usa esses metadados para obter informações sobre o uso do AWS CDK e encontrar maneiras de melhorá-lo. Para obter detalhes, incluindo como optar por não receber relatórios de versão, consulte Relatórios de versão.
Ao definir uma única construção L2, o AWS CDK cria um CloudFormation modelo extenso contendo seus recursos do Lambda, junto com as permissões e a lógica de colagem necessárias para que seus recursos interajam com seu aplicativo.
Etapa 9: Implantar sua pilha de CDK
Nesta etapa, você usa o comando CDK cdk deploy
CLI para implantar sua pilha CDK. Esse comando recupera seu CloudFormation modelo gerado e o implanta por meio dele AWS CloudFormation, que provisiona seus recursos como parte de uma CloudFormation pilha.
Da raiz do seu projeto, execute o seguinte. Confirme as alterações, se solicitado:
$ cdk deploy ✨ Synthesis time: 2.69s HelloCdkStack: start: Building <unique-identifier>:current_account-current_region HelloCdkStack: success: Built <unique-identifier>:current_account-current_region HelloCdkStack: start: Publishing <unique-identifier>:current_account-current_region HelloCdkStack: success: Published <unique-identifier>:current_account-current_region This deployment will make potentially sensitive changes according to your current security approval level (--require-approval broadening). Please confirm you intend to make the following modifications: IAM Statement Changes ┌───┬───────────────────────────────────────┬────────┬──────────────────────────┬──────────────────────────────┬───────────┐ │ │ Resource │ Effect │ Action │ Principal │ Condition │ ├───┼───────────────────────────────────────┼────────┼──────────────────────────┼──────────────────────────────┼───────────┤ │ + │ ${HelloWorldFunction.Arn} │ Allow │ lambda:InvokeFunctionUrl │ * │ │ ├───┼───────────────────────────────────────┼────────┼──────────────────────────┼──────────────────────────────┼───────────┤ │ + │ ${HelloWorldFunction/ServiceRole.Arn} │ Allow │ sts:AssumeRole │ Service:lambda.amazonaws.com │ │ └───┴───────────────────────────────────────┴────────┴──────────────────────────┴──────────────────────────────┴───────────┘ IAM Policy Changes ┌───┬───────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────┐ │ │ Resource │ Managed Policy ARN │ ├───┼───────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────┤ │ + │ ${HelloWorldFunction/ServiceRole} │ arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole │ └───┴───────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────┘ (NOTE: There may be security-related changes not in this list. See https://github.com/aws/aws-cdk/issues/1299) Do you wish to deploy these changes (y/n)? y
Da mesma formacdk synth
, você não precisa especificar a pilha AWS CDK, pois o aplicativo contém uma única pilha.
Durante a implantação, a CLI do CDK exibe informações de progresso à medida que sua pilha é implantada. Quando terminar, você pode acessar o console do AWS CloudFormation HelloCdkStack
. Você também pode acessar o console Lambda para ver seu recurso HelloWorldFunction
.
Quando a implantação for concluída, a CLI do CDK exibirá o URL do seu endpoint. Copie esse URL para a próxima etapa. Veja um exemplo a seguir:
... HelloCdkStack: deploying... [1/1] HelloCdkStack: creating CloudFormation changeset... ✅ HelloCdkStack ✨ Deployment time: 41.65s Outputs: HelloCdkStack.myFunctionUrlOutput = https://<api-id>.lambda-url.<Region>.on.aws/ Stack ARN: arn:aws:cloudformation:<Region:account-id>:stack/HelloCdkStack/<unique-identifier> ✨ Total time: 44.34s
Etapa 10: Interaja com seu aplicativo em AWS
Nesta etapa, você interage com seu aplicativo AWS invocando sua função Lambda por meio do URL da função. Quando você acessa o URL, sua função do Lambda retorna a mensagem Hello World!
.
Para invocar sua função, acesse o URL da função pelo navegador ou pela linha de comando. Veja um exemplo a seguir:
$ curl https://<api-id>.lambda-url.<Region>.on.aws/ "Hello World!"%
Etapa 11: Modificar sua aplicação
Nesta etapa, você modifica a mensagem que a função do Lambda retorna quando invocada. Você executa uma comparação usando o cdk diff
comando CDK CLI para visualizar suas alterações e implantar para atualizar seu aplicativo. Em seguida, você interage com seu aplicativo AWS para ver sua nova mensagem.
Modifique a instância myFunction
em seu arquivo de pilha CDK da seguinte forma:
Atualmente, suas alterações de código não fizeram nenhuma atualização direta em seu recurso Lambda implantado. Seu código define o estado desejado do seu recurso. Para modificar seu recurso implantado, você usará a CLI do CDK para sintetizar o estado desejado em um novo modelo. AWS CloudFormation Em seguida, você implantará seu novo 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 visualizar suas alterações, execute o comando cdk diff
. Veja um exemplo a seguir:
$ cdk diff Stack HelloCdkStack Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff) Resources [~] AWS::Lambda::Function HelloWorldFunction HelloWorldFunction<unique-identifier> └─ [~] Code └─ [~] .ZipFile: ├─ [-] exports.handler = async function(event) { return { statusCode: 200, body: JSON.stringify('Hello World!'), }; }; └─ [+] exports.handler = async function(event) { return { statusCode: 200, body: JSON.stringify('Hello CDK!'), }; }; ✨ Number of stacks with differences: 1
Para criar essa diferença, a CLI do CDK consulta sua AWS conta para obter o modelo mais recente AWS CloudFormation da pilha. HelloCdkStack
Em seguida, ele compara o modelo mais recente com o modelo que acabou de sintetizar da sua aplicação.
Para implementar suas alterações, execute o comando cdk deploy
. Veja um exemplo a seguir:
$ cdk deploy ✨ Synthesis time: 2.12s HelloCdkStack: start: Building <unique-identifier>:current_account-current_region HelloCdkStack: success: Built <unique-identifier>:current_account-current_region HelloCdkStack: start: Publishing <unique-identifier>:current_account-current_region HelloCdkStack: success: Published <unique-identifier>:current_account-current_region HelloCdkStack: deploying... [1/1] HelloCdkStack: creating CloudFormation changeset... ✅ HelloCdkStack ✨ Deployment time: 26.96s Outputs: HelloCdkStack.myFunctionUrlOutput = https://<unique-identifier>.lambda-url.<Region>.on.aws/ Stack ARN: arn:aws:cloudformation:<Region:account-id>:stack/HelloCdkStack/<unique-identifier> ✨ Total time: 29.07s
Para interagir com seu aplicativo, repita a Etapa 10: Interaja com seu aplicativo ativado AWS. Veja um exemplo a seguir:
$ curl https://<api-id>.lambda-url.<Region>.on.aws/ "Hello CDK!"%
Etapa 12: Excluir sua aplicação
Nesta etapa, você usa o comando CDK cdk destroy
CLI para excluir seu aplicativo. Esse comando exclui a CloudFormation pilha associada à sua pilha CDK, que inclui os recursos que você criou.
Para excluir sua aplicação, execute o comando cdk destroy
e confirme sua solicitação para excluir a aplicação. Veja um exemplo a seguir:
$ cdk destroy Are you sure you want to delete: HelloCdkStack (y/n)? y HelloCdkStack: destroying... [1/1] ✅ HelloCdkStack: destroyed
Próximas etapas
Parabéns! Você concluiu este tutorial e usou o AWS CDK para criar, modificar e excluir recursos na AWS nuvem com sucesso. Agora você está pronto para começar a usar o AWS CDK.
Para saber mais sobre como usar o AWS CDK em sua linguagem de programação preferida, consulte Trabalhar com a biblioteca AWS CDK.
Para recursos adicionais, consulte o seguinte:
-
Experimente o CDK Workshop
para um tour mais aprofundado envolvendo um projeto mais complexo. -
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.
O AWS CDK é um projeto de código aberto. Para contribuir, consulte Contribuindo com o AWS Cloud Development Kit (AWS CDK)