Ceci est le guide du AWS CDK développeur de la version 2. L'ancien CDK v1 est entré 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.

Contexte d'exécution

Les valeurs de contexte sont des paires clé-valeur qui peuvent être associées à une application, une pile ou une construction. Ils peuvent être fournis à votre application à partir d'un fichier (généralement dans le répertoire de votre projet cdk.json ou cdk.context.json dans le répertoire de votre projet) ou sur la ligne de commande.

Le kit d'outils CDK utilise le contexte pour mettre en cache les valeurs extraites de votre AWS compte lors de la synthèse. Les valeurs incluent les zones de disponibilité de votre compte ou les identifiants Amazon Machine Image (AMI) actuellement disponibles pour les instances Amazon EC2. Comme ces valeurs sont fournies par votre AWS compte, elles peuvent changer entre les exécutions de votre application CDK. Cela en fait une source potentielle de changements involontaires. Le comportement de mise en cache du kit CDK « bloque » ces valeurs pour votre application CDK jusqu'à ce que vous décidiez d'accepter les nouvelles valeurs.

Imaginez le scénario suivant sans mise en cache du contexte. Supposons que vous ayez spécifié la « dernière version d'Amazon Linux » comme AMI pour vos instances Amazon EC2 et qu'une nouvelle version de cette AMI ait été publiée. Ensuite, la prochaine fois que vous déploierez votre pile CDK, vos instances déjà déployées utiliseront l'ancienne (« mauvaise ») AMI et devront être mises à niveau. La mise à niveau entraînerait le remplacement de toutes vos instances existantes par de nouvelles, ce qui serait probablement inattendu et indésirable.

Le CDK enregistre plutôt les AMI disponibles pour votre compte dans le cdk.context.json fichier de votre projet et utilise la valeur stockée pour les futures opérations de synthèse. Ainsi, la liste des AMI n'est plus une source potentielle de changement. Vous pouvez également être sûr que vos piles seront toujours synthétisées selon les mêmes AWS CloudFormation modèles.

Les valeurs de contexte ne sont pas toutes des valeurs mises en cache dans votre AWS environnement. Drapeaux caractéristiquessont également des valeurs contextuelles. Vous pouvez également créer vos propres valeurs de contexte à utiliser par vos applications ou constructions.

Les clés de contexte sont des chaînes de caractères. Les valeurs peuvent être de n'importe quel type pris en charge par JSON : nombres, chaînes, tableaux ou objets.

De nombreuses valeurs de contexte sont associées à un AWS environnement particulier, et une application CDK donnée peut être déployée dans plusieurs environnements. La clé de ces valeurs inclut le AWS compte et la région afin que les valeurs issues de différents environnements n'entrent pas en conflit.

La clé de contexte suivante illustre le format utilisé par le AWS CDK, y compris le compte et la région.

availability-zones:account=123456789012:region=eu-central-1

Sources des valeurs contextuelles

Les valeurs de contexte peuvent être fournies à votre AWS CDK application de six manières différentes :

Le fichier de projet cdk.context.json est l'endroit où sont mises en AWS CDK cache les valeurs de contexte extraites de votre AWS compte. Cette pratique permet d'éviter des modifications inattendues de vos déploiements lorsque, par exemple, une nouvelle zone de disponibilité est introduite. Le AWS CDK n'écrit pas de données contextuelles dans aucun des autres fichiers répertoriés.

Les valeurs de contexte sont limitées à la structure qui les a créées ; elles sont visibles pour les structures enfants, mais pas pour les parents ou les frères et sœurs. Les valeurs de contexte définies par le AWS CDK Toolkit (la cdk commande) peuvent être définies automatiquement, à partir d'un fichier ou à partir de l'--contextoption. Les valeurs de contexte issues de ces sources sont définies implicitement dans la App construction. Ils sont donc visibles pour toutes les constructions de chaque pile de l'application.

Votre application peut lire une valeur de contexte à l'aide de construct.node.tryGetContext cette méthode. Si l'entrée demandée ne se trouve pas dans le build actuel ou dans l'un de ses parents, le résultat estundefined. (Le résultat peut également être l'équivalent de votre langage, comme None en Python.)

Méthodes de contexte

Il AWS CDK prend en charge plusieurs méthodes contextuelles qui permettent aux AWS CDK applications d'obtenir des informations contextuelles à partir de l' AWS environnement. Par exemple, vous pouvez obtenir une liste des zones de disponibilité disponibles dans un AWS compte et une région donnés à l'aide de la méthode Stack.AvailabilityZones.

Les méthodes contextuelles sont les suivantes :

