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.

# Cloud-Assembly-Quellen der AWS CDK Toolkit Library verwalten
<a name="toolkit-library-configure-ca"></a>

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
<a name="toolkit-library-configure-ca-options"></a>


| 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
<a name="toolkit-library-configure-ca-how"></a>

### Aus einer vorhandenen CDK-App
<a name="toolkit-library-configure-ca-how-app"></a>

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
<a name="toolkit-library-configure-ca-how-builder"></a>

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
<a name="toolkit-library-configure-ca-how-directory"></a>

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
<a name="toolkit-library-configure-ca-cache"></a>

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
<a name="toolkit-library-configure-ca-cache-how"></a>

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
<a name="toolkit-library-configure-ca-cache-dispose"></a>

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
<a name="toolkit-library-configure-ca-cache-lifetime"></a>

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
<a name="toolkit-library-configure-ca-best-practices"></a>

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<void> {
    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
<a name="toolkit-library-configure-ca-troubleshooting"></a>

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();
}
```