Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 gewartet und der Support wurde am 1. Juni 2023 eingestellt. Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # AWS CDK-CLI-Referenz Das AWS Cloud Development Kit (AWS CDK) Command Line Interface (AWS CDK CLI), auch bekannt als CDK Toolkit, ist das wichtigste Tool für die Interaktion mit Ihrer CDK-App. AWS Es führt Ihre App aus, fragt das von Ihnen definierte Anwendungsmodell ab und erstellt und implementiert die vom CDK generierten Vorlagen. AWS CloudFormation AWS Es bietet auch andere Funktionen, die für die Erstellung und Arbeit mit CDK-Projekten nützlich sind. AWS Dieses Thema enthält Informationen zu häufigen Anwendungsfällen der CDK-CLI. Die CDK-CLI wird mit dem Node Package Manager installiert. In den meisten Fällen empfehlen wir, es global zu installieren. ``` npm install -g aws-cdk # install latest version npm install -g aws-cdk@X.YY.Z # install specific version ``` **Tipp** Wenn Sie regelmäßig mit mehreren Versionen des AWS CDK arbeiten, sollten Sie erwägen, eine passende Version der CDK-CLI in einzelnen CDK-Projekten zu installieren. Um dies zu tun, lassen Sie den Befehl `-g` aus. `npm install` Verwenden Sie es dann`npx aws-cdk`, um es aufzurufen. Dadurch wird die lokale Version ausgeführt, falls eine existiert, und falls nicht, wird auf eine globale Version zurückgegriffen. ## CDK-CLI-Befehle Alle CDK-CLI-Befehle beginnen mit`cdk`, gefolgt von einem Unterbefehl (`list`, `synthesize``deploy`, usw.). Einige Unterbefehle haben eine kürzere Version (`ls`, usw.)`synth`, die gleichwertig ist. Optionen und Argumente folgen dem Unterbefehl in beliebiger Reihenfolge. Eine Beschreibung aller Unterbefehle, Optionen und Argumente finden Sie in der [AWS CDK-CLI-Befehlsreferenz](ref-cli-cmd.md). ## Geben Sie Optionen und ihre Werte an Befehlszeilenoptionen beginnen mit zwei Bindestrichen ()`--`. Einige häufig verwendete Optionen haben Synonyme aus einem Buchstaben, die mit einem einzelnen Bindestrich beginnen (z. B. `--app` hat ein Synonym). `-a` Die Reihenfolge der Optionen in einem CDK-CLI-Befehl ist nicht wichtig. Alle Optionen akzeptieren einen Wert, der dem Optionsnamen folgen muss. Der Wert kann durch Leerzeichen oder ein Gleichheitszeichen `=` vom Namen getrennt werden. Die folgenden beiden Optionen sind gleichwertig. ``` --toolkit-stack-name MyBootstrapStack --toolkit-stack-name=MyBootstrapStack ``` Einige Optionen sind Flags (Boolesche Werte). Sie können `true` oder `false` als ihren Wert angeben. Wenn Sie keinen Wert angeben, wird der Wert als `true` Sie können dem Optionsnamen auch implizit ein Präfix voranstellen`false`. `no-` ``` # sets staging flag to true --staging --staging=true --staging true # sets staging flag to false --no-staging --staging=false --staging false ``` Einige Optionen, nämlich`--context`, `--parameters``--plugin`, und `--tags``--trust`, können mehrfach angegeben werden, um mehrere Werte anzugeben. Es wird darauf hingewiesen, dass sie die CDK-CLI-Hilfe `[array]` eingegeben haben. Beispiel: ``` cdk bootstrap --tags costCenter=0123 --tags responsibleParty=jdoe ``` ## Integrierte Hilfe Die CDK-CLI hat eine integrierte Hilfe. Allgemeine Hilfe zum Tool und eine Liste der bereitgestellten Unterbefehle finden Sie, indem Sie Folgendes eingeben: ``` cdk --help ``` Um beispielsweise Hilfe für einen bestimmten Unterbefehl zu erhalten`deploy`, geben Sie ihn vor dem `--help` Flag an. ``` cdk deploy --help ``` Problem `cdk version` beim Anzeigen der Version der CDK-CLI. Geben Sie diese Informationen an, wenn Sie Support anfordern. ## Versionsberichterstattung Um einen Einblick in die Verwendung des AWS CDK zu erhalten, werden die von AWS CDK-Anwendungen verwendeten Konstrukte anhand einer als identifizierten Ressource gesammelt und gemeldet. ` AWS::CDK::Metadata` Weitere Informationen finden Sie unter [Konfigurieren der Berichterstattung über AWS CDK-Nutzungsdaten](usage-data.md). ## Authentifizierung mit AWS Je nach Umgebung und verfügbarem Zugriff gibt es verschiedene Möglichkeiten, den programmatischen AWS Zugriff auf AWS Ressourcen zu konfigurieren. Informationen zur Auswahl Ihrer Authentifizierungsmethode und deren Konfiguration für die CDK-CLI finden [Sie unter Sicherheitsanmeldedaten für die AWS CDK-CLI konfigurieren](configure-access.md). Der empfohlene Ansatz für neue Benutzer, die sich lokal entwickeln und von ihrem Arbeitgeber keine Authentifizierungsmethode erhalten, ist die Einrichtung von AWS IAM Identity Center. Diese Methode beinhaltet die Installation der AWS CLI, um die Konfiguration zu vereinfachen und sich regelmäßig beim AWS Zugriffsportal anzumelden. Wenn Sie sich für diese Methode entscheiden, sollte Ihre Umgebung die folgenden Elemente enthalten, nachdem Sie das Verfahren für die [IAM Identity Center-Authentifizierung](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) im Referenzhandbuch * AWS SDKs und im Tools-Referenzhandbuch* abgeschlossen haben: + Die AWS CLI, mit der Sie eine AWS Access-Portal-Sitzung starten, bevor Sie Ihre Anwendung ausführen. + Eine [gemeinsam genutzte AWS Konfigurationsdatei](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) mit einem `[default]` Profil mit einer Reihe von Konfigurationswerten, auf die vom AWS CDK aus verwiesen werden kann. Informationen zum Speicherort dieser Datei finden Sie unter [Speicherort der gemeinsam genutzten Dateien](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) im Referenzhandbuch * AWS SDKs und im Tools-Referenzhandbuch.* + Die gemeinsam genutzte `config` Datei legt die [Regionseinstellung](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) fest. Dadurch wird die AWS Standardregion festgelegt, die das AWS CDK und die CDK-CLI für AWS Anfragen verwenden. + Die CDK-CLI verwendet die [SSO-Token-Provider-Konfiguration](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile) des Profils, um Anmeldeinformationen abzurufen, bevor Anfragen an AWS gesendet werden. Der `sso_role_name` Wert, bei dem es sich um eine IAM-Rolle handelt, die mit einem IAM Identity Center-Berechtigungssatz verbunden ist, sollte den Zugriff auf die in Ihrer Anwendung verwendeten AWS Dienste ermöglichen. Die folgende `config` Beispieldatei zeigt ein Standardprofil, das mit der Konfiguration des SSO-Token-Anbieters eingerichtet wurde. Die `sso_session` Einstellung des Profils bezieht sich auf den benannten [`sso-session`Abschnitt](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session). Der `sso-session` Abschnitt enthält Einstellungen zum Initiieren einer AWS Access-Portal-Sitzung. ``` [default] sso_session = sso_account_id = <111122223333> sso_role_name = region = output = [sso-session ] sso_region = sso_start_url = sso_registration_scopes = sso:account:access ``` ### Starten Sie eine AWS Access-Portal-Sitzung Bevor Sie auf AWS Dienste zugreifen können, benötigen Sie eine aktive AWS Zugriffsportalsitzung, damit die CDK-CLI die IAM Identity Center-Authentifizierung zur Auflösung von Anmeldeinformationen verwenden kann. Abhängig von Ihrer konfigurierten Sitzungslänge läuft Ihr Zugriff irgendwann ab und die CDK-CLI wird auf einen Authentifizierungsfehler stoßen. Führen Sie den folgenden Befehl in der AWS CLI aus, um sich beim AWS Access Portal anzumelden. ``` aws sso login ``` Wenn Ihre SSO-Token-Provider-Konfiguration ein benanntes Profil anstelle des Standardprofils verwendet, lautet der Befehl`aws sso login --profile `. Geben Sie dieses Profil auch an, wenn Sie `cdk` Befehle mit der `--profile` Option oder der `AWS_PROFILE` Umgebungsvariablen ausgeben. Führen Sie den folgenden AWS CLI-Befehl aus, um zu testen, ob Sie bereits eine aktive Sitzung haben. ``` aws sts get-caller-identity ``` In der Antwort auf diesen Befehl sollten das in der freigegebenen `config`-Datei konfigurierte IAM-Identity-Center-Konto und der Berechtigungssatz angegeben werden. **Anmerkung** Wenn Sie bereits über eine aktive AWS Access-Portal-Sitzung verfügen und diese ausführen`aws sso login`, müssen Sie keine Anmeldeinformationen angeben. Beim Anmeldevorgang werden Sie möglicherweise aufgefordert, der AWS CLI Zugriff auf Ihre Daten zu gewähren. Da die AWS CLI auf dem SDK für Python aufbaut, können Berechtigungsnachrichten Variationen des `botocore` Namens enthalten. ## Geben Sie die Region und andere Konfigurationen an Die CDK-CLI muss die AWS Region kennen, in der Sie die Bereitstellung durchführen, und darüber, wie Sie sich authentifizieren. AWS Dies wird für Bereitstellungsvorgänge und zum Abrufen von Kontextwerten während der Synthese benötigt. Ihr Konto und Ihre Region bilden zusammen die *Umgebung*. Die Region kann mithilfe von Umgebungsvariablen oder in Konfigurationsdateien angegeben werden. Dies sind dieselben Variablen und Dateien, die von anderen AWS Tools wie der AWS CLI und den verschiedenen verwendet werden AWS SDKs. Die CDK-CLI sucht in der folgenden Reihenfolge nach diesen Informationen. + Die `AWS_DEFAULT_REGION`-Umgebungsvariable + Ein benanntes Profil, das in der AWS `config` Standarddatei definiert und mit der `--profile` Option für `cdk` Befehle angegeben wurde. + Der `[default]` Abschnitt der AWS `config` Standarddatei. Neben der Angabe der AWS Authentifizierung und einer Region im `[default]` Abschnitt können Sie auch einen oder mehrere `[profile ]` Abschnitte hinzufügen, in denen sich der Name des Profils `` befindet. Weitere Informationen zu benannten Profilen finden Sie unter [Dateien mit gemeinsam genutzten Konfigurationen und Anmeldeinformationen](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) im * AWS SDKs Referenzhandbuch zu Tools*. Die AWS `config` Standarddatei befindet sich unter `~/.aws/config` (MacOS/Linux) oder `%USERPROFILE%\.aws\config` (Windows). Einzelheiten und alternative Speicherorte finden Sie unter [Speicherort der gemeinsam genutzten Konfigurationsdateien und Anmeldeinformationen im Referenzhandbuch](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) für * AWS SDKs Tools* Die Umgebung, die Sie in Ihrer AWS CDK-App mithilfe der `env` Stack-Eigenschaft angeben, wird bei der Synthese verwendet. Es wird verwendet, um eine umgebungsspezifische AWS CloudFormation Vorlage zu generieren, und während der Bereitstellung überschreibt es das Konto oder die Region, das mit einer der vorherigen Methoden angegeben wurde. Weitere Informationen finden Sie unter [Umgebungen für](environments.md) das CDK. AWS **Anmerkung** Das AWS CDK verwendet Anmeldeinformationen aus denselben Quelldateien wie andere AWS Tools SDKs, einschließlich der [AWS Befehlszeilenschnittstelle](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). Das AWS CDK kann sich jedoch etwas anders verhalten als diese Tools. Es verwendet das AWS SDK für den Einsatz JavaScript unter der Haube. Vollständige Informationen zum Einrichten von Anmeldeinformationen für das AWS SDK für JavaScript finden Sie unter [Anmeldeinformationen einrichten](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials.html). Sie können optional die Option `--role-arn` (oder`-r`) verwenden, um den ARN einer IAM-Rolle anzugeben, die für die Bereitstellung verwendet werden soll. Diese Rolle muss von dem verwendeten AWS Konto übernommen werden können. ## Geben Sie den App-Befehl an Für viele Funktionen der CDK-CLI müssen eine oder mehrere AWS CloudFormation Vorlagen synthetisiert werden, was wiederum die Ausführung Ihrer Anwendung erfordert. Das AWS CDK unterstützt Programme, die in einer Vielzahl von Sprachen geschrieben wurden. Daher verwendet es eine Konfigurationsoption, um genau den Befehl anzugeben, der zum Ausführen Ihrer App erforderlich ist. Diese Option kann auf zwei Arten angegeben werden. Erstens und am häufigsten kann sie mithilfe des `app` Schlüssels in der Datei angegeben werden`cdk.json`. Dies befindet sich im Hauptverzeichnis Ihres AWS CDK-Projekts. Die CDK-CLI bietet einen entsprechenden Befehl, wenn Sie ein neues Projekt mit `cdk init` erstellen. Hier ist zum Beispiel das `cdk.json` aus einem neuen TypeScript Projekt. ``` { "app": "npx ts-node bin/hello-cdk.ts" } ``` Die CDK-CLI sucht `cdk.json` im aktuellen Arbeitsverzeichnis, wenn sie versucht, Ihre App auszuführen. Aus diesem Grund können Sie im Hauptverzeichnis Ihres Projekts eine Shell für die Ausgabe von CDK-CLI-Befehlen geöffnet lassen. Die CDK-CLI sucht auch nach dem App-Schlüssel in `~/.cdk.json` (d. h. in Ihrem Home-Verzeichnis), wenn sie ihn nicht finden kann. `./cdk.json` Das Hinzufügen des App-Befehls hier kann nützlich sein, wenn Sie normalerweise mit CDK-Code in derselben Sprache arbeiten. Wenn du dich in einem anderen Verzeichnis befindest oder wenn du deine App mit einem anderen Befehl als dem in ausführen möchtest`cdk.json`, verwende die Option `--app` (oder`-a`), um ihn anzugeben. ``` cdk --app "npx ts-node bin/hello-cdk.ts" ls ``` Bei der Bereitstellung können Sie auch ein Verzeichnis angeben, das synthetisierte Cloud-Assemblys enthält`cdk.out`, z. B. als Wert von`--app`. Die angegebenen Stacks werden von diesem Verzeichnis aus bereitgestellt; die App wird nicht synthetisiert. ## Geben Sie Stapel an Viele CDK-CLI-Befehle (zum Beispiel`cdk deploy`) funktionieren mit Stacks, die in Ihrer App definiert sind. Wenn Ihre App nur einen Stack enthält, geht die CDK-CLI davon aus, dass Sie diesen meinen, wenn Sie keinen Stack explizit angeben. Andernfalls müssen Sie den Stack oder die Stacks angeben, mit denen Sie arbeiten möchten. Sie können dies tun, indem Sie die gewünschten Stacks einzeln nach ID in der Befehlszeile angeben. Denken Sie daran, dass die ID der Wert ist, der durch das zweite Argument angegeben wird, wenn Sie den Stack instanziieren. ``` cdk synth PipelineStack LambdaStack ``` Sie können auch Platzhalter verwenden, um anzugeben, IDs dass sie einem Muster entsprechen. + `?`entspricht einem beliebigen einzelnen Zeichen + `*`entspricht einer beliebigen Anzahl von Zeichen (`*`allein entspricht allen Stapeln) + `**`entspricht allem in einer Hierarchie Sie können die `--all` Option auch verwenden, um alle Stapel anzugeben. Wenn Ihre App [CDK Pipelines](cdk-pipeline.md) verwendet, versteht die CDK-CLI Ihre Stacks und Stages als Hierarchie. Außerdem entsprechen die `--all` Option und der `*` Platzhalter nur Stacks der obersten Ebene. Um alle Stapel abzugleichen, verwenden Sie. `**` Wird auch verwendet`**`, um alle Stapel unter einer bestimmten Hierarchie anzugeben. Wenn Sie Platzhalter verwenden, setzen Sie das Muster in Anführungszeichen oder maskieren Sie die Platzhalter mit. `\` Wenn Sie dies nicht tun, versucht Ihre Shell möglicherweise, das Muster auf die Namen der Dateien im aktuellen Verzeichnis zu erweitern. Im besten Fall wird dies nicht das tun, was Sie erwarten. Im schlimmsten Fall könnten Sie Stacks bereitstellen, die Sie nicht beabsichtigt hatten. Dies ist unter Windows nicht unbedingt erforderlich, da Platzhalter `cmd.exe` nicht erweitert werden, ist aber dennoch eine bewährte Methode. ``` cdk synth "*Stack" # PipelineStack, LambdaStack, etc. cdk synth 'Stack?' # StackA, StackB, Stack1, etc. cdk synth \* # All stacks in the app, or all top-level stacks in a CDK Pipelines app cdk synth '**' # All stacks in a CDK Pipelines app cdk synth 'PipelineStack/Prod/**' # All stacks in Prod stage in a CDK Pipelines app ``` **Anmerkung** Die Reihenfolge, in der Sie die Stapel angeben, entspricht nicht unbedingt der Reihenfolge, in der sie verarbeitet werden. Die CDK-CLI berücksichtigt Abhängigkeiten zwischen Stacks, wenn sie entscheidet, in welcher Reihenfolge sie verarbeitet werden sollen. Nehmen wir zum Beispiel an, dass ein Stapel einen Wert verwendet, der von einem anderen erzeugt wird (z. B. den ARN einer im zweiten Stack definierten Ressource). In diesem Fall wird der zweite Stapel aufgrund dieser Abhängigkeit vor dem ersten synthetisiert. Sie können Abhängigkeiten zwischen Stacks manuell hinzufügen, indem Sie die Methode des Stacks ` [addDependency()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#addwbrdependencytarget-reason) ` verwenden. ## Bootstrap für deine Umgebung AWS Für die Bereitstellung von Stacks mit dem CDK müssen spezielle, dedizierte AWS CDK-Ressourcen bereitgestellt werden. Der `cdk bootstrap` Befehl erstellt die erforderlichen Ressourcen für Sie. Sie müssen das Bootstrap nur ausführen, wenn Sie einen Stack bereitstellen, der diese dedizierten Ressourcen benötigt. Einzelheiten finden Sie unter [AWS CDK-Bootstrapping](bootstrapping.md). ``` cdk bootstrap ``` Wenn der `cdk bootstrap` Befehl ohne Argumente ausgegeben wird, wie hier gezeigt, synthetisiert er die aktuelle App und bootet die Umgebungen, in denen die Stacks bereitgestellt werden. Wenn die App umgebungsunabhängige Stacks enthält, die nicht explizit eine Umgebung angeben, werden das Standardkonto und die Region oder die mit angegebene Umgebung gebootet. `--profile` Außerhalb einer App müssen Sie die Umgebung, für die ein Bootstrap erstellt werden soll, explizit angeben. Sie können dies auch tun, um eine Umgebung zu booten, die nicht in Ihrer App oder Ihrem lokalen Profil angegeben ist. AWS Die Anmeldeinformationen müssen für das angegebene Konto und die angegebene Region konfiguriert sein (z. B. in`~/.aws/credentials`). Sie können ein Profil angeben, das die erforderlichen Anmeldeinformationen enthält. ``` cdk bootstrap / # e.g. cdk bootstrap 1111111111/us-east-1 cdk bootstrap --profile test 1111111111/us-east-1 ``` **Wichtig** Jede Umgebung (Kombination aus Konto und Region), in der Sie einen solchen Stack bereitstellen, muss separat gebootet werden. Für das, was das AWS CDK in den Bootstrap-Ressourcen speichert, können AWS Gebühren anfallen. Darüber hinaus wird bei Verwendung ein AWS KMS-Schlüssel erstellt`--bootstrap-customer-key`, für den ebenfalls Gebühren pro Umgebung anfallen. **Anmerkung** In früheren Versionen der Bootstrap-Vorlage wurde standardmäßig ein KMS-Schlüssel erstellt. Um Gebühren zu vermeiden, starten Sie das System erneut mit. `--no-bootstrap-customer-key` **Anmerkung** CDK CLI v2 unterstützt nicht die ursprüngliche Bootstrap-Vorlage, die als Legacy-Template bezeichnet wird und standardmäßig mit CDK v1 verwendet wird. **Wichtig** Die moderne Bootstrap-Vorlage gewährt praktisch jedem Konto in der Liste die `--cloudformation-execution-policies` damit verbundenen Berechtigungen. AWS `--trust` Standardmäßig werden dadurch die Lese- und Schreibberechtigungen für alle Ressourcen im Bootstrap-Konto erweitert. Stellen Sie sicher, dass [Sie den Bootstrapping-Stack mit Richtlinien und vertrauenswürdigen Konten konfigurieren](bootstrapping-customizing.md), mit denen Sie vertraut sind. ## Erstellen Sie eine neue App Um eine neue App zu erstellen, erstellen Sie ein Verzeichnis dafür und geben Sie dann innerhalb des Verzeichnisses das Problem ein`cdk init`. ``` mkdir my-cdk-app cd my-cdk-app cdk init