Personalização do bootstrapping do AWS CDK - AWS Kit de desenvolvimento em nuvem (AWS CDK) v2
Use a CLI do CDK para personalizar o bootstrappingModificar o modelo de bootstrapping padrãoSiga o contrato de bootstrap

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á.

Personalização do bootstrapping do AWS CDK

É possível personalizar o bootstrapping do kit de desenvolvimento em nuvem da AWS (CDK da AWS) usando a interface de linha de comandos do CDK da AWS (CLI do CDK da AWS) ou modificando e implantando o modelo de bootstrapping do AWS CloudFormation.

Para uma introdução ao bootstrapping, consulte Bootstrapping do CDK da AWS.

Use a CLI do CDK para personalizar o bootstrapping

A seguir estão alguns exemplos de como é possível personalizar o bootstrapping usando a CLI do CDK. Para obter uma lista de todas as opções do cdk bootstrap, consulte cdk bootstrap.

Substituir o nome do bucket do Amazon S

Use a opção --bootstrap-bucket-name para substituir o nome do bucket padrão do Amazon S3. Isso pode exigir que você modifique a síntese do modelo. Para obter mais informações, consulte Personalização da síntese de pilhas do CDK.

Modificar as chaves de criptografia no lado do servidor de bucket do Amazon S

Por padrão, o bucket do Amazon S3 na pilha de bootstrapping é configurado para usar chaves gerenciadas da AWS para criptografia do lado do servidor. Para usar uma chave gerenciada pelo cliente existente, use a opção --bootstrap-kms-key-id e forneça um valor para a chave do AWS Key Management Service (AWS KMS) a usar. Se você quiser mais controle sobre a chave de criptografia, forneça --bootstrap-customer-key para usar uma chave gerenciada pelo cliente.

Anexe políticas gerenciadas ao perfil de implantação assumido pelo AWS CloudFormation

Por padrão, as pilhas são implantadas com permissões totais de administrador usando a política AdministratorAccess. Para usar suas próprias políticas gerenciadas, use a opção --cloudformation-execution-policies e forneça os ARNs das políticas gerenciadas a serem anexadas ao perfil de implantação.

Para fornecer várias políticas, passe a elas uma única string, separada por vírgulas:

$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"

Para evitar falhas na implantação, verifique se as políticas especificadas são suficientes para qualquer implantação que você executará no ambiente que está sendo inicializado.

Alterar o qualificador que é adicionado aos nomes dos recursos em sua pilha de bootstrap

Por padrão, o qualificador hnb659fds é adicionado ao ID físico dos recursos em sua pilha de bootstrap. Para alterar esse valor, use a opção --qualifier.

Essa modificação é útil ao provisionar várias pilhas de bootstrapping no mesmo ambiente para evitar conflitos de nomes.

A alteração do qualificador visa o isolamento de nomes entre testes automatizados do próprio CDK. A menos que você possa definir com precisão as permissões do IAM concedidas ao perfil de execução do CloudFormation, não há benefícios de isolamento de permissão em ter duas pilhas de bootstrapping diferentes em uma única conta. Portanto, geralmente não há necessidade de alterar esse valor.

Quando você altera o qualificador, sua aplicação CDK deve passar o valor alterado para o sintetizador de pilha. Para obter mais informações, consulte Personalização da síntese de pilhas do CDK.

Adicionar tags à pilha de bootstrap

Use a opção --tags no formato de KEY=VALUE para adicionar tags do CloudFormation à sua pilha de bootstrap.

Especifique outras contas da AWS que possam implantar no ambiente que está sofrendo bootstrapping

Use a opção --trust para fornecer outras contas da AWS que têm permissão para implantar no ambiente que está sofrendo bootstrapping. Por padrão, a conta que executa o bootstrapping sempre será confiável.

Essa opção é útil quando você está fazendo bootstrapping em um ambiente no qual um Pipeline do CDK de outro ambiente será implantado.

Ao usar essa opção, você também deve fornecer --cloudformation-execution-policies.

Para adicionar contas confiáveis a uma pilha de bootstrapping existente, é necessário especificar todas as contas confiáveis, incluindo aquelas que podem ter sido fornecidas anteriormente. Se você fornecer apenas novas contas confiáveis, as contas anteriormente confiáveis serão removidas.

