Como fazer bootstrapping em seu ambiente Quando fazer bootstrapping em seu ambiente Recursos padrão criados durante o bootstrapping Permissões para usar ao fazer bootstrapping em seu ambiente Personalizar o bootstrapping Bootstrapping com CDK Pipelines Histórico de versões do modelo de bootstrap Atualizar do modelo de bootstrapping legado para o moderno Abordar descobertas do Security Hub Considerações

Bootstrapping do seu ambiente para uso com o AWS CDK

Faça o bootstrapping de seu ambiente da AWS para prepará-lo para implantações em pilhas do kit de desenvolvimento em nuvem da AWS (CDK da AWS).

Para obter uma introdução aos ambientes, consulte Ambientes para o CDK da AWS.
Para uma introdução ao bootstrapping, consulte Bootstrapping do CDK da AWS.

Como fazer bootstrapping em seu ambiente

É possível usar a interface de linha de comandos do AWS CDK (CLI do AWS CDK) ou a ferramenta de implantação do AWS CloudFormation de sua preferência para fazer bootstrapping do seu ambiente.

Use a CLI do CDK

É possível usar o comando cdk bootstrap da 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.

Fazer o bootstrapping 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. Veja um exemplo a seguir:


$ cdk bootstrap <aws://123456789012/us-east-1>

dica

Se você não tem o número da sua conta da AWS, é possível obtê-lo no Console de Gerenciamento da AWS. Você também pode usar o comando da AWS CLi a seguir para exibir as informações padrão da sua conta, incluindo o número da sua conta:


$ aws sts get-caller-identity

Se você nomeou perfis em seus arquivos da AWS, config e credentials, use a opção --profile para recuperar as informações da conta de um perfil específico. Veja um exemplo a seguir:


$ 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>

Bootstrapping a partir do diretório principal de um projeto do CDK

É possível executar cdk bootstrap a partir do diretório principal de um projeto do CDK contendo um arquivo cdk.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 arquivos config e credentials ou 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 config e credentials, use a opção --profile:


$ cdk bootstrap --profile <prod>

Para obter mais informações sobre o comando cdk bootstrap e opções com suporte, consulte cdk bootstrap.

Use qualquer ferramenta do AWS CloudFormation

É possível copiar o modelo de bootstrapping do repositório aws-cdk-cli do GitHub ou obter o modelo com o comando cdk bootstrap --show-template. Em seguida, use qualquer ferramenta do AWS CloudFormation para implantar o modelo em seu ambiente.

Com esse método, é possível usar StackSets do AWS CloudFormation ou o AWS Control Tower. Você também pode usar o console do AWS CloudFormation ou a a interface da linha de comandos (AWS CLI) da AWS. É 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-template para recuperar e salvar o modelo de bootstrapping em sua máquina local:

nota

Se os avisos do CDK estiverem aparecendo na saída do modelo do AWS CloudFormation, forneça a opção --no-notices 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 de uso da AWS CLI para implantar o modelo:

Para obter informações sobre como usar os StackSets do CloudFormation para o bootstrapping de vários ambientes, consulte Bootstrapping de várias contas da AWS para o AWS CDK usando StackSets do CloudFormation no blog AWS Cloud Operations & Migrations.

Quando fazer bootstrapping em seu ambiente

É necessário fazer o bootstrapping em cada ambiente da AWS 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)

Atualizar a 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

Perfis do IAM criados durante o bootstrapping

Por padrão, o bootstrapping provisiona os perfis do AWS Identity and Access Management (IAM) a seguir em seu ambiente:

CloudFormationExecutionRole
DeploymentActionRole
FilePublishingRole
ImagePublishingRole
LookupRole

CloudFormationExecutionRole

Esse perfil do IAM é uma perfil de serviço do CloudFormation que concede permissão ao CloudFormation para realizar implantações de pilha em seu nome. Esse perfil dá permissão ao CloudFormation para realizar chamadas de API da AWS em sua conta, incluindo a implantação de pilhas.

Ao usar um perfil de serviço, as permissões provisionadas para o perfil de serviço determinam quais ações podem ser executadas em seus recursos do CloudFormation. Sem esse perfil de serviço, as credenciais de segurança que você fornece com a CLI do CDK determinariam o que o CloudFormation tem permissão para 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 um perfil para implantações, você pode realizar implantações em várias contas, pois o perfil pode ser assumido por identidades da AWS 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

Esse perfil do IAM concede permissão readOnly para pesquisar valores de contexto do ambiente da AWS. É assumido pela CLI do CDK ao executar tarefas como síntese e implantações de modelos.

IDs de recursos criados durante o bootstrapping

