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.
Les ressources sont celles que vous configurez pour être utilisées Services AWS dans vos applications. Les ressources sont une fonctionnalité de AWS CloudFormation. En configurant les ressources et leurs propriétés dans un AWS CloudFormation modèle, vous pouvez les déployer AWS CloudFormation pour provisionner vos ressources. Avec le AWS Cloud Development Kit (AWS CDK), vous pouvez configurer les ressources par le biais de constructions. Vous déployez ensuite votre application CDK, ce qui implique de synthétiser un AWS CloudFormation modèle et de le déployer pour AWS CloudFormation provisionner vos ressources.
Configuration des ressources à l'aide de constructions
Comme décrit dansAWS CDK Constructions, il AWS CDK fournit une riche bibliothèque de classes de constructions, appelées AWS constructions, qui représentent toutes les AWS ressources.
Pour créer une instance d'une ressource à l'aide de la structure correspondante, transmettez le scope comme premier argument, l'ID logique de la construction et un ensemble de propriétés de configuration (accessoires). Par exemple, voici comment créer une file d'attente Amazon SQS AWS KMS chiffrée à l'aide de la construction SQS.Queue de la bibliothèque Construct. AWS
import * as sqs from '@aws-cdk/aws-sqs';
new sqs.Queue(this, 'MyQueue', {
encryption: sqs.QueueEncryption.KMS_MANAGED
});Certains accessoires de configuration sont facultatifs et, dans de nombreux cas, ont des valeurs par défaut. Dans certains cas, tous les accessoires sont facultatifs et le dernier argument peut être totalement omis.
Attributs de ressource
La plupart des ressources de la bibliothèque AWS Construct exposent des attributs, qui sont résolus au moment du déploiement par AWS CloudFormation. Les attributs sont exposés sous forme de propriétés sur les classes de ressources avec le nom du type comme préfixe. L'exemple suivant montre comment obtenir l'URL d'une file d'attente Amazon SQS à l'aide de la propriété (queueUrlPython :queue_url).
import * as sqs from '@aws-cdk/aws-sqs';
const queue = new sqs.Queue(this, 'MyQueue');
const url = queue.queueUrl; // => A string representing a deploy-time valueConsultez Les jetons et le AWS CDK pour plus d'informations sur la façon dont les attributs du AWS CDK moment du déploiement sont codés sous forme de chaînes.
Ressources de référencement
Lorsque vous configurez des ressources, vous devez souvent référencer les propriétés d'une autre ressource. Voici quelques exemples :
-
Une ressource Amazon Elastic Container Service (Amazon ECS) nécessite une référence au cluster sur lequel elle s'exécute.
-
Une CloudFront distribution Amazon nécessite une référence au bucket Amazon Simple Storage Service (Amazon S3) contenant le code source.
Vous pouvez référencer les ressources de l'une des manières suivantes :
-
En transmettant une ressource définie dans votre application CDK, soit dans la même pile, soit dans une autre
-
En transmettant un objet proxy faisant référence à une ressource définie dans votre AWS compte, créé à partir d'un identifiant unique de la ressource (tel qu'un ARN)
Si la propriété d'une construction représente une construction pour une autre ressource, son type est celui du type d'interface de la construction. Par exemple, la construction Amazon ECS utilise une propriété cluster de typeecs.ICluster. Un autre exemple est la construction de CloudFront distribution qui prend une propriété sourceBucket (Python :source_bucket) de types3.IBucket.
Vous pouvez transmettre directement n'importe quel objet de ressource du type approprié défini dans la même AWS CDK application. L'exemple suivant définit un cluster Amazon ECS, puis l'utilise pour définir un service Amazon ECS.
const cluster = new ecs.Cluster(this, 'Cluster', { /*...*/ });
const service = new ecs.Ec2Service(this, 'Service', { cluster: cluster });Référencement de ressources dans une pile différente
Vous pouvez faire référence aux ressources d'une pile différente à condition qu'elles soient définies dans la même application et qu'elles se trouvent dans le même AWS environnement. Le schéma suivant est généralement utilisé :
-
Stockez une référence à la construction en tant qu'attribut de la pile qui produit la ressource. (Pour obtenir une référence à la pile de la construction actuelle, utilisez
Stack.of(this).) -
Transmettez cette référence au constructeur de la pile qui consomme la ressource en tant que paramètre ou propriété. La pile consommatrice la transmet ensuite en tant que propriété à toute construction qui en a besoin.
L'exemple suivant définit une pilestack1. Cette pile définit un compartiment Amazon S3 et stocke une référence à la structure du compartiment en tant qu'attribut de la pile. Ensuite, l'application définit une deuxième pilestack2, qui accepte un bucket lors de l'instanciation. stack2peut, par exemple, définir une AWS Glue table qui utilise le bucket pour le stockage des données.
const prod = { account: '123456789012', region: 'us-east-1' };
const stack1 = new StackThatProvidesABucket(app, 'Stack1', { env: prod });
// stack2 will take a property { bucket: IBucket }
const stack2 = new StackThatExpectsABucket(app, 'Stack2', {
bucket: stack1.bucket,
env: prod
});Si le AWS CDK détermine que la ressource se trouve dans le même environnement, mais dans une pile différente, il synthétise automatiquement les AWS CloudFormation exportations dans la pile productrice et un Fn : : ImportValue dans la pile consommatrice pour transférer ces informations d'une pile à l'autre.
Résoudre les blocages de dépendance
Le fait de référencer une ressource d'une pile dans une pile différente crée une dépendance entre les deux piles. Cela permet de s'assurer qu'ils sont déployés dans le bon ordre. Une fois les piles déployées, cette dépendance est concrète. Ensuite, la suppression de l'utilisation de la ressource partagée de la pile consommatrice peut entraîner un échec de déploiement inattendu. Cela se produit s'il existe une autre dépendance entre les deux piles qui les oblige à être déployées dans le même ordre. Cela peut également se produire sans dépendance si la pile productrice est simplement choisie par le CDK Toolkit pour être déployée en premier. L' AWS CloudFormation exportation est supprimée de la pile productrice car elle n'est plus nécessaire, mais la ressource exportée est toujours utilisée dans la pile consommatrice car sa mise à jour n'est pas encore déployée. Par conséquent, le déploiement de la pile de producteurs échoue.
Pour sortir de cette impasse, supprimez l'utilisation de la ressource partagée de la pile consommatrice. (Cela supprime l'exportation automatique de la pile de production.) Ajoutez ensuite manuellement la même exportation à la pile de production en utilisant exactement le même identifiant logique que l'exportation générée automatiquement. Supprimez l'utilisation de la ressource partagée dans la pile consommatrice et déployez les deux piles. Supprimez ensuite l'exportation manuelle (et la ressource partagée si elle n'est plus nécessaire) et déployez à nouveau les deux piles. La exportValue() méthode de la pile est un moyen pratique de créer l'exportation manuelle à cette fin. (Voir l'exemple dans la référence de méthode liée.)
Référencement des ressources de votre compte AWS
Supposons que vous souhaitiez utiliser une ressource déjà disponible dans votre AWS compte dans votre AWS CDK application. Il peut s'agir d'une ressource définie via la console, un AWS SDK, directement avec AWS CloudFormation ou dans une autre AWS CDK application. Vous pouvez transformer l'ARN de la ressource (ou un autre attribut d'identification, ou groupe d'attributs) en un objet proxy. L'objet proxy sert de référence à la ressource en appelant une méthode d'usine statique sur la classe de la ressource.
Lorsque vous créez un tel proxy, la ressource externe ne fait pas partie de votre AWS CDK application. Par conséquent, les modifications que vous apportez au proxy dans votre AWS CDK application n'affectent pas la ressource déployée. Le proxy peut toutefois être transmis à n'importe quelle AWS CDK méthode nécessitant une ressource de ce type.
L'exemple suivant montre comment référencer un bucket basé sur un bucket existant avec l'ARN arn:aws:s3 : ::amzn-s3-demo-bucket1, et un Amazon Virtual Private Cloud basé sur un VPC existant ayant un ID spécifique.
// Construct a proxy for a bucket by its name (must be same account)
s3.Bucket.fromBucketName(this, 'MyBucket', 'amzn-s3-demo-bucket1');
// Construct a proxy for a bucket by its full ARN (can be another account)
s3.Bucket.fromBucketArn(this, 'MyBucket', 'arn:aws:s3:::amzn-s3-demo-bucket1');
// Construct a proxy for an existing VPC from its attribute(s)
ec2.Vpc.fromVpcAttributes(this, 'MyVpc', {
vpcId: 'vpc-1234567890abcde',
});Regardons de plus près la Vpc.fromLookup()méthode. La ec2.Vpc construction étant complexe, vous pouvez sélectionner le VPC à utiliser avec votre application CDK de nombreuses manières. Pour résoudre ce problème, la construction VPC utilise une méthode fromLookup statique (Python :from_lookup) qui vous permet de rechercher le VPC Amazon souhaité en interrogeant votre AWS compte au moment de la synthèse.
Pour être utiliséVpc.fromLookup(), le système qui synthétise la pile doit avoir accès au compte propriétaire de l'Amazon VPC. Cela est dû au fait que le CDK Toolkit interroge le compte pour trouver le bon Amazon VPC au moment de la synthèse.
De plus, ne Vpc.fromLookup() fonctionne que dans les piles définies avec un compte et une région explicites (voirEnvironnements pour le AWS CDK). S'il AWS CDK essaie de rechercher un Amazon VPC à partir d'une pile indépendante de l'environnement, le CDK Toolkit ne sait pas quel environnement interroger pour trouver le VPC.
Vous devez fournir des Vpc.fromLookup() attributs suffisants pour identifier de manière unique un VPC dans votre AWS
compte. Par exemple, il ne peut y avoir qu'un seul VPC par défaut, il suffit donc de spécifier le VPC comme VPC par défaut.
ec2.Vpc.fromLookup(this, 'DefaultVpc', {
isDefault: true
});Vous pouvez également utiliser la tags propriété pour effectuer une recherche VPCs par balise. Vous pouvez ajouter des balises à l'Amazon VPC au moment de sa création en utilisant AWS CloudFormation ou le. AWS CDK Vous pouvez modifier les balises à tout moment après leur création à l'aide du SDK AWS Management Console AWS CLI, du ou d'un AWS SDK. En plus des balises que vous ajoutez vous-même, les balises suivantes AWS CDK sont automatiquement ajoutées à toutes les VPCs balises créées.
-
Nom — Le nom du VPC.
-
aws-cdk:subnet-name — Nom du sous-réseau.
-
aws-cdk:subnet-type — Type du sous-réseau : public, privé ou isolé.
ec2.Vpc.fromLookup(this, 'PublicVpc',
{tags: {'aws-cdk:subnet-type': "Public"}});Les résultats de Vpc.fromLookup() sont mis en cache dans le cdk.context.json fichier du projet. (Consultez Les valeurs contextuelles et le AWS CDK.) Passez ce fichier au contrôle de version afin que votre application continue de faire référence au même Amazon VPC. Cela fonctionne même si vous modifiez ultérieurement les attributs de votre VPCs VPC de manière à sélectionner un autre VPC. Cela est particulièrement important si vous déployez la pile dans un environnement qui n'a pas accès au AWS compte qui définit le VPC, tel que CDK Pipelines.
Bien que vous puissiez utiliser une ressource externe partout où vous utiliseriez une ressource similaire définie dans votre AWS CDK application, vous ne pouvez pas la modifier. Par exemple, appeler addToResourcePolicy (Python :add_to_resource_policy) sur un appareil externe s3.Bucket ne fait rien.
Noms physiques des ressources
Les noms logiques des ressources dans AWS CloudFormation sont différents des noms des ressources qui apparaissent AWS Management Console après leur déploiement par AWS CloudFormation. Les AWS CDK appels, ces derniers nomment des noms physiques.
Par exemple, AWS CloudFormation vous pouvez créer le compartiment Amazon S3 avec l'ID logique Stack2MyBucket4DD88B4F et le nom physiquestack2MyBucket4dd88b4f-iuv1rbv9z3to.
Vous pouvez spécifier un nom physique lors de la création de constructions représentant des ressources à l'aide de la propriété <resourceType> Name. L'exemple suivant crée un compartiment Amazon S3 avec le nom physiqueamzn-s3-demo-bucket.
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: 'amzn-s3-demo-bucket',
});L'attribution de noms physiques aux ressources présente certains inconvénients. AWS CloudFormation Plus important encore, toute modification des ressources déployées nécessitant le remplacement d'une ressource, telle que la modification des propriétés d'une ressource qui sont immuables après sa création, échouera si un nom physique est attribué à une ressource. Si vous vous retrouvez dans cet état, la seule solution est de supprimer la AWS CloudFormation pile, puis de déployer à nouveau l' AWS CDK application. Consultez la AWS CloudFormation documentation pour plus de détails.
Dans certains cas, par exemple lors de la création d'une AWS CDK application avec des références interenvironnementales, des noms physiques sont nécessaires pour AWS CDK qu'elle fonctionne correctement. Dans ces cas, si vous ne voulez pas vous embêter à trouver vous-même un nom physique, vous pouvez laisser le AWS CDK nom pour vous. Pour ce faire, utilisez la valeur spécialePhysicalName.GENERATE_IF_NEEDED, comme suit.
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: core.PhysicalName.GENERATE_IF_NEEDED,
});Transmission d'identifiants de ressources uniques
Dans la mesure du possible, vous devez transmettre les ressources par référence, comme décrit dans la section précédente. Cependant, dans certains cas, vous n'avez pas d'autre choix que de faire référence à une ressource par l'un de ses attributs. Les exemples de cas d'utilisation incluent les suivants :
-
Lorsque vous utilisez des AWS CloudFormation ressources de bas niveau.
-
Lorsque vous devez exposer des ressources aux composants d'exécution d'une AWS CDK application, par exemple lorsque vous faites référence à des fonctions Lambda par le biais de variables d'environnement.
Ces identifiants sont disponibles sous forme d'attributs sur les ressources, tels que les suivants.
bucket.bucketName lambdaFunc.functionArn securityGroup.groupArn
L'exemple suivant montre comment transmettre le nom d'un bucket généré à une AWS Lambda fonction.
const bucket = new s3.Bucket(this, 'Bucket');
new lambda.Function(this, 'MyLambda', {
// ...
environment: {
BUCKET_NAME: bucket.bucketName,
},
});Octroi d'autorisations entre les ressources
Les constructions de niveau supérieur permettent d'obtenir des autorisations avec le moindre privilège en proposant des exigences d'autorisation simples, basées sur l'intention ou explicites. APIs Par exemple, de nombreuses constructions L2 proposent des méthodes d'octroi que vous pouvez utiliser pour accorder à une entité (telle qu'un rôle ou un utilisateur IAM) l'autorisation d'utiliser la ressource, sans avoir à créer manuellement des déclarations d'autorisation IAM.
L'exemple suivant crée les autorisations permettant au rôle d'exécution d'une fonction Lambda de lire et d'écrire des objets dans un compartiment Amazon S3 particulier. Si le compartiment Amazon S3 est chiffré à l'aide d'une AWS KMS clé, cette méthode autorise également le rôle d'exécution de la fonction Lambda à déchiffrer avec la clé.
if (bucket.grantReadWrite(func).success) {
// ...
}Les méthodes de subvention renvoient un iam.Grant objet. Utilisez l'successattribut de l'Grantobjet pour déterminer si la subvention a été appliquée efficacement (par exemple, elle n'a peut-être pas été appliquée à des ressources externes). Vous pouvez également utiliser la méthode assertSuccess (Python :assert_success) de l'Grantobjet pour vérifier que la subvention a été correctement appliquée.
Si aucune méthode d'autorisation spécifique n'est disponible pour le cas d'utilisation en question, vous pouvez utiliser une méthode d'autorisation générique pour définir une nouvelle autorisation avec une liste d'actions spécifiée.
L'exemple suivant montre comment accorder à une fonction Lambda l'accès à l'action Amazon DynamoDB. CreateBackup
table.grant(func, 'dynamodb:CreateBackup');De nombreuses ressources, telles que les fonctions Lambda, nécessitent qu'un rôle soit assumé lors de l'exécution du code. Une propriété de configuration vous permet de spécifier uniam.IRole. Si aucun rôle n'est spécifié, la fonction crée automatiquement un rôle spécifiquement pour cet usage. Vous pouvez ensuite utiliser des méthodes d'attribution sur les ressources pour ajouter des instructions au rôle.
Les méthodes de subvention sont conçues à l'aide d'un niveau inférieur APIs pour la gestion des politiques IAM. Les politiques sont modélisées sous forme d'PolicyDocumentobjets. Ajoutez des instructions directement aux rôles (ou au rôle attaché à une construction) à l'aide de la addToRolePolicy méthode (Python :add_to_role_policy), ou à la politique d'une ressource (telle qu'une Bucket politique) à l'aide de la méthode addToResourcePolicy (Python :add_to_resource_policy).
Indicateurs de ressources et alarmes
De nombreuses ressources émettent CloudWatch des métriques qui peuvent être utilisées pour configurer des tableaux de bord de surveillance et des alarmes. Les constructions de niveau supérieur utilisent des méthodes métriques qui vous permettent d'accéder aux métriques sans rechercher le nom correct à utiliser.
L'exemple suivant montre comment définir une alarme lorsque le nombre d'une file ApproximateNumberOfMessagesNotVisible d'attente Amazon SQS dépasse 100.
import * as cw from '@aws-cdk/aws-cloudwatch';
import * as sqs from '@aws-cdk/aws-sqs';
import { Duration } from '@aws-cdk/core';
const queue = new sqs.Queue(this, 'MyQueue');
const metric = queue.metricApproximateNumberOfMessagesNotVisible({
label: 'Messages Visible (Approx)',
period: Duration.minutes(5),
// ...
});
metric.createAlarm(this, 'TooManyMessagesAlarm', {
comparisonOperator: cw.ComparisonOperator.GREATER_THAN_THRESHOLD,
threshold: 100,
// ...
});S'il n'existe aucune méthode pour une métrique particulière, vous pouvez utiliser la méthode métrique générale pour spécifier le nom de la métrique manuellement.
Les métriques peuvent également être ajoutées aux CloudWatch tableaux de bord. Consultez CloudWatch.
Trafic réseau
Dans de nombreux cas, vous devez activer les autorisations sur un réseau pour qu'une application fonctionne, par exemple lorsque l'infrastructure informatique doit accéder à la couche de persistance. Les ressources qui établissent ou écoutent les connexions exposent les méthodes qui permettent les flux de trafic, notamment la définition de règles de groupe de sécurité ou de réseau ACLs.
IConnectableles ressources ont une connections propriété qui constitue la passerelle vers la configuration des règles de trafic réseau.
Vous permettez aux données de circuler sur un chemin réseau donné à l'aide de allow méthodes. L'exemple suivant active les connexions HTTPS vers le Web et les connexions entrantes du groupe Amazon EC2 Auto Scalingfleet2.
import * as asg from '@aws-cdk/aws-autoscaling';
import * as ec2 from '@aws-cdk/aws-ec2';
const fleet1: asg.AutoScalingGroup = asg.AutoScalingGroup(/*...*/);
// Allow surfing the (secure) web
fleet1.connections.allowTo(new ec2.Peer.anyIpv4(), new ec2.Port({ fromPort: 443, toPort: 443 }));
const fleet2: asg.AutoScalingGroup = asg.AutoScalingGroup(/*...*/);
fleet1.connections.allowFrom(fleet2, ec2.Port.AllTraffic());Des ports par défaut sont associés à certaines ressources. Les exemples incluent l'écouteur d'un équilibreur de charge sur le port public et les ports sur lesquels le moteur de base de données accepte les connexions pour les instances d'une base de données Amazon RDS. Dans de tels cas, vous pouvez renforcer le contrôle du réseau sans avoir à spécifier manuellement le port. Pour ce faire, utilisez les allowToDefaultPort méthodes allowDefaultPortFrom et (Python :allow_default_port_from,allow_to_default_port).
L'exemple suivant montre comment activer les connexions depuis n'importe quelle IPV4 adresse et une connexion depuis un groupe Auto Scaling pour accéder à une base de données.
listener.connections.allowDefaultPortFromAnyIpv4('Allow public access');
fleet.connections.allowToDefaultPort(rdsDatabase, 'Fleet can access database');Gestion des événements
Certaines ressources peuvent servir de sources d'événements. Utilisez la addEventNotification méthode (Python :add_event_notification) pour enregistrer une cible d'événement pour un type d'événement particulier émis par la ressource. En outre, les addXxxNotification méthodes offrent un moyen simple d'enregistrer un gestionnaire pour les types d'événements courants.
L'exemple suivant montre comment déclencher une fonction Lambda lorsqu'un objet est ajouté à un compartiment Amazon S3.
import * as s3nots from '@aws-cdk/aws-s3-notifications';
const handler = new lambda.Function(this, 'Handler', { /*…*/ });
const bucket = new s3.Bucket(this, 'Bucket');
bucket.addObjectCreatedNotification(new s3nots.LambdaDestination(handler));Politiques de suppression
Les ressources qui conservent des données persistantes, telles que les bases de données, les compartiments Amazon S3 et les registres Amazon ECR, sont soumises à une politique de suppression. La politique de suppression indique s'il faut supprimer les objets persistants lorsque la AWS CDK
pile qui les contient est détruite. Les valeurs spécifiant la politique de suppression sont disponibles via l'RemovalPolicyénumération du AWS CDK core module.
Note
Les ressources autres que celles qui stockent des données de manière persistante peuvent également removalPolicy avoir une utilisation à des fins différentes. Par exemple, une version de fonction Lambda utilise un removalPolicy attribut pour déterminer si une version donnée est conservée lors du déploiement d'une nouvelle version. Elles ont des significations et des valeurs par défaut différentes de celles de la politique de suppression d'un bucket Amazon S3 ou d'une table DynamoDB.
| Valeur | Signification |
|---|---|
|
|
Conservez le contenu de la ressource lors de la destruction de la pile (par défaut). La ressource est devenue orpheline de la pile et doit être supprimée manuellement. Si vous tentez de redéployer la pile alors que la ressource existe toujours, vous recevrez un message d'erreur en raison d'un conflit de nom. |
|
|
La ressource sera détruite en même temps que la pile. |
AWS CloudFormation ne supprime pas les compartiments Amazon S3 contenant des fichiers, même si leur politique de suppression est définie sur. DESTROY Tenter de le faire est une AWS CloudFormation erreur. Pour AWS CDK supprimer tous les fichiers du bucket avant de le détruire, définissez la autoDeleteObjects propriété du bucket surtrue.
Vous trouverez ci-dessous un exemple de création d'un compartiment Amazon S3 avec RemovalPolicy of DESTROY et autoDeleteOjbects défini surtrue.
import * as cdk from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';
export class CdkTestStack extends cdk.Stack {
constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const bucket = new s3.Bucket(this, 'Bucket', {
removalPolicy: cdk.RemovalPolicy.DESTROY,
autoDeleteObjects: true
});
}
}Vous pouvez également appliquer une politique de suppression directement à la AWS CloudFormation ressource sous-jacente via la applyRemovalPolicy() méthode. Cette méthode est disponible sur certaines ressources dynamiques qui n'ont pas de removalPolicy propriété dans les accessoires de leur ressource L2. Voici quelques exemples :
-
AWS CloudFormation piles
-
Groupes d’utilisateurs Amazon Cognito
-
Instances de base de données Amazon DocumentDB
-
EC2 Volumes Amazon
-
Domaines Amazon OpenSearch Service
-
Systèmes de FSx fichiers Amazon
-
Files d'attente Amazon SQS
const resource = bucket.node.findChild('Resource') as cdk.CfnResource;
resource.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);Note
Le « AWS CDK s » RemovalPolicy se AWS CloudFormation traduit par « DeletionPolicy ». Cependant, la valeur par défaut AWS CDK est de conserver les données, ce qui est le contraire de la AWS CloudFormation valeur par défaut.