Veja a seguir um exemplo que confia em duas contas:

$ cdk bootstrap aws://123456789012/us-west-2 --trust 234567890123 --trust 987654321098 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess
 ⏳  Bootstrapping environment aws://123456789012/us-west-2...
Trusted accounts for deployment: 234567890123, 987654321098
Trusted accounts for lookup: (none)
Execution policies: arn:aws:iam::aws:policy/AdministratorAccess
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://123456789012/us-west-2 bootstrapped.
Especifique outras contas da AWS que possam pesquisar informações no ambiente que está sofrendo bootstrapping

Use a opção --trust-for-lookup para especificar contas da AWS que têm a permissão de pesquisar informações de contexto do ambiente que está sofrendo bootstrapping. Essa opção é útil para dar permissão às contas para sintetizar pilhas que serão implantadas no ambiente, sem realmente dar a elas permissão para implantar essas pilhas diretamente.

Ative a proteção de encerramento para a pilha de bootstrap

Se uma pilha de bootstrapping for excluída, os recursos da AWS que foram originalmente provisionados no ambiente também serão excluídos. Depois que seu ambiente sofreu bootstrapping, recomendamos que você não exclua e recrie a pilha de bootstrapping do ambiente, a menos que esteja fazendo isso intencionalmente. Em vez disso, tente atualizar a pilha de bootstrapping para uma nova versão executando o comando cdk bootstrap novamente.

Use a opção --termination-protection para gerenciar as configurações de proteção contra encerramento da pilha de bootstrap. Ao ativar a proteção contra encerramento na pilha, é possível impedir que uma pilha de bootstrapping e seus recursos sejam excluídos acidentalmente. Isso é especialmente importante se você usa Pipelines do CDK, pois não há opção geral de recuperação se você excluir acidentalmente a pilha de bootstrap.

Depois de ativar a proteção contra encerramento, será possível usar a AWS CLI ou o console do AWS CloudFormation para verificar.

Para habilitar a proteção contra encerramento

  1. Execute o comando a seguir para ativar a proteção contra encerramento em uma pilha de bootstrapping nova ou existente:

    $ cdk bootstrap --termination-protection

  2. Use a AWS CLI ou o console do CloudFormation para verificar. Veja a seguir um exemplo usando a AWS CLI. Se você modificou o nome da pilha de bootstrapping, substitua CDKToolkit pelo nome da pilha:

    $ aws cloudformation describe-stacks --stack-name <CDKToolkit> --query "Stacks[0].EnableTerminationProtection"
true

Modificar o modelo de bootstrapping padrão

Quando você precisar de mais personalização do que a CLI do CDK pode fornecer, é possível modificar o modelo de bootstrapping conforme necessário. Em seguida, implante o modelo para fazer o bootstrapping em seu ambiente.

Para modificar e implantar o modelo de bootstrapping padrão

  1. Obtenha o modelo de bootstrapping padrão usando a opção --show-template. Por padrão, a CLI do CDK exibirá o modelo na janela do terminal. É possível modificar o comando da CLI do CDK para salvar o modelo em sua máquina local. Veja um exemplo a seguir:

    $ cdk bootstrap --show-template > <my-bootstrap-template.yaml>

  2. Modifique o modelo de bootstrapping conforme necessário. Todas as alterações que você fizer devem seguir o modelo de contrato de bootstrap. Para obter mais informações sobre o modelo de contrato de bootstrapping, consulte Siga o contrato de bootstrapping.

    Para garantir que suas personalizações não sejam substituídas por acidente posteriormente por alguém executando o cdk bootstrap usando o modelo padrão, altere o valor padrão do parâmetro do modelo BootstrapVariant. A CLI do CDK só permitirá substituir a pilha de bootstrapping por modelos que tenham a mesma BootstrapVariant e uma versão igual ou superior ao modelo atualmente implantado.

  3. Implante seu modelo modificado usando o método de implantação do AWS CloudFormation de sua preferência. Veja a seguir um exemplo que usa a CLI do CDK:

    $ cdk bootstrap --template <my-bootstrap-template.yaml>

Siga o contrato de bootstrap

