Este é o Guia do Desenvolvedor AWS CDK v2. A versão CDK 1 mais antiga 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 AWS CDK aplicativo
Comece a usar o AWS Cloud Development Kit (AWS CDK) usando a AWS CDK Command Line Interface (AWS CDK CLI) para desenvolver seu primeiro CDK aplicativo, inicializar seu AWS ambiente e implantar seu aplicativo em AWS.
Pré-requisitos
Antes de iniciar este tutorial, conclua todas as etapas de configuração emComeçando com o AWS CDK.
Sobre este tutorial
Neste tutorial, você criará e implantará um aplicativo simples AWS usando AWS CDK o. O aplicativo consiste em uma AWS Lambda função que retorna uma Hello World!
mensagem quando invocada. A função será invocada por meio de uma URL função Lambda que serve como um endpoint (S) HTTP dedicado para sua função Lambda.
Por meio deste tutorial, você executará o seguinte:
-
Crie seu projeto — Crie um CDK projeto usando o CDK CLI
cdk init
comando. -
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 da função Lambda. URL
-
Prepare seu aplicativo para implantação — Use o CDK CLI para criar seu aplicativo e sintetizar um AWS CloudFormation modelo.
-
Implante seu aplicativo — Use o CDK CLI
cdk deploy
comando para implantar seu aplicativo e provisionar seus AWS recursos. -
Interaja com seu aplicativo — Interaja com sua função AWS Lambda implantada invocando-a e recebendo uma resposta.
-
Modifique seu aplicativo — Modifique sua função Lambda e implante para implementar suas alterações.
-
Exclua seu aplicativo — exclua todos os recursos que você criou usando o CDK CLI
cdk destroy
comando.
Etapa 1: Crie seu CDK projeto
Nesta etapa, você cria um novo CDK projeto. Um CDK projeto deve estar em seu próprio diretório, com suas próprias dependências de módulos locais.
Para criar um CDK projeto
-
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. O CDK CLI usa esse nome de diretório para nomear coisas em seu CDK código. Se você usar um nome de diretório diferente, você terá problemas durante este tutorial. -
No
hello-cdk
diretório, inicialize um novo CDK projeto usando o CDK CLIcdk init
comando. Especifique oapp
modelo e sua linguagem de programação preferida com a--language
opção:
O cdk init
comando cria uma estrutura de arquivos e pastas dentro do hello-cdk
diretório para ajudar a organizar o código-fonte do seu CDK aplicativo. Essa estrutura de arquivos e pastas é chamada de seu CDK projeto. Reserve um momento para explorar seu CDK projeto.
Se você Git instalou, cada projeto que você cria usando também cdk init
é inicializado como um Git repositório.
Durante a inicialização do projeto, CDK CLI ele cria um CDK aplicativo contendo uma única CDK pilha. A instância do CDK aplicativo é criada usando a App
construção. A seguir está uma parte desse código do arquivo do seu CDK aplicativo:
A CDK pilha é criada usando a Stack
construção. Veja a seguir uma parte desse código do seu arquivo de CDK pilha:
Etapa 2: configurar seu AWS ambiente
Nesta etapa, você configura o AWS ambiente para sua CDK pilha. Ao fazer isso, você especifica em qual ambiente sua CDK pilha será implantada.
Primeiro, determine o AWS ambiente que você deseja usar. Um AWS ambiente consiste em um Conta da AWS Região da AWS e.
Ao usar o AWS CLI para configurar as credenciais de segurança em sua máquina local, você pode então usar o AWS CLI para obter informações de AWS ambiente para um perfil específico.
Para usar o AWS CLI para obter seu Conta da AWS ID
-
Execute o AWS CLI comando a seguir para obter o Conta da AWS ID 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
--profile
opção:$
aws sts get-caller-identity --profile
your-profile-name
--query "Account" --output text
Para usar o AWS CLI para obter seu Região da AWS
-
Execute o AWS CLI comando a seguir para obter a região que você configurou para o seu
default
perfil:$
aws configure get region
-
Se você preferir usar um perfil nomeado, forneça o nome do seu perfil usando a
--profile
opção:$
aws configure get region --profile
your-profile-name
Em seguida, você configurará o AWS ambiente da sua CDK pilha 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, consulteConfigure ambientes para usar com o AWS CDK.
Para configurar o ambiente para sua CDK pilha
-
No arquivo do aplicativo, use a
env
propriedade daStack
construção 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 CDK implantações.
Para inicializar seu ambiente, execute o seguinte a partir da raiz do seu CDK projeto:
$
cdk bootstrap
Ao inicializar a partir da raiz do seu CDK projeto, você não precisa fornecer nenhuma informação adicional. CDKCLIObtém informações sobre o ambiente do seu projeto. Ao inicializar fora de um CDK projeto, você deve fornecer informações do ambiente com o cdk bootstrap
comando. Para obter mais informações, consulte Inicialize seu ambiente para uso com o AWS CDK.
Etapa 4: criar seu CDK 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 ele 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 5: liste as CDK pilhas em seu aplicativo
Nesse ponto, você deve ter um CDK aplicativo contendo uma única CDK pilha. Para verificar, use o CDK CLI cdk list
comando para exibir suas pilhas. A saída deve exibir uma única pilha chamadaHelloCdkStack
:
$
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 Etapa 1: Crie seu CDK projeto e tente novamente.
Etapa 6: Definir sua função 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 CDK pilha da seguinte forma:
Vamos dar uma olhada mais de perto na Function
construção. Como todas as construções, a Function
classe usa três parâmetros:
-
escopo — Define sua
Stack
instância como a mãe daFunction
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
Function
dentro do seu AWS CDK aplicativo. 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. 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 éHelloWorldFunction
. As funções também podem ter um nome, especificado com afunctionName
propriedade. Isso é diferente do ID lógico. -
props — Um pacote de valores que define as propriedades da função. Aqui você define
runtime
ascode
propriedadeshandler
, e.Os adereços são representados de forma diferente nos idiomas suportados pelo AWS CDK.
-
In TypeScript andJavaScript,
props
é um único argumento e você passa um objeto contendo as propriedades desejadas. -
EmPython, os adereços são passados como argumentos de palavras-chave.
-
EmJava, um Construtor é fornecido para passar os adereços. Existem dois: um para
FunctionProps
e um segundo para permitir que vocêFunction
construa a construção e seu objeto de adereços em uma única etapa. Esse código usa o último. -
EmC#, 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 os 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 7: Definir sua função Lambda URL
Nesta etapa, você usa o método addFunctionUrl
auxiliar da Function
construção para definir uma função URL Lambda. Para gerar o valor disso URL na implantação, você criará uma AWS CloudFormation saída usando a CfnOutput
construção.
Adicione o seguinte ao seu arquivo CDK de pilha:
Atenção
Para manter esse tutorial simples, sua função Lambda URL é definida 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 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 CDK CLI cdk
synth
comando. Esse comando executa a validação básica do seu CDK código, executa seu CDK aplicativo e gera um CloudFormation modelo da sua CDK pilha.
Se seu aplicativo contiver mais de uma pilha, você deverá especificar quais pilhas sintetizar. Como seu aplicativo contém uma única pilha, ele detecta CDK CLI automaticamente a pilha para sintetizar.
Se você não sintetizar um modelo, o CDK CLI executará automaticamente essa etapa quando você implantar. No entanto, recomendamos que você execute essa etapa antes de cada implantação para verificar se há erros de síntese.
Antes de sintetizar um modelo, você pode, opcionalmente, criar seu aplicativo para capturar erros de sintaxe e de tipo. Para obter instruções, consulte Etapa 4: criar seu CDK aplicativo.
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 hello-cdk
diretório e tente novamente:
--app is required either in command-line, in cdk.json or in ~/.cdk.json
Se for bem-sucedido, o CDK CLI exibirá um CloudFormation modelo YAML formatado em stdout
—e salvará um modelo JSON —formatado no cdk.out
diretório do seu projeto.
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 HelloWorldFunctionunique-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: - HelloWorldFunctionServiceRoleunique-identifier
- Arn Runtime: nodejs20.x DependsOn: - HelloWorldFunctionServiceRoleunique-identifier
Metadata: aws:cdk:path: HelloCdkStack/HelloWorldFunction/Resource HelloWorldFunctionFunctionUrlunique-identifier
: Type: AWS::Lambda::Url Properties: AuthType: NONE TargetFunctionArn: Fn::GetAtt: - HelloWorldFunctionunique-identifier
- Arn Metadata: aws:cdk:path: HelloCdkStack/HelloWorldFunction/FunctionUrl/Resource HelloWorldFunctioninvokefunctionurlunique-identifier
: Type: AWS::Lambda::Permission Properties: Action: lambda:InvokeFunctionUrl FunctionName: Fn::GetAtt: - HelloWorldFunctionunique-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: - HelloWorldFunctionFunctionUrlunique-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 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.
Ao definir uma única construção L2, AWS CDK ele 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 CDK pilha
Nesta etapa, você usa o CDK CLI cdk deploy
comando para implantar sua CDK pilha. 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.
Na raiz do seu projeto, execute o seguinte. Confirme as alterações, se solicitado:
$
cdk deploy
✨ Synthesis time: 2.69s HelloCdkStack: start: Buildingunique-identifier
:current_account-current_region HelloCdkStack: success: Builtunique-identifier
:current_account-current_region HelloCdkStack: start: Publishingunique-identifier
:current_account-current_region HelloCdkStack: success: Publishedunique-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 AWS CDK pilha, pois o aplicativo contém uma única pilha.
Durante a implantaçã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 Lambda para ver seu HelloWorldFunction
recurso.
Quando a implantação for concluída, CDK CLI ele exibirá seu endpointURL. Copie isso 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 da função. URL Quando você acessa oURL, sua função Lambda retorna a Hello World!
mensagem.
Para invocar sua função, acesse a função URL pelo navegador ou pela linha de comando. Veja um exemplo a seguir:
$
curl https://
"Hello World!"%<api-id>
.lambda-url.<Region>
.on.aws/
Etapa 11: Modificar seu aplicativo
Nesta etapa, você modifica a mensagem que a função Lambda retorna quando invocada. Você executa uma comparação usando o CDK CLI cdk diff
comando 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 myFunction
instância no seu arquivo CDK de pilha 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á o CDK CLI 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 cdk diff
comando. 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 HelloWorldFunctionunique-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, ele CDK CLI consulta sua Conta da AWS conta para obter o AWS CloudFormation modelo mais recente da pilha. HelloCdkStack
Em seguida, ele compara o modelo mais recente com o modelo que acabou de sintetizar do seu aplicativo.
Para implementar suas alterações, execute o cdk deploy
comando. Veja um exemplo a seguir:
$
cdk deploy
✨ Synthesis time: 2.12s HelloCdkStack: start: Buildingunique-identifier
:current_account-current_region HelloCdkStack: success: Builtunique-identifier
:current_account-current_region HelloCdkStack: start: Publishingunique-identifier
:current_account-current_region HelloCdkStack: success: Publishedunique-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, repitaEtapa 10: Interaja com seu aplicativo em AWS. Veja um exemplo a seguir:
$
curl https://
"Hello CDK!"%<api-id>
.lambda-url.<Region>
.on.aws/
Etapa 12: excluir seu aplicativo
Nesta etapa, você usa o CDK CLI cdk destroy
comando para excluir seu aplicativo. Esse comando exclui a CloudFormation pilha associada à sua CDK pilha, que inclui os recursos que você criou.
Para excluir seu aplicativo, execute o cdk destroy
comando e confirme sua solicitação para excluir o aplicativo. 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 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, consulteTrabalhe com a AWS CDK biblioteca.
Para obter recursos adicionais, consulte o seguinte:
-
Experimente o CDKWorkshop
para um tour mais aprofundado envolvendo um projeto mais complexo. -
Veja a APIreferência para começar a explorar as CDK construções disponíveis para seus AWS serviços favoritos.
-
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)