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à. # Migrazione da AWS CDK v1 a CDK v2 AWS La versione 2 del AWS Cloud Development Kit (AWS CDK) è progettata per semplificare la scrittura dell'infrastruttura come codice nel linguaggio di programmazione preferito. Questo argomento descrive le modifiche tra la v1 e la v2 del CDK. AWS **Suggerimento** [Per identificare gli stack distribuiti con AWS CDK v1, usa l'utilità awscdk-v1-stack-finder.](https://www.npmjs.com/package/awscdk-v1-stack-finder) Le principali modifiche AWS da CDK v1 a CDK v2 sono le seguenti. + AWS CDK v2 consolida le parti stabili della AWS Construct Library, inclusa la libreria principale, in un unico pacchetto,. `aws-cdk-lib` Gli sviluppatori non devono più installare pacchetti aggiuntivi per i singoli AWS servizi che utilizzano. Questo approccio a pacchetto singolo significa anche che non è necessario sincronizzare le versioni dei vari pacchetti della libreria CDK. I costrutti L1 (CFNxxxx), che rappresentano le esatte risorse disponibili in AWS CloudFormation, sono sempre considerati stabili e quindi sono inclusi. `aws-cdk-lib` + I moduli sperimentali, in cui stiamo ancora collaborando con la comunità per sviluppare nuovi costrutti [L2 o L3](constructs.md#constructs-lib-levels), non sono inclusi. `aws-cdk-lib` Vengono invece distribuiti come pacchetti singoli. I pacchetti sperimentali sono denominati con un `alpha` suffisso e un numero di versione semantico. Il numero di versione semantico corrisponde alla prima versione della AWS Construct Library con cui sono compatibili, anch'essa con un suffisso. `alpha` I costrutti entrano in gioco `aws-cdk-lib` dopo essere stati designati come stabili, permettendo alla Construct Library principale di aderire a un rigoroso sistema di versioni semantiche. La stabilità è specificata a livello di servizio. Ad esempio, se iniziamo a creare uno o più [costrutti L2](constructs.md#constructs-lib-levels) per Amazon AppFlow, che al momento della stesura di questo documento ha solo costrutti L1, questi appaiono per la prima volta in un modulo denominato. `@aws-cdk/aws-appflow-alpha` Poi, passano a `aws-cdk-lib` quando riteniamo che i nuovi costrutti soddisfino le esigenze fondamentali dei clienti. Una volta che un modulo è stato designato stabile e incorporato`aws-cdk-lib`, APIs ne vengono aggiunti di nuovi utilizzando la convenzione «BetAN» descritta nel prossimo bullet. Una nuova versione di ogni modulo sperimentale viene rilasciata con ogni versione del AWS CDK. Per la maggior parte, tuttavia, non è necessario mantenerli sincronizzati. Puoi aggiornare `aws-cdk-lib` il modulo sperimentale ogni volta che vuoi. L'eccezione è che quando due o più moduli sperimentali correlati dipendono l'uno dall'altro, devono avere la stessa versione. + Per i moduli stabili a cui vengono aggiunte nuove funzionalità, i nuovi APIs (siano essi costrutti completamente nuovi o nuovi metodi o proprietà su un costrutto esistente) ricevono un `Beta1` suffisso mentre il lavoro è in corso. (Seguito da `Beta2``Beta3`, e così via quando sono necessarie modifiche sostanziali). Una versione dell'API senza il suffisso viene aggiunta quando l'API è designata stabile. Tutti i metodi tranne il più recente (versione beta o finale) vengono quindi obsoleti. Ad esempio, se aggiungiamo un nuovo metodo `grantPower()` a un costrutto, inizialmente appare come. `grantPowerBeta1()` Se sono necessarie modifiche sostanziali (ad esempio, un nuovo parametro o proprietà obbligatorio), verrà denominata `grantPowerBeta2()` la versione successiva del metodo e così via. Quando il lavoro è completo e l'API è finalizzata, viene aggiunto il metodo `grantPower()` (senza suffisso) e i metodi BetAN diventano obsoleti. Tutte le versioni beta APIs rimarranno nella Construct Library fino alla prossima versione principale (3.0) e le relative firme non cambieranno. Se li utilizzate, vedrete degli avvisi di obsolescenza, quindi dovreste passare alla versione finale dell'API il prima possibile. Tuttavia, nessuna versione futura di AWS CDK 2.x interromperà l'applicazione. + La `Construct` classe è stata estratta dal AWS CDK in una libreria separata, insieme ai tipi correlati. Questo viene fatto per supportare gli sforzi volti ad applicare il Construct Programming Model ad altri domini. Se state scrivendo i vostri costrutti o state usando related APIs, dovete dichiarare il `constructs` modulo come dipendenza e apportare piccole modifiche alle importazioni. Se utilizzi funzionalità avanzate, come il collegamento al ciclo di vita dell'app CDK, potrebbero essere necessarie ulteriori modifiche. [Per tutti i dettagli, consulta la RFC.](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0192-remove-constructs-compat.md#release-notes) + Le proprietà, i metodi e i tipi obsoleti in AWS CDK v1.x e nella relativa Construct Library sono stati rimossi completamente dall'API CDK v2. Nella maggior parte delle lingue supportate, questi APIs generano avvisi nella versione 1.x, quindi potresti aver già effettuato la migrazione alla versione sostitutiva. APIs Un [elenco completo delle versioni obsolete di CDK v1.x è disponibile su. APIs](https://github.com/aws/aws-cdk/blob/master/DEPRECATED_APIs.md) GitHub + Il comportamento limitato dai flag di funzionalità in CDK v1.x è abilitato di default in AWS CDK v2. I contrassegni di funzionalità precedenti non sono più necessari e nella maggior parte dei casi non sono supportati. Alcuni sono ancora disponibili per consentire di ripristinare il comportamento di CDK v1 in circostanze molto specifiche. Per ulteriori informazioni, vedete [Aggiornamento dei](#migrating-v2-v1-upgrade-cdk-json) flag di funzionalità. + Con CDK v2, gli ambienti in cui vengono implementati devono essere avviati utilizzando il moderno stack di bootstrap. Lo stack di bootstrap legacy (predefinito nella versione v1) non è più supportato. CDK v2 richiede inoltre una nuova versione dello stack moderno. Per aggiornare gli ambienti esistenti, riavviali. Non è più necessario impostare alcun flag di funzionalità o variabile di ambiente per utilizzare il moderno stack di bootstrap. **Importante** Il moderno modello di bootstrap concede efficacemente le autorizzazioni implicite da a qualsiasi account nell'`--cloudformation-execution-policies`elenco. AWS `--trust` Per impostazione predefinita, questo estende le autorizzazioni di lettura e scrittura a qualsiasi risorsa nell'account avviato. Assicurati di [configurare lo stack di bootstrap](bootstrapping-customizing.md) con politiche e account affidabili con cui ti senti a tuo agio. ## Nuovi prerequisiti La maggior parte dei requisiti per AWS CDK v2 sono gli stessi di CDK v1.x. AWS I requisiti aggiuntivi sono elencati qui. + Per TypeScript gli sviluppatori, è richiesta la versione TypeScript 3.8 o successiva. + È necessaria una nuova versione del CDK Toolkit per l'uso con CDK v2. Ora che CDK v2 è generalmente disponibile, la v2 è la versione predefinita per l'installazione di CDK Toolkit. È retrocompatibile con i progetti CDK v1, quindi non è necessario mantenere installata la versione precedente a meno che non si desideri creare progetti CDK v1. Per eseguire l'aggiornamento, emetti. `npm install -g aws-cdk` ## Aggiornamento da AWS CDK v2 Developer Preview Se utilizzi CDK v2 Developer Preview, il tuo progetto dipende da una versione Release Candidate del CDK, ad esempio. AWS `2.0.0-rc1` Aggiorna questi moduli a`2.0.0`, quindi aggiorna i moduli installati nel progetto. **Example** `npm install` o `yarn install` `npm install` o `yarn install` ``` python -m pip install -r requirements.txt ``` ``` mvn package ``` ``` dotnet restore ``` ``` go get ``` Dopo aver aggiornato le dipendenze, esegui l'aggiornamento `npm update -g aws-cdk` di CDK Toolkit alla versione di rilascio. ## Migrazione da AWS CDK v1 a CDK v2 Per migrare la tua app a AWS CDK v2, aggiorna prima i flag delle funzionalità in. `cdk.json` Quindi aggiorna le dipendenze e le importazioni dell'app secondo necessità per il linguaggio di programmazione in cui è scritta. ### Aggiornamento a una versione v1 recente Stiamo assistendo all'aggiornamento da una vecchia versione di AWS CDK v1 alla versione più recente della v2 in un unico passaggio. Anche se è certamente possibile farlo, si comporterebbe sia l'aggiornamento dopo diversi anni di modifiche (che sfortunatamente non tutti sono stati sottoposti alla stessa quantità di test evolutivi che eseguiamo oggi), sia l'aggiornamento tra versioni con nuove impostazioni predefinite e un'organizzazione del codice diversa. Per un'esperienza di aggiornamento più sicura e per diagnosticare più facilmente l'origine di eventuali modifiche impreviste, ti consigliamo di separare questi due passaggi: prima esegui l'aggiornamento alla versione v1 più recente, quindi passa alla v2. ### Aggiornamento dei contrassegni delle funzionalità Rimuovi i seguenti flag di funzionalità della v1, `cdk.json` se esistono, poiché sono tutti attivi per impostazione predefinita in AWS CDK v2. Se il loro vecchio effetto è importante per l'infrastruttura, sarà necessario apportare modifiche al codice sorgente. Per ulteriori informazioni, consulta [l'elenco delle bandiere su GitHub](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cx-api/FEATURE_FLAGS.md). + `@aws-cdk/core:enableStackNameDuplicates` + `aws-cdk:enableDiffNoFail` + `@aws-cdk/aws-ecr-assets:dockerIgnoreSupport` + `@aws-cdk/aws-secretsmanager:parseOwnedSecretName` + `@aws-cdk/aws-kms:defaultKeyPolicies` + `@aws-cdk/aws-s3:grantWriteWithoutAcl` + `@aws-cdk/aws-efs:defaultEncryptionAtRest` È possibile impostare alcuni flag di funzionalità della versione 1 per `false` ripristinare comportamenti specifici di AWS CDK v1; per un riferimento completo, vedere [Ripristino del comportamento della versione 1 o l'elenco successivo](featureflags.md#featureflags-disabling). GitHub Per entrambi i tipi di flag, utilizzate il `cdk diff` comando per controllare le modifiche al modello sintetizzato per vedere se le modifiche a uno di questi flag influiscono sulla vostra infrastruttura. ### Compatibilità con CDK Toolkit CDK v2 richiede la versione 2 o successiva del CDK Toolkit. Questa versione è retrocompatibile con le app CDK v1. Pertanto, puoi utilizzare un'unica versione di CDK Toolkit installata a livello globale con tutti i tuoi progetti CDK, indipendentemente dal fatto che utilizzino la v1 AWS o la v2. Un'eccezione è che CDK Toolkit v2 crea solo progetti CDK v2. **Se è necessario creare progetti CDK v1 e v2, non installate CDK Toolkit v2 a livello globale.** (Rimuovilo se lo hai già installato:.) `npm remove -g aws-cdk` Per richiamare CDK Toolkit, usate `npx` to run v1 o v2 del CDK Toolkit come desiderate. ``` npx aws-cdk@1.x init app --language typescript npx aws-cdk@2.x init app --language typescript ``` **Suggerimento** Imposta gli alias della riga di comando in modo da poter utilizzare `cdk1` i comandi `cdk` and per richiamare la versione desiderata di CDK Toolkit. ``` alias cdk1="npx aws-cdk@1.x" alias cdk="npx aws-cdk@2.x" ``` ``` doskey cdk1=npx aws-cdk@1.x $* doskey cdk=npx aws-cdk@2.x $* ``` ### Aggiornamento delle dipendenze e delle importazioni Aggiorna le dipendenze dell'app, quindi installa i nuovi pacchetti. Infine, aggiorna le importazioni nel codice. **Example** **Applicazioni** Per le app CDK, esegui l'aggiornamento `package.json` come segue. Rimuovi le dipendenze dai singoli moduli stabili in stile v1 e stabilisci la versione più bassa richiesta per la tua applicazione (2.0.0 qui). `aws-cdk-lib` I costrutti sperimentali sono forniti in pacchetti separati, con versioni indipendenti, con nomi che terminano con e un numero di versione alfa. `alpha` Il numero di versione alpha corrisponde alla prima versione `aws-cdk-lib` con cui sono compatibili. Qui, abbiamo aggiunto la versione `aws-codestar` v2.0.0-alpha.1. ``` { "dependencies": { "aws-cdk-lib": "^2.0.0", "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1", "constructs": "^10.0.0" } } ``` **Costruisci librerie** Per le librerie di costruzione, stabilisci la versione più bassa richiesta per la tua applicazione (2.0.0 qui) e aggiorna come segue. `aws-cdk-lib` `package.json` Nota che `aws-cdk-lib` appare sia come dipendenza tra pari che come dipendenza di sviluppo. ``` { "peerDependencies": { "aws-cdk-lib": "^2.0.0", "constructs": "^10.0.0" }, "devDependencies": { "aws-cdk-lib": "^2.0.0", "constructs": "^10.0.0", "typescript": "~3.9.0" } } ``` Quando si rilascia una libreria compatibile con v2, è necessario eseguire un aumento importante della versione del numero di versione della libreria, poiché si tratta di una modifica fondamentale per gli utenti delle biblioteche. Non è possibile supportare sia CDK v1 che v2 con una singola libreria. Per continuare a supportare i clienti che utilizzano ancora la v1, puoi mantenere la versione precedente in parallelo o creare un nuovo pacchetto per la v2. Sei tu a decidere per quanto tempo vuoi continuare a supportare i clienti AWS CDK v1. Potresti prendere spunto dal ciclo di vita del CDK v1 stesso, che è entrato in manutenzione il 1° giugno 2022 e terminerà il 1° giugno 2023. end-of-life [Per tutti i dettagli, consulta la Politica di manutenzione di CDK.AWS](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0079-cdk-2.0.md#aws-cdk-maintenance-policy) **Sia le librerie che le app** Installa le nuove dipendenze eseguendo `npm install` o`yarn install`. Modificate le importazioni in modo `Construct` da importare dal nuovo `constructs` modulo i tipi principali (ad esempio `App` e `Stack` dal livello superiore di`aws-cdk-lib`) e i moduli stabili di Construct Library per i servizi utilizzati dai namespace sottostanti. `aws-cdk-lib` ``` import { Construct } from 'constructs'; import { App, Stack } from 'aws-cdk-lib'; // core constructs import { aws_s3 as s3 } from 'aws-cdk-lib'; // stable module import * as codestar from '@aws-cdk/aws-codestar-alpha'; // experimental module ``` Aggiorna come segue. `package.json` Rimuovi le dipendenze dai singoli moduli stabili in stile v1 e stabilisci la versione più bassa richiesta per la tua applicazione (2.0.0 qui). `aws-cdk-lib` I costrutti sperimentali sono forniti in pacchetti separati, con versioni indipendenti, con nomi che terminano con e un numero di versione alfa. `alpha` Il numero di versione alpha corrisponde alla prima versione `aws-cdk-lib` con cui sono compatibili. Qui, abbiamo aggiunto la versione `aws-codestar` v2.0.0-alpha.1. ``` { "dependencies": { "aws-cdk-lib": "^2.0.0", "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1", "constructs": "^10.0.0" } } ``` Installa le nuove dipendenze eseguendo o. `npm install` `yarn install` Modifica le importazioni dell'app per effettuare le seguenti operazioni: + Importa `Construct` dal nuovo `constructs` modulo + Importa i tipi principali, come `App` e`Stack`, dal livello superiore di `aws-cdk-lib` + Importa AWS i moduli di Construct Library dai namespace in `aws-cdk-lib` ``` const { Construct } = require('constructs'); const { App, Stack } = require('aws-cdk-lib'); // core constructs const s3 = require('aws-cdk-lib').aws_s3; // stable module const codestar = require('@aws-cdk/aws-codestar-alpha'); // experimental module ``` Aggiorna `requirements.txt` la `install_requires` definizione come segue. `setup.py` Rimuovi le dipendenze dai singoli moduli stabili in stile v1. I costrutti sperimentali sono forniti in pacchetti separati, con versioni indipendenti, con nomi che terminano con `alpha` e un numero di versione alfa. Il numero di versione alpha corrisponde alla prima versione `aws-cdk-lib` con cui sono compatibili. Qui, abbiamo bloccato la versione `aws-codestar` v2.0.0alpha1. ``` install_requires=[ "aws-cdk-lib>=2.0.0", "constructs>=10.0.0", "aws-cdk.aws-codestar-alpha>=2.0.0alpha1", # ... ], ``` Disinstalla tutte le altre versioni dei moduli AWS CDK già installate nell'ambiente virtuale dell'app utilizzando. `pip uninstall` Quindi installa le nuove dipendenze con. `python -m pip install -r requirements.txt` Modifica le importazioni dell'app per effettuare le seguenti operazioni: + Importa `Construct` dal nuovo `constructs` modulo + Importa i tipi principali, come `App` e`Stack`, dal livello superiore di `aws_cdk` + Importa AWS i moduli di Construct Library dai namespace in `aws_cdk` ``` from constructs import Construct from aws_cdk import App, Stack # core constructs from aws_cdk import aws_s3 as s3 # stable module import aws_cdk.aws_codestar_alpha as codestar # experimental module # ... class MyConstruct(Construct): # ... class MyStack(Stack): # ... s3.Bucket(...) ``` In`pom.xml`, rimuovi tutte le `software.amazon.awscdk` dipendenze per i moduli stabili e sostituiscile con dipendenze da (for) e. `software.constructs` `Construct` `software.amazon.awscdk` I costrutti sperimentali sono forniti in pacchetti separati, con versioni indipendenti, con nomi che terminano con `alpha` e un numero di versione alfa. Il numero di versione alpha corrisponde alla prima versione `aws-cdk-lib` con cui sono compatibili. Qui, abbiamo aggiunto la versione `aws-codestar` v2.0.0-alpha.1. ``` software.amazon.awscdk aws-cdk-lib 2.0.0 software.amazon.awscdk code-star-alpha 2.0.0-alpha.1 software.constructs constructs 10.0.0 ``` Installa le nuove dipendenze eseguendo. `mvn package` Modifica il codice per eseguire le seguenti operazioni: + Importa `Construct` dalla nuova `software.constructs` libreria + Importa le classi principali, ad esempio `Stack` e `App` da `software.amazon.awscdk` + Importa costrutti di servizio da `software.amazon.awscdk.services` ``` import software.constructs.Construct; import software.amazon.awscdk.Stack; import software.amazon.awscdk.StackProps; import software.amazon.awscdk.App; import software.amazon.awscdk.services.s3.Bucket; import software.amazon.awscdk.services.codestar.alpha.GitHubRepository; ``` Il modo più semplice per aggiornare le dipendenze di un'applicazione C\$1 CDK consiste nel modificare il file manualmente. `.csproj` Rimuovi tutti i riferimenti stabili ai `Amazon.CDK.*` pacchetti e sostituiscili con riferimenti ai pacchetti and. `Amazon.CDK.Lib` `Constructs` I costrutti sperimentali sono forniti in pacchetti separati, con versioni indipendenti, con nomi che terminano con `alpha` e un numero di versione alfa. Il numero di versione alpha corrisponde alla prima versione `aws-cdk-lib` con cui sono compatibili. Qui, abbiamo aggiunto la versione `aws-codestar` v2.0.0-alpha.1. ``` ``` Installa le nuove dipendenze eseguendo. `dotnet restore` Modifica le importazioni nei tuoi file sorgente come segue. ``` using Constructs; // for Construct class using Amazon.CDK; // for core classes like App and Stack using Amazon.CDK.AWS.S3; // for stable constructs like Bucket using Amazon.CDK.Codestar.Alpha; // for experimental constructs ``` Problema `go get` per aggiornare le dipendenze alla versione più recente e aggiornare il `.mod` file del progetto. ## Verifica dell'app migrata prima della distribuzione Prima di distribuire gli stack, usali per verificare eventuali modifiche impreviste `cdk diff` alle risorse. **Non** sono previste modifiche alla logica IDs (che causano la sostituzione delle risorse). Le modifiche previste includono, a titolo esemplificativo ma non esaustivo: + Modifiche alla `CDKMetadata` risorsa. + Hash degli asset aggiornati. + Modifiche relative alla sintesi dello stack di nuova concezione. Si applica se l'app utilizzava il sintetizzatore stack legacy nella v1. + L'aggiunta di una regola. `CheckBootstrapVersion` Le modifiche impreviste in genere non sono causate dall'aggiornamento a AWS CDK v2 di per sé. Di solito, sono il risultato di un comportamento obsoleto che in precedenza era stato modificato dai flag di funzionalità. Questo è un sintomo dell'aggiornamento da una versione di CDK precedente alla 1.85.x circa. Le stesse modifiche si vedrebbero eseguendo l'aggiornamento all'ultima versione v1.x. Di solito puoi risolvere questo problema effettuando le seguenti operazioni: 1. Aggiorna la tua app all'ultima versione v1.x 1. Rimuovi i contrassegni delle funzionalità 1. Se necessario, modificate il codice 1. Implementazione 1. Esegui l'aggiornamento alla v2 **Nota** [Se l'app aggiornata non è più utilizzabile dopo l'aggiornamento in due fasi, segnala il problema.](https://github.com/aws/aws-cdk/issues/new/choose) Quando sei pronto per distribuire gli stack nella tua app, valuta la possibilità di distribuirne prima una copia in modo da poterla testare. Il modo più semplice per farlo è distribuirla in un'altra regione. Tuttavia, puoi anche modificare lo IDs stack. Dopo il test, assicurati di distruggere la copia di prova con`cdk destroy`. ## Risoluzione dei problemi **TypeScript `'from' expected`o `';' expected` errore nelle importazioni** Aggiornamento alla versione TypeScript 3.8 o successiva. **Esegui 'cdk bootstrap'** Se vedi un errore come il seguente: ``` ❌ MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html) at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13) at processTicksAndRejections (internal/process/task_queues.js:97:5) MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html) ``` AWS CDK v2 richiede uno stack di bootstrap aggiornato e, inoltre, tutte le distribuzioni v2 richiedono risorse bootstrap. (Con la v1, puoi implementare stack semplici senza bootstrap.) [Per i dettagli completi, consulta CDK bootstrapping.AWS](bootstrapping.md) ## Trovare gli stack v1 Durante la migrazione dell'applicazione CDK dalla v1 alla v2, potresti voler identificare gli stack distribuiti AWS CloudFormation che sono stati creati utilizzando v1. Per fare ciò, esegui il seguente comando: ``` npx awscdk-v1-stack-finder ``` [Per i dettagli sull'utilizzo, consulta il file README di awscdk-v1-stack-finder.](https://github.com/cdklabs/awscdk-v1-stack-finder/blob/main/README.md)