View a markdown version of this page

distribuzione cdk - AWS Kit di sviluppo cloud (AWS CDK) v2
UtilizzoArguments (Argomenti)OpzioniEsempi

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

distribuzione cdk

Implementa uno o più stack AWS CDK nel tuo ambiente. AWS

Durante l'implementazione, la CLI CDK emetterà indicatori di avanzamento, simili a quelli osservabili dalla console. AWS CloudFormation

Se l' AWS ambiente non viene avviato, verranno implementati correttamente solo gli stack privi di risorse e con modelli sintetizzati inferiori a 51.200 byte.

Utilizzo

$ cdk deploy <arguments> <options>

Arguments (Argomenti)

ID dello stack CDK

L'ID di costruzione dello stack CDK dell'app da distribuire.

▬Tipo: stringa

Obbligatorio: no

Opzioni

Per un elenco delle opzioni globali che funzionano con tutti i comandi CLI CDK, vedi Opzioni globali. Opzioni globali

--all <BOOLEAN>

Distribuisci tutti gli stack nella tua app CDK.

Valore predefinito: false

--asset-parallelism <BOOLEAN>

Specifica se creare e pubblicare risorse in parallelo.

--asset-prebuild <BOOLEAN>

Specificate se creare tutte le risorse prima di distribuire il primo stack. Questa opzione è utile per le build Docker non riuscite.

Valore predefinito: true

--build-exclude, -E <ARRAY>

Non ricostruite l'asset con l'ID specificato.

Questa opzione può essere specificata più volte in un singolo comando.

Valore predefinito: []

--change-set-name <STRING>

Il nome del set di AWS CloudFormation modifiche da creare.

Questa opzione non è compatibile con--method='direct'.

--concurrency <NUMBER>

Distribuisci più stack in parallelo tenendo conto delle dipendenze tra stack. Usa questa opzione per velocizzare le implementazioni. Devi comunque tenere conto di eventuali altri limiti AWS CloudFormation relativi alla tariffa AWS dell'account.

Fornisci un numero per specificare il numero massimo di distribuzioni simultanee (a seconda delle dipendenze) da eseguire.

Valore predefinito: 1

--exclusively, -e <BOOLEAN>

Distribuisci solo gli stack richiesti e non includi le dipendenze.

--express <BOOLEAN>

Esegui l'implementazione utilizzando la modalità express. CloudFormation La modalità Express consente implementazioni più rapide CloudFormation segnalando il completamento delle operazioni dello stack non appena viene CloudFormation applicata la configurazione delle risorse. Tuttavia, CloudFormation segnala il successo senza attendere che le risorse si stabilizzino. Inoltre, la modalità express non esegue il rollback automaticamente e lascerà gli stack in uno stato di errore se qualcosa va storto. Per abilitare il rollback automatico con la modalità express, includi il --rollback flag nella tua distribuzione in modalità express.

Per ulteriori informazioni, vedere la modalità express nella Guida per l' AWS CloudFormation utente.

Nota

La modalità Express non attende la stabilizzazione prima di segnalare l'esito positivo e non esegue il rollback automatico in caso di errore. Non è consigliata la modalità express per le implementazioni di produzione. La modalità Express è destinata alle distribuzioni iterative da eseguire durante lo sviluppo dell'applicazione.

Valore predefinito: false

--force, -f <BOOLEAN>

Quando si esegue la distribuzione per aggiornare uno stack esistente, la CLI CDK confronterà il modello e i tag dello stack distribuito con lo stack che sta per essere distribuito. Se non viene rilevata alcuna modifica, la CLI CDK salterà la distribuzione.

Per ignorare questo comportamento e distribuire sempre gli stack, anche se non viene rilevata alcuna modifica, usa questa opzione.

Valore predefinito: false

--help, -h <BOOLEAN>

Mostra le informazioni di riferimento per il comando. cdk deploy

--hotswap <BOOLEAN>

