Personnaliser le AWS CDK bootstrap - AWS Cloud Development Kit (AWS CDK) v2
Utilisez le CDK CLI pour personnaliser le bootstrapModifier le modèle de bootstrap par défautLe contrat Bootstrap

Ceci est le guide du AWS CDK développeur de la version 2. L'ancienne CDK version 1 est entrée en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Personnaliser le AWS CDK bootstrap

Vous pouvez personnaliser le AWS Cloud Development Kit (AWS CDK) bootstrap à l'aide de l'interface de ligne de AWS CDK commande (AWS CDK CLI) ou en modifiant et en déployant le modèle de AWS CloudFormation bootstrap.

Pour une introduction au bootstrap, voir. AWS CDK bootstrap

Utilisez le CDK CLI pour personnaliser le bootstrap

Voici quelques exemples de la façon dont vous pouvez personnaliser le bootstrap à l'aide du. CDK CLI Pour obtenir la liste de toutes les options cdk bootstrap, consultez cdk bootstrap.

Remplacer le nom du compartiment Amazon S3

Utilisez --bootstrap-bucket-name cette option pour remplacer le nom du compartiment Amazon S3 par défaut. Cela peut nécessiter que vous modifiiez la synthèse du modèle. Pour de plus amples informations, veuillez consulter Personnalisez la synthèse des CDK piles.

Modifier les clés de chiffrement côté serveur pour le compartiment Amazon S3

Par défaut, le compartiment Amazon S3 de la pile bootstrap est configuré pour utiliser des clés AWS gérées pour le chiffrement côté serveur. Pour utiliser une clé gérée par le client existante, utilisez l'--bootstrap-kms-key-idoption et fournissez une valeur pour la clé AWS Key Management Service (AWS KMS) à utiliser. Si vous souhaitez mieux contrôler la clé de chiffrement, proposez --bootstrap-customer-key d'utiliser une clé gérée par le client.

Associez des politiques gérées au rôle de déploiement assumé par AWS CloudFormation

Par défaut, les piles sont déployées avec des autorisations d'administrateur complètes conformément à la AdministratorAccess politique. Pour utiliser vos propres politiques gérées, utilisez l'--cloudformation-execution-policiesoption et fournissez ARNs les politiques gérées à associer au rôle de déploiement.

Pour fournir plusieurs politiques, transmettez-leur une seule chaîne, séparée par des virgules :

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

Pour éviter les échecs de déploiement, assurez-vous que les politiques que vous spécifiez sont suffisantes pour tous les déploiements que vous allez effectuer dans l'environnement en cours de démarrage.

Modifiez le qualificatif ajouté aux noms des ressources de votre pile bootstrap

Par défaut, le hnb659fds qualificatif est ajouté à l'identifiant physique des ressources de votre pile bootstrap. Pour modifier cette valeur, utilisez l'--qualifieroption.

Cette modification est utile lors du provisionnement de plusieurs piles de bootstrap dans le même environnement afin d'éviter les conflits de noms.

La modification du qualificatif est destinée à isoler le nom entre les tests automatisés sur CDK lui-même. À moins que vous ne puissiez définir très précisément les IAM autorisations accordées au rôle CloudFormation d'exécution, le fait d'avoir deux piles de bootstrap différentes dans un seul compte ne présente aucun avantage en termes d'isolation des autorisations. Il n'est donc généralement pas nécessaire de modifier cette valeur.

Lorsque vous modifiez le qualificatif, votre CDK application doit transmettre la valeur modifiée au synthétiseur de pile. Pour de plus amples informations, veuillez consulter Personnalisez la synthèse des CDK piles.

Ajouter des balises à la pile bootstrap

Utilisez l'--tagsoption au format de KEY=VALUE pour ajouter des CloudFormation balises à votre stack bootstrap.

Spécifiez Comptes AWS les éléments supplémentaires qui peuvent être déployés dans l'environnement en cours de démarrage

Utilisez --trust cette option pour fournir des informations supplémentaires Comptes AWS autorisées à être déployées dans l'environnement en cours de démarrage. Par défaut, le compte effectuant le bootstrap sera toujours fiable.

Cette option est utile lorsque vous amorcez un environnement dans lequel un CDK Pipeline autre environnement sera déployé.

