Ini adalah Panduan Pengembang AWS CDK v2. CDK v1 yang lebih lama memasuki pemeliharaan pada 1 Juni 2022 dan mengakhiri dukungan pada 1 Juni 2023.

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Mengelola AWS sumber perakitan cloud Perpustakaan Toolkit CDK
<a name="toolkit-library-configure-ca"></a>

Gunakan Perpustakaan Toolkit AWS CDK untuk mengonfigurasi sumber perakitan cloud dan menyesuaikan cara Anda menerapkan aplikasi CDK Anda. Panduan ini menunjukkan cara mengonfigurasi sumber perakitan cloud untuk memenuhi persyaratan penerapan dan kebutuhan alur kerja Anda.

Sebelum Anda menggunakan CDK Toolkit, tentukan sumber perakitan cloud. *Sumber perakitan cloud* memberikan instruksi untuk membuat perakitan cloud dari aplikasi CDK Anda. Perakitan cloud yang dihasilkan berisi artefak infrastruktur yang disintesis yang digunakan oleh CDK Toolkit. AWS

Perpustakaan Toolkit CDK menawarkan beberapa pendekatan untuk mengonfigurasi sumber perakitan cloud, masing-masing cocok untuk skenario dan alur kerja yang berbeda.

## Memilih sumber perakitan cloud
<a name="toolkit-library-configure-ca-options"></a>


| Metode | Terbaik Untuk | Pertimbangan | 
| --- | --- | --- | 
|   `fromCdkApp`   |  Bekerja dengan aplikasi CDK yang ada dalam bahasa apa pun yang didukung.  |  Membutuhkan runtime bahasa yang sesuai untuk diinstal.  | 
|   `fromAssemblyBuilder`   |  Membuat konstruksi CDK sejalan dengan kontrol penuh atas proses sintesis.  |  Menyediakan akses tingkat rendah ke fungsionalitas CDK dan dapat digunakan untuk membangun versi khusus dari metode lain seperti. `fromCdkApp`  | 
|   `fromAssemblyDirectory`   |  Menggunakan rakitan cloud yang telah disintesis sebelumnya.  |  Eksekusi lebih cepat karena langkah sintesis dilewati.  | 
|  Sumber Kustom  |  Skenario yang sangat khusus yang membutuhkan implementasi kustom lengkap.  |  Membutuhkan implementasi `ICloudAssemblySource` antarmuka dari awal; tidak memiliki fungsionalitas bawaan seperti pencarian konteks; jarang diperlukan untuk sebagian besar kasus penggunaan.  | 

## Mengonfigurasi sumber perakitan cloud Anda
<a name="toolkit-library-configure-ca-how"></a>

### Dari aplikasi CDK yang ada
<a name="toolkit-library-configure-ca-how-app"></a>

Gunakan `fromCdkApp` metode ini untuk bekerja dengan aplikasi CDK yang ditulis dalam bahasa apa pun yang didukung. Pendekatan ini sangat ideal ketika Anda memiliki aplikasi CDK yang ada dan ingin menerapkannya secara terprogram.

```
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");
```

### Dari pembuat perakitan inline
<a name="toolkit-library-configure-ca-how-builder"></a>

Buat aplikasi CDK langsung di kode Anda menggunakan fungsi pembuat perakitan. Pendekatan ini berguna untuk penerapan sederhana atau skenario pengujian di mana Anda ingin menentukan infrastruktur Anda secara inline.

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

### Dari direktori perakitan yang ada
<a name="toolkit-library-configure-ca-how-directory"></a>

Jika Anda sudah memiliki rakitan cloud yang disintesis, Anda dapat menggunakannya secara langsung. Ini berguna ketika Anda sudah menjalankan `cdk synth` atau saat bekerja dengan rakitan cloud yang dihasilkan oleh pipeline CI/CD.

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

## Bekerja dengan rakitan cloud yang di-cache
<a name="toolkit-library-configure-ca-cache"></a>

Saat bekerja dengan rakitan cloud, Anda memiliki dua opsi:

1. Gunakan sumber perakitan cloud secara langsung (sederhana tetapi mungkin lebih lambat):

   ```
   // Each operation triggers a new synthesis
   await toolkit.deploy(cloudAssemblySource, { /* options */ });
   await toolkit.list(cloudAssemblySource, { /* options */ });
   ```

1. Cache rakitan cloud (lebih cepat untuk beberapa operasi):

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

Gunakan rakitan yang di-cache saat:
+ Anda melakukan beberapa operasi (menyebarkan, daftar, diff, dll.).
+ Aplikasi CDK Anda tidak sering berubah selama operasi.
+ Anda menginginkan kinerja yang lebih cepat.

Gunakan sumber perakitan cloud secara langsung saat:
+ Kau melakukan satu operasi.
+ Aplikasi CDK Anda sering berubah.
+ Anda menginginkan kode yang lebih sederhana dan tidak perlu memprioritaskan kecepatan operasi Toolkit.

**penting**  
Sebagian besar interaksi Toolkit harus menggunakan rakitan yang di-cache untuk kinerja yang lebih baik. Satu-satunya waktu untuk menghindari caching adalah ketika sumber Anda sering berubah dan memeriksa perubahan akan mahal.

### Cara membuat, cache, dan menggunakan kembali rakitan cloud
<a name="toolkit-library-configure-ca-cache-how"></a>

