Das ist der AWS CDK v2-Entwicklerhandbuch. Für das ältere CDK v1 wurde am 1. Juni 2022 der Wartungsservice aufgenommen und der Support endete am 1. Juni 2023.

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.

Bewahren Sie beim Refactoring von CDK-Code die bereitgestellten Ressourcen auf

Mit AWS Cloud-Entwicklungskit (AWS Beim Refactoring (CDK) können Sie Ihren CDK-Code umgestalten, z. B. Konstrukte umbenennen, Ressourcen zwischen Stapeln verschieben und Ihre Anwendung neu organisieren. Dabei bleiben Ihre bereitgestellten Ressourcen erhalten, anstatt sie zu ersetzen. Diese Funktion hilft Ihnen dabei, bewährte Methoden der 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 IDs. Die AWS CDK generiert diese logischen IDs auf der 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, AWS CloudFormation interpretiert dies 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 Betriebsunterbrechungen oder Datenverlust führen.

CDK-Refactoring begegnet dieser Herausforderung durch:

Sie können das CDK-Refactoring entweder mit der CDK-CLI durchführen cdk refactor Befehl oder die CDK Toolkit-Bibliothek refactor Aktion. In diesem Handbuch wird hauptsächlich der CLI-Ansatz behandelt, die zugrunde liegenden Prinzipien gelten jedoch für beide Methoden. Informationen zur Verwendung der Toolkit-Bibliothek finden Sie unter Führen Sie programmatische Aktionen mithilfe der CDK Toolkit-Bibliothek durch.

Vorteile des CDK-Refactorings

CDK-Refactoring bietet die folgenden Vorteile für AWS CDK-Entwickler:

Wie funktioniert das CDK CLI CDK-Refaktor Befehl funktioniert

Zuerst stellen Sie Ihre erste CDK-Anwendung bereit, um die Basisressourcen in Ihrem AWS Konto. Nachdem Sie Ihren CDK-Code umgestaltet haben, z. B. Konstrukte umbenannt oder Ressourcen zwischen Stapeln 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 Status der Bereitstellung vergleicht. Es überprüft, ob Ihre CDK-Anwendung genau die gleichen Ressourcen wie der Status „Bereitgestellt“ 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 nach Ihrer Bestätigung AWS CloudFormationDie Refactoring-API, um die logischen IDs von 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. Dabei werden Ressourcen identifiziert, die funktionell gleichwertig sind, aber unterschiedliche Pfade im Konstruktbaum haben. Wenn Ressourcen hinzugefügt, gelöscht oder geändert werden, wird der Refactoring-Vorgang mit einer Fehlermeldung abgelehnt.

Beispiel für die Schonung von Ressourcen beim Refactoring von CDK-Code

In diesem Beispiel behalten wir die bereitgestellten Ressourcen bei und refaktorieren gleichzeitig unseren CDK-Code mithilfe der CDK-CLI cdk refactor Befehl.

Unsere CDK-Beispielanwendung besteht aus einem einzelnen Stack, der einen S3-Bucket enthält, einen CloudFront Verteilung und eine Lambda-Funktion. 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 so 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 dazu führen AWS CloudFormation um neue Ressourcen zu erstellen und die alten zu löschen, da sich die logischen IDs ändern würden:

Beim CDK-Refactoring erkennt die CDK-CLI diese Pfadänderungen und verwendet AWS CloudFormationbietet Refactoring-Funktionen, um die zugrunde liegenden Ressourcen zu schonen. Wenn du rennst cdk refactor, die CLI zeigt Ihnen 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 bestätigen, indem Sie Folgendes eingeben y, die CDK-CLI zeigt 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 logischen IDs aktualisiert werden, sodass sie Ihrer neuen Codestruktur entsprechen.

Dieselbe Zuordnung wird auch in der Ausgabe von angezeigt cdk diff Befehl, sortiert 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

Erfüllen Sie die folgenden Voraussetzungen, um mit dem Refactoring zu beginnen:

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 stößt, die sie nicht alleine lösen kann. Verwenden Sie eine Override-Datei, um eine Anleitung für die CDK-CLI bereitzustellen.

Refactoring von Stacks in mehreren Umgebungen

Eine CDK-Anwendung kann mehrere Stacks enthalten, die in verschiedenen Umgebungen bereitgestellt werden (AWS Konten und Regionen). Wenn beim Refactoring in solchen Anwendungen Ressourcen geschont werden, behandelt die CDK CLI Umgebungen auf eine bestimmte Art und Weise:

Dieses Verhalten stellt sicher, dass die Ressourcen in ihrem ursprünglichen Zustand bleiben AWS Konto und Region, was notwendig ist, weil CloudFormation Ressourcen können nicht physisch über Konto- oder Regionsgrenzen hinweg verschoben werden.

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 innerhalb der Entwicklungsumgebung oder innerhalb der Produktionsumgebung zwischen Stacks verschoben werden, jedoch nicht von der Entwicklung zur Produktion oder umgekehrt.

Umgang mit Ressourcen, die ersetzt werden sollen

Einige CDK-Konstrukte basieren auf CloudFormationdas Verhalten beim Ersetzen von Ressourcen als Teil ihres Designs. Zum Beispiel das von API Gateway Deployment und Lambdas Version Konstrukte sind so konzipiert, dass sie neue Ressourcen erstellen, wenn sich ihre Eigenschaften ändern.

Nehmen Sie beim Refactoring keine Änderungen vor, die zu einem Austausch von Ressourcen führen sollten. Andernfalls erkennt und bewahrt die CDK-CLI diese Ressourcen möglicherweise auf. Das bedeutet, dass Ressourcen, die für den Austausch vorgesehen sind, getrennt von den 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 es Ihnen gleichzeitig, das CDK-Refactoring für andere Ressourcen zu nutzen.

Allgemeine Überlegungen und Einschränkungen

Beachten Sie beim Schonen von Ressourcen beim CDK-Refactoring die folgenden Überlegungen:

Refactoring mit CI/CD Rohrleitungen

Um die Refactoring-Funktion zu verwenden in CI/CD Pipelines, Sie müssen 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 Ihre CI/CD Arbeitsablauf.

Zugehörige Ressourcen

Für Informationen zu Optionen und Argumenten für die CDK-CLI cdk refactor Befehl finden Sie unter cdk refactor .

Um mit der CDK Toolkit Library zu beginnen refactor Aktion, siehe Führen Sie programmatische Aktionen mithilfe der CDK Toolkit-Bibliothek durch.