Lorsque vous utilisez cette option, vous devez également fournir--cloudformation-execution-policies.

Pour ajouter des comptes fiables à une pile bootstrap existante, vous devez spécifier tous les comptes auxquels faire confiance, y compris ceux que vous avez fournis précédemment. Si vous ne fournissez que de nouveaux comptes auxquels faire confiance, les comptes précédemment approuvés seront supprimés.

Voici un exemple qui fait confiance à deux comptes :

$ 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.
Spécifiez des informations supplémentaires Comptes AWS pouvant rechercher des informations dans l'environnement en cours d'amorçage

Utilisez Comptes AWS cette --trust-for-lookup option pour spécifier les personnes autorisées à rechercher des informations contextuelles à partir de l'environnement en cours d'amorçage. Cette option est utile pour autoriser les comptes à synthétiser les piles qui seront déployées dans l'environnement, sans pour autant leur donner l'autorisation de déployer ces piles directement.

Activer la protection de terminaison pour la pile bootstrap

Si une pile bootstrap est supprimée, les AWS ressources initialement provisionnées dans l'environnement seront également supprimées. Une fois votre environnement amorcé, nous vous recommandons de ne pas supprimer ni recréer la pile d'amorçage de l'environnement, sauf si vous le faites intentionnellement. Essayez plutôt de mettre à jour la pile bootstrap vers une nouvelle version en exécutant à nouveau la cdk bootstrap commande.

Utilisez --termination-protection cette option pour gérer les paramètres de protection contre la résiliation pour la pile bootstrap. En activant la protection contre la résiliation, vous empêchez la suppression accidentelle de la pile bootstrap et de ses ressources. Ceci est particulièrement important si vous l'utilisez, CDK Pipelines car il n'existe aucune option de restauration générale si vous supprimez accidentellement la pile bootstrap.

Après avoir activé la protection contre la résiliation, vous pouvez utiliser la AWS CloudFormation console AWS CLI or pour vérifier.

Pour activer la protection contre le licenciement

  1. Exécutez la commande suivante pour activer la protection contre la résiliation sur une pile bootstrap nouvelle ou existante :

    $ cdk bootstrap --termination-protection

  2. Utilisez la CloudFormation console AWS CLI or pour vérifier. Voici un exemple avec utilisation de l' AWS CLI. Si vous avez modifié le nom de votre pile bootstrap, remplacez-le CDKToolkit par le nom de votre pile :

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

Modifier le modèle de bootstrap par défaut

Lorsque vous avez besoin de plus de personnalisation que ce que vous CDK CLI pouvez fournir, vous pouvez modifier le modèle de bootstrap selon vos besoins. Déployez ensuite le modèle pour démarrer votre environnement.

Pour modifier et déployer le modèle de bootstrap par défaut

  1. Obtenez le modèle de bootstrap par défaut à l'aide de l'--show-templateoption. Par défaut, le modèle CDK CLI sera affiché dans la fenêtre de votre terminal. Vous pouvez modifier la CDK CLI commande pour enregistrer le modèle sur votre machine locale. Voici un exemple :

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

  2. Modifiez le modèle de bootstrap selon vos besoins. Toutes les modifications que vous apportez doivent respecter le modèle de contrat de démarrage. Pour plus d'informations sur le modèle de contrat de démarrage, consultez. Suivez le contrat Bootstrap

    Pour vous assurer que vos personnalisations ne seront pas accidentellement remplacées ultérieurement par une personne cdk bootstrap utilisant le modèle par défaut, modifiez la valeur par défaut du paramètre du BootstrapVariant modèle. Cela CDK CLI permettra uniquement de remplacer la pile bootstrap par des modèles dont la version est identique BootstrapVariant ou supérieure à celle du modèle actuellement déployé.

  3. Déployez votre modèle modifié à l'aide de votre méthode AWS CloudFormation de déploiement préférée. Voici un exemple qui utilise CDK CLI :

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

Suivez le contrat Bootstrap

