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à.

Conserva le risorse distribuite durante il refactoring del codice CDK

Con il refactoring del AWS Cloud Development Kit (AWS CDK), puoi eseguire il refactoring del codice CDK, ad esempio rinominando i costrutti, spostando le risorse tra gli stack e riorganizzando l'applicazione, preservando al contempo le risorse distribuite anziché sostituirle. Questa funzionalità ti aiuta a mantenere buone pratiche di ingegneria del software senza comportare sostituzioni involontarie delle risorse.

Cos'è il refactoring CDK con conservazione delle risorse?

Quando si distribuisce un'applicazione CDK, AWS CloudFormation identifica le risorse in base ai loro ID logici. Il AWS CDK genera questi ID logici in base all'ID del costrutto e al relativo percorso nell'albero dei costrutti. Se si modifica l'ID di un costrutto o lo si sposta in una posizione diversa nel codice, in AWS CloudFormation genere lo interpreta come una richiesta di creazione di una nuova risorsa ed eliminazione di quella precedente. Per le risorse con stato come database, bucket di archiviazione o code, questa sostituzione può causare interruzioni del servizio o perdita di dati.

Il refactoring CDK risolve questa sfida mediante:

È possibile eseguire il refactoring CDK utilizzando il cdk refactor comando CDK CLI o l'azione della libreria CDK Toolkit. refactor Questa guida illustra principalmente l'approccio CLI, ma i principi di base si applicano a entrambi i metodi. Per informazioni sull'uso della libreria Toolkit, consulta Eseguire azioni programmatiche utilizzando la libreria CDK Toolkit.

Vantaggi del refactoring CDK

Il refactoring CDK offre i seguenti vantaggi per gli sviluppatori CDK: AWS

Come funziona il comando CDK CLI cdk refactor

Innanzitutto, distribuisci l'applicazione CDK iniziale per stabilire le risorse di base nel tuo account. AWS Dopo aver eseguito il refactoring del codice CDK, ad esempio rinominando i costrutti o spostando le risorse tra gli stack, utilizzate il cdk refactor comando per iniziare il processo di refactoring delle risorse distribuite.

Quando eseguite il comando refactor, la CLI CDK rileva le modifiche locali confrontando il codice corrente con lo stato distribuito. Verifica che l'applicazione CDK contenga esattamente lo stesso set di risorse dello stato distribuito, con differenze solo per la loro posizione nell'albero di costruzione. La CLI CDK genera quindi un piano di refactoring che mappa le vecchie posizioni delle risorse nelle nuove posizioni. La CLI CDK mostra le modifiche proposte e, dopo la conferma, utilizza AWS CloudFormation l'API di refactoring per aggiornare gli ID logici delle risorse senza sostituirle.

Dietro le quinte, la CLI CDK determina quali risorse sono state spostate confrontando le loro proprietà e dipendenze, identificando le risorse funzionalmente equivalenti ma con percorsi diversi nell'albero dei costrutti. Se rileva aggiunte, eliminazioni o modifiche di risorse, l'operazione di refactoring verrà rifiutata con un messaggio di errore.

Esempio di conservazione delle risorse durante il refactoring del codice CDK

In questo esempio, conserviamo le risorse distribuite eseguendo il refactoring del nostro codice CDK utilizzando il comando CDK CLI. cdk refactor

La nostra applicazione CDK di esempio è costituita da un singolo stack contenente un bucket S3, una distribuzione e una funzione Lambda. CloudFront L'albero dei costrutti è strutturato come segue:

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

Di seguito è riportato un esempio del codice della nostra applicazione:

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Ora, immagina di voler rifattorizzare questo codice in:

Dopo il refactoring, l'albero dei costrutti sarebbe simile al seguente:

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

E il codice rifattorizzato sarebbe:

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Senza il refactoring CDK, queste modifiche comporterebbero la AWS CloudFormation creazione di nuove risorse e l'eliminazione di quelle vecchie, poiché gli ID logici cambierebbero:

