View a markdown version of this page

Les identifiants et le CDK AWS - AWS Kit de développement Cloud (AWS CDK) v2
Construire IDsCheminsUnique IDsLogique IDs

Ceci est le guide du développeur du AWS CDK v2. 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 identifiants et le CDK AWS

Lorsque vous créez des applications AWS Cloud Development Kit (AWS CDK), vous utiliserez de nombreux types d'identifiants et de noms. Pour utiliser le AWS CDK de manière efficace et éviter les erreurs, il est important de comprendre les types d'identifiants.

Les identifiants doivent être uniques dans le cadre dans lequel ils ont été créés ; ils n'ont pas besoin d'être uniques globalement dans votre application AWS CDK.

Si vous tentez de créer un identifiant avec la même valeur dans la même portée, le AWS CDK génère une exception.

Construire IDs

L'identifiant le plus courant est l'identifiant passé comme deuxième argument lors de l'instanciation d'un objet de construction. id Cet identifiant, comme tous les identifiants, doit uniquement être unique dans le cadre dans lequel il a été créé, ce qui est le premier argument lors de l'instanciation d'un objet de construction.

Note

Le code id d'une pile est également l'identifiant que vous utilisez pour y faire référence dans la référence de la CLI AWS CDK.

Regardons un exemple où nous avons deux constructions avec l'identifiant MyBucket dans notre application. Le premier est défini dans le périmètre de la pile avec l'identifiantStack1. Le second est défini dans le périmètre d'une pile avec l'identifiantStack2. Comme ils sont définis dans des étendues différentes, cela ne provoque aucun conflit et ils peuvent coexister dans la même application sans problème.

Exemple
TypeScript
import { App, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyBucket');
  }
}

const app = new App();
new MyStack(app, 'Stack1');
new MyStack(app, 'Stack2');
JavaScript
const { App , Stack } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');

class MyStack extends Stack {
  constructor(scope, id, props = {}) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyBucket');
  }
}

const app = new App();
new MyStack(app, 'Stack1');
new MyStack(app, 'Stack2');
Python
from aws_cdk import App, Construct, Stack, StackProps
from constructs import Construct
from aws_cdk import aws_s3 as s3

class MyStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs):

        super().__init__(scope, id, **kwargs)
        s3.Bucket(self, "MyBucket")

app = App()
MyStack(app, 'Stack1')
MyStack(app, 'Stack2')
Java
// MyStack.java
package com.myorg;

import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.constructs.Construct;
import software.amazon.awscdk.services.s3.Bucket;

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        new Bucket(this, "MyBucket");
    }
}

// Main.java
package com.myorg;

import software.amazon.awscdk.App;

public class Main {
    public static void main(String[] args) {
        App app = new App();
        new MyStack(app, "Stack1");
        new MyStack(app, "Stack2");
    }
}
C#
using Amazon.CDK;
using constructs;
using Amazon.CDK.AWS.S3;

public class MyStack : Stack
{
    public MyStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
    {
        new Bucket(this, "MyBucket");
    }
}

class Program
{
    static void Main(string[] args)
    {
        var app = new App();
        new MyStack(app, "Stack1");
        new MyStack(app, "Stack2");
    }
}

Chemins

Les constructions d'une application AWS CDK forment une hiérarchie ancrée dans la App classe. Nous appelons chemin la collection IDs d'une construction donnée, de sa construction parente, de son grand-parent, etc. jusqu'à la racine de l'arbre de construction.

Le AWS CDK affiche généralement les chemins dans vos modèles sous forme de chaîne. Les niveaux IDs de départ sont séparés par des barres obliques, en commençant par le nœud situé juste sous l'Appinstance racine, qui est généralement une pile. Par exemple, les chemins des deux ressources du compartiment Amazon S3 dans l'exemple de code précédent sont Stack1/MyBucket etStack2/MyBucket.

Vous pouvez accéder au chemin de n'importe quelle construction par programmation, comme illustré dans l'exemple suivant. Cela permet d'obtenir le chemin de myConstruct (oumy_construct, comme l'écriraient les développeurs Python). Comme ils IDs doivent être uniques dans le cadre de leur création, leurs chemins sont toujours uniques au sein d'une application AWS CDK.