Setelah Anda membuat sumber perakitan cloud, Anda dapat membuat perakitan cloud dengan mensintesisnya. Perakitan cloud berisi AWS CloudFormation template dan aset yang diperlukan untuk penerapan.

Kami menyarankan Anda membuat perakitan cloud sekali dan menggunakannya kembali untuk beberapa operasi Toolkit. Pendekatan caching ini lebih efisien daripada meregenerasi rakitan untuk setiap operasi. Pertimbangkan untuk meregenerasi rakitan hanya jika sumber Anda sering berubah.

Berikut cara membuat rakitan cloud yang di-cache:

```
// Generate a cloud assembly from your source
const cloudAssembly = await toolkit.synth(cloudAssemblySource);
```

Anda kemudian dapat melakukan berbagai tindakan Toolkit pada rakitan cloud yang di-cache, seperti, `list()``deploy()`, dan. `diff()` Dengan cache rakitan cloud, tindakan Toolkit selanjutnya dilakukan lebih cepat karena sintesis hanya terjadi sekali. Untuk informasi selengkapnya, lihat [synth - Menghasilkan rakitan cloud](toolkit-library-actions.md#toolkit-library-actions-synth).

### Buang sumber daya perakitan cloud
<a name="toolkit-library-configure-ca-cache-dispose"></a>

Selalu buang rakitan cloud setelah Anda selesai menggunakannya untuk membersihkan sumber daya sementara. Sebaiknya gunakan blok coba/akhirnya untuk memastikan pembersihan yang tepat, terutama saat melakukan beberapa operasi:

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

Berikut adalah contoh yang menunjukkan cara membuat dan membuang rakitan cloud yang di-cache:

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

### Memahami masa pakai perakitan cloud
<a name="toolkit-library-configure-ca-cache-lifetime"></a>

Saat Anda membuat rakitan cloud yang di-cache menggunakan`synth()`, Anda mendapatkan tipe khusus yang berfungsi sebagai file yang dapat dibaca `CloudAssembly` dan file. `CloudAssemblySource` Setiap rakitan cloud yang dihasilkan dari rakitan cache ini (misalnya, dari operasi daftar atau penerapan) terkait dengan masa pakai induk:
+ Hanya panggilan dispose () induk yang benar-benar membersihkan sumber daya
+ Rakitan cloud dari operasi daftar/penerapan dikelola oleh induknya
+ Gagal membuang rakitan cloud yang di-cache dianggap sebagai bug

## Praktik terbaik untuk sumber perakitan cloud
<a name="toolkit-library-configure-ca-best-practices"></a>

Saat bekerja dengan sumber perakitan cloud, pertimbangkan praktik terbaik ini:
+  **Pilih metode sumber yang tepat**: Pilih pendekatan yang paling sesuai dengan alur kerja dan persyaratan Anda.
+  **Rakitan cloud cache: Hasilkan rakitan** cloud setelah digunakan `synth()` dan gunakan kembali untuk beberapa operasi untuk menghindari sintesis yang tidak perlu, terutama untuk aplikasi besar.
+  **Penanganan kesalahan**: Menerapkan penanganan kesalahan dasar untuk menangkap dan menampilkan kesalahan kepada pengguna. Jaga penanganan kesalahan tetap sederhana dan fokus pada penyediaan pesan kesalahan yang jelas.
+  **Kompatibilitas versi**: Pastikan versi CDK Toolkit Library Anda dapat mendukung rakitan cloud yang sedang Anda kerjakan. Jika Perpustakaan Konstruksi yang digunakan untuk membuat perakitan cloud lebih baru dari yang didukung Perpustakaan Toolkit Anda, Anda akan menerima kesalahan.
+  **Variabel lingkungan**: Sadarilah bahwa variabel lingkungan tertentu dapat memengaruhi sintesis dan penerapan perakitan cloud. Variabel seperti`CDK_DEFAULT_ACCOUNT`,`CDK_DEFAULT_REGION`,`CDK_OUTDIR`, dan `CDK_CONTEXT_JSON` dapat mengesampingkan perilaku default. Pastikan ini diatur dengan tepat untuk lingkungan penerapan Anda.

Contoh berikut menunjukkan cara menerapkan penanganan kesalahan dan pembersihan yang tepat saat menggunakan kembali perakitan cloud untuk beberapa operasi:

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

## Menyelesaikan masalah potensial
<a name="toolkit-library-configure-ca-troubleshooting"></a>

Ikuti langkah-langkah ini untuk mengatasi potensi masalah dengan sumber perakitan cloud:
+  **Instal dependensi yang hilang**: Jalankan `npm install` untuk menginstal dependensi yang diperlukan untuk aplikasi CDK Anda.
+  **Perbaiki masalah jalur**: Periksa apakah jalur ke aplikasi CDK dan direktori perakitan ada dan dapat diakses.
+  **Selesaikan ketidakcocokan versi: Perbarui** versi CDK Toolkit Library agar sesuai dengan versi aplikasi CDK Anda.
+  **Memperbaiki kesalahan sintesis**: Tinjau kode aplikasi CDK Anda untuk kesalahan sintaks atau konfigurasi yang tidak valid.

Ketika kesalahan terjadi selama operasi Toolkit, jaga agar penanganan kesalahan tetap sederhana dan fokus pada penyediaan pesan kesalahan yang jelas kepada pengguna. Selalu buang rakitan cloud setelah Anda selesai menggunakannya. Berikut adalah contoh yang menunjukkan penanganan kesalahan dasar dengan pembersihan yang tepat:

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