Quando você implanta o modelo de bootstrapping padrão, IDs físicos para recursos de bootstrapping 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: o ID da conta da AWS do ambiente.
Região: a região da AWS do 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 fazer bootstrapping em um ambiente da AWS, a identidade do IAM que executa o bootstrapping 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.

Para obter mais informações sobre como personalizar o bootstrapping, consulte Personalização do bootstrapping do AWS CDK.

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 bootstrapping for excluída, os recursos da AWS que foram originalmente provisionados no ambiente para oferecer suporte a implantações do 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 bootstrap novamente.

Para se proteger contra a exclusão acidental de sua pilha de bootstrapping, recomendamos que você forneça a opção --termination-protection com o comando cdk bootstrap para 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 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.

nota

As versões anteriores do modelo de bootstrapping criavam uma chave do AWS KMS em cada ambiente que recebia o bootstrapping 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	Versão do AWS 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 `FileAssetKeyArn` para poder adicionar permissões de descriptografia aos consumidores de ativos.
4	1.61.0	As permissões do AWS KMS agora estão implícitas via Amazon S3 e não exigem mais o `FileAssetKeyArn`. Adicione o parâmetro `CdkBootstrapVersion` do SSM para que a versão da pilha de bootstrapping possa ser verificada sem saber o nome da pilha.
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 `aws-cdk:bootstrap-role` aos perfis de implantação, publicação de arquivos e publicação de imagens.
7	1.110.0	O perfil de implantação não pode mais ler buckets diretamente na conta de destino. (Entretanto, esse perfil é efetivamente de administrador e, de qualquer forma, sempre pode usar suas permissões do AWS CloudFormation para tornar o bucket legível).
8	1.114.0	O perfil de pesquisa tem permissões somente leitura completas para o ambiente de destino e também tem uma tag `aws-cdk:bootstrap-role`.
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 ScanOnPush do Amazon ECR agora 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 experimentais `cdk import`.
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 propriedade AccessControl foi removida do modelo. (#27.964)
20	2.119.0	Adição da ação `ssm:GetParameters` ao perfil do IAM de implantação do AWS CloudFormation. Para obter mais informações, consulte a #28336.
21	2.149.0	Adicione uma condição ao perfil de publicação de arquivos.
22	2.160.0	Adicione permissões `sts:TagSession` à política de confiança dos perfis do IAM de bootstrap.
23	2.161.0	Adicione as permissões `cloudformation:RollbackStack` e `cloudformation:ContinueUpdateRollback` à política de confiança do perfil do IAM de implantação. Isso fornece permissões para o comando `cdk rollback`.
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 `cdk gc` introduz a capacidade de excluir objetos no bucket de bootstrapping, esse novo comportamento garante que os objetos excluídos permaneçam no bucket de bootstrapping por 30 dias em vez de 365 dias. Para obter mais informações sobre essa alteração, consulte `aws-cdk` PR #31949
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 `aws-cdk` PR #31956
26	2.1002.0	Adição de duas políticas relacionadas à exclusão (`UpdateReplacePolicy` e `DeletionPolicy`) ao recurso `FileAssetsBucketEncryptionKey`. Essas políticas garantem que o recurso antigo da chave do AWS KMS seja excluído adequadamente quando a pilha de bootstrapping for atualizada ou excluída. Para obter mais informações sobre essa alteração, consulte `aws-cdk-cli` PR #100
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 `aws-cdk-cli` PR #112

Atualizar do modelo de bootstrapping legado para o moderno

O AWS CDK v1 oferecia suporte a dois modelos de bootstrapping, legado e moderno. 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.

Recurso	Legado (somente v1)	Moderno (v1 e v2)
Implantação entre contas	Não permitido	Permitido
Permissões do AWS CloudFormation	Implanta usando as permissões atuais do usuário (determinadas pelo perfil da AWS, variáveis de ambiente etc.)	Implanta usando as permissões especificadas quando a pilha de bootstrapping foi provisionada (por exemplo, usando `--trust`)
Versionamento	Apenas uma versão da pilha de bootstrapping está disponível	A pilha de bootstrapping tem versão; novos recursos podem ser adicionados em versões futuras e as aplicações do AWS CDK podem exigir uma versão mínima
Recursos*	Bucket do Amazon S3	Bucket do Amazon S3 Chave do AWS KMS Perfis do IAM Repositório do Amazon ECR Parâmetro SSM para versionamento
AWS Chave do KMS	Perfis do IAM	Repositório do Amazon ECR
Nomenclatura de recursos	Gerado automaticamente	Deterministic
Criptografia do bucket	Chave padrão	Chave gerenciada pela AWS por padrão. É possível personalizar o uso de uma chave gerenciada pelo cliente.

Adicionaremos recursos extras ao modelo de bootstrapping 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 as aplicações do AWS CDK no ambiente pelo menos uma vez antes de excluir o bucket legado.

Abordar descobertas do Security Hub

Se você estiver usando o AWS Security Hub, poderá ver descobertas relatadas sobre alguns dos recursos criados pelo processo de bootstrapping 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.

[KMS.2] As entidades principais do IAM não devem ter políticas incorporadas do IAM que permitam ações de descriptografia em todas as chaves do KMS

O perfil de implantação (DeploymentActionRole) concede permissão para ler dados criptografados, o que é necessário para implantações entre contas com o CDK Pipelines. As políticas nesse perfil não concedem permissão a todos os dados. Elas só concedem permissão para ler dados criptografados do Amazon S3 e no AWS KMS somente quando esses recursos permitem isso por meio de seu bucket ou política de chaves.

Veja a seguir um trecho dessas duas declarações no perfil de implantação do modelo de bootstrap:


DeploymentActionRole:
    Type: AWS::IAM::Role
    Properties:
      ...
      Policies:
        - PolicyDocument:
            Statement:
              ...
              - Sid: PipelineCrossAccountArtifactsBucket
                Effect: Allow
                Action:
                  - s3:GetObject*
                  - s3:GetBucket*
                  - s3:List*
                  - s3:Abort*
                  - s3:DeleteObject*
                  - s3:PutObject*
                Resource: "*"
                Condition:
                  StringNotEquals:
                    s3:ResourceAccount:
                      Ref: AWS::AccountId
              - Sid: PipelineCrossAccountArtifactsKey
                Effect: Allow
                Action:
                  - kms:Decrypt
                  - kms:DescribeKey
                  - kms:Encrypt
                  - kms:ReEncrypt*
                  - kms:GenerateDataKey*
                Resource: "*"
                Condition:
                  StringEquals:
                    kms:ViaService:
                      Fn::Sub: s3.${AWS::Region}.amazonaws.com
              ...

Por que o Security Hub sinaliza isso?

As políticas contêm uma cláusula Resource: * combinada com uma Condition. O Security Hub sinaliza o curinga *. Esse curinga é usado porque, no momento em que a conta recebe o bootstrapping, a chave do AWS KMS criada pelo CDK Pipelines para o bucket de artefatos do CodePipeline ainda não existe e, portanto, não pode ser referenciada no modelo de bootstrapping pelo ARN. Além disso, o Security Hub não considera a cláusula Condition ao levantar essa bandeira. Esse Condition restringe o Resource: * às solicitações feitas com a mesma conta da AWS da chave do AWS KMS. Essas solicitações devem vir do Amazon S3 da mesma região AWS que a chave do AWS KMS.

Preciso corrigir essa descoberta?

Desde que você não tenha modificado a chave do AWS KMS em seu modelo de bootstrapping para ser excessivamente permissiva, o perfil de implantação não permitirá mais acesso do que o necessário. Portanto, não é necessário corrigir essa descoberta.

E se eu quiser corrigir essa descoberta?

A forma como você corrige essa descoberta depende se você usará ou não o CDK Pipelines para implantações entre contas.

Para corrigir a descoberta do Security Hub e usar o CDK Pipelines para implantações entre contas

Se ainda não o tiver feito isso, implante a pilha de bootstrapping do CDK usando o comando cdk bootstrap.
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 CDK Pipelines.
Obtenha o ARN da chave do AWS KMS do bucket de artefatos do 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:
```
$ cdk bootstrap --show-template > bootstrap-template.yaml
```
Modifique o modelo substituindo o Resource: * da declaração PipelineCrossAccountArtifactsKey pelo valor do ARN.
Implante o modelo para atualizar sua pilha de bootstrap. Veja a seguir um exemplo, usando a CLI do CDK:
```
$ cdk bootstrap aws://<account-id>/<region> --template bootstrap-template.yaml
```

Para corrigir a descoberta do Security Hub se você não está usando o CDK Pipelines para implantações entre contas

Obtenha uma cópia do modelo de bootstrapping do CDK para modificá-lo. Veja a seguir um exemplo, usando a CLI do CDK:
```
$ cdk bootstrap --show-template > bootstrap-template.yaml
```
Exclua as instruções PipelineCrossAccountArtifactsBucket e PipelineCrossAccountArtifactsKey do modelo.
Implante o modelo para atualizar sua pilha de bootstrap. Veja a seguir um exemplo, usando a CLI do CDK:
```
$ cdk bootstrap aws://<account-id>/<region> --template bootstrap-template.yaml
```

Considerações

Como o bootstrapping provisiona recursos em seu ambiente, é possível incorrer em cobranças da AWS quando esses recursos são usados com o AWS CDK.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Configuração da telemetria da CLI do CDK

Personalizar o bootstrapping