Exemple
TypeScript
const path: string = myConstruct.node.path;
JavaScript
const path = myConstruct.node.path;
Python
path = my_construct.node.path
Java
String path = myConstruct.getNode().getPath();
C#
string path = myConstruct.Node.Path;

Unique IDs

AWS CloudFormation exige que tous les éléments logiques IDs d'un modèle soient uniques. Pour cette raison, le AWS CDK doit être capable de générer un identifiant unique pour chaque construction d'une application. Les ressources ont des chemins globalement uniques (les noms de toutes les étendues de la pile vers une ressource spécifique). Par conséquent, le AWS CDK génère les identifiants uniques nécessaires en concaténant les éléments du chemin et en ajoutant un hachage à 8 chiffres. (Le hachage est nécessaire pour distinguer des chemins distincts, tels que A/B/C etA/BC, qui donneraient le même AWS CloudFormation identifiant. AWS CloudFormation les identifiants sont alphanumériques et ne peuvent pas contenir de barres obliques ou d'autres caractères de séparation.) Le AWS CDK appelle cette chaîne l'identifiant unique de la construction.

En général, votre application AWS CDK ne devrait pas avoir besoin de connaître l'unique IDs. Vous pouvez toutefois accéder à l'identifiant unique de n'importe quelle construction par programmation, comme indiqué dans l'exemple suivant.

Exemple
TypeScript
const uid: string = Names.uniqueId(myConstruct);
JavaScript
const uid = Names.uniqueId(myConstruct);
Python
uid = Names.unique_id(my_construct)
Java
String uid = Names.uniqueId(myConstruct);
C#
string uid = Names.Uniqueid(myConstruct);

L'adresse est un autre type d'identifiant unique qui distingue de manière unique les ressources CDK. Dérivé du hachage SHA-1 du chemin, il n'est pas lisible par l'homme. Cependant, sa longueur constante et relativement courte (toujours 42 caractères hexadécimaux) le rend utile dans les situations où l'identifiant unique « traditionnel » peut être trop long. Certaines constructions peuvent utiliser l'adresse du AWS CloudFormation modèle synthétisé au lieu de l'identifiant unique. Encore une fois, votre application ne devrait généralement pas avoir besoin de connaître les adresses de ses constructions, mais vous pouvez récupérer l'adresse d'une construction comme suit.

Exemple
TypeScript
const addr: string = myConstruct.node.addr;
JavaScript
const addr = myConstruct.node.addr;
Python
addr = my_construct.node.addr
Java
String addr = myConstruct.getNode().getAddr();
C#
string addr = myConstruct.Node.Addr;

Logique IDs

Lorsque le AWS CDK synthétise votre application dans un AWS CloudFormation modèle, il génère un identifiant logique pour chaque ressource. AWS CloudFormation utilise la logique IDs pour identifier les ressources au sein d'un modèle et pour les suivre d'un déploiement à l'autre. Comprendre comment la logique est générée IDs vous permet d'éviter les remplacements de ressources involontaires lorsque vous refactorisez votre code CDK.

Comment IDs les logiques sont-elles générées

Le AWS CDK génère une logique IDs à partir du chemin de construction en utilisant l'algorithme suivant :

  1. Concaténez les composants du chemin à partir de l'arbre de construction, à l'exception de la pile elle-même.

  2. Appliquez des heuristiques pour améliorer la lisibilité (voir Heuristique des composants du chemin d'identification logique).

  3. Ajoutez un hachage à 8 caractères du chemin complet pour garantir son unicité.

Le format obtenu est le suivant :

<human-readable-portion><8-character-hash>

Par exemple, une table de routage de sous-réseau privé VPC peut produire l'ID logique. VPCPrivateSubnet2RouteTable0A19E10E

Les règles suivantes s'appliquent à la génération d'identifiants logiques :

  • La longueur maximale est de 255 caractères. La partie lisible par l'homme est limitée à 240 caractères.

  • Le hachage à 8 caractères garantit que les chemins tels que A/B/C etA/BC, qui sont concaténés pour former la même chaîne, produisent une logique différente. IDs

  • Les ressources qui sont des enfants directs de la pile (chemins à composant unique) utilisent leur nom directement sans hachage, à condition que le nom comporte 255 caractères ou moins.

Heuristique des composants du chemin d'identification logique

Le AWS CDK applique les heuristiques suivantes aux composants du chemin lorsqu'il génère la partie logique lisible par l'homme. IDs

Default— entièrement supprimé

Si un composant de chemin l'estDefault, le CDK le supprime à la fois de la partie lisible par l'homme et de l'entrée de hachage. Cela signifie que le fait d'encapsuler une construction existante dans une nouvelle construction (et de nommer la construction interneDefault) produit exactement le même identifiant logique que la construction déballée d'origine. Il s'agit du mécanisme clé pour refactoriser en toute sécurité le code plat en constructions de niveau supérieur sans modifier l'identité des ressources déployées.

Resource— masqué uniquement dans la partie lisible par l'homme

Si un composant de chemin l'estResource, le CDK l'omet de la partie lisible par l'homme mais l'inclut toujours dans le calcul du hachage. Les constructions L1 (CloudFormation) utilisent Resource comme identifiant de construction par convention. Cela permet de IDs raccourcir la logique sans perdre son caractère unique.

Dupliquer des composants consécutifs — dédupliqués

Si le nom du composant de chemin précédent se termine par le nom du composant actuel, le CDK ignore le composant actuel. Cela permet d'éviter les répétitions redondantes dans la logique IDs.

DefaultÀ utiliser pour préserver la logique IDs lorsque vous refactorisez

Lorsque vous refactorisez une pile plate en constructions de niveau supérieur, vous pouvez l'utiliser Default comme ID de construction pour la ressource principale afin de préserver son identifiant logique. Cela AWS CloudFormation empêche le remplacement de la ressource lors du déploiement.

L'exemple suivant montre une pile avec des ressources définies directement :

Exemple
TypeScript
export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new s3.Bucket(this, 'DataBucket');
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}
JavaScript
class MyStack extends cdk.Stack {
  constructor(scope, id) {
    super(scope, id);
    new s3.Bucket(this, 'DataBucket');
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}
Python
from aws_cdk import (
    Stack,
    aws_s3 as s3,
    aws_lambda as _lambda,
)
from constructs import Construct

class MyStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)
        s3.Bucket(self, "DataBucket")
        _lambda.Function(self, "ProcessFunction", # ...
        )
Java
package com.myorg;

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        new Bucket(this, "DataBucket");
        Function.Builder.create(this, "ProcessFunction")
            // ...
            .build();
    }
}
C#
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;