Implementazioni hotswap per uno sviluppo più rapido. Questa opzione tenta di eseguire una distribuzione hotswap più rapida, se possibile. Ad esempio, se modifichi il codice di una funzione Lambda nella tua app CDK, la CLI CDK aggiornerà la risorsa direttamente tramite le API di servizio invece di eseguire una distribuzione. CloudFormation

Se la CLI CDK rileva modifiche che non supportano l'hotswap, tali modifiche verranno ignorate e verrà visualizzato un messaggio. Se preferisci eseguire una CloudFormation distribuzione completa come alternativa, usa invece. --hotswap-fallback

La CLI CDK utilizza le tue AWS credenziali correnti per eseguire le chiamate API. Non assume i ruoli dello stack di bootstrap, anche se il flag della @aws-cdk/core:newStyleStackSynthesis funzionalità è impostato su. true Questi ruoli non dispongono delle autorizzazioni necessarie per aggiornare le AWS risorse direttamente, senza utilizzarle. CloudFormation Per questo motivo, assicurati che le tue credenziali appartengano allo stesso AWS account degli stack su cui stai eseguendo le distribuzioni hotswap e che dispongano delle autorizzazioni IAM necessarie per aggiornare le risorse.

L'hotswapping è attualmente supportato per le seguenti modifiche:

  • Risorse di codice (incluse immagini Docker e codice in linea), modifiche ai tag e modifiche alla configurazione (sono supportate solo la descrizione e le variabili di ambiente) delle funzioni Lambda.

  • Versioni Lambda e modifiche agli alias.

  • Modifiche alle definizioni delle macchine a stati AWS Step Functions.

  • Modifiche agli asset dei container dei servizi Amazon ECS.

  • Modifiche agli asset del sito Web delle distribuzioni dei bucket Amazon S3.

  • Modifiche all'origine e all'ambiente dei progetti. AWS CodeBuild

  • Modifiche al modello di mappatura VTL per AWS AppSync resolver e funzioni.

  • Modifiche allo schema per le API GraphQL. AWS AppSync

  • API REST, distribuzione e modifiche ai metodi per Amazon API Gateway.

  • Modifiche alle API e all'integrazione per Amazon API Gateway V2.

  • Modifiche alla configurazione degli agenti Amazon Bedrock.

  • Modifiche alla configurazione di Amazon AgentCore Bedrock Runtime

  • Modifiche alle regole per Amazon EventBridge.

  • Modifiche alla configurazione delle tabelle Amazon DynamoDB e delle tabelle globali.

  • Modifiche alla configurazione delle code Amazon SQS.

  • Modifiche all'allarme, all'allarme composito e al pannello di controllo per Amazon. CloudWatch

L'utilizzo di alcune funzioni CloudFormation intrinseche è supportato come parte di una distribuzione hotswapped. Ciò include:

  • Ref

  • Fn::GetAtt— Supportato solo parzialmente, utilizza una combinazione di API Cloud Control e implementazioni personalizzate. Fai riferimento all'elenco delle risorse supportate dall'API Cloud Control e da questa implementazione per l'elenco completo delle risorse supportate.

  • Fn::ImportValue

  • Fn::Join

  • Fn::Select

  • Fn::Split

  • Fn::Sub

Questa opzione è compatibile anche con gli stack annidati.

Nota

  • Questa opzione introduce deliberatamente la deriva negli CloudFormation stack per velocizzare le implementazioni. Per questo motivo, utilizzala solo per scopi di sviluppo. Non utilizzate questa opzione per le distribuzioni di produzione.

  • Le impostazioni predefinite per alcuni parametri possono essere diverse con il parametro hotswap. Ad esempio, la percentuale minima di integrità di un servizio Amazon ECS sarà attualmente impostata su. 0 In tal caso, esamina la fonte di conseguenza.

  • Quando si esegue una CloudFormation distribuzione dopo una distribuzione hotswap, usatela con un set di modifiche che cdk deploy --revert-drift tenga conto della deriva e riconciliate eventuali deviazioni introdotte dall'hotswap.

Valore predefinito: false

