Dies ist das AWS CDK v2 Developer Guide. Für das ältere CDK v1 wurde am 1. Juni 2022 die Wartung abgeschlossen 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.

Schonen Sie die bereitgestellten Ressourcen, wenn Sie den CDK-Code umgestalten

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. 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, werden Ressourcen AWS CloudFormation anhand ihrer logischen IDs identifiziert. Das 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, wird dies in AWS CloudFormation der Regel als Aufforderung interpretiert, 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 Datenverlusten führen.

Das CDK-Refactoring begegnet dieser Herausforderung durch:

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, die zugrunde liegenden Prinzipien gelten jedoch für beide Methoden. Informationen zur Verwendung der Toolkit-Bibliothek finden Sie unter Durchfü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 CLI-Befehl cdk refactor

Zunächst stellen Sie Ihre erste CDK-Anwendung bereit, um die Basisressourcen in Ihrem AWS Konto einzurichten. 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 AWS CloudFormation nach Ihrer Bestätigung die Refactoring-API, um die logischen 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 äquivalent sind, aber unterschiedliche Pfade im Konstruktbaum haben. Wenn Ressourcen hinzugefügt, gelöscht oder geändert werden, wird der Refactoring-Vorgang mit einer Fehlermeldung zurückgewiesen.

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 des CDK-CLI-Befehls. 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 das CDK-Refactoring würden diese Änderungen AWS CloudFormation dazu führen, dass neue Ressourcen erstellt und die alten gelöscht werden, da sich die logischen IDs ändern würden:

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 die CLI 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 durch 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 logischen IDs aktualisiert werden, sodass sie Ihrer neuen Codestruktur entsprechen.

Dieselbe Zuordnung wird auch in der Ausgabe des cdk diff Befehls angezeigt, 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 (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:

Dieses Verhalten stellt sicher, dass Ressourcen innerhalb ihres ursprünglichen AWS Kontos und ihrer Region verbleiben. 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 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 verlassen sich bei ihrem CloudFormation Entwurf auf das Verhalten beim Ersetzen von Ressourcen. Beispielsweise sind die Version Konstrukte von API Gateway Deployment und Lambda 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 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 Arbeitsablauf. 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-Bibliothek finden Sie unter Durchführen von programmatischen Aktionen mithilfe der CDK Toolkit-Bibliothek.