namespace MyApp
{
    public class MyStack : Stack
    {
        public MyStack(Construct scope, string id, StackProps props = null) : base(scope, id, props)
        {
            new Bucket(this, "DataBucket");
            new Function(this, "ProcessFunction", new FunctionProps
            {
                // ...
            });
        }
    }
}
Go
package main

import (
	"github.com/aws/aws-cdk-go/awscdk/v2"
	"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
	"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
)

type MyStackProps struct {
	awscdk.StackProps
}

func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
	stack := awscdk.NewStack(scope, &id, &props.StackProps)

	awss3.NewBucket(stack, jsii.String("DataBucket"), &awss3.BucketProps{})
	awslambda.NewFunction(stack, jsii.String("ProcessFunction"), &awslambda.FunctionProps{
		// ...
	})

	return stack
}

Le chemin du bucket estMyStack/DataBucket/Resource, ce qui produit un ID logique deDataBucket<hash>.

Vous pouvez extraire le bucket dans une construction de niveau supérieur et conserver le même identifiant logique en nommant la construction interne : Default

Exemple
TypeScript
class DataPipeline extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new s3.Bucket(this, 'Default');  // 'Default' is hidden from logical ID
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new DataPipeline(this, 'DataBucket');
  }
}
JavaScript
class DataPipeline extends Construct {
  constructor(scope, id) {
    super(scope, id);
    new s3.Bucket(this, 'Default');  // 'Default' is hidden from logical ID
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}

class MyStack extends cdk.Stack {
  constructor(scope, id) {
    super(scope, id);
    new DataPipeline(this, 'DataBucket');
  }
}
Python
from aws_cdk import (
    Stack,
    aws_s3 as s3,
    aws_lambda as _lambda,
)
from constructs import Construct

class DataPipeline(Construct):
    def __init__(self, scope: Construct, id: str) -> None:
        super().__init__(scope, id)
        s3.Bucket(self, "Default")  # 'Default' is hidden from logical ID
        _lambda.Function(self, "ProcessFunction", # ...
        )

class MyStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)
        DataPipeline(self, "DataBucket")
