View a markdown version of this page

Identificatori e CDK AWS - AWS Cloud Development Kit (AWS CDK) v2
Costruisci IDsPercorsiUnici IDsLogico IDs

Questa è la AWS CDK v2 Developer Guide. Il vecchio CDK v1 è entrato in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Identificatori e CDK AWS

Quando crei app AWS Cloud Development Kit (AWS CDK), utilizzerai molti tipi di identificatori e nomi. Per utilizzare il AWS CDK in modo efficace ed evitare errori, è importante comprendere i tipi di identificatori.

Gli identificatori devono essere unici nell'ambito in cui vengono creati; non è necessario che siano univoci a livello globale nell'applicazione CDK. AWS

Se si tenta di creare un identificatore con lo stesso valore all'interno dello stesso ambito, il AWS CDK genera un'eccezione.

Costruisci IDs

L'identificatore più comune,id, è l'identificatore passato come secondo argomento durante l'istanziazione di un oggetto di costruzione. Questo identificatore, come tutti gli identificatori, deve essere univoco solo nell'ambito in cui viene creato, che è il primo argomento quando si crea un'istanza di un oggetto di costruzione.

Nota

L'idof a stack è anche l'identificatore utilizzato per fare riferimento ad esso nel riferimento AWS CDK CLI.

Diamo un'occhiata a un esempio in cui abbiamo due costrutti con l'identificatore nella nostra app. MyBucket Il primo è definito nell'ambito dello stack con l'identificatore. Stack1 Il secondo è definito nell'ambito di uno stack con l'identificatore. Stack2 Poiché sono definiti in ambiti diversi, ciò non causa alcun conflitto e possono coesistere nella stessa app senza problemi.

Esempio
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");
    }
}

Percorsi

I costrutti in un'applicazione AWS CDK formano una gerarchia radicata nella classe. App Ci riferiamo alla raccolta di elementi IDs da un determinato costrutto, dal suo costrutto genitore, dal suo predecessore e così via fino alla radice dell'albero dei costrutti, come percorso.

Il AWS CDK in genere visualizza i percorsi nei modelli sotto forma di stringa. I livelli sono separati IDs da barre, a partire dal nodo immediatamente sotto l'Appistanza root, che di solito è una pila. Ad esempio, i percorsi delle due risorse del bucket Amazon S3 nell'esempio di codice precedente sono e. Stack1/MyBucket Stack2/MyBucket

È possibile accedere al percorso di qualsiasi costrutto a livello di codice, come illustrato nell'esempio seguente. Questo ottiene il percorso di myConstruct (omy_construct, come lo scriverebbero gli sviluppatori Python). Poiché IDs devono essere unici nell'ambito in cui vengono creati, i loro percorsi sono sempre unici all'interno di un'applicazione AWS CDK.

Esempio
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;

Unici IDs

AWS CloudFormation richiede che tutte le IDs logiche di un modello siano uniche. Per questo motivo, il AWS CDK deve essere in grado di generare un identificatore univoco per ogni costrutto di un'applicazione. Le risorse hanno percorsi univoci a livello globale (i nomi di tutti gli ambiti dallo stack a una risorsa specifica). Pertanto, il AWS CDK genera gli identificatori univoci necessari concatenando gli elementi del percorso e aggiungendo un hash a 8 cifre. (L'hash è necessario per distinguere percorsi distinti, come A/B/C eA/BC, che risulterebbero nello stesso identificatore. AWS CloudFormation AWS CloudFormation gli identificatori sono alfanumerici e non possono contenere barre o altri caratteri separatori.) Il AWS CDK chiama questa stringa l'ID univoco del costrutto.

In generale, la tua app AWS CDK non dovrebbe aver bisogno di conoscere l'unicità. IDs Tuttavia, potete accedere all'ID univoco di qualsiasi costrutto a livello di codice, come illustrato nell'esempio seguente.

Esempio
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'indirizzo è un altro tipo di identificatore univoco che distingue in modo univoco le risorse CDK. Derivato dall'hash SHA-1 del percorso, non è leggibile dall'uomo. Tuttavia, la sua lunghezza costante e relativamente breve (sempre 42 caratteri esadecimali) lo rende utile in situazioni in cui l'ID univoco «tradizionale» potrebbe essere troppo lungo. Alcuni costrutti possono utilizzare l'indirizzo nel AWS CloudFormation modello sintetizzato anziché l'ID univoco. Anche in questo caso, la tua app in genere non dovrebbe aver bisogno di conoscere gli indirizzi dei suoi costrutti, ma puoi recuperare l'indirizzo di un costrutto come segue.

Esempio
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;