--hotswap-fallback <BOOLEAN>

--hotswapQuesta opzione è simile a. La differenza è che --hotswap-fallback ricorrerà all'esecuzione di una CloudFormation distribuzione se viene rilevata una modifica che la richiede.

Per ulteriori informazioni su questa opzione, consulta --hotswap.

Valore predefinito: false

--ignore-no-stacks <BOOLEAN>

Esegui una distribuzione anche se la tua app CDK non contiene stack.

Questa opzione è utile nel seguente scenario: potresti avere un'app con più ambienti, come e. dev prod Quando si avvia lo sviluppo, l'app prod potrebbe non disporre di risorse o le risorse potrebbero essere commentate. Ciò comporterà un errore di distribuzione con un messaggio che indica che l'app non ha stack. Usalo --ignore-no-stacks per bypassare questo errore.

Valore predefinito: false

--import-existing-resources <BOOLEAN>

Importa AWS CloudFormation risorse esistenti e non gestite dal tuo AWS account.

Quando utilizzi questa opzione, le risorse del AWS CloudFormation modello sintetizzato con lo stesso nome personalizzato delle risorse non gestite esistenti nello stesso account verranno importate nello stack.

Puoi usare questa opzione per importare risorse esistenti in stack nuovi o esistenti.

È possibile importare risorse esistenti e distribuire nuove risorse con lo stesso cdk deploy comando.

Per ulteriori informazioni sui nomi personalizzati, vedere Tipo di nome nella Guida per l' AWS CloudFormation utente.

Per ulteriori informazioni sul ImportExistingResources CloudFormation parametro, vedere AWS CloudFormation Semplifica l'importazione delle risorse con un nuovo parametro per ChangeSets.

Per ulteriori informazioni sull'uso di questa opzione, consulta Importare risorse esistenti nel repository GitHub aws-cdk-cli.

--logs <BOOLEAN>

Mostra Amazon CloudWatch log in lo standard output (stdout) per tutti gli eventi provenienti da tutte le risorse negli stack selezionati.

Questa opzione è compatibile solo con--watch.

Valore predefinito: true

--method, -m <STRING>

Configurare il metodo per eseguire una distribuzione.

  • change-set— Metodo predefinito. La CLI CDK crea un set di CloudFormation modifiche con le modifiche che verranno implementate, quindi esegue la distribuzione.

  • direct— Non creare un set di modifiche. Applica invece immediatamente la modifica. Questa operazione è in genere più rapida rispetto alla creazione di un set di modifiche, ma i dettagli sullo stato di avanzamento della distribuzione vengono persi nell'output della CLI.

  • prepare-change-set— Crea un set di modifiche ma non esegui la distribuzione. Ciò è utile se disponi di strumenti esterni che ispezionano il set di modifiche o se disponi di un processo di approvazione per i set di modifiche. Utilizzare execute-change-set per eseguire il set di modifiche preparato.

  • execute-change-set— Esegue un set di modifiche precedentemente creato conprepare-change-set. Il nome predefinito del set di modifiche ècdk-deploy-change-set, oppure è possibile specificare un nome personalizzato con. --change-set-name

Valori validi: change-set, direct, execute-change-set, prepare-change-set

Valore predefinito: change-set

--notification-arns <ARRAY>

Gli argomenti ARN di Amazon SNS che CloudFormation notificheranno gli eventi relativi allo stack.

--outputs-file, -O <STRING>

Il percorso in cui vengono scritti gli output dello stack delle distribuzioni.

Dopo la distribuzione, gli output dello stack verranno scritti nel file di output specificato in formato JSON.

Puoi configurare questa opzione nel cdk.json file del progetto o ~/.cdk.json sul tuo computer di sviluppo locale:

{
   "app": "npx ts-node bin/myproject.ts",
   // ...
   "outputsFile": "outputs.json"
}

Se vengono distribuiti più stack, gli output vengono scritti nello stesso file di output, organizzato per chiavi che rappresentano il nome dello stack.

--parameters <ARRAY>