Con il refactoring CDK, la CLI CDK rileva questi cambiamenti di percorso e utilizza le funzionalità di refactoring per preservare le AWS CloudFormation risorse sottostanti. Durante l'esecuzionecdk refactor, la CLI mostra le modifiche che apporterà:

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

Quando confermate inserendoy, la CLI CDK mostra lo stato di avanzamento dell'operazione di refactoring:

Refactoring...
✅  Stack refactor complete

Dopo la conferma, la CLI CDK esegue l'operazione di refactoring, preservando entrambe le risorse e aggiornando i relativi ID logici in modo che corrispondano alla nuova struttura del codice.

La stessa mappatura è mostrata anche nell'output del comando, organizzato per stack: cdk diff

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

Inizia con il refactoring CDK

Per iniziare con il refactoring, completa questi prerequisiti:

Usa i file di override per risolvere le ambiguità nel refactoring

La CLI CDK calcola automaticamente tutte le mappature delle risorse in base al confronto del codice con le risorse distribuite. Nella maggior parte dei casi, questo rilevamento automatico funziona bene, ma ci sono situazioni in cui la CLI potrebbe riscontrare ambiguità che non è in grado di risolvere da sola. Per fornire una guida alla CLI CDK, utilizzate un file di override.

Il refactoring degli stack in più ambienti

Un'applicazione CDK può contenere più stack che vengono distribuiti in ambienti diversi (account e regioni).AWS Quando si preservano le risorse durante il refactoring in tali applicazioni, la CLI CDK gestisce gli ambienti in un modo specifico:

Questo comportamento garantisce che le risorse rimangano all'interno AWS dell'account e della regione originali, il che è necessario perché CloudFormation le risorse non possono essere spostate fisicamente oltre i confini dell'account o della regione.

Ad esempio, se l'applicazione CDK definisce stack sia per gli ambienti di sviluppo che per quelli di produzione, l'operazione di refactoring verrà eseguita indipendentemente in ciascun ambiente. Le risorse possono essere spostate tra gli stack all'interno dell'ambiente di sviluppo o all'interno dell'ambiente di produzione, ma non dallo sviluppo alla produzione o viceversa.

Gestione delle risorse progettate per essere sostituite

Alcuni costrutti CDK si basano sul comportamento CloudFormation di sostituzione delle risorse come parte della loro progettazione. Ad esempio, i Version costrutti di API Gateway Deployment e Lambda sono progettati per creare nuove risorse quando le loro proprietà cambiano.

Durante il refactoring, non includete alcuna modifica che dovrebbe comportare la sostituzione delle risorse. Altrimenti, l'interfaccia a riga di comando del CDK potrebbe rilevare e conservare queste risorse. Ciò significa che le risorse progettate per essere sostituite devono essere gestite separatamente dalle operazioni di refactoring.

Per gestire correttamente le risorse progettate per essere sostituite:

Questo approccio in due fasi garantisce che le risorse progettate per essere sostituite siano gestite correttamente, pur consentendo di trarre vantaggio dal refactoring CDK per altre risorse.

Considerazioni e limitazioni generali

Quando conservi le risorse durante il refactoring CDK, tieni a mente queste considerazioni:

Refactoring con pipeline CI/CD

Per utilizzare la funzionalità di refactoring nelle CI/CD pipeline, devi essere in grado di eseguire la CLI CDK come parte della pipeline. Di seguito sono riportate alcune considerazioni importanti per l'integrazione del refactoring nel flusso di lavoro. CI/CD

Risorse correlate

Per informazioni sulle opzioni e gli argomenti per il cdk refactor comando CDK CLI, vedere. cdk refactor

Per iniziare con l'refactorazione della libreria CDK Toolkit, consulta Eseguire azioni programmatiche utilizzando la libreria CDK Toolkit.