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á.
Inicialize seu ambiente para uso com o CDK AWS
Inicialize seu AWS ambiente para prepará-lo para implantações de pilhas do AWS Cloud Development Kit (AWS CDK).
-
Para uma introdução aos ambientes, consulte Ambientes para o AWS CDK.
-
Para uma introdução ao bootstrapping, consulte Bootstrapping do AWS CDK.
Como fazer bootstrapping em seu ambiente
Você pode usar a AWS CDK Command Line Interface (AWS CDK CLI) ou sua ferramenta de AWS CloudFormation implantação preferida para inicializar seu ambiente.
- Use a CLI do CDK
-
É possível usar o comando
cdk bootstrapda CLI do CDK para fazer o bootstrapping em seu ambiente. Esse é o método que recomendamos se você não precisar de modificações significativas no bootstrapping.- Inicialize a partir de qualquer diretório de trabalho
-
Para fazer o bootstrapping a partir de qualquer diretório de trabalho, forneça o ambiente no qual fazer o bootstrapping como um argumento de linha de comandos. Este é um exemplo:
$ cdk bootstrap <aws://123456789012/us-east-1>dica
Se você não tiver o número AWS da sua conta, poderá obtê-lo no AWS Management Console. Você também pode usar o seguinte comando da AWS CLI para exibir as informações padrão da sua conta, incluindo o número da sua conta:
$ aws sts get-caller-identitySe você nomeou perfis em seus
credentialsarquivos AWSconfige, use a--profileopção para recuperar as informações da conta de um perfil específico. Este é um exemplo:$ aws sts get-caller-identity --profile <prod>Para exibir a região padrão, use o comando
aws configure get:$ aws configure get region $ aws configure get region --profile <prod>Ao fornecer um argumento, o prefixo
aws://é opcional. Veja o que é válido a seguir:$ cdk bootstrap <123456789012/us-east-1>Para fazer o bootstrapping em vários ambientes ao mesmo tempo, forneça vários argumentos:
$ cdk bootstrap <aws://123456789012/us-east-1> <aws://123456789012/us-east-2> - Bootstrap a partir do diretório principal de um projeto CDK
-
É possível executar
cdk bootstrapa partir do diretório principal de um projeto do CDK contendo um arquivocdk.json. Se você não fornecer um ambiente como argumento, a CLI do CDK obterá informações do ambiente de fontes padrão, como seus arquivosconfigecredentialsou qualquer informação de ambiente especificada para sua pilha do CDK.Quando você inicializa a partir do diretório principal de um projeto do CDK, os ambientes fornecidos a partir de argumentos de linha de comandos têm precedência sobre outras fontes.
Para fazer o bootstrapping em um ambiente especificado em seus arquivos
configecredentials, use a opção--profile:$ cdk bootstrap --profile <prod>Para obter mais informações sobre o comando
cdk bootstrape opções com suporte, consulte cdk bootstrap.
- Use qualquer AWS CloudFormation ferramenta
-
Você pode copiar o modelo de bootstrap
do aws-cdk-cli GitHub repositório ou obter o modelo com o cdk bootstrap --show-templatecomando. Em seguida, use qualquer AWS CloudFormation ferramenta para implantar o modelo em seu ambiente.Com esse método, você pode usar AWS CloudFormation StackSets nosso AWS Control Tower. Você também pode usar o AWS CloudFormation console ou a Interface de Linha de AWS Comando (AWS CLI). É possível fazer modificações no seu modelo antes de implantá-lo. Esse método pode ser mais flexível e adequado para implantações em grande escala.
Veja a seguir um exemplo de como usar a opção
--show-templatepara recuperar e salvar o modelo de bootstrapping em sua máquina local:exemplo
nota
Se os avisos do CDK estiverem aparecendo na saída AWS CloudFormation do modelo, forneça a
--no-noticesopção com seu comando.Para implantar esse modelo usando a CLI do CDK, é possível executar o seguinte:
$ cdk bootstrap --template <bootstrap-template.yaml>Veja a seguir um exemplo do uso da AWS CLI para implantar o modelo:
exemplo
Para obter informações sobre como usar CloudFormation StackSets para inicializar vários ambientes, consulte Como inicializar várias AWS contas para AWS CDK usando CloudFormation StackSets
no blog AWS Cloud Operations & Migrations.
Quando fazer bootstrapping em seu ambiente
Você deve inicializar cada AWS ambiente antes de implantá-lo no ambiente. Recomendamos que você fazer o bootstrapping proativamente em cada ambiente que planeja usar. É possível fazer isso antes de planejar realmente implantar aplicações do CDK no ambiente. Ao fazer o bootstrapping proativamente em seus ambientes, você evita possíveis problemas futuros, como conflitos de nomes de buckets do Amazon S3 ou implantação de aplicações do CDK em ambientes que não receberam o bootstrapping.
Não há problema em fazer o bootstrapping em um ambiente mais de uma vez. Se um ambiente já tiver recebido o bootstrapping, a pilha de bootstrapping será atualizada, se necessário. Caso contrário, nada acontecerá.
Se você tentar implantar uma pilha do CDK em um ambiente em que não foi feito o bootstrapping, você verá um erro como o seguinte:
$ cdk deploy ✨ Synthesis time: 2.02s ❌ Deployment failed: Error: BootstrapExampleStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
- Atualize sua pilha de bootstrap
-
Periodicamente, a equipe do CDK atualizará o modelo de bootstrapping para uma nova versão. Quando isso acontece, recomendamos que você atualize a pilha de bootstrap. Se você não personalizou o processo de bootstrapping, é possível atualizar sua pilha de bootstrapping seguindo as mesmas etapas que você seguiu para fazer o bootstrapping originalmente em seu ambiente. Para obter mais informações, consulte Histórico de versões de modelos de bootstrapping.
Recursos padrão criados durante o bootstrapping
- Funções do IAM criadas durante a inicialização
-
Por padrão, a inicialização provisiona as seguintes funções de AWS Identity and Access Management (IAM) em seu ambiente:
-
CloudFormationExecutionRole -
DeploymentActionRole -
FilePublishingRole -
ImagePublishingRole -
LookupRole
-
CloudFormationExecutionRole -
Essa função do IAM é uma função CloudFormation de serviço que concede CloudFormation permissão para realizar implantações de pilha em seu nome. Essa função dá CloudFormation permissão para realizar chamadas de AWS API em sua conta, incluindo a implantação de pilhas.
Ao usar uma função de serviço, as permissões provisionadas para a função de serviço determinam quais ações podem ser executadas em seus CloudFormation recursos. Sem essa função de serviço, as credenciais de segurança que você fornece com a CLI do CDK determinariam o que CloudFormation é permitido fazer.
-
DeploymentActionRole -
Esse perfil do IAM concede permissões para realizar implantações em seu ambiente. É assumido pela CLI do CDK durante as implantações.
Ao usar uma função para implantações, você pode realizar implantações em várias contas, pois a função pode ser assumida por AWS identidades em uma conta diferente.
-
FilePublishingRole -
Esse perfil do IAM concede permissões para a execução de ações no bucket de bootstrapping do Amazon Simple Storage Service (Amazon S3), incluindo o carregamento e a exclusão de ativos. É assumido pela CLI do CDK durante as implantações.
-
ImagePublishingRole -
Esse perfil do IAM concede permissões para a execução de ações no repositório de bootstrapping do Amazon Elastic Container Registry (Amazon ECR). É assumido pela CLI do CDK durante as implantações.
-
LookupRole -
Essa função do IAM concede
readOnlypermissão para pesquisar valores de contexto do AWS ambiente. É assumido pela CLI do CDK ao executar tarefas como síntese e implantações de modelos.
-
- Recurso IDs criado durante a inicialização
-
Quando você implanta o modelo de bootstrap padrão, recursos físicos IDs para bootstrap são criados usando a seguinte estrutura:.
cdk-<qualifier>-<description>-<account-ID>-<Region>-
Qualificador: um valor de string exclusivo de nove caracteres de
hnb659fds. O valor real não tem significado. -
Descrição: uma descrição breve do recurso. Por exemplo, .
container-assets -
ID da conta — A ID da AWS conta do ambiente.
-
Região — A AWS região do meio ambiente.
A seguir está um exemplo de ID físico do bucket de armazenamento do Amazon S3 criado durante a o bootstrapping:
cdk-hnb659fds-assets-012345678910-us-west-1. -
Permissões para usar ao fazer bootstrapping em seu ambiente
Ao inicializar um AWS ambiente, a identidade do IAM que executa a inicialização deve ter pelo menos as seguintes permissões:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:*", "ecr:*", "ssm:*", "s3:*", "iam:*" ], "Resource": "*" } ] }
Com o tempo, a pilha de bootstrapping, incluindo os recursos criados e as permissões que eles exigem, pode mudar. Com futuras alterações, talvez seja necessário modificar as permissões necessárias para fazer bootstrapping em um ambiente.
Personalizar o bootstrapping
Se o modelo de bootstrapping padrão não atender às suas necessidades, é possível personalizar a o bootstrapping de recursos em seu ambiente das seguintes maneiras:
-
Use as opções da linha de comandos com o comando
cdk bootstrap: esse método é melhor para fazer alterações pequenas e específicas que são compatíveis com as opções da linha de comandos. -
Modifique o modelo de bootstrapping padrão e implante-o: esse método é melhor para fazer alterações complexas ou se você quiser controle total sobre a configuração dos recursos provisionados durante o bootstrapping.
Bootstrapping com CDK Pipelines
Se você estiver usando o CDK Pipelines para implantar no ambiente de outra conta e receber uma mensagem como a seguinte:
Policy contains a statement with one or more invalid principals
Essa mensagem de erro significa que os perfis do IAM apropriados não existem no outro ambiente. A causa mais provável é que o ambiente não tenha recebido o bootstrapping. Faça o bootstrapping no ambiente e tente novamente.
- Proteger sua pilha de bootstrapping contra exclusão
-
Se uma pilha de bootstrap for excluída, os AWS recursos que foram originalmente provisionados no ambiente para suportar implantações de CDK também serão excluídos. Isso fará com que o pipeline pare de funcionar. Se isso acontecer, não há solução geral para recuperação.
Depois que seu ambiente receber o bootstrapping, não exclua e recrie a pilha de bootstrapping do ambiente. Em vez disso, tente atualizar a pilha de bootstrapping para uma nova versão executando o comando
cdk bootstrapnovamente.Para se proteger contra a exclusão acidental de sua pilha de bootstrapping, recomendamos que você forneça a opção
--termination-protectioncom o comandocdk bootstrappara ativar a proteção contra encerramento. É possível ativar a proteção contra encerramento em pilhas de bootstrapping novas ou existentes. Para instruções sobre como ativar a proteção contra encerramento, consulte Habilitar proteção contra encerramento para a pilha de bootstrap.
Histórico de versões do modelo de bootstrap
O modelo de bootstrap é versionado e evolui com o tempo com o próprio CDK. AWS Se você fornecer seu próprio modelo de bootstrapping, mantenha-o atualizado com o modelo padrão canônico. Você quer garantir que seu modelo continue funcionando com todos os atributos do CDK.
nota
As versões anteriores do modelo de bootstrap criavam uma chave AWS KMS em cada ambiente inicializado por padrão. Para evitar cobranças pela chave do KMS, faça o bootstrapping nesses ambientes novamente usando o --no-bootstrap-customer-key. O padrão atual é a ausência de chave do KMS, o que ajuda a evitar essas cobranças.
Esta seção contém uma lista das alterações feitas em cada versão.
| Versão do modelo | AWS Versão CDK | Alterações |
|---|---|---|
|
1 |
1.40.0 |
Versão inicial do modelo com bucket, chave, repositório e perfis. |
|
2 |
1.45,0 |
Divida o perfil de publicação de ativos em perfis separados de publicação de arquivos e imagens. |
|
3 |
1.46.0 |
Adicione a exportação |
|
4 |
1.61.0 |
AWS As permissões do KMS agora estão implícitas via Amazon S3 e não são mais necessárias. |
|
5 |
1.87.0 |
O perfil de implantação pode ler o parâmetro do SSM. |
|
6 |
1.108.0 |
Adicione um perfil de pesquisa separado do perfil de implantação. |
|
6 |
1.109.0 |
Anexe a tag |
|
7 |
1.10.0 |
O perfil de implantação não pode mais ler buckets diretamente na conta de destino. (No entanto, essa função é efetivamente de administrador e, de qualquer forma, sempre pode usar suas AWS CloudFormation permissões para tornar o bucket legível). |
|
8 |
1.14.0 |
O perfil de pesquisa tem permissões somente leitura completas para o ambiente de destino e também tem uma tag |
|
9 |
2.1.0 |
Impede que os carregamentos de ativos do Amazon S3 sejam rejeitados pela criptografia SCP comumente referenciada. |
|
10 |
2.4.0 |
O Amazon ECR agora ScanOnPush está habilitado por padrão. |
|
11 |
2.18.0 |
Adiciona uma política que permite que o Lambda extraia dos repositórios do Amazon ECR para que ele sobreviva à nova realização do bootstrapping. |
|
12 |
2.20.0 |
Adiciona suporte para |
|
13 |
2.25.0 |
Torna imutáveis as imagens de contêiner nos repositórios do Amazon ECR criados pelo bootstrap. |
|
14 |
2.34.0 |
Por padrão, desativa a verificação de imagens do Amazon ECR no nível do repositório para permitir o bootstrapping de regiões que não oferecem suporte à verificação de imagens. |
|
15 |
2.60,0 |
As chaves do KMS não podem ser marcadas com tags. |
|
16 |
2.69,0 |
Aborda a descoberta KMS.2 do Security Hub. |
|
17 |
2.72.0 |
Aborda a descoberta ECR.3 do Security Hub. |
|
18 |
2.80,0 |
Alterações revertidas feitas para a versão 16, pois elas não funcionam em todas as partições e não são recomendadas. |
|
19 |
2.106.1 |
Alterações revertidas feitas na versão 18, em que a AccessControl propriedade foi removida do modelo. (#27.964 |
|
20 |
2.119.0 |
Adicione |
|
21 |
2.149.0 |
Adicione uma condição ao perfil de publicação de arquivos. |
|
22 |
2.160,0 |
Adicione permissões |
|
23 |
2.161,0 |
Adicione as permissões |
|
24 |
2.165.0 |
Alteração da duração dos dias em que os objetos não atuais no bucket de bootstrapping serão retidos, de 365 para 30 dias. Como o novo comando |
|
25 |
2.165.0 |
Adição de suporte ao bucket de bootstrapping para a remoção de uploads incompletos de várias partes. Os uploads incompletos de várias partes serão excluídos após 1 dia. Para obter mais informações sobre essa alteração, consulte |
|
26 |
2.1002.0 |
Adição de duas políticas relacionadas à exclusão ( |
|
27 |
2.1003.0 |
Adição de uma nova política de recursos do Amazon EMR para conceder ao Amazon EMR Sem Servidor permissões específicas para a recuperação de imagens de contêineres. Para obter mais informações sobre essa alteração, consulte |
|
28 |
2.1015.0 |
Adicione permissões para realizar ações do Stack Refactoring à função de implantação e TagSession permissões a todas as funções. Para obter mais informações sobre essa mudança, consulte |
|
29 |
2.1026.0 |
Todas as AssumeRole chamadas que fornecem um ExternalId serão rejeitadas por padrão, a menos que sejam desativadas. Para obter mais informações sobre essa mudança, consulte |
|
30 |
2.1034,0 |
Adicione permissões para descrever eventos de pilha à função de implantação para poder mostrar erros de validação CloudFormation antecipada com precisão. Para obter mais informações sobre essa mudança, consulte [#bootstrapping -template] == Atualização do modelo de bootstrap legado para o moderno O AWS CDK v1 suportava dois modelos de bootstrap, antigos e modernos. O CDK v2 oferece suporte somente ao modelo moderno. Para referência, aqui estão as diferenças de alto nível entre esses dois modelos. [cols="1h,1,1", options="cabeçalho "] |
| Funcionalidade | Legado (somente v1) | Moderno (v1 e v2)
|Implantações entre contas |Não permitidas |Permitidas
|AWS CloudFormation Permissões |Implanta usando as permissões atuais do usuário (determinadas pelo AWS perfil, variáveis de ambiente etc.) |Implanta usando as permissões especificadas quando a pilha de bootstrap foi provisionada (por exemplo, usando) --trust
|Versionamento |Somente uma versão da pilha de bootstrap está disponível |A pilha de bootstrap tem versão; novos recursos podem ser adicionados em versões futuras e aplicativos CDK podem exigir uma versão mínima AWS
|Recursos* |Amazon S3 bucket a|
-
Bucket do Amazon S3.
-
AWS Chave KMS
-
Perfis do IAM
-
Repositório do Amazon ECR
-
Parâmetro SSM para versionamento
|AWS Chave KMS | Funções do IAM | Repositório Amazon ECR
|Nomeação de recursos |Gerado automaticamente |Determinístico
|Criptografia de bucket |Chave padrão | chave AWS gerenciada por padrão. Você pode personalizar o uso de uma chave gerenciada pelo cliente.
|
* Adicionaremos recursos extras ao modelo de bootstrap conforme necessário. Um ambiente em que foi feito o bootstrapping usando o modelo legado deve ser atualizado para usar o modelo moderno do CDK v2 por meio de um novo bootstrapping. Reimplante todos os aplicativos AWS CDK no ambiente pelo menos uma vez antes de excluir o bucket legado. [#bootstrapping -securityhub] == Endereçar as descobertas do Security Hub Se você estiver usando o AWS Security Hub, poderá ver descobertas relatadas sobre alguns dos recursos criados pelo processo de inicialização do AWS CDK. As descobertas do Security Hub ajudam você a encontrar configurações de recursos que você deve verificar novamente quanto à precisão e segurança. Analisamos essas configurações específicas de recursos com a AWS Security e temos certeza de que elas não constituem um problema de segurança. [# bootstrapping-securityhub-kms 2] [KMS.2] Os diretores do IAM não devem ter políticas embutidas do IAM que permitam ações de descriptografia em todas as chaves do KMS:: + A função deploy ( cdk bootstrap comando. Se ainda não o tiver feito isso, crie e implante o Pipeline do CDK. Para obter instruções, consulte Integração e entrega contínuas (CI/CD) usando o CDK Pipelines. Obtenha o ARN da chave AWS KMS do bucket de artefatos CodePipeline . Esse recurso é criado durante a criação do pipeline. Obtenha uma cópia do modelo de bootstrapping do CDK para modificá-lo. Veja a seguir um exemplo, usando a CLI do AWS CDK: + [source, bash, subs="verbatim, attributes "] ---- $ cdk bootstrap --show-template bootstrap-template.yaml ----. Modifique o modelo Resource:
substituindo a PipelineCrossAccountArtifactsKey declaração pelo valor do ARN. Implante o modelo para atualizar sua pilha de bootstrap. Veja a seguir um exemplo, usando a CLI do CDK: + [source, bash, subs="verbatim, attributes "] ---- $ cdk bootstrap aws: //account-id/region --template bootstrap-template.yaml ---- + |