Passa parametri aggiuntivi a durante la distribuzione CloudFormation .

Questa opzione accetta un array nel seguente formato:STACK:KEY=VALUE.

  • STACK— Il nome dello stack a cui associare il parametro.

  • KEY— Il nome del parametro dello stack.

  • VALUE— Il valore da trasmettere al momento della distribuzione.

Se non viene fornito un nome di stack o se * viene fornito come nome dello stack, i parametri verranno applicati a tutti gli stack distribuiti. Se uno stack non utilizza il parametro, la distribuzione avrà esito negativo.

I parametri non si propagano agli stack annidati. Per passare parametri agli stack annidati, usa il costrutto. NestedStack

Valore predefinito: {}

--previous-parameters <BOOLEAN>

Utilizzate i valori precedenti per i parametri esistenti.

Quando questa opzione è impostata sufalse, è necessario specificare tutti i parametri in ogni distribuzione.

Valore predefinito: true

--progress <STRING>

Configura il modo in cui la CLI CDK mostra l'avanzamento della distribuzione.

  • bar— Visualizza gli eventi di distribuzione dello stack come barra di avanzamento, con gli eventi relativi alla risorsa attualmente in fase di distribuzione.

  • events— Fornisci una cronologia completa, inclusi tutti gli CloudFormation eventi.

Puoi anche configurare questa opzione nel cdk.json file del progetto o ~/.cdk.json sul tuo computer di sviluppo locale:

{
   "progress": "events"
}

Valori validi: bar, events

Valore predefinito: bar

--require-approval <STRING>

Specifica quali modifiche richiedono l'approvazione manuale.

  • any-change— È richiesta l'approvazione manuale per qualsiasi modifica allo stack.

  • broadening— È richiesta l'approvazione manuale se le modifiche comportano un ampliamento delle autorizzazioni o delle regole del gruppo di sicurezza.

  • never— L'approvazione non è richiesta.

Valori validi:any-change,broadening, never

Valore predefinito: broadening

--revert-drift

Usa un set di modifiche compatibile con la deriva per la distribuzione. Questo crea un set di modifiche con CloudFormation la modalità di REVERT_DRIFT distribuzione, che rileva le risorse che si sono allontanate dalle definizioni dei modelli a causa di modifiche fuori banda e le riporta allo stato desiderato definito nel modello.

Consulta la documentazione di Cloudformation sui changeset sensibili alla deriva per ulteriori informazioni su come funzionano.

Valore predefinito: false

--rollback | --no-rollback, -R

Durante la distribuzione, se una risorsa non viene creata o aggiornata, la distribuzione tornerà all'ultimo stato stabile prima che la CLI CDK ritorni. Tutte le modifiche apportate fino a quel momento verranno annullate. Le risorse create verranno eliminate e gli aggiornamenti effettuati verranno annullati.

Specifica --no-rollback di disattivare questo comportamento. Se una risorsa non viene creata o aggiornata, la CLI del CDK lascerà le modifiche apportate fino a quel momento e le restituirà. Ciò lascerà la distribuzione in uno stato di interruzione e non riuscita. Da qui, puoi aggiornare il codice e riprovare la distribuzione. Ciò può essere utile negli ambienti di sviluppo in cui si esegue un'iterazione rapida.

Se una distribuzione eseguita con --no-rollback esito negativo e decidi di voler ripristinare la distribuzione, puoi utilizzare il comando. cdk rollback Per ulteriori informazioni, vedere cdk rollback.

Nota

Con--no-rollback, le distribuzioni che causano la sostituzione delle risorse falliranno sempre. È possibile utilizzare questo valore dell'opzione solo per le distribuzioni che aggiornano o creano nuove risorse.

Valore predefinito: --rollback

--toolkit-stack-name <STRING>

Il nome dello stack CDK Toolkit esistente.

Per impostazione predefinita, cdk bootstrap distribuisce uno stack denominato CDKToolkit nell'ambiente specificato. AWS Usa questa opzione per fornire un nome diverso per il tuo stack di bootstrap.