Si aucune valeur de contexte requise n'est disponible, l' AWS CDK application indique au kit d'outils CDK que les informations de contexte sont manquantes. Ensuite, la CLI interroge le AWS compte courant pour obtenir les informations et stocke les informations contextuelles obtenues dans le cdk.context.json fichier. Ensuite, il exécute à nouveau l' AWS CDK application avec les valeurs de contexte.

Affichage et gestion du contexte

Utilisez la cdk context commande pour afficher et gérer les informations de votre cdk.context.json fichier. Pour voir ces informations, utilisez la cdk context commande sans aucune option. Le résultat devrait ressembler à ce qui suit.

Context found in cdk.json:

┌───┬─────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
│ # │ Key                                                         │ Value                                                   │
├───┼─────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ 1 │ availability-zones:account=123456789012:region=eu-central-1 │ [ "eu-central-1a", "eu-central-1b", "eu-central-1c" ]   │
├───┼─────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ 2 │ availability-zones:account=123456789012:region=eu-west-1    │ [ "eu-west-1a", "eu-west-1b", "eu-west-1c" ]            │
└───┴─────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────┘

Run cdk context --reset KEY_OR_NUMBER to remove a context key. If it is a cached value, it will be refreshed on the next cdk synth.

Pour supprimer une valeur de contextecdk context --reset, exécutez en spécifiant la clé ou le numéro correspondant à la valeur. L'exemple suivant supprime la valeur qui correspond à la deuxième clé de l'exemple précédent. Cette valeur représente la liste des zones de disponibilité de la région Europe (Irlande).

cdk context --reset 2

Context value
availability-zones:account=123456789012:region=eu-west-1
reset. It will be refreshed on the next SDK synthesis run.

Par conséquent, si vous souhaitez effectuer une mise à jour vers la dernière version de l'AMI Amazon Linux, utilisez l'exemple précédent pour effectuer une mise à jour contrôlée de la valeur de contexte et la réinitialiser. Ensuite, synthétisez et déployez à nouveau votre application.

cdk synth

Pour effacer toutes les valeurs de contexte stockées pour votre applicationcdk context --clear, exécutez comme suit.

cdk context --clear

Seules les valeurs de contexte stockées cdk.context.json peuvent être réinitialisées ou effacées. Ne touche AWS CDK pas les autres valeurs de contexte. Par conséquent, pour empêcher la réinitialisation d'une valeur de contexte à l'aide de ces commandes, vous pouvez copier la valeur danscdk.json.

AWS CDK--contextDrapeau Toolkit

Utilisez l'option --context (en abrégé) -c pour transmettre les valeurs de contexte d'exécution à votre application CDK lors de la synthèse ou du déploiement.

cdk synth --context key=value MyStack

Pour spécifier plusieurs valeurs de contexte, répétez l'--contextoption autant de fois que vous le souhaitez, en fournissant une paire clé-valeur à chaque fois.

cdk synth --context key1=value1 --context key2=value2 MyStack

Lors de la synthèse de plusieurs piles, les valeurs de contexte spécifiées sont transmises à toutes les piles. Pour fournir différentes valeurs de contexte à des piles individuelles, utilisez des touches différentes pour les valeurs ou utilisez plusieurs cdk synth cdk deploy commandes.

Les valeurs de contexte transmises depuis la ligne de commande sont toujours des chaînes. Si une valeur est généralement d'un autre type, votre code doit être prêt à la convertir ou à l'analyser. Des valeurs de contexte autres que des chaînes peuvent être fournies d'une autre manière (par exemple, danscdk.context.json). Pour vous assurer que ce type de valeur fonctionne comme prévu, vérifiez qu'il s'agit d'une chaîne avant de la convertir.

Exemple

Voici un exemple d'utilisation d'un Amazon VPC existant à l'aide AWS CDK du contexte.

TypeScript

import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import { Construct } from 'constructs';

export class ExistsVpcStack extends cdk.Stack {

  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
  
    super(scope, id, props);
    
    const vpcid = this.node.tryGetContext('vpcid');
    const vpc = ec2.Vpc.fromLookup(this, 'VPC', {
      vpcId: vpcid,
    });
    
    const pubsubnets = vpc.selectSubnets({subnetType: ec2.SubnetType.PUBLIC});
    
    new cdk.CfnOutput(this, 'publicsubnets', {
      value: pubsubnets.subnetIds.toString(),
    });
  }
}

JavaScript

const cdk = require('aws-cdk-lib');
const ec2 = require('aws-cdk-lib/aws-ec2');

class ExistsVpcStack extends cdk.Stack {

