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 migliori pratiche per lo sviluppo e l'implementazione dell'infrastruttura cloud con AWS CDK

Con AWS CDK, gli sviluppatori o gli amministratori possono definire la propria infrastruttura cloud utilizzando un linguaggio di programmazione supportato. Le applicazioni CDK devono essere organizzate in unità logiche, come API, database e risorse di monitoraggio, e opzionalmente disporre di una pipeline per le implementazioni automatizzate. Le unità logiche devono essere implementate come costrutti, tra cui:

Gli stack definiscono il modello di implementazione di queste unità logiche. Per un'introduzione più dettagliata ai concetti alla base del CDK, vedere. Iniziare con AWS CDK

AWS CDK Ciò riflette un'attenta considerazione delle esigenze dei nostri clienti e dei team interni e dei modelli di errore che spesso si verificano durante l'implementazione e la manutenzione continua di applicazioni cloud complesse. Abbiamo scoperto che gli errori sono spesso correlati a "out-of-band" modifiche apportate a un'applicazione che non sono state completamente testate, come le modifiche alla configurazione. Pertanto, lo abbiamo sviluppato AWS CDK attorno a un modello in cui l'intera applicazione è definita in codice, non solo la logica aziendale ma anche l'infrastruttura e la configurazione. In questo modo, le modifiche proposte possono essere esaminate attentamente, testate in modo completo in ambienti che assomigliano a vari livelli alla produzione e annullate completamente se qualcosa va storto.

Al momento dell'implementazione, AWS CDK sintetizza un assembly cloud che contiene quanto segue:

Con il CDK, ogni commit nel ramo di controllo della versione principale dell'applicazione può rappresentare una versione completa, coerente e distribuibile dell'applicazione. L'applicazione può quindi essere distribuita automaticamente ogni volta che viene apportata una modifica.

La filosofia alla base AWS CDK ci porta alle nostre migliori pratiche consigliate, che abbiamo suddiviso in quattro grandi categorie.

Best Practice dell'organizzazione

Nelle fasi iniziali dell' AWS CDK adozione, è importante considerare come preparare l'organizzazione per il successo. È consigliabile disporre di un team di esperti responsabile della formazione e della guida del resto dell'azienda nell'adozione del CDK. Le dimensioni di questo team possono variare, da una o due persone in una piccola azienda a un vero e proprio Cloud Center of Excellence (CCoE) presso un'azienda più grande. Questo team è responsabile della definizione degli standard e delle politiche per l'infrastruttura cloud dell'azienda e anche della formazione e del tutoraggio degli sviluppatori.

Il CCoE potrebbe fornire indicazioni su quali linguaggi di programmazione dovrebbero essere utilizzati per l'infrastruttura cloud. I dettagli variano da un'organizzazione all'altra, ma una buona politica aiuta a garantire che gli sviluppatori possano comprendere e gestire l'infrastruttura cloud dell'azienda.

Il CCoE crea anche una «landing zone» che definisce le unità organizzative all'interno. AWS Una landing zone è un AWS ambiente preconfigurato, sicuro, scalabile e multi-account basato su modelli di best practice. Per unire i servizi che compongono la tua landing zone, puoi utilizzare AWS Control Tower, che configura e gestisce l'intero sistema multi-account da un'unica interfaccia utente.

I team di sviluppo dovrebbero essere in grado di utilizzare i propri account per testare e distribuire nuove risorse in questi account, se necessario. I singoli sviluppatori possono trattare queste risorse come estensioni della propria workstation di sviluppo. Utilizzando CDK Pipelines, AWS CDK le applicazioni possono quindi essere distribuite tramite un account CI/CD in ambienti di test, integrazione e produzione (ciascuno isolato nella propria regione o account). AWS Questo viene fatto unendo il codice degli sviluppatori nel repository canonico dell'organizzazione.

Le migliori pratiche di codifica

Questa sezione presenta le migliori pratiche per organizzare il AWS CDK codice. Il diagramma seguente mostra la relazione tra un team e gli archivi di codice, i pacchetti, le applicazioni e le librerie di costruzione del team.

Inizia in modo semplice e aggiungi complessità solo quando ne hai bisogno

