Configurer les environnements à utiliser avec AWS CDK - AWS Cloud Development Kit (AWS CDK) v2

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.

Configurer les environnements à utiliser avec AWS CDK

Vous pouvez configurer AWS les environnements de différentes manières à utiliser avec le AWS Cloud Development Kit (AWS CDK). La meilleure méthode de gestion AWS des environnements varie en fonction de vos besoins spécifiques.

Chaque CDK pile de votre application doit éventuellement être associée à un environnement afin de déterminer où la pile est déployée.

Pour une introduction aux AWS environnements, voirEnvironnements pour AWS CDK.

D'où vous pouvez spécifier des environnements à partir de

Vous pouvez spécifier des environnements dans les informations d'identification et les fichiers de configuration, ou en utilisant la env propriété de la Stack construction de la AWS bibliothèque de constructions.

Informations d'identification et fichiers de configuration

Vous pouvez utiliser le AWS Command Line Interface (AWS CLI) pour créer des credentials config fichiers qui stockent, organisent et gèrent les informations relatives à votre AWS environnement. Pour en savoir plus sur ces fichiers, consultez la section Configuration et paramètres des fichiers d'identification dans le Guide de l'AWS Command Line Interface utilisateur.

Les valeurs stockées dans ces fichiers sont organisées par profils. La façon dont vous nommez vos profils et les paires clé-valeur dans ces fichiers varie en fonction de votre méthode de configuration de l'accès par programmation. Pour en savoir plus sur les différentes méthodes, consultezConfigurez les informations d'identification de sécurité pour AWS CDKCLI.

En général, il AWS CDK résout les Compte AWS informations de votre credentials fichier et Région AWS les informations de votre config fichier.

Une fois vos config fichiers credentials et configurés, vous pouvez spécifier l'environnement à utiliser avec AWS CDK CLI et par le biais de variables d'environnement.

propriété env de la construction Stack

Vous pouvez spécifier l'environnement de chaque pile en utilisant la env propriété de la Stack construction. Cette propriété définit le compte et la région à utiliser. Vous pouvez transmettre des valeurs codées en dur à cette propriété ou transmettre des variables d'environnement proposées par leCDK.

Pour transmettre des variables d'environnement, utilisez les variables d'AWS_DEFAULT_REGIONenvironnement AWS_DEFAULT_ACCOUNT et. Ces variables d'environnement peuvent transmettre des valeurs provenant de vos config fichiers credentials et. Vous pouvez également utiliser la logique de votre CDK code pour déterminer les valeurs de ces variables d'environnement.

Priorité environnementale avec AWS CDK

Si vous utilisez plusieurs méthodes pour spécifier des environnements, la priorité suivante est AWS CDK respectée :

  1. Valeurs codées en dur spécifiées avec la env propriété de la Stack construction.

  2. AWS_DEFAULT_ACCOUNTet les variables d'AWS_DEFAULT_REGIONenvironnement spécifiées avec la env propriété de la Stack construction.

  3. Informations sur l'environnement associées au profil provenant de vos config fichiers credentials et transmises au CDK CLI en utilisant l'--profileoption.

  4. Le default profil de vos config fichiers credentials et.

Quand spécifier les environnements

Lorsque vous développez avec leCDK, vous commencez par définir des CDK piles, qui contiennent des structures représentant AWS des ressources. Ensuite, vous synthétisez chaque CDK pile dans un AWS CloudFormation modèle. Vous déployez ensuite le CloudFormation modèle dans votre environnement. La façon dont vous spécifiez les environnements détermine le moment où les informations relatives à votre environnement sont appliquées et peut affecter CDK le comportement et les résultats.

Spécifier les environnements lors de la synthèse du modèle

Lorsque vous spécifiez des informations d'environnement à l'aide de la env propriété de la Stack construction, celles-ci sont appliquées lors de la synthèse du modèle. Exécution cdk synth ou cdk deploy production d'un modèle spécifique à l'environnement CloudFormation .

Si vous utilisez des variables d'environnement dans la env propriété, vous devez utiliser l'--profileoption avec CDK CLI commandes pour transmettre le profil contenant les informations de votre environnement à partir de vos informations d'identification et de vos fichiers de configuration. Ces informations seront ensuite appliquées lors de la synthèse du modèle pour produire un modèle spécifique à l'environnement.

Les informations relatives à l'environnement contenues dans le CloudFormation modèle ont priorité sur les autres méthodes. Par exemple, si vous fournissez un environnement différent aveccdk deploy --profile profile, le profil sera ignoré.

