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.
Vous pouvez personnaliser la synthèse par AWS Cloud Development Kit (AWS CDK) pile en modifiant le synthétiseur par défaut, en utilisant d'autres synthétiseurs intégrés disponibles ou en créant votre propre synthétiseur.
AWS CDK Il inclut les synthétiseurs intégrés suivants que vous pouvez utiliser pour personnaliser le comportement de synthèse :
-
DefaultStackSynthesizer
— Si vous ne spécifiez pas de synthétiseur, celui-ci est utilisé automatiquement. Il prend en charge les déploiements entre comptes et les déploiements utilisant la CDK structure Pipelines. Son contrat de démarrage nécessite un compartiment Amazon S3 existant avec un nom connu, un ECR référentiel Amazon existant avec un nom connu et cinq IAM rôles existants avec des noms connus. Le modèle d'amorçage par défaut répond à ces exigences. -
CliCredentialsStackSynthesizer
— Le contrat de démarrage de ce synthétiseur nécessite un compartiment Amazon S3 et un référentiel Amazon ECR existants. Il ne nécessite aucun IAM rôle. Pour effectuer des déploiements, ce synthétiseur s'appuie sur les autorisations du CDK CLI utilisateur et est recommandé aux organisations qui souhaitent restreindre les informations d'identification IAM de déploiement. Ce synthétiseur ne prend pas en charge les déploiements entre comptes ni les pipelines. CDK -
LegacyStackSynthesizer
— Ce synthétiseur émule le comportement de la synthèse CDK v1. Son contrat de démarrage nécessite un bucket Amazon S3 existant portant un nom arbitraire et prévoit que les emplacements des actifs seront transmis sous forme de paramètres de CloudFormation pile. Si vous utilisez ce synthétiseur, vous devez utiliser le CDK CLI pour effectuer le déploiement.
Si aucun de ces synthétiseurs intégrés ne convient à votre cas d'utilisation, vous pouvez écrire votre propre synthétiseur sous forme de classe qui implémente IStackSynthesizer
ou examine les synthétiseurs
Personnaliser le DefaultStackSynthesizer
DefaultStackSynthesizer
Il s'agit du synthétiseur par défaut pour le AWS CDK. Il est conçu pour permettre les déploiements d'CDKapplications entre comptes, ainsi que le déploiement d'CDKapplications à partir d'un système CI/CD qui ne prend pas explicitement en charge le AWS CDK, mais qui prend en charge les CloudFormation déploiements réguliers, tels que. AWS CodePipeline Ce synthétiseur est la meilleure option pour la plupart des cas d'utilisation.
DefaultStackSynthesizer
contrat bootstrap
DefaultStackSynthesizer
nécessite le contrat bootstrap suivant. Voici les ressources qui doivent être créées lors du démarrage :
Ressource Bootstrap | Description | Nom de ressource attendu par défaut | Objectif |
---|---|---|---|
Compartiment Amazon S3 |
seau de mise en scène |
cdk-hnb659fds-assets- - |
Stocke les actifs des fichiers. |
ECRRéférentiel Amazon |
Référentiel de préparation |
cdk-hnb659 - - fds-container-assets |
Stocke et gère Docker actifs d'image. |
Rôle IAM |
Rôle de déploiement |
cdk-hnb659 - - fds-deploy-role |
Supposé par le CDK CLI et éventuellement CodePipeline pour assumer d'autres rôles et démarrer le AWS CloudFormation déploiement. La politique de confiance associée à ce rôle contrôle les personnes autorisées à effectuer un déploiement AWS CDK dans cet AWS environnement. |
Rôle IAM |
AWS CloudFormation rôle d'exécution |
cdk-hnb659 - - fds-cfn-exec-role |
Ce rôle est utilisé AWS CloudFormation pour effectuer le déploiement. Les politiques de ce rôle contrôlent les opérations que le CDK déploiement peut effectuer. |
Rôle IAM |
Rôle de recherche |
cdk-hnb659 - - fds-lookup-role |
Ce rôle est utilisé lorsque CDK CLI doit effectuer des recherches de contexte environnemental. La politique de confiance de ce rôle contrôle les personnes autorisées à rechercher des informations dans l'environnement. |
Rôle IAM |
Rôle de publication de fichiers |
cdk-hnb659 - - fds-file-publishing-role |
Ce rôle est utilisé pour télécharger des actifs dans le compartiment intermédiaire Amazon S3. Il est assumé à partir du rôle de déploiement. |
Rôle IAM |
Rôle de publication d'images |
cdk-hnb659 - - fds-image-publishing-role |
Ce rôle est utilisé pour télécharger Docker images vers le référentiel Amazon ECR Staging. Il est assumé à partir du rôle de déploiement. |
SSM paramètre |
Paramètre de version Bootstrap |
/cdk-bootstrap/hnb659fds/ |
Version du modèle bootstrap. Il est utilisé par le modèle bootstrap et le CDK CLI pour valider les exigences. |
Une façon de personnaliser la synthèse des CDK piles consiste à modifier leDefaultStackSynthesizer
. Vous pouvez personnaliser ce synthétiseur pour une seule CDK pile en utilisant la synthesizer
propriété de votre Stack
instance. Vous pouvez également modifier toutes DefaultStackSynthesizer
les piles de votre CDK application à l'aide de la defaultStackSynthesizer
propriété de votre App
instance.
Modifier le qualificatif
Le qualificatif est ajouté au nom des ressources créées lors du démarrage. Cette valeur est hnb659fds
par défaut. Lorsque vous modifiez le qualificatif pendant le démarrage, vous devez personnaliser la synthèse de CDK pile pour utiliser le même qualificatif.
Pour modifier le qualificatif, configurez la qualifier
propriété du qualificatif DefaultStackSynthesizer
ou configurez-le en tant que clé de contexte dans le cdk.json
fichier de votre CDK projet.
Voici un exemple de configuration de la qualifier
propriété de DefaultStackSynthesizer
:
new MyStack(this, 'MyStack', {
synthesizer: new DefaultStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
Voici un exemple de configuration du qualificatif en tant que clé de contexte dans cdk.json
:
{
"app": "...",
"context": {
"@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER"
}
}
Modifier le nom des ressources
Toutes les autres DefaultStackSynthesizer
propriétés concernent les noms des ressources dans le modèle bootstrap. Vous ne devez fournir l'une de ces propriétés que si vous avez modifié le modèle de bootstrap et modifié le nom des ressources ou le schéma de dénomination.
Toutes les propriétés acceptent les espaces réservés spéciaux${Qualifier}
, ${AWS::Partition}
${AWS::AccountId}
, et${AWS::Region}
. Ces espaces réservés sont remplacés par les valeurs du qualifier
paramètre et de la AWS partition, l'ID du compte et Région AWS les valeurs de l'environnement de la pile, respectivement.
L'exemple suivant montre les propriétés les plus couramment utilisées DefaultStackSynthesizer
ainsi que leurs valeurs par défaut, comme si vous instanciez le synthétiseur. Pour une liste complète, voir DefaultStackSynthesizerProps:
new DefaultStackSynthesizer({
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
// ARN of the role assumed by the CLI and Pipeline to deploy here
deployRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}',
deployRoleExternalId: '',
// ARN of the role used for file asset publishing (assumed from the CLI role)
fileAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}',
fileAssetPublishingExternalId: '',
// ARN of the role used for Docker asset publishing (assumed from the CLI role)
imageAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-image-publishing-role-${AWS::AccountId}-${AWS::Region}',
imageAssetPublishingExternalId: '',
// ARN of the role passed to CloudFormation to execute the deployments
cloudFormationExecutionRole: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-cfn-exec-role-${AWS::AccountId}-${AWS::Region}',
// ARN of the role used to look up context information in an environment
lookupRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-lookup-role-${AWS::AccountId}-${AWS::Region}',
lookupRoleExternalId: '',
// Name of the SSM parameter which describes the bootstrap stack version number
bootstrapStackVersionSsmParameter: '/cdk-bootstrap/${Qualifier}/version',
// Add a rule to every template which verifies the required bootstrap stack version
generateBootstrapVersionRule: true,
})
Utiliser CliCredentialsStackSynthesizer
Pour modifier les informations de sécurité utilisées pour fournir des autorisations lors CDK des déploiements, vous pouvez personnaliser la synthèse en utilisantCliCredentialsStackSynthesizer
. Ce synthétiseur fonctionne avec les AWS ressources par défaut créées lors du démarrage pour stocker des actifs, tels que le compartiment Amazon S3 et le référentiel Amazon. ECR Au lieu d'utiliser les IAM rôles par défaut créés par le CDK pendant le démarrage, il utilise les informations de sécurité de l'acteur à l'origine du déploiement. Par conséquent, les informations d'identification de sécurité de l'acteur doivent disposer d'autorisations valides pour effectuer toutes les actions de déploiement. Le schéma suivant illustre le processus de déploiement lors de l'utilisation de ce synthétiseur :
Lors de l'utilisation de CliCredentialsStackSynthesizer
:
-
Par défaut, CloudFormation effectue API des appels dans votre compte en utilisant les autorisations de l'acteur. Par conséquent, l'identité actuelle doit être autorisée à apporter les modifications nécessaires aux AWS ressources de la CloudFormation pile, ainsi que les autorisations nécessaires pour effectuer les CloudFormation opérations nécessaires, telles que
CreateStack
ouUpdateStack
. Les capacités de déploiement seront limitées aux autorisations de l'acteur. -
La publication et les CloudFormation déploiements des actifs seront effectués en utilisant l'IAMidentité actuelle. Cette identité doit disposer d'autorisations suffisantes pour lire et écrire dans le compartiment de ressources et le référentiel.
-
Les recherches sont effectuées à l'aide de l'IAMidentité actuelle, et les recherches sont soumises à ses politiques.
Lorsque vous utilisez ce synthétiseur, vous pouvez utiliser un rôle d' CloudFormation exécution distinct en le spécifiant à l'aide de l'--role-arn
option with any CDK CLI commande.
CliCredentialsStackSynthesizer
contrat bootstrap
CliCredentialsStackSynthesizer
nécessite le contrat bootstrap suivant. Voici les ressources qui doivent être créées lors du démarrage :
Ressource Bootstrap | Description | Nom de ressource attendu par défaut | Objectif |
---|---|---|---|
Compartiment Amazon S3 |
seau de mise en scène |
cdk-hnb659fds-assets- - |
Stocke les actifs des fichiers. |
ECRRéférentiel Amazon |
Référentiel de préparation |
cdk-hnb659 - - fds-container-assets |
Stocke et gère Docker actifs d'image. |
La chaîne figurant hnb659fds
dans le nom de la ressource s'appelle le qualificatif. Sa valeur par défaut n'a aucune signification particulière. Vous pouvez avoir plusieurs copies des ressources bootstrap dans un même environnement, à condition qu'elles aient un qualificatif différent. Le fait de disposer de plusieurs copies peut être utile pour séparer les actifs de différentes applications dans le même environnement.
Vous pouvez déployer le modèle de bootstrap par défaut pour satisfaire le contrat CliCredentialsStackSynthesizer
de bootstrap. Le modèle de bootstrap par défaut créera des IAM rôles, mais ce synthétiseur ne les utilisera pas. Vous pouvez également personnaliser le modèle bootstrap pour supprimer les IAM rôles.
Modifier CliCredentialsStackSynthesizer
Si vous modifiez le qualificatif ou l'un des noms de ressources d'amorçage par défaut pendant le démarrage, vous devez modifier le synthétiseur pour qu'il utilise les mêmes noms. Vous pouvez modifier le synthétiseur pour une seule pile ou pour toutes les piles de votre application. Voici un exemple :
new MyStack(this, 'MyStack', {
synthesizer: new CliCredentialsStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
L'exemple suivant montre les propriétés les plus couramment utilisées CliCredentialsStackSynthesizer
ainsi que leurs valeurs par défaut. Pour une liste complète, voir CliCredentialsStackSynthesizerProps:
new CliCredentialsStackSynthesizer({
// Value for '${Qualifier}' in the resource names
qualifier: 'hnb659fds',
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
})
Utiliser LegacyStackSynthesizer
Le LegacyStackSynthesizer
émule le comportement des déploiements de la CDK version 1. Les informations de sécurité de l'acteur effectuant le déploiement seront utilisées pour établir les autorisations. Les actifs du fichier seront chargés dans un bucket qui doit être créé à l'aide d'une AWS CloudFormation pile nomméeCDKToolkit
. L'interface CDK CLI créera un ECR référentiel Amazon non géré nommé aws-cdk/assets
pour stocker Docker actifs d'image. Vous serez responsable du nettoyage et de la gestion de ce dépôt. Les piles synthétisées à l'aide du ne LegacyStackSynthesizer
peuvent être déployées qu'à l'aide du CDK CLI.
Vous pouvez utiliser le LegacyStackSynthesizer
si vous migrez de la CDK v1 vers la CDK v2 et que vous ne parvenez pas à redémarrer vos environnements. Pour les nouveaux projets, nous vous recommandons de ne pas utiliserLegacyStackSynthesizer
.
LegacyStackSynthesizer
contrat bootstrap
LegacyStackSynthesizer
nécessite le contrat bootstrap suivant. Voici les ressources qui doivent être créées lors du démarrage :
Ressource Bootstrap | Description | Nom de ressource attendu par défaut | Objectif |
---|---|---|---|
Compartiment Amazon S3 |
seau de mise en scène |
cdk-hnb659fds-assets- - |
Stocke les actifs des fichiers. |
CloudFormation sortie |
Sortie du nom du bucket |
Empilez — Nom de sortie — |
Une CloudFormation sortie décrivant le nom du bucket intermédiaire |
LegacyStackSynthesizer
Cela ne suppose pas l'existence d'un compartiment Amazon S3 avec un nom fixe. Au lieu de cela, le CloudFormation modèle synthétisé contiendra trois CloudFormation paramètres pour chaque ressource de fichier. Ces paramètres stockeront le nom du compartiment Amazon S3, la clé d'objet Amazon S3 et le hachage de l'artefact pour chaque actif de fichier.
Docker les ressources d'image seront publiées dans un ECR référentiel Amazon nomméaws-cdk/assets
. Ce nom peut être modifié par ressource. Les référentiels seront créés s'ils n'existent pas.
Une CloudFormation pile doit exister avec le nom par défautCDKToolkit
. Cette pile doit avoir un nom CloudFormation d'exportation BucketName
qui fait référence au bucket intermédiaire.
Le modèle de bootstrap par défaut est conforme au contrat de LegacyStackSynthesizer
bootstrap. Toutefois, seul le compartiment Amazon S3 issu des ressources bootstrap du modèle bootstrap sera utilisé. Vous pouvez personnaliser le modèle bootstrap pour supprimer les ressources Amazon ECR et SSM bootstrap. IAM
LegacyStackSynthesizer
processus de déploiement
Lorsque vous utilisez ce synthétiseur, le processus suivant est effectué lors du déploiement :
-
L'interface CDK CLI recherche une CloudFormation pile nommée
CDKToolkit
dans votre environnement. À partir de cette pile, le CDK CLI lit la CloudFormation sortie nomméeBucketName
. Vous pouvez utiliser l'--toolkit-stack-name
option withcdk deploy
pour spécifier un autre nom de pile. -
Les informations d'identification de sécurité de l'acteur à l'origine du déploiement seront utilisées pour établir les autorisations de déploiement. Par conséquent, l'acteur doit disposer d'autorisations suffisantes pour effectuer toutes les actions de déploiement. Cela inclut la lecture et l'écriture dans le compartiment intermédiaire Amazon S3, la création et l'écriture dans le ECR référentiel Amazon, le démarrage et le suivi AWS CloudFormation des déploiements, ainsi que l'exécution de tous les API appels nécessaires au déploiement.
-
Si nécessaire, et si les autorisations sont valides, les actifs du fichier seront publiés dans le compartiment intermédiaire Amazon S3.
-
Si nécessaire, et si les autorisations sont valides, Docker les actifs d'image sont publiés dans le référentiel nommé par la
repositoryName
propriété de l'actif. La valeur par défaut est'aws-cdk/assets'
si vous ne fournissez pas de nom de dépôt. -
Si les autorisations sont valides, le AWS CloudFormation déploiement est effectué. Les emplacements du compartiment intermédiaire et des clés Amazon S3 sont transmis sous forme de CloudFormation paramètres.