Il principio guida della maggior parte delle nostre best practice è quello di mantenere le cose il più semplici possibile, ma non di più. Aggiungete complessità solo quando le vostre esigenze impongono una soluzione più complicata. Con AWS CDK, puoi rifattorizzare il codice secondo necessità per supportare nuovi requisiti. Non è necessario progettare in anticipo tutti gli scenari possibili.

Allineamento con il AWS Well-Architected Framework

Il AWS Well-Architected Framework definisce un componente come il codice, la configurazione AWS e le risorse che insieme soddisfano un requisito. Un componente è spesso l'unità di proprietà tecnica ed è disaccoppiato dagli altri componenti. Il termine carico di lavoro viene utilizzato per identificare un insieme di componenti che insieme forniscono valore aziendale. Un carico di lavoro è in genere il livello di dettaglio di cui comunicano i leader aziendali e tecnologici.

Un' AWS CDK applicazione è mappata a un componente come definito dal AWS Well-Architected Framework. AWS CDK le app sono un meccanismo per codificare e fornire le migliori pratiche per le applicazioni cloud Well-Architected. Puoi anche creare e condividere componenti come librerie di codice riutilizzabili tramite repository di artefatti, come. AWS CodeArtifact

Ogni applicazione inizia con un singolo pacchetto in un unico repository

Un singolo pacchetto è il punto di ingresso della tua AWS CDK app. Qui definisci come e dove distribuire le diverse unità logiche dell'applicazione. È inoltre necessario definire la pipeline CI/CD per distribuire l'applicazione. I costrutti dell'app definiscono le unità logiche della soluzione.

Utilizzate pacchetti aggiuntivi per i costrutti utilizzati in più di un'applicazione. (I costrutti condivisi dovrebbero inoltre avere il proprio ciclo di vita e la propria strategia di test.) Le dipendenze tra i pacchetti nello stesso repository sono gestite dagli strumenti di compilazione del repository.

Sebbene sia possibile, non consigliamo di inserire più applicazioni nello stesso repository, specialmente quando si utilizzano pipeline di distribuzione automatizzate. In questo modo si aumenta il «raggio d'azione» delle modifiche durante la distribuzione. Quando in un repository sono presenti più applicazioni, le modifiche apportate a un'applicazione attivano la distribuzione delle altre (anche se le altre non sono state modificate). Inoltre, un'interruzione in un'applicazione impedisce la distribuzione delle altre applicazioni.

Sposta il codice nei repository in base al ciclo di vita del codice o alla proprietà del team

Quando i pacchetti iniziano a essere utilizzati in più applicazioni, spostali nel rispettivo repository. In questo modo, i pacchetti possono essere referenziati dai sistemi di compilazione delle applicazioni che li utilizzano e possono anche essere aggiornati con cadenze indipendenti dai cicli di vita delle applicazioni. Tuttavia, all'inizio potrebbe avere senso mettere tutti i costrutti condivisi in un unico repository.

Inoltre, sposta i pacchetti nel proprio repository quando diversi team stanno lavorando su di essi. Questo aiuta a rafforzare il controllo degli accessi.

Per utilizzare i pacchetti oltre i confini del repository, è necessario un archivio di pacchetti privato, simile a NPM o Maven Central PyPi, ma interno all'organizzazione. È inoltre necessario un processo di rilascio che compili, verifichi e pubblichi il pacchetto nell'archivio privato dei pacchetti. CodeArtifactpuò ospitare pacchetti per i linguaggi di programmazione più diffusi.

Le dipendenze dai pacchetti nel repository dei pacchetti sono gestite dal gestore di pacchetti della lingua, come NPM for TypeScript o le applicazioni. JavaScript Il tuo gestore di pacchetti aiuta a garantire che le build siano ripetibili. Lo fa registrando le versioni specifiche di ogni pacchetto da cui dipende l'applicazione. Consente inoltre di aggiornare tali dipendenze in modo controllato.