Lorsque vous fournissez des informations sur l'environnement de cette manière, vous pouvez utiliser un code et une logique dépendants de l'environnement dans votre CDK application. Cela signifie également que le modèle synthétisé peut être différent, en fonction de la machine, de l'utilisateur ou de la session sous laquelle il est synthétisé. Cette approche est souvent acceptable ou souhaitable au cours du développement, mais elle n'est pas recommandée pour une utilisation en production.

Spécifier les environnements lors du déploiement de la pile

Si vous ne spécifiez pas d'environnement à l'aide de la env propriété de la Stack construction, le CDK CLI produira un CloudFormation modèle indépendant de l'environnement lors de la synthèse. Vous pouvez ensuite spécifier l'environnement dans lequel le déploiement doit être effectué à l'aide decdk deploy --profile profile.

Si vous ne spécifiez pas de profil lors du déploiement d'un modèle indépendant de l'environnement, le CDK CLI tentera d'utiliser les valeurs d'environnement issues du default profil de vos config fichiers credentials et de vos fichiers lors du déploiement.

Si les informations relatives à l'environnement ne sont pas disponibles au moment du déploiement, AWS CloudFormation tentera de les résoudre au moyen d'attributs liés à l'environnement tels que stack.accountstack.region, etstack.availabilityZones.

Pour les piles indépendantes de l'environnement, les constructions de la pile ne peuvent pas utiliser les informations d'environnement et vous ne pouvez pas utiliser de logique nécessitant des informations d'environnement. Par exemple, vous ne pouvez pas écrire du code if (stack.region ==== 'us-east-1') ou utiliser des méthodes de construction qui nécessitent des informations d'environnement telles queVpc.fromLookup. Pour utiliser ces fonctionnalités, vous devez spécifier un environnement avec la env propriété.

Pour les piles indépendantes de l'environnement, toute construction utilisant des zones de disponibilité comportera deux zones de disponibilité, ce qui permettra de déployer la pile dans n'importe quelle région.

Comment spécifier des environnements à l'aide du AWS CDK

Spécifiez des environnements codés en dur pour chaque pile

Utilisez la env propriété de la Stack construction pour spécifier les valeurs d' AWS environnement de votre pile. Voici un exemple :

TypeScript
const envEU = { account: '2383838383', region: 'eu-west-1' }; const envUSA = { account: '8373873873', region: 'us-west-2' }; new MyFirstStack(app, 'first-stack-us', { env: envUSA }); new MyFirstStack(app, 'first-stack-eu', { env: envEU });
JavaScript
const envEU = { account: '2383838383', region: 'eu-west-1' }; const envUSA = { account: '8373873873', region: 'us-west-2' }; new MyFirstStack(app, 'first-stack-us', { env: envUSA }); new MyFirstStack(app, 'first-stack-eu', { env: envEU });
Python
env_EU = cdk.Environment(account="8373873873", region="eu-west-1") env_USA = cdk.Environment(account="2383838383", region="us-west-2") MyFirstStack(app, "first-stack-us", env=env_USA) MyFirstStack(app, "first-stack-eu", env=env_EU)
Java
public class MyApp { // Helper method to build an environment static Environment makeEnv(String account, String region) { return Environment.builder() .account(account) .region(region) .build(); } public static void main(final String argv[]) { App app = new App(); Environment envEU = makeEnv("8373873873", "eu-west-1"); Environment envUSA = makeEnv("2383838383", "us-west-2"); new MyFirstStack(app, "first-stack-us", StackProps.builder() .env(envUSA).build()); new MyFirstStack(app, "first-stack-eu", StackProps.builder() .env(envEU).build()); app.synth(); } }
C#
Amazon.CDK.Environment makeEnv(string account, string region) { return new Amazon.CDK.Environment { Account = account, Region = region }; } var envEU = makeEnv(account: "8373873873", region: "eu-west-1"); var envUSA = makeEnv(account: "2383838383", region: "us-west-2"); new MyFirstStack(app, "first-stack-us", new StackProps { Env=envUSA }); new MyFirstStack(app, "first-stack-eu", new StackProps { Env=envEU });
Go
env_EU := awscdk.Environment{ Account: jsii.String("8373873873"), Region: jsii.String("eu-west-1"), } env_USA := awscdk.Environment{ Account: jsii.String("2383838383"), Region: jsii.String("us-west-2"), } MyFirstStack(app, "first-stack-us", &awscdk.StackProps{ Env: &env_USA, }) MyFirstStack(app, "first-stack-eu", &awscdk.StackProps{ Env: &env_EU, })

Nous recommandons cette approche pour les environnements de production. En spécifiant explicitement l'environnement de cette manière, vous pouvez vous assurer que la pile est toujours déployée dans l'environnement spécifique.

Spécifier les environnements à l'aide de variables d'environnement

AWS CDK fournit deux variables d'environnement que vous pouvez utiliser dans votre CDK code : CDK_DEFAULT_ACCOUNT etCDK_DEFAULT_REGION. Lorsque vous utilisez ces variables d'environnement dans la env propriété de votre instance de stack, vous pouvez transmettre des informations d'environnement provenant de vos informations d'identification et de vos fichiers de configuration à l'aide du CDK CLI --profileoption.

Voici un exemple de la manière de spécifier ces variables d'environnement :

TypeScript

Accédez aux variables d'environnement via l'processobjet de Node.

Note

Vous avez besoin du DefinitelyTyped module pour l'utiliser process dans TypeScript. cdk initinstalle ce module pour vous. Cependant, vous devez installer ce module manuellement si vous travaillez avec un projet créé avant son ajout, ou si vous n'avez pas configuré votre projet à l'aide decdk init.

npm install @types/node
new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION }});
JavaScript