Java
package com.myorg;

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;

public class DataPipeline extends Construct {
    public DataPipeline(final Construct scope, final String id) {
        super(scope, id);
        new Bucket(this, "Default");  // 'Default' is hidden from logical ID
        Function.Builder.create(this, "ProcessFunction")
            // ...
            .build();
    }
}

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        new DataPipeline(this, "DataBucket");
    }
}
C#
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;

namespace MyApp
{
    public class DataPipeline : Construct
    {
        public DataPipeline(Construct scope, string id) : base(scope, id)
        {
            new Bucket(this, "Default");  // 'Default' is hidden from logical ID
            new Function(this, "ProcessFunction", new FunctionProps
            {
                // ...
            });
        }
    }

    public class MyStack : Stack
    {
        public MyStack(Construct scope, string id, StackProps props = null) : base(scope, id, props)
        {
            new DataPipeline(this, "DataBucket");
        }
    }
}
Go
package main

import (
	"github.com/aws/aws-cdk-go/awscdk/v2"
	"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
	"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
)

type DataPipeline struct {
	constructs.Construct
}

func NewDataPipeline(scope constructs.Construct, id string) constructs.Construct {
	this := constructs.NewConstruct(scope, &id)

	// 'Default' is hidden from logical ID
	awss3.NewBucket(this, jsii.String("Default"), &awss3.BucketProps{})
	awslambda.NewFunction(this, jsii.String("ProcessFunction"), &awslambda.FunctionProps{
		// ...
	})

	return this
}

type MyStackProps struct {
	awscdk.StackProps
}

func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
	stack := awscdk.NewStack(scope, &id, &props.StackProps)

	NewDataPipeline(stack, "DataBucket")

	return stack
}

Le chemin du bucket est maintenantMyStack/DataBucket/Default/Resource. Comme il Default est supprimé à la fois de la partie lisible par l'homme et de l'entrée de hachage, l'identifiant logique reste DataBucket<hash> identique à l'original.

Important

Vous ne pouvez avoir qu'un seul enfant avec l'ID Default par étendue de construction. Si vous avez besoin de plusieurs ressources au même niveau, donnez-leur une description IDs. Le Default modèle fonctionne mieux avec les constructions à responsabilité unique qui ont une seule ressource principale.

Limites et considérations

Gardez les points suivants à l'esprit lorsque vous travaillez avec Lotical IDs :

  • Vous ne pouvez attribuer l'ID de Default construction qu'à un seul enfant par portée.

  • Si vous modifiez un ID de construction après le déploiement, l'ID logique change, ce qui AWS CloudFormation entraîne le remplacement de la ressource. cdk diffÀ utiliser pour vérifier les modifications avant le déploiement.

  • Dans les cas où la logique a IDs déjà changé, vous pouvez utiliser la cdk refactor commande pour associer l'ancienne logique IDs à la nouvelle. Pour plus d'informations, voir Préserver les ressources déployées lors de la refactorisation du code CDK.

  • Pour plus d'informations sur la façon dont la logique IDs apparaît dans les modèles synthétisés, consultez la section Logique générée IDs dans votre AWS CloudFormation modèle.

Stabilité de l'identifiant logique

Évitez de modifier l'ID logique d'une ressource après sa création. AWS CloudFormation identifie les ressources par leur identifiant logique. Par conséquent, si vous modifiez l'identifiant logique d'une ressource, AWS CloudFormation créez une nouvelle ressource avec le nouvel identifiant logique, puis supprimez l'identifiant existant. Selon le type de ressource, cela peut entraîner une interruption de service, une perte de données, ou les deux.