I pacchetti condivisi richiedono una strategia di test diversa. Per una singola applicazione, potrebbe essere sufficiente distribuire l'applicazione in un ambiente di test e confermare che funzioni ancora. Tuttavia, i pacchetti condivisi devono essere testati indipendentemente dall'applicazione che li utilizza, come se fossero rilasciati al pubblico. (L'organizzazione potrebbe scegliere di rilasciare effettivamente alcuni pacchetti condivisi al pubblico.)

Tenete presente che un costrutto può essere arbitrariamente semplice o complesso. A Bucket è un costrutto, ma CameraShopWebsite potrebbe essere anche un costrutto.

L'infrastruttura e il codice di runtime risiedono nello stesso pacchetto

Oltre a generare AWS CloudFormation modelli per l'implementazione dell'infrastruttura, raggruppa AWS CDK anche risorse di runtime come funzioni Lambda e immagini Docker e le distribuisce insieme all'infrastruttura. In questo modo è possibile combinare il codice che definisce l'infrastruttura e il codice che implementa la logica di runtime in un unico costrutto. È consigliabile eseguire questa operazione. Non è necessario che questi due tipi di codice risiedano in repository o addirittura in pacchetti separati.

Per far evolvere insieme i due tipi di codice, è possibile utilizzare un costrutto autonomo che descriva completamente una funzionalità, incluse l'infrastruttura e la logica. Con un costrutto autonomo, puoi testare i due tipi di codice separatamente, condividere e riutilizzare il codice tra i progetti e creare una versione sincronizzata di tutto il codice.

Costruisci le migliori pratiche

Questa sezione contiene le migliori pratiche per lo sviluppo di costrutti. I costrutti sono moduli riutilizzabili e componibili che incapsulano risorse. Sono gli elementi costitutivi delle app. AWS CDK

Modella con costrutti, implementa con pile

Gli stack sono l'unità di distribuzione: tutto in uno stack viene distribuito insieme. Pertanto, quando create le unità logiche di livello superiore dell'applicazione a partire da più AWS risorse, rappresentate ogni unità logica come una, non come una Construct. Stack Utilizzate gli stack solo per descrivere come devono essere composti e collegati i costrutti per i vari scenari di implementazione.

Ad esempio, se una delle tue unità logiche è un sito Web, i costrutti che lo compongono (come un bucket Amazon S3, API Gateway, funzioni Lambda o tabelle Amazon RDS) devono essere composti in un unico costrutto di alto livello. Quindi quel costrutto deve essere istanziato in uno o più stack per la distribuzione.

Utilizzando costrutti per la costruzione e stack per l'implementazione, si migliora il potenziale di riutilizzo dell'infrastruttura e si ottiene una maggiore flessibilità nel modo in cui viene implementata.

Configura con proprietà e metodi, non con variabili di ambiente

Le ricerche delle variabili di ambiente all'interno di costrutti e pile sono un anti-pattern comune. Sia i costrutti che gli stack devono accettare un oggetto properties per consentire la completa configurabilità nel codice. In caso contrario si crea una dipendenza dalla macchina su cui verrà eseguito il codice, il che crea ulteriori informazioni di configurazione che è necessario monitorare e gestire.

In generale, le ricerche delle variabili di ambiente devono essere limitate al livello più alto di un'app. AWS CDK Dovrebbero essere utilizzati anche per trasmettere le informazioni necessarie per l'esecuzione in un ambiente di sviluppo. Per ulteriori informazioni, consulta Ambienti.

Esegui un test unitario della tua infrastruttura

Per eseguire in modo coerente una suite completa di unit test in fase di compilazione in tutti gli ambienti, evita le ricerche in rete durante la sintesi e modella tutte le fasi di produzione in codice. (Queste best practice verranno illustrate più avanti). Se ogni singolo commit restituisce sempre lo stesso modello generato, puoi fidarti degli unit test che scrivi per confermare che i modelli generati abbiano l'aspetto che ti aspetti. Per ulteriori informazioni, consulta Costrutti di test.

Non modificate l'ID logico delle risorse stateful

La modifica dell'ID logico di una risorsa comporta la sostituzione della risorsa con una nuova alla successiva distribuzione. Per risorse statiche come database e bucket S3 o infrastrutture persistenti come Amazon VPC, questo è raramente ciò che si desidera. Fai attenzione a eventuali refactoring del AWS CDK codice che potrebbero causare la modifica dell'ID. Scrivi test unitari che affermino che gli ID logici delle tue risorse stateful rimangono statici. L'ID logico deriva da quello specificato quando si id crea un'istanza del costrutto e dalla posizione del costrutto nell'albero dei costrutti. Per ulteriori informazioni, consulta ID logici.

I costrutti non sono sufficienti per la conformità

Molti clienti aziendali scrivono i propri wrapper per i costrutti L2 (i costrutti «curati» che rappresentano AWS risorse individuali con impostazioni predefinite e best practice integrate). Questi wrapper applicano le migliori pratiche di sicurezza come la crittografia statica e politiche IAM specifiche. Ad esempio, potresti crearne uno MyCompanyBucket da utilizzare nelle tue applicazioni al posto del solito costrutto Amazon S3Bucket. Questo modello è utile per far emergere le linee guida sulla sicurezza nelle prime fasi del ciclo di vita dello sviluppo del software, ma non utilizzarlo come unico mezzo di applicazione.

Utilizza invece AWS funzionalità come le politiche di controllo dei servizi e i limiti di autorizzazione per far rispettare le barriere di sicurezza a livello di organizzazione. Usa Aspetti strumenti come CloudFormation Guard per fare affermazioni sulle proprietà di sicurezza degli elementi dell'infrastruttura prima della distribuzione. Usala AWS CDK per ciò che sa fare meglio.

Infine, tenete presente che scrivere i vostri costrutti «L2+» potrebbe impedire agli sviluppatori di sfruttare AWS CDK pacchetti come AWS Solutions Constructs o costrutti di terze parti di Construct Hub. Questi pacchetti sono in genere costruiti su AWS CDK costrutti standard e non saranno in grado di utilizzare i costrutti wrapper.

Le migliori pratiche applicative

In questa sezione spieghiamo come scrivere le AWS CDK applicazioni, combinando costrutti per definire il modo in cui le AWS risorse sono connesse.

Prendi decisioni al momento della sintesi

Sebbene AWS CloudFormation consenta di prendere decisioni al momento dell'implementazione (utilizzando Conditions{ Fn::If }, eParameters) e consenta di accedere a questi meccanismi, si consiglia di non utilizzarli. AWS CDK I tipi di valori che è possibile utilizzare e i tipi di operazioni che è possibile eseguire su di essi sono limitati rispetto a quelli disponibili in un linguaggio di programmazione generico.

Provate invece a prendere tutte le decisioni, ad esempio il costrutto da istanziare, nell' AWS CDK applicazione utilizzando le istruzioni del linguaggio di if programmazione e altre funzionalità. Ad esempio, un linguaggio CDK comune, che esegue un'iterazione su un elenco e istanzia un costrutto con i valori di ogni elemento dell'elenco, semplicemente non è possibile utilizzare le espressioni. AWS CloudFormation

Consideralo un dettaglio di implementazione che AWS CDK utilizza per solide implementazioni cloud, non AWS CloudFormation come un obiettivo linguistico. Non stai scrivendo AWS CloudFormation modelli in TypeScript Python, stai scrivendo codice CDK che viene utilizzato CloudFormation per la distribuzione.

Usa nomi di risorse generate, non nomi fisici

I nomi sono una risorsa preziosa. Ogni nome può essere usato una sola volta. Pertanto, se codifichi un nome di tabella o un nome di bucket nell'infrastruttura e nell'applicazione, non puoi implementare quella parte di infrastruttura due volte nello stesso account. (Il nome di cui stiamo parlando qui è il nome specificato, ad esempio, dalla bucketName proprietà su un costrutto di bucket Amazon S3.)

Quel che è peggio, non è possibile apportare modifiche alla risorsa che richiedono la sua sostituzione. Se una proprietà può essere impostata solo al momento della creazione KeySchema della risorsa, ad esempio una tabella Amazon DynamoDB, tale proprietà è immutabile. La modifica di questa proprietà richiede una nuova risorsa. Tuttavia, la nuova risorsa deve avere lo stesso nome per essere una vera sostituta. Ma non può avere lo stesso nome mentre la risorsa esistente utilizza ancora quel nome.

Un approccio migliore consiste nello specificare il minor numero possibile di nomi. Se ometti i nomi delle risorse, li AWS CDK genererà automaticamente in modo da non causare problemi. Supponiamo di avere una tabella come risorsa. È quindi possibile passare il nome della tabella generata come variabile di ambiente alla AWS Lambda funzione. Nell' AWS CDK applicazione, è possibile fare riferimento al nome della tabella cometable.tableName. In alternativa, puoi generare un file di configurazione sull'istanza Amazon EC2 all'avvio o scrivere il nome effettivo della tabella nel AWS Systems Manager Parameter Store in modo che l'applicazione possa leggerlo da lì.

Se il posto in cui ti serve è un'altra AWS CDK pila, è ancora più semplice. Supponendo che uno stack definisca la risorsa e un altro stack debba utilizzarla, vale quanto segue:

Definisci le politiche di rimozione e la conservazione dei log

I AWS CDK tentativi di impedirti di perdere dati adottando per impostazione predefinita politiche che conservano tutto ciò che crei. Ad esempio, la politica di rimozione predefinita per le risorse che contengono dati (come i bucket Amazon S3 e le tabelle del database) prevede di non eliminare la risorsa quando viene rimossa dallo stack. Invece, la risorsa rimane orfana dallo stack. Analogamente, l'impostazione predefinita del CDK è quella di conservare tutti i log per sempre. Negli ambienti di produzione, queste impostazioni predefinite possono comportare rapidamente l'archiviazione di grandi quantità di dati che non sono effettivamente necessari e la relativa fattura. AWS

Valuta attentamente quali politiche desideri siano per ogni risorsa di produzione e specificale di conseguenza. AspettiUtilizzatele per convalidare le politiche di rimozione e registrazione nello stack.

Separa l'applicazione in più stack in base ai requisiti di implementazione

Non esiste una regola fissa per stabilire il numero di stack necessari all'applicazione. In genere si finisce per basare la decisione sui modelli di distribuzione. Tieni a mente le seguenti linee guida:

Impegnati a evitare comportamenti cdk.context.json non deterministici

Il determinismo è fondamentale per implementazioni di successo. AWS CDK Un' AWS CDK app dovrebbe avere essenzialmente lo stesso risultato ogni volta che viene distribuita in un determinato ambiente.

Poiché AWS CDK l'app è scritta in un linguaggio di programmazione generico, può eseguire codice arbitrario, utilizzare librerie arbitrarie ed effettuare chiamate di rete arbitrarie. Ad esempio, puoi utilizzare un AWS SDK per recuperare alcune informazioni dal tuo account mentre sintetizzi l'app. AWS Riconosci che così facendo comporterai requisiti aggiuntivi per la configurazione delle credenziali, una maggiore latenza e una possibilità, per quanto piccola, di fallire ogni volta che esegui. cdk synth

Non modificate mai il vostro AWS account o le vostre risorse durante la sintesi. La sintesi di un'app non dovrebbe avere effetti collaterali. Le modifiche all'infrastruttura dovrebbero avvenire solo nella fase di implementazione, dopo la generazione del AWS CloudFormation modello. In questo modo, se c'è un problema, AWS CloudFormation puoi ripristinare automaticamente la modifica. Per apportare modifiche che non possono essere apportate facilmente all'interno del AWS CDK framework, utilizza risorse personalizzate per eseguire codice arbitrario al momento della distribuzione.

Anche le chiamate strettamente di sola lettura non sono necessariamente sicure. Considerate cosa succede se il valore restituito da una chiamata di rete cambia. Su quale parte della tua infrastruttura avrà questo impatto? Cosa accadrà alle risorse già impiegate? Di seguito sono riportati due esempi di situazioni in cui una modifica improvvisa dei valori potrebbe causare un problema.

Queste situazioni possono essere pericolose perché il AWS cambiamento potrebbe verificarsi dopo mesi o anni di implementazioni riuscite. Improvvisamente le vostre implementazioni falliscono «senza motivo» e molto tempo fa avete dimenticato cosa avete fatto e perché.

Fortunatamente, AWS CDK include un meccanismo chiamato context providers per registrare un'istantanea di valori non deterministici. Ciò consente alle future operazioni di sintesi di produrre esattamente lo stesso modello utilizzato quando sono state implementate per la prima volta. Le uniche modifiche al nuovo modello sono le modifiche apportate al codice. Quando si utilizza il .fromLookup() metodo di un costrutto, il risultato della chiamata viene memorizzato nella cache. cdk.context.json Dovresti affidarlo al controllo della versione insieme al resto del codice per assicurarti che le future esecuzioni della tua app CDK utilizzino lo stesso valore. Il CDK Toolkit include comandi per gestire la cache contestuale, in modo da poter aggiornare voci specifiche quando necessario. Per ulteriori informazioni, consulta Contesto di runtime.

Se avete bisogno di un valore (proveniente AWS o altrove) per il quale non esiste un provider di contesto CDK nativo, vi consigliamo di scrivere uno script separato. Lo script dovrebbe recuperare il valore e scriverlo in un file, quindi leggerlo nell'app CDK. Esegui lo script solo quando desideri aggiornare il valore memorizzato, non come parte del normale processo di compilazione.

Lascia che AWS CDK gestiscano ruoli e gruppi di sicurezza

Con i metodi di grant() praticità della libreria AWS CDK construct, puoi creare AWS Identity and Access Management ruoli che garantiscono l'accesso a una risorsa da parte di un'altra utilizzando autorizzazioni con ambito minimo. Ad esempio, considera una riga come la seguente:

myBucket.grantRead(myLambda)

Questa singola riga aggiunge una policy al ruolo della funzione Lambda (anch'essa creata per te). Quel ruolo e le relative politiche sono più di una dozzina di righe CloudFormation che non devi scrivere. AWS CDK Concede solo le autorizzazioni minime richieste alla funzione per leggere dal bucket.

Se si richiede agli sviluppatori di utilizzare sempre ruoli predefiniti creati da un team di sicurezza, la AWS CDK codifica diventa molto più complicata. I vostri team potrebbero perdere molta flessibilità nel modo in cui progettano le loro applicazioni. Un'alternativa migliore consiste nell'utilizzare le politiche di controllo dei servizi e i limiti di autorizzazione per assicurarsi che gli sviluppatori rimangano entro i limiti.

Modella tutte le fasi di produzione in codice

Negli AWS CloudFormation scenari tradizionali, l'obiettivo è produrre un singolo artefatto parametrizzato in modo che possa essere distribuito in vari ambienti di destinazione dopo aver applicato valori di configurazione specifici a tali ambienti. Nel CDK, è possibile e si deve inserire tale configurazione nel codice sorgente. Crea uno stack per il tuo ambiente di produzione e crea uno stack separato per ciascuna delle altre fasi. Quindi, inserisci i valori di configurazione per ogni stack nel codice. Utilizzate servizi come Secrets Manager e Systems Manager Parameter Store per valori sensibili che non desiderate trasferire al controllo del codice sorgente, utilizzando i nomi o gli ARN di tali risorse.

Quando sintetizzi l'applicazione, l'assembly cloud creato nella cdk.out cartella contiene un modello separato per ogni ambiente. L'intera build è deterministica. Non ci sono out-of-band modifiche all'applicazione e ogni commit restituisce sempre lo stesso identico AWS CloudFormation modello e le stesse risorse di accompagnamento. Ciò rende i test unitari molto più affidabili.

Misura tutto

Il raggiungimento dell'obiettivo di un'implementazione completa e continua, senza intervento umano, richiede un elevato livello di automazione. Tale automazione è possibile solo con un'ampia quantità di monitoraggio. Per misurare tutti gli aspetti delle risorse distribuite, crea metriche, allarmi e dashboard. Non limitarti a misurare cose come l'utilizzo della CPU e lo spazio su disco. Registra anche le metriche aziendali e utilizza tali misurazioni per automatizzare le decisioni di implementazione, come i rollback. La maggior parte dei costrutti L2 include metodi pratici per aiutarti a creare metriche, come il metodo sulla classe DynamoDB.Table. AWS CDKmetricUserErrors()