Accédez aux variables d'environnement via l'processobjet de Node.

new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION }});
Python

Utilisez le environ dictionnaire du os module pour accéder aux variables d'environnement.

import os MyDevStack(app, "dev", env=cdk.Environment( account=os.environ["CDK_DEFAULT_ACCOUNT"], region=os.environ["CDK_DEFAULT_REGION"]))
Java

System.getenv()À utiliser pour obtenir la valeur d'une variable d'environnement.

public class MyApp { // Helper method to build an environment static Environment makeEnv(String account, String region) { account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account; region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region; return Environment.builder() .account(account) .region(region) .build(); } public static void main(final String argv[]) { App app = new App(); Environment envEU = makeEnv(null, null); Environment envUSA = makeEnv(null, null); new MyDevStack(app, "first-stack-us", StackProps.builder() .env(envUSA).build()); new MyDevStack(app, "first-stack-eu", StackProps.builder() .env(envEU).build()); app.synth(); } }
C#

System.Environment.GetEnvironmentVariable()À utiliser pour obtenir la valeur d'une variable d'environnement.

Amazon.CDK.Environment makeEnv(string account=null, string region=null) { return new Amazon.CDK.Environment { Account = account ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"), Region = region ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION") }; } new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
Go
import "os" MyDevStack(app, "dev", &awscdk.StackProps{ Env: &awscdk.Environment{ Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")), Region: jsii.String(os.Getenv("CDK_DEFAULT_REGION")), }, })

En spécifiant des environnements à l'aide de variables d'environnement, vous pouvez synthétiser la même CDK pile en AWS CloudFormation modèles pour différents environnements. Cela signifie que vous pouvez déployer la même CDK pile AWS dans différents environnements sans avoir à modifier votre CDK code. Il suffit de spécifier le profil à utiliser lors de l'exécutioncdk synth.

Cette approche est idéale pour les environnements de développement lors du déploiement de la même pile dans différents environnements. Toutefois, nous ne recommandons pas cette approche pour les environnements de production, car le même CDK code peut synthétiser différents modèles, en fonction de la machine, de l'utilisateur ou de la session sous laquelle il est synthétisé.

Spécifiez les environnements à partir de vos informations d'identification et de vos fichiers de configuration à l'aide du CDK CLI

Lorsque vous déployez un modèle indépendant de l'environnement, utilisez l'option avec n'importe quel --profile CDK CLI commande pour spécifier le profil à utiliser. Voici un exemple de déploiement d'une CDK pile nommée à myStack l'aide du prod profil défini dans les config fichiers credentials et :

$ cdk deploy myStack --profile prod

Pour plus d'informations sur --profile cette option, ainsi que sur d'autres CDK CLI commandes et options, voirAWS CDK CLI Référence des commandes  .

Considérations à prendre en compte lors de la configuration d'environnements avec AWS CDK

Les services que vous définissez à l'aide de structures au sein de vos piles doivent prendre en charge la région dans laquelle vous effectuez le déploiement. Pour obtenir la liste des services pris en charge Services AWS par région, consultez la section AWS Services par région.

Vous devez disposer d'informations d'identification valides AWS Identity and Access Management (IAM) pour effectuer des déploiements de stack AWS CDK dans les environnements que vous avez spécifiés.

Exemples

Synthétiser un modèle indépendant de l'environnement à partir d'une pile CloudFormation CDK

Dans cet exemple, nous créons un CloudFormation modèle indépendant de l'environnement à partir de notre pile. CDK Nous pouvons ensuite déployer ce modèle dans n'importe quel environnement.

Voici notre exemple de CDK pile. Cette pile définit un compartiment Amazon S3 et une sortie de CloudFormation pile pour la région du compartiment. Dans cet exemple, n'envest pas défini :

TypeScript
export class CdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Create the S3 bucket const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY, }); // Create an output for the bucket's Region new cdk.CfnOutput(this, 'BucketRegion', { value: bucket.env.region, }); } }
JavaScript
class CdkAppStack extends cdk.Stack { constructor(scope, id, props) { super(scope, id, props); // Create the S3 bucket const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY, }); // Create an output for the bucket's Region new cdk.CfnOutput(this, 'BucketRegion', { value: bucket.env.region, }); } }
Python
class CdkAppStack(cdk.Stack): def __init__(self, scope: cdk.Construct, id: str, **kwargs) -> None: super().__init__(scope, id, **kwargs) # Create the S3 bucket bucket = s3.Bucket(self, 'amzn-s3-demo-bucket', removal_policy=cdk.RemovalPolicy.DESTROY ) # Create an output for the bucket's Region cdk.CfnOutput(self, 'BucketRegion', value=bucket.env.region )
Java
public class CdkAppStack extends Stack { public CdkAppStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); // Create the S3 bucket Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket") .removalPolicy(RemovalPolicy.DESTROY) .build(); // Create an output for the bucket's Region CfnOutput.Builder.create(this, "BucketRegion") .value(this.getRegion()) .build(); } }
C#
namespace MyCdkApp { public class CdkAppStack : Stack { public CdkAppStack(Construct scope, string id, IStackProps props = null) : base(scope, id, props) { // Create the S3 bucket var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps { RemovalPolicy = RemovalPolicy.DESTROY }); // Create an output for the bucket's Region new CfnOutput(this, "BucketRegion", new CfnOutputProps { Value = this.Region }); } } }
Go
func NewCdkAppStack(scope constructs.Construct, id string, props *CdkAppStackProps) awscdk.Stack { stack := awscdk.NewStack(scope, &id, &props.StackProps) // Create the S3 bucket bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{ RemovalPolicy: awscdk.RemovalPolicy_DESTROY, }) // Create an output for the bucket's Region awscdk.NewCfnOutput(stack, jsii.String("BucketRegion"), &awscdk.CfnOutputProps{ Value: stack.Region(), }) return stack }

Lorsque nous couronscdk synth, le CDK CLI produit un CloudFormation modèle avec le pseudo paramètre AWS::Region comme valeur de sortie pour la région du compartiment. Ce paramètre sera résolu lors du déploiement :

Outputs: BucketRegion: Value: Ref: AWS::Region

Pour déployer cette pile dans un environnement spécifié dans le dev profil de nos informations d'identification et de nos fichiers de configuration, nous exécutons les opérations suivantes :

$ cdk deploy CdkAppStack --profile dev

Si nous ne spécifiez pas de profil, le CDK CLI tentera d'utiliser les informations d'environnement du default profil dans nos informations d'identification et nos fichiers de configuration.

Utiliser la logique pour déterminer les informations relatives à l'environnement lors de la synthèse du modèle

Dans cet exemple, nous configurons la env propriété de notre stack instance pour utiliser une expression valide. Nous spécifiez deux variables d'environnement supplémentaires, CDK_DEPLOY_ACCOUNT etCDK_DEPLOY_REGION. Ces variables d'environnement peuvent remplacer les valeurs par défaut au moment de la synthèse si elles existent :

TypeScript
new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION }});
JavaScript
new MyDevStack(app, 'dev', { env: { account: process.env.CDK_DEPLOY_ACCOUNT || process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEPLOY_REGION || process.env.CDK_DEFAULT_REGION }});
Python
MyDevStack(app, "dev", env=cdk.Environment( account=os.environ.get("CDK_DEPLOY_ACCOUNT", os.environ["CDK_DEFAULT_ACCOUNT"]), region=os.environ.get("CDK_DEPLOY_REGION", os.environ["CDK_DEFAULT_REGION"])
Java
public class MyApp { // Helper method to build an environment static Environment makeEnv(String account, String region) { account = (account == null) ? System.getenv("CDK_DEPLOY_ACCOUNT") : account; region = (region == null) ? System.getenv("CDK_DEPLOY_REGION") : region; account = (account == null) ? System.getenv("CDK_DEFAULT_ACCOUNT") : account; region = (region == null) ? System.getenv("CDK_DEFAULT_REGION") : region; return Environment.builder() .account(account) .region(region) .build(); } public static void main(final String argv[]) { App app = new App(); Environment envEU = makeEnv(null, null); Environment envUSA = makeEnv(null, null); new MyDevStack(app, "first-stack-us", StackProps.builder() .env(envUSA).build()); new MyDevStack(app, "first-stack-eu", StackProps.builder() .env(envEU).build()); app.synth(); } }
C#
Amazon.CDK.Environment makeEnv(string account=null, string region=null) { return new Amazon.CDK.Environment { Account = account ?? System.Environment.GetEnvironmentVariable("CDK_DEPLOY_ACCOUNT") ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"), Region = region ?? System.Environment.GetEnvironmentVariable("CDK_DEPLOY_REGION") ?? System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION") }; } new MyDevStack(app, "dev", new StackProps { Env = makeEnv() });
Go
var account, region string var b bool if account, b = os.LookupEnv("CDK_DEPLOY_ACCOUNT"); !b || len(account) == 0 { account = os.Getenv("CDK_DEFAULT_ACCOUNT") } if region, b = os.LookupEnv("CDK_DEPLOY_REGION"); !b || len(region) == 0 { region = os.Getenv("CDK_DEFAULT_REGION") } MyDevStack(app, "dev", &awscdk.StackProps{ Env: &awscdk.Environment{ Account: &account, Region: &region, }, })

Une fois l'environnement de notre pile déclaré de cette façon, nous pouvons ensuite écrire un court script ou un fichier batch et définir des variables à partir des arguments de la ligne de commande, puis appelercdk deploy. Voici un exemple. Tous les arguments situés au-delà des deux premiers sont transmis cdk deploy à pour spécifier les options ou les arguments de la ligne de commande :

macOS/Linux
#!/usr/bin/env bash if [[ $# -ge 2 ]]; then export CDK_DEPLOY_ACCOUNT=$1 export CDK_DEPLOY_REGION=$2 shift; shift npx cdk deploy "$@" exit $? else echo 1>&2 "Provide account and region as first two args." echo 1>&2 "Additional args are passed through to cdk deploy." exit 1 fi

Enregistrez le script souscdk-deploy-to.sh, puis exécutez-le chmod +x cdk-deploy-to.sh pour le rendre exécutable.

Windows
@findstr /B /V @ %~dpnx0 > %~dpn0.ps1 && powershell -ExecutionPolicy Bypass %~dpn0.ps1 %* @exit /B %ERRORLEVEL% if ($args.length -ge 2) { $env:CDK_DEPLOY_ACCOUNT, $args = $args $env:CDK_DEPLOY_REGION, $args = $args npx cdk deploy $args exit $lastExitCode } else { [console]::error.writeline("Provide account and region as first two args.") [console]::error.writeline("Additional args are passed through to cdk deploy.") exit 1 }

La version Windows du script fournit PowerShell les mêmes fonctionnalités que la version macOS/Linux. Il contient également des instructions permettant de l'exécuter sous forme de fichier batch afin qu'il puisse être facilement invoqué à partir d'une ligne de commande. Il doit être enregistré sous le nomcdk-deploy-to.bat. Le fichier cdk-deploy-to.ps1 sera créé lorsque le fichier batch sera invoqué.

Nous pouvons ensuite écrire des scripts supplémentaires qui utilisent le cdk-deploy-to script pour le déployer dans des environnements spécifiques. Voici un exemple :

macOS/Linux
#!/usr/bin/env bash # cdk-deploy-to-test.sh ./cdk-deploy-to.sh 123457689 us-east-1 "$@"
Windows
@echo off rem cdk-deploy-to-test.bat cdk-deploy-to 135792469 us-east-1 %*

L'exemple suivant utilise le cdk-deploy-to script pour le déployer dans plusieurs environnements. Si le premier déploiement échoue, le processus s'arrête :

macOS/Linux
#!/usr/bin/env bash # cdk-deploy-to-prod.sh ./cdk-deploy-to.sh 135792468 us-west-1 "$@" || exit ./cdk-deploy-to.sh 246813579 eu-west-1 "$@"
Windows
@echo off rem cdk-deploy-to-prod.bat cdk-deploy-to 135792469 us-west-1 %* || exit /B cdk-deploy-to 245813579 eu-west-1 %*