La CLI CDK utilizza questo valore per verificare la versione dello stack di bootstrap.

--watch <BOOLEAN>

Osserva continuamente i file di progetto CDK e distribuisci automaticamente gli stack specificati quando vengono rilevate modifiche.

Questa opzione implica per impostazione predefinita--hotswap.

Questa opzione ha un comando CDK CLI equivalente. Per ulteriori informazioni, vedere cdk watch.

Esempi

Distribuisci lo stack denominato MyStackName

$ cdk deploy MyStackName --app='node bin/main.js'

Distribuisci più stack in un'app

Usa cdk list per elencare i tuoi stack:

$ cdk list
CdkHelloWorldStack
CdkStack2
CdkStack3

Per distribuire tutti gli stack, usa l'opzione: --all

$ cdk deploy --all

Per scegliere quali stack distribuire, fornisci i nomi degli stack come argomenti:

$ cdk deploy CdkHelloWorldStack CdkStack3

Distribuisci stack di pipeline

cdk listUsalo per mostrare i nomi degli stack come percorsi, mostrando dove si trovano nella gerarchia della pipeline:

$ cdk list
PipelineStack
PiplelineStack/Prod
PipelineStack/Prod/MyService

Usa l'--allopzione o il carattere jolly * per distribuire tutti gli stack. Se hai una gerarchia di pile come descritto sopra --all e * corrisponderai solo alle pile del livello superiore. Per abbinare tutti gli stack della gerarchia, usa. **

Puoi combinare questi modelli. Quanto segue distribuisce tutti gli stack dello stage: Prod

$ cdk deploy PipelineStack/Prod/**

Passa i parametri durante l'implementazione

Definisci i parametri nel tuo stack CDK. Di seguito è riportato un esempio che crea un parametro denominato TopicNameParam per un argomento di Amazon SNS:

new sns.Topic(this, 'TopicParameter', {
    topicName: new cdk.CfnParameter(this, 'TopicNameParam').value.toString()
});

Per fornire un valore di parametro diparameterized, esegui quanto segue:

$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterized"

È possibile sovrascrivere i valori dei parametri utilizzando l'--forceopzione. Di seguito è riportato un esempio di sovrascrittura del nome dell'argomento di una distribuzione precedente:

$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterName" --force

Scrive gli output dello stack in un file dopo la distribuzione

Definisci gli output nel tuo file stack CDK. Di seguito è riportato un esempio che crea un output per una funzione ARN:

const fn = new lambda.Function(this, "fn", {
  handler: "index.handler",
  code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
  runtime: lambda.Runtime.NODEJS_LATEST
});

new cdk.CfnOutput(this, 'FunctionArn', {
  value: fn.functionArn,
});

Distribuisci lo stack e scrivi gli output su: outputs.json

$ cdk deploy --outputs-file outputs.json

Di seguito è riportato un esempio di outputs.json post-distribuzione:

{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  }
}

In questo esempio, la chiave FunctionArn corrisponde all'ID logico dell'CfnOutputistanza.

Di seguito è riportato un esempio di outputs.json dopo la distribuzione quando vengono distribuiti più stack:

{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  },
  "AnotherStack": {
    "VPCId": "vpc-z0mg270fee16693f"
  }
}

Modificare il metodo di distribuzione

Per una distribuzione più rapida, senza utilizzare set di modifiche, utilizza: --method='direct'

$ cdk deploy --method='direct'

Per creare un set di modifiche ma non distribuirlo, usa. --method='prepare-change-set' Per impostazione predefinita, cdk-deploy-change-set verrà creato un set di modifiche denominato. Se esiste un set di modifiche precedente con questo nome, verrà sovrascritto. Se non viene rilevata alcuna modifica, viene comunque creato un set di modifiche vuoto.

Puoi anche assegnare un nome al set di modifiche. Di seguito è riportato un esempio:

$ cdk deploy --method='prepare-change-set' --change-set-name='MyChangeSetName'