Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 in die Wartung aufgenommen 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.
# Führen Sie programmatische Aktionen mit der CDK Toolkit Library aus
## Die CDK Toolkit-Bibliothek verstehen
Mit der CDK Toolkit Library können Sie CDK-Aktionen programmgesteuert über Code ausführen, anstatt CLI-Befehle zu verwenden. Sie können diese Bibliothek verwenden, um benutzerdefinierte Tools zu erstellen, spezielle CLI-Anwendungen zu erstellen und CDK-Funktionen in Ihre Entwicklungsworkflows zu integrieren.
**Verwalten Sie den Lebenszyklus Ihrer Infrastruktur mit programmatischer Steuerung**
Die CDK Toolkit Library bietet programmatische Schnittstellen für die folgenden CDK-Aktionen:
+ **Synthese** — Generieren Sie AWS CloudFormation Vorlagen und Bereitstellungsartefakte.
+ **Bereitstellung** — Bereitstellung oder Aktualisierung der Infrastruktur mithilfe von CloudFormation Vorlagen.
+ **Refactor** — Beim Refactoring von CDK-Code, z. B. beim Umbenennen von Konstrukten oder beim Verschieben von Konstrukten zwischen Stacks, bleiben die bereitgestellten Ressourcen erhalten.
+ **Liste — Zeigt Informationen** zu Stacks und ihren Abhängigkeiten an.
+ **Beobachten** — Überwachen Sie CDK-Apps auf lokale Änderungen.
+ **Rollback** — Setzt Stacks in ihren letzten stabilen Zustand zurück.
+ **Zerstören** — Entfernt CDK-Stacks und zugehörige Ressourcen.
**Verbessern und passen Sie Ihr Infrastrukturmanagement an**
+ **Kontrolle durch Code** — Integrieren Sie das Infrastrukturmanagement direkt in Ihre Anwendungen und erstellen Sie reaktionsschnelle Bereitstellungspipelines.
+ **Cloud-Assemblys verwalten** — Erstellen, überprüfen und transformieren Sie Ihre Infrastrukturdefinitionen vor der Bereitstellung.
+ **Passen Sie Bereitstellungen an** — Konfigurieren Sie Parameter, Rollback-Verhalten und Überwachung entsprechend Ihren Anforderungen.
+ **Ressourcen beim Refactoring schonen** — Automatische Erkennung und Erhaltung von Ressourcen, wenn Sie CDK-Code umgestalten.
+ **Präzise Fehlerbehandlung** — Implementieren Sie eine strukturierte Fehlerbehandlung mit detaillierten Diagnoseinformationen.
+ **Maßgeschneiderte Kommunikation** — Konfigurieren Sie benutzerdefinierte Fortschrittsindikatoren und Protokollierung der `IoHost` Implementierungen.
+ **Connect mit AWS ** — Konfigurieren Sie Profile, Regionen und Authentifizierungsabläufe programmgesteuert.
## Wählen Sie, wann die CDK Toolkit-Bibliothek verwendet werden soll
Die CDK Toolkit Library ist besonders nützlich, wenn Sie:
+ Automatisieren Sie Infrastrukturbereitstellungen als Teil von Pipelines. CI/CD
+ Erstellen Sie maßgeschneiderte Bereitstellungstools, die auf die Bedürfnisse Ihres Unternehmens zugeschnitten sind.
+ Integrieren Sie CDK-Aktionen in bestehende Anwendungen oder Plattformen.
+ Erstellen Sie spezielle Bereitstellungsworkflows mit benutzerdefinierten Validierungs- oder Genehmigungsschritten.
+ Implementieren Sie erweiterte Infrastrukturmanagementmuster in mehreren Umgebungen.
+ Automatisieren Sie Refactoring-Operationen, um Ressourcen zu schonen, wenn Sie CDK-Code umgestalten.
## Verwenden der CDK Toolkit-Bibliothek
Das folgende Beispiel zeigt, wie Sie mithilfe der CDK Toolkit Library einen einfachen S3-Bucket erstellen und bereitstellen:
```
// Import required packages
import { Toolkit } from '@aws-cdk/toolkit-lib';
import { App, Stack } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
// Create and configure the CDK Toolkit
const toolkit = new Toolkit();
// Create a cloud assembly source with an inline app
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new App();
const stack = new Stack(app, 'SimpleStorageStack');
// Create an S3 bucket in the stack
new s3.Bucket(stack, 'MyFirstBucket', {
versioned: true
});
return app.synth();
});
// Deploy the stack
await toolkit.deploy(cloudAssemblySource);
```
**Was können Sie als Nächstes tun**
+ **Automatisieren Sie Bereitstellungen** — lösen Sie Bereitstellungen programmgesteuert aus und fügen Sie Bereitstellungsschritte hinzu. pre/post
+ In **Systeme integrieren** — Connect zu CI/CD Workflows, benutzerdefinierten Tools und Überwachungslösungen her.
+ **Steuern Sie die Bereitstellungsdetails** — Konfigurieren Sie detaillierte Optionen für die Stack-Auswahl und Bereitstellungen in mehreren Umgebungen.
+ **Erhöhen Sie die Zuverlässigkeit** — Implementieren Sie eine produktionsbereite Fehlerbehandlung und Nachverfolgung des Bereitstellungsfortschritts.
+ **Automatisieren Sie das Refactoring** — Erkennen und schonen Sie Ressourcen, wenn Sie CDK-Code umgestalten.
## Nächste Schritte
Informationen zum Einstieg in die CDK Toolkit-Bibliothek finden Sie unter [Erste Schritte](toolkit-library-gs.md) mit der CDK Toolkit-Bibliothek.
## Weitere Informationen
Weitere Informationen zur CDK Toolkit Library finden Sie im Folgenden:
+ [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)im Paket *@aws -cdk/toolkit-lib*`npm`.
+ [AWS API-Referenz für die CDK Toolkit-Bibliothek.](https://docs.aws.amazon.com/cdk/api/toolkit-lib/)
# Erste Schritte mit der CDK Toolkit Library
Beginnen Sie mit der Verwendung der AWS CDK Toolkit-Bibliothek, um CDK-Aktionen wie Synthese und Bereitstellung programmgesteuert in Ihrem Code auszuführen.
## Voraussetzungen
1. Unterstützte Version von Node.js ist installiert.
1. AWS Anmeldeinformationen konfiguriert.
1. Grundlegende Vertrautheit mit dem AWS CDK.
Weitere Informationen finden Sie unter [AWS CDK-Voraussetzungen](prerequisites.md).
## Schritt 1: Installation der CDK Toolkit-Bibliothek
Installieren Sie das CDK Toolkit Library-Paket in der Entwicklungsumgebung Ihres Projekts, indem Sie den folgenden Befehl ausführen:
```
npm install --save @aws-cdk/toolkit-lib
```
## Schritt 2: Initialisierung der CDK Toolkit Library
Erstellen Sie eine CDK Toolkit-Instanz, um programmatische Aktionen in Ihrer CDK-App auszuführen.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit({
// Optional configuration options go here
});
```
Sie können die CDK Toolkit-Instanz während der Erstellung anpassen. Anweisungen finden Sie unter [Konfiguration Ihrer CDK](toolkit-library-configure.md) Toolkit-Instanz.
## Schritt 3: Erstellen Sie eine Cloud-Assembly-Quelle für Ihre CDK-App
Eine Cloud-Assembly-Quelle enthält Anweisungen zum Generieren von CloudFormation Vorlagen aus Ihrer CDK-App. Sie können eine auf verschiedene Arten erstellen. Im Folgenden sind einige Beispiele aufgeführt:
1. **Eine Inline-Assembly Builder-Funktion**:
```
import * as cdk from 'aws-cdk-lib';
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new cdk.App();
new MyStack(app, 'MyStack');
return app.synth();
});
```
1. **Eine vorhandene CDK-App-Datei**:
```
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
```
Weitere Informationen finden Sie unter [Cloud-Assembly-Quellen konfigurieren](toolkit-library-configure-ca.md).
## Schritt 4: Definieren Sie programmatische Aktionen für Ihre CDK-App
Nachdem Sie nun eine CDK Toolkit-Instanz und eine Cloud-Assembly-Quelle erstellt haben, können Sie mit der Definition programmatischer Aktionen beginnen. Im Folgenden finden Sie ein grundlegendes Beispiel, das eine Bereitstellung des Stacks erstellt: `MyStack`
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH, // Deploy only stacks that exactly match the provided patterns
patterns: ["MyStack"],
},
});
```
## Schritt 5: Das CDK Toolkit weiter anpassen
Sie können das CDK Toolkit weiter an Ihre Bedürfnisse anpassen und konfigurieren:
+ **Nachrichten und Interaktionen** — Konfigurieren Sie, wie das CDK Toolkit mit Benutzern und Anwendungen kommuniziert. Siehe [Nachrichten und Interaktionen konfigurieren](toolkit-library-configure-messages.md).
+ **Fehlerbehandlung** — Implementieren Sie eine strukturierte Fehlerbehandlung für CDK-Operationen. Siehe [Fehlerbehandlung konfigurieren](toolkit-library-configure.md#toolkit-library-configure-errors).
## Weitere Ressourcen
Weitere Informationen zum CDK Toolkit Library-Paket finden Sie [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)im `npm` Paket *@aws `npm` -cdk/toolkit-lib*.
[API-Referenzinformationen finden Sie in der API-Referenz zur CDK Toolkit Library.](https://docs.aws.amazon.com/cdk/api/toolkit-lib/)
# Programmgesteuerte Aktionen des CDK Toolkit konfigurieren
Die AWS CDK Toolkit Library bietet programmatische Schnittstellen für Aktionen im Lebenszyklus von Anwendungen wie Synthese, Bereitstellung und Stack-Management. In diesem Handbuch wird erklärt, wie Sie die einzelnen Aktionen in Ihrem Code verwenden.
## Generieren von Cloud-Assemblys mit Synth
Die `synth` Aktion generiert eine Cloud-Assembly aus Ihrer Cloud-Assembly-Quelle. Weitere Informationen zur Synthese finden [Sie unter CDK-Stack-Synthese konfigurieren und durchführen](configure-synth.md). Eine Cloud-Assembly enthält die folgenden Bereitstellungsartefakte aus Ihrer CDK-App:
+ AWS CloudFormation Vorlagen, die Ihre Infrastruktur definieren.
+ Assets wie Lambda-Funktionscode oder Docker-Images.
+ Metadaten und Konfiguration der Bereitstellung.
So verwenden Sie die `synth` Aktion, um eine Cloud-Assembly zu erstellen:
```
// Create a toolkit instance
const toolkit = new Toolkit();
// Create a cloud assembly source from a TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
// Use the cloud assembly for operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
await toolkit.diff(cloudAssembly);
// Query information from the cloud assembly
const template = cloudAssembly.getStack("my-stack").template;
```
**Tipp**
Die Verwendung einer Cloud-Assembly kann die Leistung optimieren, wenn Sie mehrere Operationen ausführen müssen, da die Synthese nur einmal erfolgt. Weitere Informationen zur Verwaltung von Cloud-Assemblys, einschließlich Zwischenspeicherung und Löschung, finden Sie unter [Cloud-Assemblys erstellen und verwalten](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache).
## Stack-Informationen mit Liste anzeigen
Die `list` Aktion ruft Informationen über die Stacks in Ihrer CDK-Anwendung ab, einschließlich ihrer Abhängigkeiten und des aktuellen Status. Verwenden Sie diese Aktion, um Ihre Infrastruktur vor der Bereitstellung zu überprüfen oder Berichte zu erstellen.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Get information about specific stacks
const stackDetails = await toolkit.list(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["my-stack"], // Only include stacks matching this pattern
}
});
// Process the returned stack information
for (const stack of stackDetails) {
console.log(`Stack: ${stack.id}, Dependencies: ${stack.dependencies}`);
}
```
## Bereitstellung der Infrastruktur mit Deploy
Die `deploy` Aktion stellt Ihre Infrastruktur AWS mithilfe der während der Synthese erstellten Cloud-Assembly bereit oder aktualisiert sie. Eine Einführung in die Bereitstellung finden Sie unter [Bereitstellen von AWS CDK-Anwendungen](deploy.md). Sie können Bereitstellungsoptionen wie Stack-Auswahl, Parameterwerte und Rollback-Verhalten steuern.
```
// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
parameters: StackParameters.exactly({
"MyStack": {
"BucketName": "amzn-s3-demo-bucket"
}
})
});
```
Die Bereitstellungsaktion unterstützt verschiedene Bereitstellungsmethoden, um verschiedenen Workflows gerecht zu werden. Für die meisten Szenarien, insbesondere in Produktionsumgebungen, empfehlen wir, die Standardbereitstellungsmethode zu verwenden, bei der CloudFormation Änderungssätze verwendet werden. Für Entwicklungsumgebungen, in denen die Iterationsgeschwindigkeit wichtig ist, können Sie alternative Methoden wie Hotswap verwenden.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Deploy using default deployment method (recommended for production)
await toolkit.deploy(cloudAssemblySource, {
parameters: StackParameters.exactly({
"MyStack": {
"BucketName": "amzn-s3-demo-bucket"
}
})
});
// For development environments only: Deploy with hotswap for faster iterations
// Note: We recommend using default deployment methods for production environments
await toolkit.deploy(cloudAssemblySource, {
deploymentMethod: { method: "hotswap", fallback: true }, // Faster but introduces drift
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["dev-stack"]
}
});
```
## Schonung der bereitgestellten Ressourcen mit Refactor
**Wichtig**
Die Refactoring-Aktion befindet sich in der Vorschauversion und kann sich ändern.
Durch die `refactor` Aktion bleiben die bereitgestellten Ressourcen erhalten, wenn Sie CDK-Code umgestalten, z. B. beim Umbenennen von Konstrukten oder beim Verschieben von Konstrukten zwischen Stapeln. Ohne diese Funktion würden diese Änderungen dazu führen, dass Ressourcen ersetzt werden, was möglicherweise CloudFormation zu Betriebsunterbrechungen oder Datenverlust führen könnte.
Die Refactoring-Aktion berechnet automatisch Zuordnungen, indem sie Ihren aktuellen Code mit dem bereitgestellten Status vergleicht. Sie ü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. Wenn sie feststellt, dass Ressourcen hinzugefügt, gelöscht oder geändert wurden, wird der Refactoring-Vorgang mit einer Fehlermeldung abgelehnt.
Sobald die Zuordnungen berechnet wurden, verwendet die Refactoring-Aktion die Refactoring-API, um die Logik CloudFormation der Ressourcen zu aktualisieren, ohne sie zu ersetzen. IDs Wenn sie auf mehrdeutige Zuordnungen stößt (bei denen es mehrere mögliche Zuordnungen gibt), können Sie explizite Überschreibungen angeben, um diese Mehrdeutigkeiten zu beheben.
```
// Perform refactoring operation to preserve resources
await toolkit.refactor(cloudAssemblySource);
// With optional overrides to resolve ambiguities
await toolkit.refactor(cloudAssemblySource, {
overrides: {
"environments": [
{
"account": "123456789012",
"region": "us-east-2",
"resources": {
"StackA.OldName": "StackA.NewName"
}
}
]
}
});
```
**Wichtig**
Refactoring-Operationen müssen 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 solche Änderungen vornehmen müssen, sollten Sie diese Änderungen zunächst separat bereitstellen und dann Ihre Ressourcen mithilfe von Refactoring neu organisieren.
**Tipp**
Weitere Informationen zum CDK-Refactoring, einschließlich dessen Funktionsweise und Verwendungszweck, finden Sie unter [Beibehaltung der bereitgestellten](refactor.md) Ressourcen beim Refactoring von CDK-Code.
## Fehlgeschlagene Bereitstellungen mit Rollback rückgängig machen
Die `rollback` Aktion versetzt einen Stack in seinen letzten stabilen Zustand zurück, wenn eine Bereitstellung fehlschlägt und nicht automatisch rückgängig gemacht werden kann. Verwenden Sie diese Aktion, um nach fehlgeschlagenen Bereitstellungen, die ein manuelles Eingreifen erfordern, eine Wiederherstellung durchzuführen.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Roll back stacks to their last stable state
await toolkit.rollback(cloudAssemblySource, {
orphanFailedResources: false, // When true, removes failed resources from CloudFormation management
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["failed-stack"]
}
});
```
## Änderungen mit Watch überwachen
Die `watch` Aktion überwacht Ihre CDK-App kontinuierlich auf lokale Dateiänderungen und führt automatisch Bereitstellungen oder Hotswaps durch. Dadurch wird ein Datei-Watcher erstellt, der läuft, bis Ihr Code beendet oder beendet wird.
**Warnung**
Bei Hotswap-Bereitstellungen werden Ressourcen, sofern möglich, direkt aktualisiert, sodass Aktualisierungen CloudFormation während der Entwicklung schneller durchgeführt werden. Dies ist standardmäßig für den Befehl aktiviert. `watch` Dies beschleunigt zwar den Entwicklungszyklus, führt aber zu Abweichungen zwischen Ihren CloudFormation Vorlagen und den bereitgestellten Ressourcen. Daher empfehlen wir, Hotswaps nicht in Produktionsumgebungen zu verwenden.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Start watching for changes
const watcher = await toolkit.watch(cloudAssemblySource, {
include: ["lib/**/*.ts"], // Only watch TypeScript files in the lib directory
exclude: ["**/*.test.ts"], // Ignore test files
deploymentMethod: { method: "hotswap" }, // This is the default, shown here for clarity
stacks: {
strategy: StackSelectionStrategy.ALL // Watch all stacks
}
});
// Later in your code, you can explicitly stop watching:
// await watcher.dispose();
```
Die Überwachungsfunktion gibt ein `IWatcher` Objekt zurück, mit dem Sie explizit steuern können, wann die Wiedergabe beendet werden soll. Rufen Sie die `dispose()` Methode für dieses Objekt auf, wenn Sie den Überwachungsvorgang beenden möchten.
## Infrastruktur wird mit Destroy entfernt
Die `destroy` Aktion entfernt CDK-Stacks und die zugehörigen Ressourcen von. AWS Verwenden Sie diese Aktion, um Ressourcen zu bereinigen, wenn sie nicht mehr benötigt werden.
**Wichtig**
Die Aktion Löschen entfernt Ressourcen dauerhaft, ohne dass eine Bestätigung angefordert wird, im Gegensatz zur CLI-Version dieses Befehls. Stellen Sie sicher, dass Sie Backups aller wichtigen Daten haben, bevor Sie Stapel zerstören.
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Remove specific stacks and their resources
await toolkit.destroy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["dev-stack"], // Only destroy stacks matching this pattern
}
});
```
# Konfiguration Ihrer CDK Toolkit-Instanz
Erfahren Sie, wie Sie Ihre AWS CDK Toolkit-Bibliotheksinstanz mit Optionen für Nachrichtenverarbeitung, AWS Profilauswahl und Strategien zur Stapelauswahl anpassen können. In diesem Handbuch werden die verfügbaren Konfigurationsoptionen erläutert und erklärt, wie Sie diese effektiv implementieren können, um Ihre spezifischen Bereitstellungsanforderungen zu erfüllen.
## Konfiguration Ihres AWS Profils
Wenn Sie die CDK Toolkit-Bibliothek verwenden, werden API-Aufrufe zur AWS Verwendung des SDK ausgeführt. Die Authentifizierung wird zwar automatisch aus Ihrer Umgebung geladen, Sie können jedoch explizit angeben, welches Profil verwendet werden soll:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## Konfiguration der Stack-Auswahl
Bei den meisten CDK Toolkit-Aktionen müssen Sie angeben, mit welchen Stacks gearbeitet werden soll. Die ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) ` Konfiguration steuert diese Auswahl.
### Wählt alle Stapel aus
Verwenden Sie dies, wenn Sie mit jedem Stack in Ihrer CDK-App arbeiten möchten:
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### Wählen Sie nur Hauptbaugruppenstapel aus
Verwenden Sie diese Option, um nur die Stapel der obersten Ebene aus der Hauptbaugruppe auszuwählen:
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### Wählen Sie einen einzelnen Stapel
Verwenden Sie dies, wenn Ihre Assembly genau einen Stapel enthält und Sie diese Bedingung bestätigen möchten. Wenn die Assembly einen einzelnen Stapel enthält, gibt sie diesen Stapel zurück. Andernfalls wird eine Ausnahme ausgelöst:
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### Wählen Sie Stapel nach Muster aus
Verwenden Sie diese Option, um bestimmte Stapel anhand des Namensmusters auszuwählen:
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**Tipp**
Verwenden Sie diese Option`PATTERN_MUST_MATCH_SINGLE`, um sicherzustellen, dass genau ein Stapel Ihren Mustern entspricht, oder `PATTERN_MATCH` wenn es akzeptabel ist, dass keine Stapel übereinstimmen. Der Musterabgleich unterstützt Platzhalter wie „\$1“, um mehrere Stapel mit ähnlichen Namen abzugleichen.
## Konfiguration der Fehlerbehandlung
Das CDK Toolkit verwendet strukturierte Fehler, um Sie bei der Identifizierung und Behandlung von Problemen zu unterstützen. Jeder Fehler beinhaltet:
+ Eine **Quelle**, die angibt, woher der Fehler stammt (Toolkit oder Benutzer).
+ Ein bestimmter **Fehlertyp** (Authentifizierung, Validierung usw.).
+ Eine beschreibende **Nachricht**.
### Fehlerbehandlung
Verwenden Sie die vom CDK Toolkit bereitgestellten Hilfsmethoden, um bestimmte Fehlertypen zu erkennen und zu behandeln:
```
import { ToolkitError } from '@aws-cdk/toolkit-lib';
try {
// Attempt a CDK Toolkit operation
await toolkit.deploy(cloudAssemblySource, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS }
});
} catch (error) {
// Handle specific error types
if (ToolkitError.isAuthenticationError(error)) {
// Example: AWS credentials are missing or invalid
console.error('Authentication failed. Check your AWS credentials.');
} else if (ToolkitError.isAssemblyError(error)) {
// Example: Your CDK app has errors in stack definitions
console.error('CDK app error:', error.message);
} else if (ToolkitError.isDeploymentError(error)) {
// Example: CloudFormation deployment failed
console.error('Deployment failed:', error.message);
} else if (ToolkitError.isToolkitError(error)) {
// Handle all other Toolkit errors
console.error('CDK Toolkit error:', error.message);
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
```
**Wichtig**
Verlassen Sie sich nicht darauf, `instanceof` nach Fehlertypen zu suchen, da diese sich unerwartet verhalten können, wenn Sie mit mehreren Kopien desselben Pakets arbeiten. Verwenden Sie immer die bereitgestellten Hilfsmethoden wie`ToolkitError.isAuthenticationError()`.
## Toolkit-Aktionen konfigurieren
Jede CDK Toolkit-Aktion (Deploy, Synth, List usw.) hat ihre eigenen spezifischen Konfigurationsoptionen. Mit diesen Aktionen können Sie den gesamten Lebenszyklus Ihrer CDK-Infrastruktur verwalten. Ausführliche Informationen zur Konfiguration einzelner Aktionen finden [Sie unter Programmatische Aktionen des CDK Toolkit konfigurieren](toolkit-library-actions.md).
**Tipp**
Erwägen Sie beim Erstellen von Automatisierungs-Workflows, mehrere Aktionen nacheinander zu kombinieren. Beispielsweise möchten Sie möglicherweise anhand `synth` Ihrer App anhand `list` der Stacks überprüfen, was bereitgestellt wird, und anschließend `deploy` die Infrastruktur.
# Cloud-Assembly-Quellen der AWS CDK Toolkit Library verwalten
Verwenden Sie die AWS CDK Toolkit-Bibliothek, um Cloud-Assembly-Quellen zu konfigurieren und die Bereitstellung Ihrer CDK-Anwendungen anzupassen. In diesem Handbuch erfahren Sie, wie Sie Cloud-Assembly-Quellen so konfigurieren, dass sie Ihren Bereitstellungsanforderungen und Workflow-Anforderungen entsprechen.
Bevor Sie das CDK Toolkit verwenden, geben Sie eine Cloud-Assembly-Quelle an. Eine *Cloud-Assembly-Quelle* enthält Anweisungen zum Generieren einer Cloud-Assembly aus Ihrer CDK-App. Die resultierende Cloud-Assembly enthält die synthetisierten Infrastrukturartefakte, auf denen das CDK Toolkit bereitgestellt wird. AWS
Die CDK Toolkit Library bietet verschiedene Ansätze zur Konfiguration von Cloud-Assembly-Quellen, die jeweils für unterschiedliche Szenarien und Workflows geeignet sind.
## Auswahl einer Cloud-Assembly-Quelle
| Methode | Am besten für | Überlegungen |
| --- | --- | --- |
| `fromCdkApp` | Arbeiten mit vorhandenen CDK-Anwendungen in jeder unterstützten Sprache. | Erfordert die Installation der entsprechenden Sprach-Runtime. |
| `fromAssemblyBuilder` | Inline-Erstellung von CDK-Konstrukten mit voller Kontrolle über den Synthesevorgang. | Bietet einfachen Zugriff auf CDK-Funktionen und kann verwendet werden, um benutzerdefinierte Versionen anderer Methoden zu erstellen, wie z. `fromCdkApp` |
| `fromAssemblyDirectory` | Verwendung von vorsynthetisierten Cloud-Assemblys. | Schnellere Ausführung, da der Syntheseschritt übersprungen wird. |
| Benutzerdefinierte Quelle | Extrem spezielle Szenarien, die eine vollständige kundenspezifische Implementierung erfordern. | Erfordert die Implementierung der `ICloudAssemblySource` Schnittstelle von Grund auf; es fehlen integrierte Funktionen wie Kontext-Lookups; wird für die meisten Anwendungsfälle selten benötigt. |
## Konfiguration Ihrer Cloud-Assembly-Quelle
### Aus einer vorhandenen CDK-App
Verwenden Sie `fromCdkApp` diese Methode, um mit CDK-Apps zu arbeiten, die in einer beliebigen unterstützten Sprache geschrieben wurden. Dieser Ansatz ist ideal, wenn Sie bereits über eine CDK-Anwendung verfügen und diese programmgesteuert bereitstellen möchten.
```
import { App } from 'aws-cdk-lib';
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance
const toolkit = new Toolkit();
// TypeScript app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Deploy a specific stack from the assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: ['MyStack']
});
// Other language examples:
// JavaScript app
// const cloudAssemblySource = await toolkit.fromCdkApp("node app.js");
// Python app
// const cloudAssemblySource = await toolkit.fromCdkApp("python app.py");
// Java app
// const cloudAssemblySource = await toolkit.fromCdkApp("mvn -e -q exec:java -Dexec.mainClass=com.mycompany.app.App");
```
### Von einem Inline-Assembly Builder
Erstellen Sie mithilfe einer Assembly Builder-Funktion eine CDK-App direkt in Ihrem Code. Dieser Ansatz ist nützlich für einfache Bereitstellungen oder Testszenarien, in denen Sie Ihre Infrastruktur inline definieren möchten.
```
import { App, Stack, RemovalPolicy, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Toolkit } from '@aws-cdk/toolkit-lib';
import { Construct } from 'constructs';
// Create a cloud assembly source from an inline CDK app
const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
const app = new App();
// Define a simple stack with an S3 bucket
class MyStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Create an S3 bucket
new Bucket(this, 'MyBucket', {
versioned: true,
removalPolicy: RemovalPolicy.DESTROY,
autoDeleteObjects: true
});
}
}
// Instantiate the stack
new MyStack(app, 'MyInlineStack');
return app.synth();
});
// Deploy using the cloud assembly source
await toolkit.deploy(cloudAssemblySource, {
stacks: ['MyInlineStack']
});
```
### Aus einem vorhandenen Assemblyverzeichnis
Wenn Sie bereits über eine synthetisierte Cloud-Assembly verfügen, können Sie diese direkt verwenden. Dies ist nützlich, wenn Sie bereits Cloud-Assemblys ausgeführt haben `cdk synth` oder wenn Sie mit Cloud-Assemblys arbeiten, die von CI/CD-Pipelines generiert wurden.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance
const toolkit = new Toolkit();
// Use an existing cloud assembly directory
const cloudAssemblySource = await toolkit.fromAssemblyDirectory("cdk.out");
// Deploy using the cloud assembly source
await toolkit.deploy(cloudAssemblySource, {
stacks: ['MyStack']
});
```
## Arbeiten mit zwischengespeicherten Cloud-Assemblys
Bei der Arbeit mit Cloud-Assemblys haben Sie zwei Möglichkeiten:
1. Verwenden Sie direkt eine Cloud-Assembly-Quelle (einfach, kann aber langsamer sein):
```
// Each operation triggers a new synthesis
await toolkit.deploy(cloudAssemblySource, { /* options */ });
await toolkit.list(cloudAssemblySource, { /* options */ });
```
1. Die Cloud-Assembly zwischenspeichern (schneller für mehrere Operationen):
```
// Synthesize once and reuse
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Multiple operations use the same assembly
await toolkit.deploy(cloudAssembly, { /* options */ });
await toolkit.list(cloudAssembly, { /* options */ });
} finally {
// Clean up when done
await cloudAssembly.dispose();
}
```
Verwenden Sie zwischengespeicherte Assemblys, wenn:
+ Sie führen mehrere Operationen aus (Deploy, List, Diff usw.).
+ Ihre CDK-App ändert sich während des Betriebs nicht häufig.
+ Sie möchten eine schnellere Leistung.
Verwenden Sie Cloud-Assembly-Quellen direkt, wenn:
+ Sie führen eine einzelne Operation durch.
+ Ihre CDK-App ändert sich häufig.
+ Sie möchten einfacheren Code und müssen der Geschwindigkeit des Toolkit-Betriebs keine Priorität einräumen.
**Wichtig**
Die meisten Toolkit-Interaktionen sollten für eine bessere Leistung eine zwischengespeicherte Assembly verwenden. Caching lässt sich nur vermeiden, wenn sich Ihre Quelle häufig ändert und die Überprüfung auf Änderungen teuer wäre.
### Wie können Cloud-Assemblys erstellt, zwischengespeichert und wiederverwendet werden
Nachdem Sie eine Cloud-Assembly-Quelle erstellt haben, können Sie eine Cloud-Assembly generieren, indem Sie sie synthetisieren. Eine Cloud-Assembly enthält die AWS CloudFormation Vorlagen und Ressourcen, die für die Bereitstellung benötigt werden.
Wir empfehlen, eine Cloud-Assembly einmal zu generieren und sie für mehrere Toolkit-Operationen wiederzuverwenden. Dieser Caching-Ansatz ist effizienter als die Neugenerierung der Assembly für jeden Vorgang. Erwägen Sie, die Baugruppe nur dann zu regenerieren, wenn sich Ihre Quelle häufig ändert.
So erstellen Sie eine zwischengespeicherte Cloud-Assembly:
```
// Generate a cloud assembly from your source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
```
Anschließend können Sie verschiedene Toolkit-Aktionen für die zwischengespeicherte Cloud-Assembly ausführen, z. B.`list()`, und`deploy()`. `diff()` Durch das Zwischenspeichern von Cloud-Assemblys werden nachfolgende Toolkit-Aktionen schneller ausgeführt, da die Synthese nur einmal erfolgt. Weitere Informationen finden Sie unter [Synth — Generieren](toolkit-library-actions.md#toolkit-library-actions-synth) von Cloud-Assemblys.
### Cloud-Assembly-Ressourcen entsorgen
Entsorgen Sie Cloud-Assemblys immer, wenn Sie sie nicht mehr zum Bereinigen temporärer Ressourcen verwenden. Wir empfehlen die Verwendung eines Try/Finaly-Blocks, um eine ordnungsgemäße Bereinigung sicherzustellen, insbesondere bei der Ausführung mehrerer Operationen:
```
// Generate a cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Use the cloud assembly for multiple operations
await toolkit.list(cloudAssembly);
await toolkit.deploy(cloudAssembly);
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
```
Hier ist ein Beispiel, das zeigt, wie eine zwischengespeicherte Cloud-Assembly erstellt und gelöscht wird:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit();
// Create cloud assembly source from a CDK app
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Create cloud assembly from source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// List stacks in the assembly
await toolkit.list(cloudAssembly);
// Check for changes
await toolkit.diff(cloudAssembly);
// Deploy if needed
await toolkit.deploy(cloudAssembly);
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
```
### Die Lebensdauer von Cloud-Assemblys verstehen
Wenn Sie eine zwischengespeicherte Cloud-Assembly mit erstellen`synth()`, erhalten Sie einen speziellen Typ, der sowohl als lesbare als auch als lesbare `CloudAssembly` Assembly dient. `CloudAssemblySource` Alle Cloud-Assemblys, die aus dieser zwischengespeicherten Assembly erstellt werden (z. B. aus Listen- oder Bereitstellungsvorgängen), sind an die Lebensdauer der übergeordneten Assembly gebunden:
+ Nur der dispose () -Aufruf des übergeordneten Elements bereinigt tatsächlich Ressourcen
+ Cloud-Assemblys aus List-/Bereitstellungsvorgängen werden von ihrem übergeordneten Element verwaltet
+ Das Versäumnis, eine zwischengespeicherte Cloud-Assembly zu löschen, wird als Fehler angesehen
## Bewährte Methoden für Cloud-Assembly-Quellen
Beachten Sie bei der Arbeit mit Cloud-Assembly-Quellen die folgenden bewährten Methoden:
+ **Wählen Sie die richtige Quellmethode**: Wählen Sie den Ansatz, der am besten zu Ihrem Arbeitsablauf und Ihren Anforderungen passt.
+ **Cloud-Assemblys zwischenspeichern**: Generieren Sie eine Cloud-Assembly, sobald Sie sie verwenden, `synth()` und verwenden Sie sie für mehrere Operationen wieder, um unnötige Synthesen zu vermeiden, insbesondere bei großen Anwendungen.
+ **Fehlerbehandlung**: Implementieren Sie eine grundlegende Fehlerbehandlung, um Fehler zu erkennen und Benutzern anzuzeigen. Halten Sie die Fehlerbehandlung einfach und konzentrieren Sie sich darauf, klare Fehlermeldungen bereitzustellen.
+ **Versionskompatibilität**: Stellen Sie sicher, dass Ihre Version der CDK Toolkit Library die Cloud-Assemblys unterstützt, mit denen Sie arbeiten. Wenn die Construct-Bibliothek, mit der die Cloud-Assembly erstellt wurde, neuer ist als die, die Ihre Toolkit-Bibliothek unterstützt, erhalten Sie eine Fehlermeldung.
+ **Umgebungsvariablen**: Beachten Sie, dass bestimmte Umgebungsvariablen die Synthese und Bereitstellung von Cloud-Assemblys beeinflussen können. Variablen wie`CDK_DEFAULT_ACCOUNT`, `CDK_DEFAULT_REGION``CDK_OUTDIR`, und `CDK_CONTEXT_JSON` können Standardverhalten überschreiben. Stellen Sie sicher, dass diese Einstellungen für Ihre Bereitstellungsumgebung geeignet sind.
Das folgende Beispiel zeigt, wie Sie die Fehlerbehandlung und die ordnungsgemäße Bereinigung implementieren und gleichzeitig eine Cloud-Assembly für mehrere Operationen wiederverwenden:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with error handling and proper cleanup
async function deployInfrastructure(): Promise {
let cloudAssembly;
try {
// Generate a cloud assembly once
cloudAssembly = await toolkit.synth(cloudAssemblySource);
// Reuse the same cloud assembly for multiple operations
await toolkit.list(cloudAssembly); // Uses existing assembly
await toolkit.deploy(cloudAssembly); // Uses existing assembly
await toolkit.diff(cloudAssembly); // Uses existing assembly
} catch (error) {
console.error("Failed to deploy:", error);
} finally {
// Always dispose when done
if (cloudAssembly) {
await cloudAssembly.dispose();
}
}
}
// Call the async function
deployInfrastructure().catch(error => {
console.error("Deployment failed:", error);
process.exit(1);
});
```
## Lösung potenzieller Probleme
Gehen Sie wie folgt vor, um potenzielle Probleme mit Cloud-Assembly-Quellen zu beheben:
+ **Fehlende Abhängigkeiten installieren**: Führen Sie `npm install` den Befehl aus, um die erforderlichen Abhängigkeiten für Ihre CDK-App zu installieren.
+ **Pfadprobleme beheben**: Überprüfe, ob Pfade zu CDK-Apps und Assemblyverzeichnissen existieren und zugänglich sind.
+ **Versionskonflikte beheben**: Aktualisieren Sie Ihre CDK Toolkit-Bibliotheksversion so, dass sie mit der Version Ihrer CDK-App übereinstimmt.
+ **Synthesefehler beheben**: Überprüfe deinen CDK-App-Code auf Syntaxfehler oder ungültige Konfigurationen.
Wenn während des Toolkit-Betriebs Fehler auftreten, halten Sie die Fehlerbehandlung einfach und konzentrieren Sie sich darauf, den Benutzern klare Fehlermeldungen zu geben. Entsorgen Sie Cloud-Assemblys immer, wenn Sie sie nicht mehr verwenden. Hier ist ein Beispiel, das die grundlegende Fehlerbehandlung bei ordnungsgemäßer Bereinigung zeigt:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with simple error handling
try {
// Create the cloud assembly source
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
// Use the cloud assembly
await toolkit.list(cloudAssembly);
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
} finally {
// Clean up resources
await cloudAssembly.dispose();
}
```
# CDK Toolkit-Nachrichten und Interaktionen konfigurieren
Die AWS CDK Toolkit Library bietet eine ` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) ` Benutzeroberfläche, mit der Sie die Art und Weise anpassen können, wie Nachrichten und Interaktionen während des CDK-Betriebs behandelt werden. So können Sie die Anzeige des Bereitstellungsfortschritts, der Fehlermeldungen und der Benutzereingaben steuern, um sie besser in die Benutzererfahrung Ihrer Anwendung zu integrieren.
Bevor Sie Operationen wie Bereitstellung oder Synthese durchführen, müssen Sie verstehen, wie das CDK Toolkit mit Benutzern kommuniziert. Die `IIoHost` Schnittstelle dient als Kommunikationskanal zwischen dem CDK Toolkit und Ihrer Anwendung und verarbeitet sowohl ausgehende Nachrichten als auch eingehende Benutzerantworten.
Wenn das CDK Toolkit Operationen ausführt, kommuniziert es über zwei Hauptmechanismen:
+ **Meldungen**: Informationsausgaben, die Sie über den Fortschritt des Vorgangs informieren (z. B. „Bereitstellung wird gestartet“ oder „Ressource erstellt“).
+ **Anfragen**: Entscheidungspunkte, für die eine Eingabe oder Bestätigung erforderlich ist (z. B. „Möchten Sie diese Änderungen implementieren?“) , um Ihnen die Möglichkeit zu geben, Informationen bereitzustellen, von denen vorher nicht bekannt war, dass sie benötigt werden.
## Verwenden der `IIoHost` Schnittstelle
Die `IIoHost` Schnittstelle besteht aus zwei Hauptmethoden:
1. `notify`: Verarbeitet unidirektionale Informationsnachrichten.
1. `requestResponse`: Behandelt interaktive Anfragen, die eine Antwort erfordern.
```
import { IoMessage, IoRequest } from '@aws-cdk/toolkit-lib';
interface IIoHost {
// Handle informational messages
notify(message: IoMessage): Promise;
// Handle requests that need responses
requestResponse(request: IoRequest): Promise;
}
```
## Nachrichtenebenen und Anforderungstypen
Das CDK Toolkit generiert verschiedene Arten von Nachrichten und Anfragen:
### Nachrichtenebenen
+ **Debug**: Detaillierte Meldungen zur Fehlerbehebung.
+ **Fehler**: Fehlermeldungen, die den Betrieb beeinträchtigen können.
+ **Info**: Allgemeine Informationsmeldungen.
+ **Ergebnis** — Hauptnachricht eines Vorgangs.
+ **Trace**: Sehr detaillierte Informationen zum Ausführungsablauf.
+ **Warnung**: Warnmeldungen, die den Betrieb nicht verhindern.
Eine vollständige Liste finden Sie unter [IoMessages Registry](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) in der * AWS CDK Toolkit Library API-Referenz*.
### Anforderungstypen
Das CDK Toolkit sendet Anfragen, wenn es eine Eingabe oder Bestätigung vom Benutzer benötigt. Dies sind spezielle Nachrichten, die eine Antwort ermöglichen. Wenn keine Antwort erfolgt, verwendet das Toolkit eine Standardantwort, sofern verfügbar.
## Grundlegende `IIoHost`-Implementierung
Hier ist ein einfaches Beispiel für die Implementierung eines benutzerdefinierten IO-Hosts:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit with custom message handling
const toolkit = new Toolkit({
ioHost: {
// Implementing the IIoHost interface
// Handle informational messages
notify: async function (msg) {
// Example: Handle different message levels appropriately
switch (msg.level) {
case 'error':
console.error(`[${msg.time}] ERROR: ${msg.message}`);
break;
case 'warning':
console.warn(`[${msg.time}] WARNING: ${msg.message}`);
break;
case 'info':
console.info(`[${msg.time}] INFO: ${msg.message}`);
break;
case 'debug':
console.debug(`[${msg.time}] DEBUG: ${msg.message}`);
break;
case 'trace':
console.debug(`[${msg.time}] TRACE: ${msg.message}`);
break;
default:
console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
}
},
// Handle requests that need responses
requestResponse: async function (msg) {
// Example: Log the request and use default response
console.log(`Request: ${msg.message}, using default: ${msg.defaultResponse}`);
return msg.defaultResponse;
// Or implement custom logic to provide responses
// if (msg.type === 'deploy') {
// return promptUserForDeployment(msg);
// }
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
Das CDK Toolkit wartet auf den Abschluss jedes Aufrufs, sodass Sie bei der Bearbeitung von Nachrichten asynchrone Operationen wie HTTP-Anfragen oder Benutzeraufforderungen ausführen können.
## Standardverhalten `IIoHost`
Wenn Sie keinen benutzerdefinierten IO-Host bereitstellen, verwendet die CDK Toolkit Library eine standardmäßige, nicht interaktive Implementierung:
+ Konsolenausgabe für Nachrichten (mit geeigneten Farben für verschiedene Nachrichtentypen).
+ Vollständig nicht interaktiv ohne Aufforderung zur Benutzereingabe.
+ Verwendet nach Möglichkeit automatisch Standardantworten (entspricht der Antwort auf Eingabeaufforderungen mit „Ja“).
+ Schlägt fehl, wenn eine Eingabe erforderlich ist, aber keine Standardantwort verfügbar ist.
Dieses Standardverhalten eignet sich für unbeaufsichtigte Operationen, nicht jedoch für interaktive Befehlszeilenanwendungen. Für Befehlszeilenanwendungen, die eine Benutzerinteraktion erfordern, müssen Sie einen benutzerdefinierten IO-Host implementieren. Benutzerdefinierte Implementierungen eignen sich auch für die Integration in Protokollierungssysteme oder andere UIs spezialisierte Umgebungen.
## Fortgeschrittene IO-Host-Implementierung
Für komplexere Szenarien empfehlen wir, den `NonInteractiveIoHost` Kurs als Ausgangspunkt zu erweitern. Dieser Ansatz ermöglicht es Ihnen, die bestehende, nicht interaktive Implementierung zu nutzen und gleichzeitig nur die spezifischen Verhaltensweisen anzupassen, die Sie ändern müssen.
Hier ist ein Beispiel für einen benutzerdefinierten IO-Host, der die Basisimplementierung erweitert:
```
import { NonInteractiveIoHost } from '@aws-cdk/toolkit-lib';
class MyCustomIoHost extends NonInteractiveIoHost {
// Override only the methods you need to customize
// Example: Custom implementation for notify
public async notify(msg: IoMessage): Promise {
// Add custom notification handling logic
if (msg.level === 'error') {
console.error(`ERROR: ${msg.message}`);
// Optionally log to a service or notify a monitoring system
await this.logToMonitoringService(msg);
} else {
await super.notify(msg);
}
}
// Example: Custom implementation for requestResponse
public async requestResponse(request: IoRequest): Promise {
// Implement custom request handling
console.log(`Received request: ${request.message}`);
return request.defaultResponse;
}
private async logToMonitoringService(msg: IoMessage): Promise {
// Implementation for monitoring service integration
console.log(`Logging to monitoring service: ${msg.level} - ${msg.message}`);
}
}
```
Dieser Ansatz ist wartungsfreundlicher als die Implementierung der gesamten `IIoHost` Schnittstelle von Grund auf, da Sie nur die spezifischen Methoden überschreiben müssen, die ein benutzerdefiniertes Verhalten erfordern.
## Integration in verschiedene Umgebungen
### Integration von Webanwendungen
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example for integrating with a web application
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Send message to frontend via WebSocket
webSocketServer.send(JSON.stringify({
type: 'cdk-notification',
messageLevel: msg.level,
message: msg.message,
time: msg.time
}));
},
requestResponse: async function (msg) {
// Create a promise that will be resolved when the user responds
return new Promise((resolve) => {
const requestId = generateUniqueId();
// Store the resolver function
pendingRequests[requestId] = resolve;
// Send request to frontend
webSocketServer.send(JSON.stringify({
type: 'cdk-request',
requestId: requestId,
requestType: msg.type,
message: msg.message,
defaultResponse: msg.defaultResponse
}));
// Frontend would call an API endpoint with the response,
// which would then call pendingRequests[requestId](response)
});
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
### Integration der CI/CD-Umgebung
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example for CI/CD environments (non-interactive)
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Log all messages with appropriate level
switch (msg.level) {
case 'error':
console.error(msg.message);
break;
case 'warning':
console.warn(msg.message);
break;
default:
console.log(msg.message);
}
},
requestResponse: async function (msg) {
// In CI/CD, always use default responses or predefined answers
console.log(`Auto-responding to request: ${msg.message} with ${msg.defaultResponse}`);
return msg.defaultResponse;
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
## Bewährte Methoden für die Implementierung von IO-Hosts
Beachten Sie bei der Implementierung eines benutzerdefinierten IO-Hosts die folgenden bewährten Methoden:
+ **Fehlerbehandlung**: Implementieren Sie eine robuste Fehlerbehandlung in Ihren IO-Host-Methoden, um zu verhindern, dass Fehler den CDK-Betrieb beeinträchtigen.
+ **Timeouts**: Erwägen Sie die Implementierung von Timeouts für Benutzerinteraktionen, um unbestimmte Wartezeiten zu vermeiden.
+ **Protokollierung**: Speichern Sie wichtige Meldungen zur Fehlerbehebung in Protokollen, insbesondere in nicht interaktiven Umgebungen.
+ **Standardantworten**: Stellen Sie sinnvolle Standardantworten für automatisierte Umgebungen bereit, in denen Benutzerinteraktionen nicht möglich sind.
+ **Fortschrittsanzeige**: Stellen Sie bei lang andauernden Vorgängen klare Fortschrittsindikatoren bereit, um die Benutzererfahrung zu verbessern.
Im folgenden Beispiel werden diese bewährten Methoden anhand der Implementierung eines benutzerdefinierten IO-Hosts mit Fehlerbehandlung, Timeouts für Benutzerinteraktionen und ordnungsgemäßer Protokollierung veranschaulicht. Diese Implementierung eignet sich für interaktive Anwendungen, bei denen Sie die Reaktionsfähigkeit der Benutzer mit einem zuverlässigen Betrieb in Einklang bringen müssen:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example with error handling and timeouts
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
try {
console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
// Additional logging or UI updates
} catch (error) {
// Ensure errors in notification handling don't break the CDK operation
console.error("Error handling notification:", error);
}
},
requestResponse: async function (msg) {
try {
// Implement timeout for user response
const response = await Promise.race([
getUserResponse(msg),
new Promise(resolve => setTimeout(() => resolve(msg.defaultResponse), 60000))
]);
return response;
} catch (error) {
console.error("Error handling request:", error);
return msg.defaultResponse;
}
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
## Fehlerbehebung
Überlegungen bei der Implementierung eines benutzerdefinierten IO-Hosts:
+ **Unbehandelte Ablehnungen von Zusagen**: Stellen Sie sicher, dass alle asynchronen Operationen mit Try/Catch-Blöcken ordnungsgemäß behandelt werden.
+ **Unendliches Warten**: Implementieren Sie Timeouts für alle Benutzerinteraktionen, um zu verhindern, dass die Anwendung hängen bleibt.
+ **Fehlende Nachrichtenebenen**: Seien Sie bereit, mit neuen Nachrichtenebenen umzugehen, die in future CDK-Versionen hinzugefügt werden könnten.
+ **Inkonsistente Antworten**: Stellen Sie sicher, dass Ihre RequestResponse-Implementierung Werte im erwarteten Format zurückgibt.
Das folgende Beispiel zeigt einen robusten Ansatz für den Umgang mit Nachrichtenebenen, einschließlich der ordnungsgemäßen Behandlung unbekannter Nachrichtentypen, die in future CDK-Versionen eingeführt werden könnten. Diese Implementierung stellt sicher, dass Ihr IO-Host mit CDK-Updates kompatibel bleibt und gleichzeitig die korrekte Protokollierung gewährleistet:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Example of handling unknown message levels
const toolkit = new Toolkit({
ioHost: {
notify: async function (msg) {
// Handle known levels
const knownLevels = ['info', 'warning', 'error', 'debug', 'trace', 'status'];
if (knownLevels.includes(msg.level)) {
// Handle known level
handleKnownMessageLevel(msg);
} else {
// Handle unknown level as info
console.log(`Unknown message level "${msg.level}": ${msg.message}`);
}
},
requestResponse: async function (msg) {
// Default implementation
return msg.defaultResponse;
}
} as IIoHost // Explicitly cast to IIoHost interface
});
```
# Beispiele für die CDK Toolkit-Bibliothek für Fortgeschrittene
Erfahren Sie anhand praktischer Beispiele, wie Sie die erweiterten Funktionen der AWS CDK Toolkit Library nutzen können. Dieses Handbuch enthält detaillierte Codebeispiele für die Fehlerbehandlung, Bereitstellungsüberwachung und Cloud-Assembly-Management, die auf den in anderen Abschnitten behandelten Grundkonzepten aufbauen.
## Funktionen integrieren
Das folgende Beispiel zeigt, wie Cloud-Assembly-Quellen, benutzerdefinierte IO-Host-Implementierung und Bereitstellungsoptionen kombiniert werden:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
async function deployApplication(appPath, environment, options = {}) {
// Create toolkit with custom message handling
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
// Add environment to all messages
console.log(`[${environment}][${msg.time}] ${msg.level}: ${msg.message}`);
},
requestResponse: async (msg) => {
// In production environments, use default responses
if (environment === 'production') {
console.log(`Auto-approving for production: ${msg.message}`);
return msg.defaultResponse;
}
// For other environments, implement custom approval logic
return promptForApproval(msg);
}
} as IIoHost
});
try {
// Create cloud assembly source from the CDK app
console.log(`Creating cloud assembly source from ${appPath}`);
const cloudAssemblySource = await toolkit.fromCdkApp(appPath);
// Synthesize the cloud assembly
console.log(`Synthesizing cloud assembly`);
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy with environment-specific options
console.log(`Deploying to ${environment} environment`);
return await toolkit.deploy(cloudAssembly, {
stacks: options.stacks || { strategy: StackSelectionStrategy.ALL_STACKS },
parameters: options.parameters || {},
tags: {
Environment: environment,
DeployedBy: 'CDK-Toolkit-Library',
DeployTime: new Date().toISOString()
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
console.error(`Deployment to ${environment} failed:`, error);
throw error;
}
}
// Example usage
await deployApplication('ts-node app.ts', 'staging', {
parameters: {
MyStack: {
InstanceType: 't3.small'
}
}
});
```
## Nachverfolgung des Bereitstellungsfortschritts
Verfolgen Sie den Bereitstellungsfortschritt mit detaillierten Status-Updates:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
// Create a progress tracker
class DeploymentTracker {
private startTime: Date;
private resources = new Map();
constructor() {
this.startTime = new Date();
}
onStackEvent(stackName: string, event: string, timestamp: string) {
// Calculate elapsed time if needed, or use the provided timestamp
const elapsed = (new Date().getTime() - this.startTime.getTime()) / 1000;
console.log(`[${timestamp}] (${elapsed.toFixed(1)}s elapsed) Stack ${stackName}: ${event}`);
}
onResourceEvent(resourceId: string, status: string) {
this.resources.set(resourceId, status);
this.printProgress();
}
private printProgress() {
console.log('\nResource Status:');
for (const [id, status] of this.resources.entries()) {
console.log(`- ${id}: ${status}`);
}
console.log();
}
}
// Use the tracker with the toolkit
const tracker = new DeploymentTracker();
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
if (msg.code.startsWith('CDK_DEPLOY')) {
// Track deployment events
if (msg.data && 'stackName' in msg.data) {
tracker.onStackEvent(msg.data.stackName, msg.message, msg.time);
}
} else if (msg.code.startsWith('CDK_RESOURCE')) {
// Track resource events
if (msg.data && 'resourceId' in msg.data) {
tracker.onResourceEvent(msg.data.resourceId, msg.message);
}
}
}
} as IIoHost
});
// Example usage with progress tracking
async function deployWithTracking(cloudAssemblySource: any) {
try {
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy using the cloud assembly
await toolkit.deploy(cloudAssembly, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
throw error;
}
}
```
## Umgang mit Fehlern bei der Wiederherstellung
Implementieren Sie eine robuste Fehlerbehandlung mit Wiederherstellungsstrategien:
```
import { Toolkit, ToolkitError, StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
async function deployWithRetry(toolkit: Toolkit, cloudAssemblySource: any) {
try {
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy using the cloud assembly
await toolkit.deploy(cloudAssembly, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Simply show the error to the user
console.error("Operation failed:", error.message);
throw error;
}
}
// Example usage
try {
await deployWithRetry(toolkit, cloudAssemblySource);
} catch (error) {
console.error("Operation failed:", error.message);
process.exit(1);
}
```
## Integration mit CI/CD-Pipelines
Integrieren Sie die CDK Toolkit-Bibliothek in eine CI/CD-Pipeline:
```
import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
import * as fs from 'fs';
import * as path from 'path';
async function cicdDeploy() {
// Create a non-interactive toolkit for CI/CD environments
const toolkit = new Toolkit({
ioHost: {
notify: async (msg) => {
// Write to both console and log file
const logMessage = `${msg.time} [${msg.level}] ${msg.message}`;
console.log(logMessage);
// Append to deployment log file
fs.appendFileSync('deployment.log', logMessage + '\n');
},
requestResponse: async (msg) => {
// Always use default responses in CI/CD
console.log(`Auto-responding to: ${msg.message} with: ${msg.defaultResponse}`);
return msg.defaultResponse;
}
} as IIoHost
});
// Determine environment from CI/CD variables
const environment = process.env.DEPLOYMENT_ENV || 'development';
// Load environment-specific parameters
const paramsPath = path.join(process.cwd(), `params.${environment}.json`);
const parameters = fs.existsSync(paramsPath)
? JSON.parse(fs.readFileSync(paramsPath, 'utf8'))
: {};
try {
// Use pre-synthesized cloud assembly from build step
const cloudAssemblySource = await toolkit.fromAssemblyDirectory('cdk.out');
// Synthesize the cloud assembly
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
try {
// Deploy with CI/CD specific options
const result = await toolkit.deploy(cloudAssembly, {
stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
parameters,
tags: {
Environment: environment,
BuildId: process.env.BUILD_ID || 'unknown',
CommitHash: process.env.COMMIT_HASH || 'unknown'
}
});
// Write outputs to a file for subsequent pipeline steps
fs.writeFileSync(
'stack-outputs.json',
JSON.stringify(result.outputs, null, 2)
);
return result;
} finally {
// Always dispose when done
await cloudAssembly.dispose();
}
} catch (error) {
// Display the error message
console.error("Operation failed:", error.message);
process.exit(1);
}
}
// Run the CI/CD deployment
cicdDeploy().then(() => {
console.log('CI/CD deployment completed successfully');
});
```
## Weitere Ressourcen
Ausführlichere Informationen zu bestimmten Komponenten, die in diesen Beispielen verwendet wurden, finden Sie unter:
+ [Cloud-Assembly-Quellen verwalten](toolkit-library-configure-ca.md) — Erfahren Sie, wie Sie Cloud-Assembly-Quellen erstellen und verwalten.
+ [Konfiguration von Nachrichten und Interaktionen](toolkit-library-configure-messages.md) — Ausführliche Anleitung zur Anpassung der `IIoHost` Benutzeroberfläche.