Para que suas aplicações do CDK sejam implantadas adequadamente, os modelos do CloudFormation produzidos durante a síntese devem especificar corretamente os recursos criados durante o bootstrapping. Esses recursos são comumente chamados de recursos de bootstrap. O bootstrapping cria recursos em seu ambiente da AWS que são usados pelo AWS CDK para realizar implantações e gerenciar ativos de aplicações. A síntese produz modelos do CloudFormation a partir de cada pilha do CDK em sua aplicação. Esses modelos não definem apenas os recursos da AWS que serão provisionados pela sua aplicação. Eles também especificam os recursos de bootstrapping a serem usados durante a implantação.

Durante a síntese, a CLI do CDK não sabe especificamente como seu ambiente da AWS recebeu o bootstrapping. Em vez disso, a CLI do CDK produz modelos do CloudFormation com base no sintetizador que você configura. Portanto, ao personalizar o bootstrapping, talvez seja necessário personalizar a síntese. Para obter instruções sobre a personalização da síntese, consulte Personalização da síntese de pilha do CDK. O objetivo é garantir que seus modelos sintetizados do CloudFormation sejam compatíveis com seu ambiente que recebeu o bootstrapping. Essa compatibilidade é conhecida como contrato de bootstrap.

O método mais simples para personalizar a síntese de pilhas é modificar a classe DefaultStackSynthesizer na sua instância de Stack. Se você precisar de personalização além do que essa classe pode oferecer, você pode escrever seu próprio sintetizador como uma classe que implementa IStackSynthesizer (talvez derivado de DefaultStackSynthesizer).

Ao personalizar o bootstrapping, siga o contrato modelo de bootstrapping para permanecer compatível com DefaultStackSynthesizer. Se você modificar o bootstrapping além do contrato do modelo de bootstrapping, precisará escrever seu próprio sintetizador.

Versionamento

O modelo de bootstrapping deve conter um recurso para criar um parâmetro do Amazon EC2 Systems Manager (SSM) com um nome conhecido e uma saída que reflita a versão do modelo:

Resources:
  CdkBootstrapVersion:
    Type: AWS::SSM::Parameter
    Properties:
      Type: String
      Name:
        Fn::Sub: '/cdk-bootstrap/${Qualifier}/version'
      Value: 4
Outputs:
  BootstrapVersion:
    Value:
      Fn::GetAtt: [CdkBootstrapVersion, Value]

Perfis

O DefaultStackSynthesizer requer cinco perfis do IAM para cinco propósitos diferentes. Se você não estiver usando os perfis padrão, deverá especificar os ARNs do perfil do IAM em seu objeto DefaultStackSynthesizer. Os perfis são os seguintes:

  • O perfil de implantação é assumido pela CLI do CDK e pelo AWS CodePipeline para implantar em um ambiente. O AssumeRolePolicy controla quem pode ser implantado no ambiente. No modelo, você pode ver as permissões que esse perfil precisa.

  • O perfil de pesquisa é assumido pela CLI do CDK para realizar pesquisas de contexto em um ambiente. O AssumeRolePolicy controla quem pode ser implantado no ambiente. As permissões que esse perfil precisa podem ser vistas no modelo.

  • O perfil de publicação de arquivos e o perfil de publicação de imagens são assumidos pela CLI do CDK e pelos projetos do AWS CodeBuild para publicar de ativos em um ambiente. Eles são usados para gravar no bucket do Amazon S3 e no repositório do Amazon ECR, respectivamente. Esses perfis exigem acesso de gravação a esses recursos.

  • O perfil de execução do AWS CloudFormation é passado ao AWS CloudFormation para realizar a implantação real. Suas permissões são as permissões sob as quais a implantação será executada. As permissões são passadas para a pilha como um parâmetro que lista os ARNs de políticas gerenciadas.

Saídas

A CLI do CDK exige que as saídas do CloudFormation a seguir existam na pilha de bootstrapping:

  • BucketName: o nome do bucket de ativos de arquivo.

  • BucketDomainName: o bucket de ativos de arquivo em formato de nome de domínio.

  • BootstrapVersion: a versão atual da pilha de bootstrap.

Histórico do modelo

O modelo de bootstrapping é versionado e evolui ao longo do tempo com o próprio AWS CDK. 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. Para obter mais informações, consulte Histórico de versões de modelos de bootstrapping.