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. # Schonen Sie die bereitgestellten Ressourcen beim Refactoring von CDK-Code **Wichtig** Das CDK-Refactoring befindet sich in der Vorschauversion und kann sich ändern. Mit dem Refactoring des AWS Cloud Development Kit (AWS CDK) können Sie Ihren CDK-Code umgestalten, z. B. Konstrukte umbenennen, Ressourcen zwischen Stacks verschieben und Ihre Anwendung neu organisieren, während Ihre bereitgestellten Ressourcen erhalten bleiben, anstatt sie zu ersetzen. Diese Funktion hilft Ihnen dabei, bewährte Methoden für die Softwareentwicklung beizubehalten, ohne dass es zu einem unbeabsichtigten Austausch von Ressourcen kommt. ## Was ist CDK-Refactoring mit Ressourcenschonung? Wenn Sie eine CDK-Anwendung bereitstellen, AWS CloudFormation identifiziert Ressourcen anhand ihrer logischen Eigenschaften. IDs Das AWS CDK generiert diese logisch auf der IDs Grundlage der Konstrukt-ID und ihres Pfads im Konstruktbaum. Wenn Sie die ID eines Konstrukts ändern oder es an eine andere Stelle in Ihrem Code verschieben, interpretiert es dies AWS CloudFormation normalerweise als Aufforderung, eine neue Ressource zu erstellen und die alte zu löschen. Bei zustandsbehafteten Ressourcen wie Datenbanken, Speicher-Buckets oder Warteschlangen kann dieser Ersatz zu Dienstunterbrechungen oder Datenverlust führen. Mit CDK-Refactoring wird diese Herausforderung wie folgt angegangen: + Erkennt, wann Ressourcen in Ihrem Code verschoben oder umbenannt wurden. + Verwenden Sie AWS CloudFormation die Refactoring-Funktionen, um die zugrunde liegenden physischen Ressourcen zu erhalten. + Logische Aktualisierung, IDs ohne die tatsächlichen Ressourcen zu ersetzen. + Beibehaltung von Verweisen zwischen Ressourcen in Ihren Stacks. Sie können das CDK-Refactoring entweder mit dem `cdk refactor` CDK-CLI-Befehl oder mit der Aktion der CDK Toolkit-Bibliothek durchführen. `refactor` In diesem Handbuch wird hauptsächlich der CLI-Ansatz behandelt, aber die zugrunde liegenden Prinzipien gelten für beide Methoden. Informationen zur Verwendung der Toolkit-Bibliothek finden Sie unter [Ausführen programmatischer Aktionen mithilfe der CDK](toolkit-library.md) Toolkit-Bibliothek. **Wichtig** Refactoring-Operationen müssen eigenständig und getrennt von anderen Aktionen wie dem Hinzufügen neuer Ressourcen, dem Löschen von Ressourcen oder dem Ändern von Ressourceneigenschaften ausgeführt werden. Wenn Sie Ressourcen hinzufügen, löschen oder ändern sowie ein Refactoring durchführen müssen, sollten Sie diese Änderungen zunächst separat bereitstellen und dann Refactoring verwenden, um Ihre Ressourcen neu zu organisieren. ## Vorteile des CDK-Refactorings CDK-Refactoring bietet CDK-Entwicklern die folgenden Vorteile: AWS + **Verbessern Sie die Codeorganisation** — Benennen Sie Konstrukte um und organisieren Sie die Struktur Ihrer CDK-Anwendung neu, ohne Ressourcen zu ersetzen. + **Erstellen Sie wiederverwendbare Komponenten** — Extrahieren Sie duplizierten Code in wiederverwendbare L3-Konstrukte und schonen Sie gleichzeitig die bereitgestellten Ressourcen. + **Verbessern Sie die architektonische Trennung** — Verschieben Sie Ressourcen zwischen Stacks, um verschiedene Teile Ihrer Anwendung besser zu isolieren. + **Vermeiden Sie den versehentlichen Austausch von Ressourcen** — Vermeiden Sie die unbeabsichtigte Wiederherstellung von Ressourcen beim Umbenennen von Konstrukten. + **Vermeiden Sie Bibliotheksänderungen von Drittanbietern** — Schützen Sie Ihre Anwendung vor logischen ID-Änderungen in Konstruktbibliotheken, auf die Sie angewiesen sind. + **Wenden Sie bewährte Methoden für die Softwareentwicklung** an — Refaktorieren Sie Ihren Code, ohne Ihre bereitgestellte Infrastruktur zu gefährden. ## So funktioniert der `cdk refactor` CDK-CLI-Befehl **Wichtig** Sie müssen die `--unstable=refactor` Option bei allen Befehlen angeben, die diese Funktion verwenden. Zunächst stellen Sie Ihre erste CDK-Anwendung bereit, um Basisressourcen in Ihrem AWS Konto einzurichten. Nachdem Sie Ihren CDK-Code umgestaltet haben, z. B. Konstrukte umbenannt oder Ressourcen zwischen Stacks verschoben haben, verwenden Sie den `cdk refactor` Befehl, um mit dem Refactoring Ihrer bereitgestellten Ressourcen zu beginnen. Wenn Sie den Refactor-Befehl ausführen, erkennt die CDK-CLI Ihre lokalen Änderungen, indem sie Ihren aktuellen Code mit dem bereitgestellten Status vergleicht. Es überprüft, ob Ihre CDK-Anwendung genau den gleichen Satz von Ressourcen wie der bereitgestellte Status enthält und sich nur in ihren Positionen im Konstruktbaum unterscheidet. Die CDK-CLI generiert dann einen Refactor-Plan, der die alten Ressourcenstandorte ihren neuen Standorten zuordnet. Die CDK-CLI zeigt Ihnen die vorgeschlagenen Änderungen und verwendet AWS CloudFormation nach Ihrer Bestätigung die Refactoring-API, um die Logik IDs der Ressourcen zu aktualisieren, ohne sie zu ersetzen. Hinter den Kulissen ermittelt die CDK-CLI, welche Ressourcen verschoben wurden, indem sie ihre Eigenschaften und Abhängigkeiten vergleicht und Ressourcen identifiziert, die funktionell gleichwertig sind, aber unterschiedliche Pfade im Konstruktbaum haben. Wenn sie feststellt, dass Ressourcen hinzugefügt, gelöscht oder geändert wurden, wird der Refactoring-Vorgang mit einer Fehlermeldung abgelehnt. ## Beispiel für die Erhaltung von Ressourcen beim Refactoring von CDK-Code In diesem Beispiel behalten wir die bereitgestellten Ressourcen bei, während wir unseren CDK-Code mithilfe des CDK-CLI-Befehls umgestalten. `cdk refactor` Unsere CDK-Beispielanwendung besteht aus einem einzelnen Stack, der einen S3-Bucket, eine CloudFront Distribution und eine Lambda-Funktion enthält. Der Konstruktbaum ist wie folgt strukturiert: ``` App └─ MyStack ├─ Bucket ├─ Distribution └─ Function ``` Das Folgende ist ein Beispiel für unseren Anwendungscode: ``` 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(); ``` Stellen Sie sich nun vor, Sie möchten diesen Code wie folgt umgestalten: 1. Benennen Sie den Bucket von `Bucket` in den `WebsiteOrigin` aussagekräftigeren um. 1. Verschieben Sie den Bucket und die Distribution in einen neuen `WebStack` Stack. Nach dem Refactoring würde der Konstruktbaum wie folgt aussehen: ``` App ├─ WebStack │ ├─ WebsiteOrigin │ └─ Distribution └─ MyStack └─ Function ``` Und der umgestaltete Code wäre: ``` // 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(); ``` Ohne CDK-Refactoring würden diese Änderungen AWS CloudFormation dazu führen, dass neue Ressourcen erstellt und die alten gelöscht werden, da sich die Logik ändern würde: IDs + `MyStack/Bucket/Resource`würde werden. `WebStack/WebsiteOrigin/Resource` + `MyStack/Distribution/Resource`würde werden`WebStack/Distribution/Resource`. Beim CDK-Refactoring erkennt die CDK-CLI diese Pfadänderungen und nutzt die Refactoring-Funktionen, um die AWS CloudFormation zugrunde liegenden Ressourcen zu schonen. Wenn Sie sie ausführen`cdk refactor`, zeigt Ihnen die CLI die Änderungen, die sie vornehmen wird: ``` $ 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)? ``` Wenn Sie mit Eingabe bestätigen`y`, zeigt die CDK-CLI den Fortschritt des Refactoring-Vorgangs an: ``` Refactoring... ✅ Stack refactor complete ``` Nach der Bestätigung führt die CDK-CLI den Refactoring-Vorgang aus, wobei beide Ressourcen erhalten bleiben und gleichzeitig ihre logische Logik IDs an Ihre neue Codestruktur angepasst wird. Dieselbe Zuordnung wird auch in der Ausgabe des `cdk diff` Befehls angezeigt, geordnet nach Stapel: ``` 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) ... ``` ## Beginnen Sie mit dem CDK-Refactoring Um mit dem Refactoring zu beginnen, müssen Sie die folgenden Voraussetzungen erfüllen: **Führen Sie ein Bootstrapping für Ihre Umgebung mit der neuesten Vorlage durch** Die CDK-Refactoring-Funktion erfordert neue Berechtigungen im Bootstrap-Stack. Um sicherzustellen, dass Sie über die erforderlichen Berechtigungen verfügen, booten Sie Ihre Umgebung mit der neuesten Vorlage: ``` cdk bootstrap ``` Weitere Informationen zu Bootstrapping finden Sie unter [Bootstrapping-Umgebungen für AWS CDK](bootstrapping-env.md). **Installieren Sie die neueste CDK-CLI-Version** CDK-Refactoring erfordert eine aktuelle Version der CDK-CLI. Um sicherzustellen, dass Sie die neueste Version haben: ``` npm install -g aws-cdk ``` Detaillierte Installationsanweisungen finden Sie unter [Erste Schritte mit dem AWS CDK](getting-started.md). ## Verwenden Sie Override-Dateien, um Unklarheiten beim Refactoring zu beheben Die CDK-CLI berechnet automatisch alle Ressourcenzuordnungen auf der Grundlage des Vergleichs Ihres Codes mit den bereitgestellten Ressourcen. In den meisten Fällen funktioniert diese automatische Erkennung gut, aber es gibt Situationen, in denen die CLI auf Unklarheiten stoßen kann, die sie alleine nicht lösen kann. Verwenden Sie eine Override-Datei, um Anleitungen für die CDK-CLI bereitzustellen. **Erstellen Sie eine Override-Datei, um Unklarheiten zu beheben** Eine Override-Datei ist eine JSON-Datei, die Zuordnungen bereitstellt, wenn die CDK-CLI keine Refactoring-Auflösung für Ressourcen ermitteln kann. Die Datei enthält nach Umgebung geordnete Ressourcenzuordnungen: ``` { "environments": [ { "account": "123456789012", "region": "us-east-2", "resources": { "StackA.OldName": "StackB.NewName", "StackC.Foo": "StackC.Bar" } } ] } ``` In dieser Datei: + Das `environments` Array enthält einen oder mehrere Umgebungseinträge mit Konto und Region. + In jeder Umgebung enthält das `resources` Objekt die Zuordnungen. + Schlüssel stellen die aktuellen Positionen im Format dar. `.` + Werte stehen für die neuen Standorte im gleichen Format. Um eine Override-Datei mit der CDK-CLI CLI: ``` cdk refactor --override-file=overrides.json ``` ## Refactoring von Stacks in mehreren Umgebungen Eine CDK-Anwendung kann mehrere Stacks enthalten, die in verschiedenen Umgebungen (AWS Konten und Regionen) bereitgestellt werden. Wenn beim Refactoring in solchen Anwendungen Ressourcen geschont werden, behandelt die CDK-CLI Umgebungen auf eine bestimmte Art und Weise: + Die CLI gruppiert Stacks nach Umgebung und führt das Refactoring in jeder Umgebung separat durch. + Sie können während des Refactorings Ressourcen zwischen Stacks verschieben, aber alle an der Verschiebung beteiligten Stacks müssen sich in derselben Umgebung befinden. + Der Versuch, Ressourcen zwischen Umgebungen zu verschieben, führt zu einem Fehler. Durch dieses Verhalten wird sichergestellt, dass Ressourcen innerhalb ihres ursprünglichen AWS Kontos und ihrer ursprünglichen Region bleiben. Dies ist notwendig, da CloudFormation Ressourcen nicht physisch über Konto- oder Regionsgrenzen hinweg verschoben werden können. Wenn Ihre CDK-Anwendung beispielsweise Stacks sowohl für Entwicklungs- als auch für Produktionsumgebungen definiert, wird der Refactoring-Vorgang in jeder Umgebung unabhängig durchgeführt. Ressourcen können zwischen Stacks innerhalb der Entwicklungsumgebung oder innerhalb der Produktionsumgebung verschoben werden, jedoch nicht von der Entwicklung zur Produktion oder umgekehrt. ## Umgang mit Ressourcen, die ersetzt werden sollen Einige CDK-Konstrukte stützen sich bei ihrem CloudFormation Entwurf auf das Verhalten beim Ersetzen von Ressourcen. Die `Version` Konstrukte von API Gateway `Deployment` und Lambda sind beispielsweise darauf ausgelegt, neue Ressourcen zu erstellen, wenn sich ihre Eigenschaften ändern. Nehmen Sie beim Refactoring keine Änderungen vor, die zu einem Austausch von Ressourcen führen sollten. Andernfalls kann die CDK-CLI diese Ressourcen erkennen und speichern. Das bedeutet, dass Ressourcen, die ersetzt werden sollen, getrennt von Refactoring-Vorgängen behandelt werden müssen. Gehen Sie wie folgt vor, um Ressourcen, die ersetzt werden sollen, ordnungsgemäß zu verwalten: 1. Stellen Sie zunächst Ihre Anwendung bereit, um diese Ressourcen nach Bedarf zu ersetzen. 1. Führen Sie dann Ihre Refactoring-Operationen separat durch, um Ihren Code neu zu organisieren. Dieser zweistufige Ansatz stellt sicher, dass Ressourcen, die ersetzt werden sollen, ordnungsgemäß behandelt werden, und ermöglicht Ihnen gleichzeitig, vom CDK-Refactoring für andere Ressourcen zu profitieren. ## Allgemeine Überlegungen und Einschränkungen Wenn Sie beim CDK-Refactoring Ressourcen schonen, sollten Sie die folgenden Überlegungen berücksichtigen: + **Umgebungsbeschränkungen**: Ressourcen können nur zwischen Stacks in derselben Umgebung verschoben werden. Umgebungsübergreifende Verschiebungen werden nicht unterstützt. + **Mehrdeutigkeit**: Wenn Sie über mehrere identische Ressourcen verfügen, die gleichzeitig umbenannt werden, kann die CDK-CLI möglicherweise nicht automatisch die richtige Zuordnung ermitteln. In diesen Fällen müssen Sie eine explizite Zuordnung mithilfe einer Override-Datei angeben. + **Bootstrap-Anforderungen**: Um beim Refactoring Ressourcen zu schonen, müssen Sie Ihren Bootstrap-Stack mit der neuesten Version aktualisieren, die die erforderlichen Berechtigungen enthält. + **Bestimmte Konstrukte sind ausgeschlossen**: Einige Konstrukte wie API Gateways `Deployment` und Lambdas sind auf den Ersatz von Ressourcen `Version` angewiesen und werden automatisch vom Refactoring ausgeschlossen. ## Refactoring mit Pipelines CI/CD Um die Refactoring-Funktion in CI/CD Pipelines verwenden zu können, müssen Sie in der Lage sein, die CDK-CLI als Teil Ihrer Pipeline auszuführen. Im Folgenden finden Sie einige wichtige Überlegungen zur Integration von Refactoring in Ihren Workflow. CI/CD **Voraussetzungen für die Verwendung von Refactoring in CI/CD** Sie müssen in der Lage sein, die CDK-CLI in Ihrer CI/CD Umgebung zu verwenden, um von dieser Funktion zu profitieren. **Integrieren Sie Refactoring in Ihren Pipeline-Workflow** Wenn Sie die CLI für die Bereitstellung in Ihrer CI/CD Pipeline verwenden, sieht Ihr Skript normalerweise wie folgt aus: ``` ... cdk deploy ... ``` Wenn Sie Refactoring als Teil des Workflows einbeziehen möchten, finden Sie im Folgenden ein einfaches Beispiel: ``` ... cdk refactor cdk deploy ... ``` Sie können das Refactoring auch als separaten Schritt in Ihrer Pipeline einrichten. **Behandlung von Refactoring-Fehlern** Beachten Sie, dass `cdk refactor` dies fehlschlägt, wenn Ihr Code neben dem Refactoring auch tatsächliche Ressourcenänderungen enthält. Da Sie Refactor automatisch in Ihrer Pipeline aufrufen, müssen Sie mit potenziellen Fehlern umgehen: ``` # Allow refactoring to fail but continue the pipeline cdk refactor || true cdk deploy ``` Alternativ möchten Sie vielleicht sicherstellen, dass keine Bereitstellung erfolgt, bis Sie einen erfolgreichen Refactor ausgeführt haben: ``` # Only deploy if refactoring succeeds cdk refactor && cdk deploy ``` **Bewährte Methoden für Umgebungen CI/CD ** So nutzen Sie Refactoring effektiv in CI/CD Pipelines: + **Trennen Sie das Refactoring von anderen Änderungen**: Denken Sie daran, dass Refactoring-Operationen von Hinzufügungen, Löschungen oder Änderungen von Ressourcen getrennt sein müssen. In Ihrer Pipeline sollten Sie erwägen, spezielle Commits und Deployments für das Refactoring einzurichten. + **Verwenden Sie Override-Dateien angemessen**: Beachten Sie, dass Override-Dateien von der CDK-CLI nur als Fallback zur Lösung von Mehrdeutigkeitsfällen verwendet werden. + In-Pipelines sind **nicht erforderlich: `--force` In nicht interaktiven Umgebungen wie CI/CD Pipelines** wird der CDK-Refactor-Befehl automatisch ausgeführt, ohne dass eine Bestätigung erforderlich ist. Die `--force` Option wird nur in interaktiven Umgebungen benötigt. ## Zugehörige Ressourcen Informationen zu Optionen und Argumenten für den `cdk refactor` CDK-CLI-Befehl finden Sie unter` cdk refactor `. Informationen zu den ersten Schritten mit der `refactor` Aktion der CDK Toolkit Library finden Sie unter [Ausführen programmatischer Aktionen mit der](toolkit-library.md) CDK Toolkit Library.