Logico IDs

Quando il AWS CDK sintetizza l'app in un AWS CloudFormation modello, genera un ID logico per ogni risorsa. AWS CloudFormation utilizza la logica IDs per identificare le risorse all'interno di un modello e per tracciarle tra le distribuzioni. Comprendere come viene generata la logica IDs aiuta a evitare sostituzioni involontarie delle risorse quando si esegue il refactoring del codice CDK.

Come vengono generati i dati logici IDs

Il AWS CDK genera dati logici IDs dal percorso di costruzione utilizzando il seguente algoritmo:

  1. Concatena i componenti del percorso dall'albero di costruzione, escludendo lo stack stesso.

  2. Applica l'euristica per migliorare la leggibilità (vedi Euristica dei componenti del percorso Logical ID).

  3. Aggiungi un hash di 8 caratteri del percorso completo per garantire l'unicità.

Il formato risultante è:

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

Ad esempio, una tabella di routing di sottorete privata VPC potrebbe produrre l'ID logico. VPCPrivateSubnet2RouteTable0A19E10E

Le seguenti regole si applicano alla generazione di ID logici:

  • La lunghezza massima è 255 caratteri. La parte leggibile dall'uomo è limitata a 240 caratteri.

  • L'hash a 8 caratteri assicura che percorsi come A/B/C e, che si concatenano nella A/BC stessa stringa, producano logiche diverse. IDs

  • Le risorse che sono figlie dirette dello stack (percorsi a componente singolo) utilizzano il proprio nome direttamente senza un hash, purché il nome sia composto da 255 caratteri o meno.

Euristica dei componenti del percorso ID logico

Il AWS CDK applica la seguente euristica ai componenti del percorso quando genera la parte di logica leggibile dall'uomo. IDs

Default— rimosso completamente

Se un componente del percorso lo èDefault, il CDK lo rimuove sia dalla parte leggibile dall'uomo che dall'input hash. Ciò significa che racchiudere un costrutto esistente all'interno di un nuovo costrutto e denominare il costrutto interno produce esattamente lo stesso ID logico del costrutto Default originale non confezionato. Questo è il meccanismo chiave per rifattorizzare in modo sicuro il codice flat in costrutti di livello superiore senza modificare le identità delle risorse distribuite.

Resource— nascosto solo nella parte leggibile dall'uomo

Se un componente del percorso lo èResource, il CDK lo omette dalla parte leggibile dall'uomo ma lo include comunque nel calcolo dell'hash. Per convenzione, i costrutti L1 (CloudFormation) vengono utilizzati come ID di costruzione. Resource Ciò mantiene la logica IDs più breve senza perdere l'unicità.

Componenti consecutivi duplicati: deduplicati

Se il nome del componente del percorso precedente termina con il nome del componente corrente, il CDK ignora il componente corrente. Ciò impedisce ripetizioni ridondanti in logica. IDs

Si usa Default per preservare la logica IDs quando si esegue il refactoring

Quando rifattorizzate un flat stack in costrutti di livello superiore, potete utilizzarlo Default come ID del costrutto per la risorsa principale per preservarne l'ID logico. Ciò impedisce di sostituire la risorsa durante la AWS CloudFormation distribuzione.

L'esempio seguente mostra uno stack con risorse definite direttamente:

Esempio
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
}

Il percorso del bucket èMyStack/DataBucket/Resource, che produce un ID logico di. DataBucket<hash>

È possibile estrarre il bucket in un costrutto di livello superiore e conservare lo stesso ID logico denominando il costrutto interno: Default

Esempio
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
}

Il percorso del bucket è ora. MyStack/DataBucket/Default/Resource Poiché Default viene rimosso sia dalla parte leggibile dall'uomo che dall'hash input, l'ID logico rimane DataBucket<hash> identico all'originale.

Importante

È possibile avere un solo figlio con l'ID per ambito del costrutto. Default Se hai bisogno di più risorse allo stesso livello, definiscile in modo descrittivo IDs. Il Default modello funziona meglio con costrutti a responsabilità singola che hanno una risorsa primaria.

Considerazioni e limitazioni

Quando lavori con logic, tieni presente quanto segue: IDs

Stabilità dell'ID logico

Evita di modificare l'ID logico di una risorsa dopo che è stata creata. AWS CloudFormation identifica le risorse in base al relativo ID logico. Pertanto, se si modifica l'ID logico di una risorsa, AWS CloudFormation crea una nuova risorsa con il nuovo ID logico, quindi elimina quello esistente. A seconda del tipo di risorsa, ciò potrebbe causare l'interruzione del servizio, la perdita di dati o entrambe le cose.