Pour que vos CDK applications soient correctement déployées, les CloudFormation modèles produits lors de la synthèse doivent spécifier correctement les ressources créées lors du démarrage. Ces ressources sont communément appelées ressources bootstrap. Le bootstrapping crée des ressources dans votre AWS environnement qui sont utilisées par le AWS CDK pour effectuer des déploiements et gérer les actifs de l'application. Synthesis produit des CloudFormation modèles à partir de chaque CDK pile de votre application. Ces modèles ne définissent pas uniquement les AWS ressources qui seront mises à disposition à partir de votre application. Ils spécifient également les ressources d'amorçage à utiliser lors du déploiement.

Pendant la synthèse, CDK CLI il ne sait pas précisément comment votre AWS environnement a été amorcé. Au lieu de cela, il CDK CLI produit des CloudFormation modèles basés sur le synthétiseur que vous configurez. Par conséquent, lorsque vous personnalisez le bootstrap, vous devrez peut-être personnaliser la synthèse. Pour obtenir des instructions sur la personnalisation de la synthèse, voirPersonnalisez la synthèse des CDK piles. L'objectif est de garantir que vos CloudFormation modèles synthétisés sont compatibles avec votre environnement d'amorçage. Cette compatibilité est appelée contrat bootstrap.

La méthode la plus simple pour personnaliser la synthèse de pile consiste à modifier la DefaultStackSynthesizer classe de votre Stack instance. Si vous avez besoin d'une personnalisation allant au-delà de ce que cette classe peut offrir, vous pouvez écrire votre propre synthétiseur sous la forme d'une classe qui implémente IStackSynthesizer (peut-être DefaultStackSynthesizer dérivée de).

Lorsque vous personnalisez le bootstrap, suivez le modèle de contrat bootstrap pour rester compatible avec. DefaultStackSynthesizer Si vous modifiez le bootstrap au-delà du contrat type de bootstrap, vous devrez écrire votre propre synthétiseur.

Gestion des versions

Le modèle bootstrap doit contenir une ressource permettant de créer un paramètre Amazon EC2 Systems Manager (SSM) avec un nom connu et une sortie reflétant la version du modèle :

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]

Rôles

DefaultStackSynthesizerCela nécessite cinq IAM rôles pour cinq objectifs différents. Si vous n'utilisez pas les rôles par défaut, vous devez spécifier votre IAM rôle ARNs au sein de votre DefaultStackSynthesizer objet. Les rôles sont les suivants :

  • Le rôle de déploiement est assumé par CDK CLI et AWS CodePipeline pour déployer dans un environnement. Il AssumeRolePolicy contrôle qui peut être déployé dans l'environnement. Dans le modèle, vous pouvez voir les autorisations dont ce rôle a besoin.

  • Le rôle de recherche est assumé par le CDK CLI pour effectuer des recherches contextuelles dans un environnement. Il AssumeRolePolicy contrôle qui peut être déployé dans l'environnement. Les autorisations dont ce rôle a besoin sont indiquées dans le modèle.

  • Le rôle de publication de fichiers et le rôle de publication d'images sont assumés par CDK CLI et par les AWS CodeBuild projets visant à publier des actifs dans un environnement. Ils sont utilisés pour écrire dans le compartiment Amazon S3 et dans le ECR référentiel Amazon, respectivement. Ces rôles nécessitent un accès en écriture à ces ressources.

  • Le rôle AWS CloudFormation d'exécution est transmis AWS CloudFormation pour effectuer le déploiement proprement dit. Ses autorisations sont celles sous lesquelles le déploiement s'exécutera. Les autorisations sont transmises à la pile sous forme de paramètre répertoriant les politiques géréesARNs.

Outputs

CDKCLICela nécessite que les CloudFormation sorties suivantes existent sur la pile bootstrap :

  • BucketName— Nom du compartiment de ressources du fichier.

  • BucketDomainName— Le compartiment des actifs de fichiers au format nom de domaine.

  • BootstrapVersion— La version actuelle de la pile bootstrap.

Historique du modèle

Le modèle bootstrap est versionné et évolue au fil du temps avec lui-même. AWS CDK Si vous fournissez votre propre modèle de bootstrap, maintenez-le à jour avec le modèle canonique par défaut. Vous devez vous assurer que votre modèle continue de fonctionner avec toutes les CDK fonctionnalités. Pour de plus amples informations, veuillez consulter Historique des versions du modèle Bootstrap.