  constructor(scope, id, props) {
  
    super(scope, id, props);
    
    const vpcid = this.node.tryGetContext('vpcid');
    const vpc = ec2.Vpc.fromLookup(this, 'VPC', {
      vpcId: vpcid
    });
    
    const pubsubnets = vpc.selectSubnets({subnetType: ec2.SubnetType.PUBLIC});
    
    new cdk.CfnOutput(this, 'publicsubnets', {
      value: pubsubnets.subnetIds.toString()
    });
  }
}

module.exports = { ExistsVpcStack }

Python

import aws_cdk as cdk
import aws_cdk.aws_ec2 as ec2
from constructs import Construct

class ExistsVpcStack(cdk.Stack):

    def __init__(scope: Construct, id: str, **kwargs):
  
        super().__init__(scope, id, **kwargs)
    
        vpcid = self.node.try_get_context("vpcid")
        vpc = ec2.Vpc.from_lookup(self, "VPC", vpc_id=vpcid)
    
        pubsubnets = vpc.select_subnets(subnetType=ec2.SubnetType.PUBLIC)
    
        cdk.CfnOutput(self, "publicsubnets",
            value=pubsubnets.subnet_ids.to_string())

Java

import software.amazon.awscdk.CfnOutput;

import software.amazon.awscdk.services.ec2.Vpc;
import software.amazon.awscdk.services.ec2.VpcLookupOptions;
import software.amazon.awscdk.services.ec2.SelectedSubnets;
import software.amazon.awscdk.services.ec2.SubnetSelection;
import software.amazon.awscdk.services.ec2.SubnetType;
import software.constructs.Construct;

public class ExistsVpcStack extends Stack {
    public ExistsVpcStack(Construct context, String id) {
        this(context, id, null);
    }
    
    public ExistsVpcStack(Construct context, String id, StackProps props) {
        super(context, id, props);
        
        String vpcId = (String)this.getNode().tryGetContext("vpcid");
        Vpc vpc = (Vpc)Vpc.fromLookup(this, "VPC", VpcLookupOptions.builder()
                .vpcId(vpcId).build());

        SelectedSubnets pubSubNets = vpc.selectSubnets(SubnetSelection.builder()
                .subnetType(SubnetType.PUBLIC).build());
        
        CfnOutput.Builder.create(this, "publicsubnets")
                .value(pubSubNets.getSubnetIds().toString()).build();                
    }
}

C#

using Amazon.CDK;
using Amazon.CDK.AWS.EC2;
using Constructs;

class ExistsVpcStack : Stack
{
    public ExistsVpcStack(Construct scope, string id, StackProps props) : base(scope, id, props)
    {
        var vpcId = (string)this.Node.TryGetContext("vpcid");
        var vpc = Vpc.FromLookup(this, "VPC", new VpcLookupOptions
        {
            VpcId = vpcId
        });

        SelectedSubnets pubSubNets = vpc.SelectSubnets([new SubnetSelection
        {
            SubnetType = SubnetType.PUBLIC
        }]);

        new CfnOutput(this, "publicsubnets", new CfnOutputProps {
            Value = pubSubNets.SubnetIds.ToString()
        });
    }
}

Vous pouvez utiliser cdk diff pour voir les effets de la transmission d'une valeur de contexte sur la ligne de commande :

cdk diff -c vpcid=vpc-0cb9c31031d0d3e22

Stack ExistsvpcStack
Outputs
[+] Output publicsubnets publicsubnets: {"Value":"subnet-06e0ea7dd302d3e8f,subnet-01fc0acfb58f3128f"}

Les valeurs de contexte résultantes peuvent être visualisées comme indiqué ici.

cdk context -j

{
  "vpc-provider:account=123456789012:filter.vpc-id=vpc-0cb9c31031d0d3e22:region=us-east-1": {
    "vpcId": "vpc-0cb9c31031d0d3e22",
    "availabilityZones": [
      "us-east-1a",
      "us-east-1b"
    ],
    "privateSubnetIds": [
      "subnet-03ecfc033225be285",
      "subnet-0cded5da53180ebfa"
    ],
    "privateSubnetNames": [
      "Private"
    ],
    "privateSubnetRouteTableIds": [
      "rtb-0e955393ced0ada04",
      "rtb-05602e7b9f310e5b0"
    ],
    "publicSubnetIds": [
      "subnet-06e0ea7dd302d3e8f",
      "subnet-01fc0acfb58f3128f"
    ],
    "publicSubnetNames": [
      "Public"
    ],
    "publicSubnetRouteTableIds": [
      "rtb-00d1fdfd823c82289",
      "rtb-04bb1969b42969bcb"
    ]
  }
}