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 rifattorizzare il 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 alla loro logica. IDs Il AWS CDK genera queste logiche in IDs base all'ID del costrutto e al relativo percorso nell'albero di costruzione. Se modificate l'ID di un costrutto o lo spostate 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 affronta questa sfida mediante:

È possibile eseguire il refactoring CDK utilizzando il cdk refactor comando CDK CLI o l'azione della CDK Toolkit Library. 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, consultate Eseguire azioni programmatiche utilizzando la libreria CDK Toolkit.

Vantaggi del refactoring CDK

Il refactoring CDK offre i seguenti vantaggi agli sviluppatori CDK: AWS

Come funziona il comando CDK cdk refactor CLI

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

Quando esegui 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, che differiscono solo nella loro posizione nell'albero di costruzione. La CLI CDK genera quindi un piano di rifattorizzazione che mappa le vecchie posizioni delle risorse nelle nuove posizioni. La CLI CDK mostra le modifiche proposte e, dopo la conferma, AWS CloudFormation utilizza l'API di refactoring per aggiornare la IDs logica delle risorse senza sostituirle.

Dietro le quinte, la CLI CDK determina quali risorse sono state spostate confrontandone le proprietà e le dipendenze, identificando le risorse che sono funzionalmente equivalenti ma hanno percorsi diversi nell'albero dei costrutti. Se rileva aggiunte, eliminazioni o modifiche alle 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 durante 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 CloudFront distribuzione e una funzione Lambda. L'albero di costruzione è strutturato come segue:

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

Di seguito è riportato un esempio del nostro codice applicativo:

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, immaginate di voler rifattorizzare questo codice in:

Dopo il refactoring, l'albero di costruzione avrebbe il seguente aspetto:

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 creazione AWS CloudFormation di nuove risorse e l'eliminazione di quelle vecchie, perché la logica cambierebbe: IDs

Con il refactoring CDK, la CLI CDK rileva questi cambiamenti di percorso e utilizza le funzionalità di refactoring di CDK per preservare le risorse AWS CloudFormation sottostanti. Quando eseguicdk refactor, la CLI ti 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 la loro logica IDs in modo che corrisponda alla nuova struttura del codice.

La stessa mappatura viene 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 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 indicazioni alla CLI CDK, utilizzate un file di override.

Stack di refactoring in più ambienti

Un'applicazione CDK può contenere più stack che vengono distribuiti in ambienti diversi (account e regioni).AWS Quando preserva 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 attraverso i confini dell'account o della regione.

Ad esempio, se l'applicazione CDK definisce gli 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. In caso contrario, la CLI 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 vengano gestite correttamente, consentendovi comunque di trarre vantaggio dal refactoring CDK per altre risorse.

Considerazioni e limitazioni generali

Quando preservate le risorse durante il refactoring CDK, tenete a mente queste considerazioni:

CI/CD Rifattorizzazione con condotte

Per utilizzare la funzionalità di refactoring nelle CI/CD pipeline, devi essere in grado di eseguire la CLI CDK come parte della tua 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 comando CDK cdk refactor CLI, vedere. cdk refactor

Per iniziare a utilizzare l'refactorazione della CDK Toolkit Library, consultate Eseguire azioni programmatiche utilizzando la CDK Toolkit Library.