Questa è la guida per sviluppatori AWS CDK v2. 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à.
Le risorse sono ciò che configuri per l'uso Servizi AWS nelle tue applicazioni. Le risorse sono una caratteristica di AWS CloudFormation. Configurando le risorse e le relative proprietà in un AWS CloudFormation modello, è possibile implementarlo per AWS CloudFormation eseguire il provisioning delle risorse. Con AWS Cloud Development Kit (AWS CDK), è possibile configurare le risorse tramite costrutti. Quindi distribuisci l'app CDK, che prevede la sintesi di un AWS CloudFormation modello e la sua implementazione per fornire le tue risorse. AWS CloudFormation
Configurazione delle risorse mediante costrutti
Come descritto inAWS CDK Costrutti, AWS CDK fornisce una ricca libreria di classi di costrutti, chiamati AWS costrutti, che rappresentano tutte le risorse. AWS
Per creare un'istanza di una risorsa utilizzando il costrutto corrispondente, inserite l'ambito come primo argomento, l'ID logico del costrutto e un insieme di proprietà di configurazione (props). Ad esempio, ecco come creare una coda Amazon SQS con AWS KMS crittografia utilizzando il costrutto SQS.Queue della Construct Library. AWS
import * as sqs from '@aws-cdk/aws-sqs';
new sqs.Queue(this, 'MyQueue', {
encryption: sqs.QueueEncryption.KMS_MANAGED
});Alcune proprietà di configurazione sono opzionali e in molti casi hanno valori predefiniti. In alcuni casi, tutti gli oggetti di scena sono opzionali e l'ultimo argomento può essere omesso completamente.
Attributi delle risorse
La maggior parte delle risorse della AWS Construct Library espongono gli attributi, che vengono risolti al momento della distribuzione da. AWS CloudFormation Gli attributi sono esposti sotto forma di proprietà sulle classi di risorse con il nome del tipo come prefisso. L'esempio seguente mostra come ottenere l'URL di una coda Amazon SQS utilizzando la proprietà (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 valueVedi Token e AWS CDK per informazioni su come AWS CDK codifica gli attributi di deploy-time come stringhe.
Risorse di riferimento
Quando si configurano le risorse, è spesso necessario fare riferimento alle proprietà di un'altra risorsa. Di seguito vengono mostrati gli esempi:
-
Una risorsa Amazon Elastic Container Service (Amazon ECS) richiede un riferimento al cluster su cui viene eseguita.
-
Una CloudFront distribuzione Amazon richiede un riferimento al bucket Amazon Simple Storage Service (Amazon S3) contenente il codice sorgente.
Puoi fare riferimento alle risorse in uno dei seguenti modi:
-
Passando una risorsa definita nell'app CDK, nello stesso stack o in uno diverso
-
Passando un oggetto proxy che fa riferimento a una risorsa definita nell' AWS account, creata da un identificatore univoco della risorsa (ad esempio un ARN)
Se la proprietà di un costrutto rappresenta un costrutto per un'altra risorsa, il suo tipo è quello del tipo di interfaccia del costrutto. Ad esempio, il costrutto Amazon ECS accetta una proprietà cluster di tipo. ecs.ICluster Un altro esempio è il costrutto di CloudFront distribuzione che accetta una proprietà sourceBucket (Pythonsource_bucket:) di tipo. s3.IBucket
È possibile passare direttamente qualsiasi oggetto risorsa del tipo corretto definito nella stessa AWS CDK app. L'esempio seguente definisce un cluster Amazon ECS e quindi lo utilizza per definire un servizio Amazon ECS.
const cluster = new ecs.Cluster(this, 'Cluster', { /*...*/ });
const service = new ecs.Ec2Service(this, 'Service', { cluster: cluster });Riferimento a risorse in uno stack diverso
Puoi fare riferimento a risorse in uno stack diverso purché siano definite nella stessa app e si trovino nello stesso ambiente. AWS In genere viene utilizzato lo schema seguente:
-
Memorizza un riferimento al costrutto come attributo dello stack che produce la risorsa. (Per ottenere un riferimento allo stack del costrutto corrente, usa.)
Stack.of(this) -
Passa questo riferimento al costruttore dello stack che consuma la risorsa come parametro o proprietà. Lo stack di consumo lo passa quindi come proprietà a qualsiasi costrutto che ne abbia bisogno.
L'esempio seguente definisce uno stack. stack1 Questo stack definisce un bucket Amazon S3 e memorizza un riferimento al costrutto del bucket come attributo dello stack. Quindi l'app definisce un secondo stack, stack2 che accetta un bucket al momento dell'istanziazione. stack2potrebbe, ad esempio, definire una AWS Glue tabella che utilizza il bucket per l'archiviazione dei dati.
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
});Se AWS CDK determina che la risorsa si trova nello stesso ambiente, ma in uno stack diverso, sintetizza automaticamente AWS CloudFormation le esportazioni nello stack di produzione e un Fn:: ImportValue nello stack di consumo per trasferire tali informazioni da uno stack all'altro.
Risoluzione delle situazioni di stallo legate alle dipendenze
Il riferimento a una risorsa da uno stack in uno stack diverso crea una dipendenza tra i due stack. In questo modo si assicura che vengano distribuiti nell'ordine corretto. Dopo l'implementazione degli stack, questa dipendenza è concreta. Dopodiché, la rimozione dell'uso della risorsa condivisa dallo stack di consumo può causare un errore di distribuzione imprevisto. Ciò accade se esiste un'altra dipendenza tra i due stack che li obbliga a essere distribuiti nello stesso ordine. Può avvenire anche senza dipendenza se lo stack di produzione viene semplicemente scelto dal CDK Toolkit per essere distribuito per primo. L' AWS CloudFormation esportazione viene rimossa dallo stack di produzione perché non è più necessaria, ma la risorsa esportata viene ancora utilizzata nello stack di consumo perché il relativo aggiornamento non è ancora stato distribuito. Pertanto, l'implementazione dello stack di produzione non riesce.
Per superare questa situazione di stallo, rimuovete l'uso della risorsa condivisa dallo stack di consumo. (Ciò rimuove l'esportazione automatica dallo stack di produzione.) Successivamente, aggiungete manualmente la stessa esportazione allo stack di produzione utilizzando esattamente lo stesso ID logico dell'esportazione generata automaticamente. Rimuovi l'uso della risorsa condivisa nello stack di consumo e distribuisci entrambi gli stack. Quindi, rimuovi l'esportazione manuale (e la risorsa condivisa se non è più necessaria) e distribuisci nuovamente entrambi gli stack. Il exportValue() metodo dello stack è un modo conveniente per creare l'esportazione manuale per questo scopo. (Vedi l'esempio nel riferimento al metodo collegato.)
Riferimento alle risorse presenti nel tuo account AWS
Supponiamo che tu voglia utilizzare una risorsa già disponibile nel tuo AWS account nella tua AWS CDK app. Potrebbe trattarsi di una risorsa definita tramite la console, un AWS SDK, direttamente con AWS CloudFormation o in un'altra AWS CDK applicazione. È possibile trasformare l'ARN della risorsa (o un altro attributo identificativo o gruppo di attributi) in un oggetto proxy. L'oggetto proxy funge da riferimento alla risorsa chiamando un metodo factory statico sulla classe della risorsa.
Quando crei un proxy di questo tipo, la risorsa esterna non diventa parte dell' AWS CDK app. Pertanto, le modifiche apportate al proxy nell' AWS CDK app non influiscono sulla risorsa distribuita. Il proxy può, tuttavia, essere passato a qualsiasi AWS CDK metodo che richieda una risorsa di quel tipo.
L'esempio seguente mostra come fare riferimento a un bucket basato su un bucket esistente con l'ARN arn:aws:s3: :amzn-s3-demo-bucket1 e a un Amazon Virtual Private Cloud basato su un VPC esistente con un ID specifico.
// 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',
});Vpc.fromLookup()Diamo un'occhiata più da vicino al metodo. Poiché il ec2.Vpc costrutto è complesso, ci sono molti modi in cui potresti voler selezionare il VPC da utilizzare con la tua app CDK. Per risolvere questo problema, il costrutto VPC ha un metodo fromLookup statico (Python:from_lookup) che consente di cercare il VPC Amazon desiderato interrogando il proprio account al momento della sintesi. AWS
Per poter essere utilizzatoVpc.fromLookup(), il sistema che sintetizza lo stack deve avere accesso all'account proprietario di Amazon VPC. Questo perché CDK Toolkit interroga l'account per trovare l'Amazon VPC giusto al momento della sintesi.
Inoltre, Vpc.fromLookup() funziona solo in pile definite con un account e una regione espliciti (vedi). Ambienti per AWS CDK Se AWS CDK tenta di cercare un Amazon VPC da uno stack indipendente dall'ambiente, CDK Toolkit non sa in quale ambiente interrogare per trovare il VPC.
Devi fornire Vpc.fromLookup() attributi sufficienti per identificare in modo univoco un VPC nel AWS
tuo account. Ad esempio, può esserci sempre un solo VPC predefinito, quindi è sufficiente specificare il VPC come predefinito.
ec2.Vpc.fromLookup(this, 'DefaultVpc', {
isDefault: true
});È inoltre possibile utilizzare la tags proprietà per eseguire query per VPCs tag. Puoi aggiungere tag ad Amazon VPC al momento della sua creazione utilizzando AWS CloudFormation o il. AWS CDK Puoi modificare i tag in qualsiasi momento dopo la creazione utilizzando il AWS Management Console AWS CLI, il o un AWS SDK. Oltre ai tag che aggiungi tu stesso, aggiunge AWS CDK automaticamente i seguenti tag a tutto ciò VPCs che crea.
-
Nome: il nome del VPC.
-
aws-cdk:subnet-name — Il nome della sottorete.
-
aws-cdk:subnet-type — Il tipo di sottorete: pubblica, privata o isolata.
ec2.Vpc.fromLookup(this, 'PublicVpc',
{tags: {'aws-cdk:subnet-type': "Public"}});I risultati di vengono memorizzati nella cache del file del progetto. Vpc.fromLookup() cdk.context.json Consultare I valori di contesto e il AWS CDK. Affida questo file al controllo della versione in modo che la tua app continui a fare riferimento allo stesso Amazon VPC. Funziona anche se successivamente modifichi gli attributi del tuo VPCs VPC in modo da selezionare un VPC diverso. Ciò è particolarmente importante se si implementa lo stack in un ambiente che non ha accesso all' AWS account che definisce il VPC, come CDK Pipelines.
Sebbene sia possibile utilizzare una risorsa esterna ovunque si utilizzi una risorsa simile definita nella propria AWS CDK app, non è possibile modificarla. Ad esempio, chiamare addToResourcePolicy (Python:add_to_resource_policy) su un dispositivo esterno s3.Bucket non fa nulla.
Nomi fisici delle risorse
I nomi logici delle risorse in AWS CloudFormation sono diversi dai nomi delle risorse visualizzati AWS Management Console dopo la loro distribuzione da AWS CloudFormation. Le AWS CDK chiamate, questi nomi finali, sono nomi fisici.
Ad esempio, AWS CloudFormation potrebbe creare il bucket Amazon S3 con l'ID logico Stack2MyBucket4DD88B4F e il nome fisico. stack2MyBucket4dd88b4f-iuv1rbv9z3to
È possibile specificare un nome fisico durante la creazione di costrutti che rappresentano risorse utilizzando la proprietà Name. <resourceType> L'esempio seguente crea un bucket Amazon S3 con il nome fisico. amzn-s3-demo-bucket
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: 'amzn-s3-demo-bucket',
});L'assegnazione di nomi fisici alle risorse presenta alcuni svantaggi in. AWS CloudFormation Soprattutto, qualsiasi modifica alle risorse distribuite che richieda la sostituzione di una risorsa, ad esempio le modifiche alle proprietà di una risorsa che sono immutabili dopo la creazione, avrà esito negativo se a una risorsa è assegnato un nome fisico. Se ti ritrovi in quello stato, l'unica soluzione è eliminare lo AWS CloudFormation stack, quindi distribuire nuovamente l'app. AWS CDK Consulta la AWS CloudFormation documentazione per i dettagli.
In alcuni casi, ad esempio quando si crea un' AWS CDK app con riferimenti interambientali, sono necessari nomi fisici AWS CDK per il corretto funzionamento dell'app. In questi casi, se non vuoi preoccuparti di inventarti un nome fisico, puoi lasciare che sia lui a AWS CDK chiamarlo per te. A tale scopo, utilizzate il valore specialePhysicalName.GENERATE_IF_NEEDED, come segue.
const bucket = new s3.Bucket(this, 'MyBucket', {
bucketName: core.PhysicalName.GENERATE_IF_NEEDED,
});Passaggio di identificatori di risorse univoci
Quando possibile, è necessario passare le risorse per riferimento, come descritto nella sezione precedente. Tuttavia, in alcuni casi non avete altra scelta che fare riferimento a una risorsa tramite uno dei suoi attributi. I casi d'uso di esempio includono quanto segue:
-
Quando si utilizzano AWS CloudFormation risorse di basso livello.
-
Quando è necessario esporre risorse ai componenti di runtime di un' AWS CDK applicazione, ad esempio quando si fa riferimento alle funzioni Lambda tramite variabili di ambiente.
Questi identificatori sono disponibili come attributi sulle risorse, come i seguenti.
bucket.bucketName lambdaFunc.functionArn securityGroup.groupArn
L'esempio seguente mostra come passare il nome di un bucket generato a una AWS Lambda funzione.
const bucket = new s3.Bucket(this, 'Bucket');
new lambda.Function(this, 'MyLambda', {
// ...
environment: {
BUCKET_NAME: bucket.bucketName,
},
});Concessione di autorizzazioni tra risorse
I costrutti di livello superiore consentono di ottenere le autorizzazioni con privilegi minimi offrendo requisiti di autorizzazione semplici, basati sull'intenzione di esprimere. APIs Ad esempio, molti costrutti L2 offrono metodi di concessione che è possibile utilizzare per concedere a un'entità (come un ruolo o un utente IAM) l'autorizzazione a lavorare con la risorsa, senza dover creare manualmente istruzioni di autorizzazione IAM.
L'esempio seguente crea le autorizzazioni per consentire al ruolo di esecuzione di una funzione Lambda di leggere e scrivere oggetti in un particolare bucket Amazon S3. Se il bucket Amazon S3 è crittografato con una AWS KMS chiave, questo metodo concede anche le autorizzazioni al ruolo di esecuzione della funzione Lambda per la decrittografia con la chiave.
if (bucket.grantReadWrite(func).success) {
// ...
}I metodi di concessione restituiscono un oggetto. iam.Grant Utilizzate l'successattributo dell'Grantoggetto per determinare se la concessione è stata effettivamente applicata (ad esempio, potrebbe non essere stata applicata a risorse esterne). Puoi anche usare il metodo assertSuccess (Python:assert_success) dell'Grantoggetto per far sì che la concessione sia stata applicata con successo.
Se un metodo di concessione specifico non è disponibile per il particolare caso d'uso, è possibile utilizzare un metodo di concessione generico per definire una nuova concessione con un elenco di azioni specificato.
L'esempio seguente mostra come concedere a una funzione Lambda l'accesso all'azione Amazon DynamoDB. CreateBackup
table.grant(func, 'dynamodb:CreateBackup');Molte risorse, come le funzioni Lambda, richiedono l'assunzione di un ruolo durante l'esecuzione del codice. Una proprietà di configurazione consente di specificare uniam.IRole. Se non viene specificato alcun ruolo, la funzione crea automaticamente un ruolo specifico per questo uso. È quindi possibile utilizzare i metodi di concessione sulle risorse per aggiungere istruzioni al ruolo.
I metodi di concessione sono creati utilizzando un livello inferiore APIs per la gestione con le politiche IAM. Le politiche sono modellate come oggetti. PolicyDocument Aggiungi istruzioni direttamente ai ruoli (o al ruolo associato a un costrutto) usando il addToRolePolicy metodo (Pythonadd_to_role_policy:) o alla politica di una risorsa (come Bucket una politica) usando il metodo addToResourcePolicy (add_to_resource_policyPython:).
Metriche e allarmi relativi alle risorse
Molte risorse emettono CloudWatch metriche che possono essere utilizzate per configurare dashboard di monitoraggio e allarmi. I costrutti di livello superiore dispongono di metodi metrici che consentono di accedere alle metriche senza cercare il nome corretto da utilizzare.
L'esempio seguente mostra come definire un allarme quando il numero ApproximateNumberOfMessagesNotVisible di una coda Amazon SQS supera 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,
// ...
});Se non esiste un metodo per una particolare metrica, puoi utilizzare il metodo metrico generale per specificare il nome della metrica manualmente.
Le metriche possono anche essere aggiunte ai dashboard. CloudWatch Per informazioni, consulta CloudWatch.
Traffico di rete
In molti casi, è necessario abilitare le autorizzazioni su una rete affinché un'applicazione funzioni, ad esempio quando l'infrastruttura di elaborazione deve accedere al livello di persistenza. Le risorse che stabiliscono o ascoltano le connessioni espongono metodi che abilitano i flussi di traffico, inclusa l'impostazione delle regole dei gruppi di sicurezza o della rete. ACLs
IConnectablele risorse hanno una connections proprietà che funge da gateway per la configurazione delle regole del traffico di rete.
È possibile abilitare il flusso dei dati su un determinato percorso di rete utilizzando allow metodi. L'esempio seguente abilita le connessioni HTTPS al Web e le connessioni in entrata dal gruppo Amazon EC2 Auto fleet2 Scaling.
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());Ad alcune risorse sono associate porte predefinite. Gli esempi includono il listener di un load balancer sulla porta pubblica e le porte su cui il motore di database accetta connessioni per le istanze di un database Amazon RDS. In questi casi, è possibile applicare un controllo rigoroso della rete senza dover specificare manualmente la porta. Per farlo, usa i allowToDefaultPort metodi allowDefaultPortFrom and (Python:allow_default_port_from,allow_to_default_port).
L'esempio seguente mostra come abilitare le connessioni da qualsiasi IPV4 indirizzo e una connessione da un gruppo Auto Scaling per accedere a un database.
listener.connections.allowDefaultPortFromAnyIpv4('Allow public access');
fleet.connections.allowToDefaultPort(rdsDatabase, 'Fleet can access database');Gestione degli eventi
Alcune risorse possono fungere da fonti di eventi. Usa il addEventNotification metodo (Python:add_event_notification) per registrare un obiettivo di evento su un particolare tipo di evento emesso dalla risorsa. Inoltre, i addXxxNotification metodi offrono un modo semplice per registrare un gestore per i tipi di eventi più comuni.
L'esempio seguente mostra come attivare una funzione Lambda quando un oggetto viene aggiunto a un bucket 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));Politiche di rimozione
Le risorse che mantengono dati persistenti, come database, bucket Amazon S3 e registri Amazon ECR, hanno una politica di rimozione. La politica di rimozione indica se eliminare gli oggetti persistenti quando lo AWS CDK
stack che li contiene viene distrutto. I valori che specificano la politica di rimozione sono disponibili tramite l'RemovalPolicyenumerazione nel modulo. AWS CDK core
Nota
Le risorse oltre a quelle che archiviano i dati in modo persistente potrebbero anche avere una removalPolicy che viene utilizzata per uno scopo diverso. Ad esempio, una versione della funzione Lambda utilizza un removalPolicy attributo per determinare se una determinata versione viene mantenuta quando viene distribuita una nuova versione. Questi hanno significati e impostazioni predefinite diversi rispetto alla politica di rimozione su un bucket Amazon S3 o una tabella DynamoDB.
| Valore | Significato |
|---|---|
|
|
Conserva il contenuto della risorsa quando distruggi lo stack (impostazione predefinita). La risorsa è rimasta orfana dallo stack e deve essere eliminata manualmente. Se tenti di ridistribuire lo stack mentre la risorsa esiste ancora, riceverai un messaggio di errore a causa di un conflitto di nomi. |
|
|
La risorsa verrà distrutta insieme allo stack. |
AWS CloudFormation non rimuove i bucket Amazon S3 che contengono file anche se la politica di rimozione è impostata su. DESTROY Tentare di farlo è un errore. AWS CloudFormation Per fare in modo che AWS CDK elimini tutti i file dal bucket prima di distruggerlo, imposta la proprietà del bucket su. autoDeleteObjects true
Di seguito è riportato un esempio di creazione di un bucket Amazon S3 con RemovalPolicy of DESTROY e autoDeleteOjbects impostato su. true
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
});
}
}Puoi anche applicare una politica di rimozione direttamente alla AWS CloudFormation risorsa sottostante tramite il applyRemovalPolicy() metodo. Questo metodo è disponibile su alcune risorse stateful che non hanno una removalPolicy proprietà negli oggetti di scena della risorsa L2. Considerare i seguenti esempi:
-
AWS CloudFormation pile
-
Pool di utenti Amazon Cognito
-
Istanze di database Amazon DocumentDB
-
EC2 Volumi Amazon
-
Domini Amazon OpenSearch Service
-
FSx File system Amazon
-
Code Amazon SQS
const resource = bucket.node.findChild('Resource') as cdk.CfnResource;
resource.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);Nota
La « AWS CDK s» RemovalPolicy si traduce in AWS CloudFormation«DeletionPolicys». Tuttavia, l'impostazione predefinita AWS CDK è quella di conservare i dati, che è l'opposto dell' AWS CloudFormation impostazione predefinita.
