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

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:

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

Vorteile des CDK-Refactorings

CDK-Refactoring bietet CDK-Entwicklern die folgenden Vorteile: AWS

So funktioniert der cdk refactor CDK-CLI-Befehl

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:

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

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ührencdk 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ätigeny, 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:

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.

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 Weise:

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:

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:

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

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 CDK Toolkit Library.