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.
# Lakukan tindakan terprogram menggunakan CDK Toolkit Library
## Memahami Perpustakaan Toolkit CDK
Perpustakaan Toolkit CDK memungkinkan Anda melakukan tindakan CDK secara terprogram melalui kode alih-alih menggunakan perintah CLI. Anda dapat menggunakan pustaka ini untuk membuat alat kustom, membangun aplikasi CLI khusus, dan mengintegrasikan kemampuan CDK ke dalam alur kerja pengembangan Anda.
**Kelola siklus hidup infrastruktur Anda dengan kontrol terprogram**
Perpustakaan Toolkit CDK menyediakan antarmuka terprogram untuk tindakan CDK berikut:
+ **Sintesis** - Menghasilkan AWS CloudFormation template dan artefak penyebaran.
+ **Deployment** - Menyediakan atau memperbarui infrastruktur menggunakan CloudFormation template.
+ **Refactor** - Mempertahankan sumber daya yang digunakan saat memfaktorkan ulang kode CDK, seperti mengganti nama konstruksi atau memindahkannya di antara tumpukan.
+ **Daftar** - Lihat informasi tentang tumpukan dan dependensinya.
+ **Tonton** - Pantau aplikasi CDK untuk perubahan lokal.
+ **Rollback** - Kembalikan tumpukan ke kondisi stabil terakhir mereka.
+ **Hancurkan** - Hapus tumpukan CDK dan sumber daya terkait.
**Tingkatkan dan sesuaikan manajemen infrastruktur Anda**
+ **Kontrol melalui kode** - Integrasikan manajemen infrastruktur langsung ke aplikasi Anda dan buat pipeline penerapan responsif.
+ **Kelola rakitan cloud** - Buat, periksa, dan ubah definisi infrastruktur Anda sebelum penerapan.
+ **Sesuaikan penerapan** - Konfigurasikan parameter, perilaku rollback, dan pemantauan agar sesuai dengan kebutuhan Anda.
+ **Pertahankan sumber daya selama refactoring** - Secara otomatis mendeteksi dan melestarikan sumber daya saat Anda memfaktorkan ulang kode CDK.
+ **Tangani kesalahan dengan tepat** - Menerapkan penanganan kesalahan terstruktur dengan informasi diagnostik terperinci.
+ **Menyesuaikan komunikasi** - Konfigurasikan indikator kemajuan khusus dan masuk melalui `IoHost` implementasi.
+ **Connect with AWS ** - Konfigurasikan profil, Wilayah, dan alur otentikasi secara terprogram.
## Memilih kapan harus menggunakan CDK Toolkit Library
Perpustakaan Toolkit CDK sangat berharga ketika Anda perlu:
+ Mengotomatiskan penyebaran infrastruktur sebagai bagian dari jaringan pipa. CI/CD
+ Buat alat penyebaran khusus yang disesuaikan dengan kebutuhan organisasi Anda.
+ Integrasikan tindakan CDK ke dalam aplikasi atau platform yang ada.
+ Buat alur kerja penerapan khusus dengan validasi kustom atau langkah persetujuan.
+ Menerapkan pola manajemen infrastruktur tingkat lanjut di berbagai lingkungan.
+ Otomatiskan operasi refactoring untuk mempertahankan sumber daya saat Anda memfaktorkan ulang kode CDK.
## Menggunakan Perpustakaan Toolkit CDK
Contoh berikut menunjukkan cara membuat dan menerapkan bucket S3 sederhana menggunakan CDK Toolkit Library:
```
// 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);
```
**Apa yang dapat Anda lakukan selanjutnya**
+ **Mengotomatiskan penerapan - Memicu penerapan secara** terprogram dan menambahkan langkah penerapan. pre/post
+ **Integrasikan dengan sistem** - Terhubung dengan CI/CD alur kerja, alat khusus, dan solusi pemantauan.
+ **Kontrol detail penerapan** - Konfigurasikan opsi berbutir halus untuk pemilihan tumpukan dan penerapan multi-lingkungan.
+ **Meningkatkan keandalan** - Menerapkan penanganan kesalahan siap produksi dan pelacakan kemajuan penerapan.
+ **Automate refactoring - Mendeteksi** dan melestarikan sumber daya saat Anda memfaktorkan ulang kode CDK.
## Langkah berikutnya
Untuk mulai menggunakan CDK Toolkit Library, lihat [Memulai dengan CDK](toolkit-library-gs.md) Toolkit Library.
## Pelajari selengkapnya
Untuk mempelajari lebih lanjut tentang CDK Toolkit Library, lihat berikut ini:
+ [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)dalam paket *@aws -cdk/toolkit-lib*`npm`.
+ AWS Referensi [API Perpustakaan Toolkit CDK](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Memulai dengan CDK Toolkit Library
Mulailah menggunakan AWS CDK Toolkit Library untuk melakukan tindakan CDK secara terprogram, seperti sintesis dan penerapan, dalam kode Anda.
## Prasyarat
1. Versi Node.js yang didukung diinstal.
1. AWS kredensi dikonfigurasi.
1. Keakraban dasar dengan AWS CDK.
Untuk informasi lebih lanjut, lihat [prasyarat AWS CDK](prerequisites.md).
## Langkah 1: Menginstal Perpustakaan Toolkit CDK
Instal paket CDK Toolkit Library di lingkungan pengembangan proyek Anda dengan menjalankan yang berikut:
```
npm install --save @aws-cdk/toolkit-lib
```
## Langkah 2: Menginisialisasi Perpustakaan Toolkit CDK
Buat instance CDK Toolkit untuk melakukan tindakan terprogram pada aplikasi CDK Anda.
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit({
// Optional configuration options go here
});
```
Anda dapat menyesuaikan instance CDK Toolkit selama pembuatan. Untuk petunjuk, lihat [Mengonfigurasi instance CDK Toolkit Anda](toolkit-library-configure.md).
## Langkah 3: Membuat sumber perakitan cloud untuk aplikasi CDK Anda
Sumber perakitan cloud memberikan instruksi untuk membuat CloudFormation templat dari aplikasi CDK Anda. Anda dapat membuatnya dengan berbagai cara. Berikut ini adalah beberapa contoh:
1. **Fungsi pembuat perakitan inline**:
```
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. **File aplikasi CDK yang ada**:
```
const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
```
Untuk informasi selengkapnya, lihat [Mengonfigurasi sumber perakitan cloud](toolkit-library-configure-ca.md).
## Langkah 4: Mendefinisikan tindakan terprogram untuk aplikasi CDK Anda
Sekarang setelah Anda membuat instance CDK Toolkit dan sumber perakitan cloud, Anda dapat mulai menentukan tindakan terprogram. Berikut ini adalah contoh dasar yang membuat penyebaran `MyStack` tumpukan:
```
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"],
},
});
```
## Langkah 5: Menyesuaikan Toolkit CDK lebih lanjut
Anda dapat mengonfigurasi dan menyesuaikan CDK Toolkit lebih lanjut untuk kebutuhan Anda:
+ **Pesan dan interaksi** - Konfigurasikan bagaimana CDK Toolkit berkomunikasi dengan pengguna dan aplikasi. Lihat [Mengonfigurasi pesan & interaksi](toolkit-library-configure-messages.md).
+ **Penanganan kesalahan** - Menerapkan penanganan kesalahan terstruktur untuk operasi CDK. Lihat [Mengonfigurasi penanganan kesalahan](toolkit-library-configure.md#toolkit-library-configure-errors).
## Sumber daya tambahan
Untuk informasi selengkapnya tentang paket CDK Toolkit Library, lihat `npm` paket *@aws [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib)`npm`-cdk/toolkit-lib*.
Untuk informasi referensi API, lihat referensi [CDK Toolkit Library API](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).
# Mengkonfigurasi tindakan terprogram CDK Toolkit
Perpustakaan Toolkit AWS CDK menyediakan antarmuka terprogram untuk tindakan siklus hidup aplikasi seperti sintesis, penerapan, dan manajemen tumpukan. Panduan ini menjelaskan cara menggunakan setiap tindakan dalam kode Anda.
## Menghasilkan rakitan cloud dengan synth
`synth`Tindakan ini menghasilkan rakitan cloud dari sumber perakitan cloud Anda. Untuk informasi selengkapnya tentang sintesis, lihat [Mengkonfigurasi dan melakukan sintesis tumpukan CDK](configure-synth.md). Rakitan cloud berisi artefak penerapan berikut dari aplikasi CDK Anda:
+ AWS CloudFormation template yang menentukan infrastruktur Anda.
+ Aset seperti kode fungsi Lambda atau gambar Docker.
+ Metadata dan konfigurasi penyebaran.
Berikut cara menggunakan `synth` tindakan untuk membuat perakitan cloud:
```
// 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;
```
**Tip**
Menggunakan perakitan cloud dapat mengoptimalkan kinerja saat Anda perlu melakukan beberapa operasi, karena sintesis hanya terjadi sekali. Untuk informasi selengkapnya tentang mengelola rakitan cloud, termasuk caching dan pembuangan, lihat [Membuat dan mengelola](toolkit-library-configure-ca.md#toolkit-library-configure-ca-cache) rakitan cloud.
## Melihat informasi tumpukan dengan daftar
`list`Tindakan ini mengambil informasi tentang tumpukan di aplikasi CDK Anda, termasuk dependensi dan statusnya saat ini. Gunakan tindakan ini untuk memeriksa infrastruktur Anda sebelum penerapan atau untuk menghasilkan laporan.
```
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}`);
}
```
## Penyediaan infrastruktur dengan deploy
`deploy`Tindakan tersebut menyediakan atau memperbarui infrastruktur Anda dalam AWS menggunakan perakitan cloud yang dihasilkan selama sintesis. Untuk pengenalan penerapan, lihat [Menerapkan aplikasi AWS CDK](deploy.md). Anda dapat mengontrol opsi penerapan seperti pemilihan tumpukan, nilai parameter, dan perilaku rollback.
```
// Deploy stacks with parameter values
await toolkit.deploy(cloudAssemblySource, {
parameters: StackParameters.exactly({
"MyStack": {
"BucketName": "amzn-s3-demo-bucket"
}
})
});
```
Tindakan penerapan mendukung metode penerapan yang berbeda untuk mengakomodasi berbagai alur kerja. Untuk sebagian besar skenario, terutama di lingkungan produksi, sebaiknya gunakan metode penerapan default yang menggunakan set CloudFormation perubahan. Untuk lingkungan pengembangan di mana kecepatan iterasi penting, Anda dapat menggunakan metode alternatif seperti hotswap.
```
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"]
}
});
```
## Melestarikan sumber daya yang digunakan dengan refactor
**penting**
Tindakan refactor ada dalam rilis pratinjau dan dapat berubah sewaktu-waktu.
`refactor`Tindakan ini mempertahankan sumber daya yang diterapkan saat Anda memfaktorkan ulang kode CDK seperti mengganti nama konstruksi atau memindahkannya di antara tumpukan. Tanpa fitur ini, perubahan ini akan CloudFormation menyebabkan penggantian sumber daya, yang berpotensi menyebabkan gangguan layanan atau kehilangan data.
Tindakan refactor secara otomatis menghitung pemetaan dengan membandingkan kode Anda saat ini dengan status yang diterapkan. Ini memverifikasi bahwa aplikasi CDK Anda berisi kumpulan sumber daya yang persis sama dengan status yang diterapkan, hanya berbeda di lokasi mereka di pohon konstruksi. Jika mendeteksi penambahan, penghapusan, atau modifikasi sumber daya apa pun, operasi refactoring akan ditolak dengan pesan kesalahan.
Setelah menghitung pemetaan, tindakan refactor menggunakan CloudFormation API refactoring untuk memperbarui logika sumber daya tanpa menggantinya. IDs Jika menemukan pemetaan ambigu (di mana ada beberapa kemungkinan pemetaan), Anda dapat memberikan penggantian eksplisit untuk menyelesaikan ambiguitas ini.
```
// 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"
}
}
]
}
});
```
**penting**
Operasi refactoring harus dilakukan secara terpisah dari tindakan lain, seperti menambahkan sumber daya baru, menghapus sumber daya, atau memodifikasi properti sumber daya. Jika Anda perlu membuat perubahan seperti itu, Anda harus terlebih dahulu menerapkan perubahan tersebut secara terpisah, dan kemudian menggunakan refactoring untuk mengatur ulang sumber daya Anda.
**Tip**
Untuk informasi selengkapnya tentang refactoring CDK, termasuk cara kerjanya dan kapan menggunakannya, lihat [Mempertahankan sumber daya yang diterapkan](refactor.md) saat memfaktorkan ulang kode CDK.
## Mengembalikan penerapan yang gagal dengan rollback
`rollback`Tindakan mengembalikan tumpukan ke status stabil terakhirnya ketika penerapan gagal dan tidak dapat dibalik secara otomatis. Gunakan tindakan ini untuk memulihkan dari penerapan gagal yang memerlukan intervensi manual.
```
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"]
}
});
```
## Memantau perubahan dengan arloji
`watch`Tindakan ini terus memantau aplikasi CDK Anda untuk perubahan file lokal dan secara otomatis melakukan penerapan atau hotswap. Ini membuat pengamat file yang berjalan sampai kode Anda keluar atau dihentikan.
**Awas**
Penerapan Hotswap memperbarui sumber daya secara langsung tanpa melalui CloudFormation bila memungkinkan, membuat pembaruan lebih cepat selama pengembangan. Ini diaktifkan secara default untuk `watch` perintah. Meskipun ini mempercepat siklus pengembangan, ini memperkenalkan penyimpangan antara CloudFormation template Anda dan sumber daya yang digunakan. Oleh karena itu, kami menyarankan Anda untuk tidak menggunakan hotswaps di lingkungan produksi.
```
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();
```
Fungsi jam tangan mengembalikan `IWatcher` objek yang memungkinkan Anda mengontrol secara eksplisit kapan harus berhenti menonton. Panggil `dispose()` metode pada objek ini ketika Anda ingin mengakhiri proses menonton.
## Menghapus infrastruktur dengan menghancurkan
`destroy`Tindakan ini menghapus tumpukan CDK dan sumber daya terkaitnya dari. AWS Gunakan tindakan ini untuk membersihkan sumber daya saat tidak lagi dibutuhkan.
**penting**
Tindakan menghancurkan secara permanen menghapus sumber daya tanpa meminta konfirmasi, tidak seperti versi CLI dari perintah ini. Pastikan Anda memiliki cadangan data penting apa pun sebelum menghancurkan tumpukan.
```
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
}
});
```
# Mengonfigurasi instans CDK Toolkit Anda
Pelajari cara menyesuaikan instance AWS CDK Toolkit Library Anda dengan opsi untuk penanganan pesan, pemilihan AWS profil, dan strategi pemilihan tumpukan. Panduan ini menjelaskan opsi konfigurasi yang tersedia dan cara menerapkannya secara efektif untuk memenuhi persyaratan penerapan spesifik Anda.
## Mengkonfigurasi profil Anda AWS
Saat Anda menggunakan CDK Toolkit Library, itu membuat panggilan API untuk AWS menggunakan SDK. Sementara otentikasi dimuat secara otomatis dari lingkungan Anda, Anda dapat secara eksplisit menentukan profil mana yang akan digunakan:
```
import { Toolkit } from '@aws-cdk/toolkit-lib';
// Create a toolkit instance with a specific AWS profile
const toolkit = new Toolkit({
sdkConfig: { profile: "my-profile" },
});
```
## Mengkonfigurasi pemilihan tumpukan
Sebagian besar tindakan CDK Toolkit mengharuskan Anda menentukan tumpukan mana yang akan dioperasikan. ` [StackSelector](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/StackSelector/) `Konfigurasi mengontrol pilihan ini.
### Pilih semua tumpukan
Gunakan ini saat Anda ingin beroperasi di setiap tumpukan di aplikasi CDK Anda:
```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';
// Select all stacks in the cloud assembly
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ALL_STACKS
}
});
```
### Pilih hanya tumpukan perakitan utama
Gunakan ini untuk memilih hanya tumpukan tingkat atas dari rakitan utama:
```
// Select only top-level stacks
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.MAIN_ASSEMBLY
}
});
```
### Pilih satu tumpukan
Gunakan ini ketika rakitan Anda berisi tepat satu tumpukan dan Anda ingin menegaskan kondisi ini. Jika perakitan menyertakan tumpukan tunggal, ia mengembalikan tumpukan itu. Jika tidak, itu melempar pengecualian:
```
// Ensure there's exactly one stack and select it
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.ONLY_SINGLE
}
});
```
### Pilih tumpukan berdasarkan pola
Gunakan ini untuk memilih tumpukan tertentu berdasarkan pola nama:
```
// Select stacks matching specific patterns
await toolkit.deploy(cloudAssemblySource, {
stacks: {
strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
patterns: ["Dev-*", "Test-Backend"], // Supports wildcards
}
});
```
**Tip**
Gunakan `PATTERN_MUST_MATCH_SINGLE` untuk memastikan persis satu tumpukan cocok dengan pola Anda, atau `PATTERN_MATCH` jika tidak ada tumpukan yang cocok. Pencocokan pola mendukung wildcard seperti “\$1” untuk mencocokkan beberapa tumpukan dengan nama yang mirip.
## Mengkonfigurasi penanganan kesalahan
CDK Toolkit menggunakan kesalahan terstruktur untuk membantu Anda mengidentifikasi dan menangani masalah. Setiap kesalahan meliputi:
+ **Sumber** yang menunjukkan dari mana kesalahan berasal (toolkit atau pengguna).
+ **Jenis kesalahan** tertentu (otentikasi, validasi, dll.).
+ **Pesan** deskriptif.
### Menangani kesalahan
Gunakan metode pembantu yang disediakan oleh CDK Toolkit untuk mendeteksi dan menangani jenis kesalahan tertentu:
```
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);
}
}
```
**penting**
Jangan mengandalkan `instanceof` pemeriksaan untuk jenis kesalahan, karena mereka dapat berperilaku tidak terduga saat bekerja dengan banyak salinan dari paket yang sama. Selalu gunakan metode pembantu yang disediakan seperti`ToolkitError.isAuthenticationError()`.
## Mengkonfigurasi tindakan Toolkit
Setiap tindakan CDK Toolkit (deploy, synth, list, dll.) Memiliki opsi konfigurasi spesifiknya sendiri. Tindakan ini memungkinkan Anda mengelola siklus hidup lengkap infrastruktur CDK Anda. Untuk informasi terperinci tentang mengonfigurasi tindakan individual, lihat [Mengonfigurasi tindakan terprogram CDK Toolkit](toolkit-library-actions.md).
**Tip**
Saat membangun alur kerja otomatisasi, pertimbangkan untuk menggabungkan beberapa tindakan secara berurutan. Misalnya, Anda mungkin ingin menggunakan aplikasi `synth` Anda, `list` tumpukan untuk memverifikasi apa yang akan digunakan, dan kemudian infrastruktur`deploy`.
# Mengelola AWS sumber perakitan cloud Perpustakaan Toolkit CDK
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
| 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
### Dari aplikasi CDK yang ada
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
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
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
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
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
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
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
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 {
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
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();
}
```
# Mengkonfigurasi pesan dan interaksi CDK Toolkit
AWS CDK Toolkit Library menyediakan ` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) ` antarmuka untuk menyesuaikan bagaimana pesan dan interaksi ditangani selama operasi CDK, memungkinkan Anda untuk mengontrol tampilan kemajuan penerapan, pesan kesalahan, dan permintaan pengguna untuk lebih terintegrasi dengan pengalaman pengguna aplikasi Anda.
Sebelum melakukan operasi seperti penyebaran atau sintesis, Anda perlu memahami bagaimana CDK Toolkit berkomunikasi dengan pengguna. `IIoHost`Antarmuka berfungsi sebagai saluran komunikasi antara CDK Toolkit dan aplikasi Anda, menangani pesan keluar dan respons pengguna yang masuk.
Ketika CDK Toolkit menjalankan operasi, ia berkomunikasi melalui dua mekanisme utama:
+ **Pesan**: Output informasi yang memberi tahu Anda tentang kemajuan operasi (seperti “Memulai penerapan” atau “Sumber daya dibuat”).
+ **Permintaan**: Poin keputusan yang memerlukan masukan atau konfirmasi (seperti “Apakah Anda ingin menerapkan perubahan ini?”) , memberi Anda kesempatan untuk memberikan informasi yang tidak diketahui dibutuhkan sebelumnya.
## Menggunakan `IIoHost` antarmuka
`IIoHost`Antarmuka terdiri dari dua metode utama:
1. `notify`: Menangani pesan informasi satu arah.
1. `requestResponse`: Menangani permintaan interaktif yang memerlukan respons.
```
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;
}
```
## Tingkat pesan dan jenis permintaan
CDK Toolkit menghasilkan beberapa jenis pesan dan permintaan:
### Tingkat pesan
+ **Debug**: Pesan terperinci untuk pemecahan masalah.
+ **Kesalahan**: Pesan kesalahan yang dapat memengaruhi operasi.
+ **Info**: Pesan informasi umum.
+ **Hasil** - Pesan utama dari suatu operasi.
+ **Trace**: Informasi alur eksekusi yang sangat rinci.
+ **Peringatan**: Pesan peringatan yang tidak mencegah operasi.
Untuk daftar lengkapnya, lihat [IoMessages Registri di Referensi](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) *API Perpustakaan Toolkit AWS CDK*.
### Tipe permintaan
CDK Toolkit mengirimkan permintaan ketika membutuhkan input atau konfirmasi dari pengguna. Ini adalah pesan khusus yang memungkinkan respons. Jika tidak ada respons yang diberikan, Toolkit akan menggunakan respons default bila tersedia.
## `IIoHost`Implementasi dasar
Berikut adalah contoh sederhana penerapan host io khusus:
```
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
});
```
CDK Toolkit menunggu penyelesaian setiap panggilan, memungkinkan Anda untuk melakukan operasi asinkron seperti permintaan HTTP atau permintaan pengguna saat menangani pesan.
## `IIoHost`Perilaku default
Jika Anda tidak menyediakan host io khusus, Perpustakaan Toolkit CDK menggunakan implementasi non-interaktif default:
+ Output konsol untuk pesan (menggunakan warna yang sesuai untuk berbagai jenis pesan).
+ Sepenuhnya non-interaktif tanpa petunjuk untuk input pengguna.
+ Secara otomatis menggunakan respons default jika memungkinkan (setara dengan menjawab “ya” untuk permintaan).
+ Gagal saat input diperlukan tetapi tidak ada respons default yang tersedia.
Perilaku default ini cocok untuk operasi tanpa pengawasan, tetapi tidak untuk aplikasi baris perintah interaktif. Untuk aplikasi baris perintah yang memerlukan interaksi pengguna, Anda harus mengimplementasikan host io khusus. Implementasi kustom juga berguna untuk mengintegrasikan dengan sistem logging UIs, atau lingkungan khusus lainnya.
## Implementasi io host tingkat lanjut
Untuk skenario yang lebih kompleks, kami sarankan untuk memperluas `NonInteractiveIoHost` kelas sebagai titik awal. Pendekatan ini memungkinkan Anda untuk memanfaatkan implementasi non-interaktif yang ada sambil hanya menyesuaikan perilaku spesifik yang perlu Anda ubah.
Berikut adalah contoh host io khusus yang memperluas implementasi dasar:
```
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}`);
}
}
```
Pendekatan ini lebih dapat dipertahankan daripada mengimplementasikan seluruh `IIoHost` antarmuka dari awal, karena Anda hanya perlu mengganti metode spesifik yang memerlukan perilaku khusus.
## Integrasi dengan lingkungan yang berbeda
### Integrasi aplikasi web
```
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
});
```
### Integrasi lingkungan CI/CD
```
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
});
```
## Praktik terbaik untuk implementasi io host
Saat menerapkan host io khusus, pertimbangkan praktik terbaik ini:
+ **Penanganan kesalahan**: Terapkan penanganan kesalahan yang kuat dalam metode host io Anda untuk mencegah kegagalan memengaruhi operasi CDK.
+ **Timeout**: Pertimbangkan untuk menerapkan batas waktu untuk interaksi pengguna untuk mencegah penantian yang tidak terbatas.
+ **Logging**: Simpan pesan penting dalam log untuk pemecahan masalah, terutama di lingkungan non-interaktif.
+ **Respons default**: Berikan respons default yang masuk akal untuk lingkungan otomatis di mana interaksi pengguna tidak dimungkinkan.
+ **Indikasi kemajuan**: Untuk operasi yang berjalan lama, berikan indikator kemajuan yang jelas untuk meningkatkan pengalaman pengguna.
Contoh berikut menunjukkan praktik terbaik ini dengan menerapkan host io khusus dengan penanganan kesalahan, batas waktu untuk interaksi pengguna, dan pencatatan yang tepat. Implementasi ini cocok untuk aplikasi interaktif di mana Anda perlu menyeimbangkan respons pengguna dengan operasi yang andal:
```
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
});
```
## Pemecahan Masalah
Pertimbangan saat menerapkan host io khusus:
+ **Penolakan janji yang tidak tertangani**: Pastikan semua operasi asinkron ditangani dengan benar dengan blok coba/tangkap.
+ **Penantian tak terbatas**: Terapkan batas waktu untuk semua interaksi pengguna untuk mencegah aplikasi macet.
+ **Tingkat pesan yang hilang**: Bersiaplah untuk menangani tingkat pesan baru yang mungkin ditambahkan di versi CDK masa depan.
+ **Respons yang tidak konsisten**: Pastikan implementasi requestResponse Anda mengembalikan nilai dalam format yang diharapkan.
Contoh berikut menunjukkan pendekatan yang kuat untuk menangani tingkat pesan, termasuk penanganan yang anggun dari jenis pesan yang tidak dikenal yang mungkin diperkenalkan di versi CDK masa depan. Implementasi ini memastikan host io Anda tetap kompatibel dengan pembaruan CDK sambil mempertahankan pencatatan yang tepat:
```
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
});
```
# Contoh Perpustakaan Toolkit CDK Tingkat Lanjut
Pelajari cara menggunakan fitur-fitur canggih dari AWS CDK Toolkit Library melalui contoh-contoh praktis. Panduan ini menyediakan contoh kode terperinci untuk penanganan kesalahan, pemantauan penerapan, dan manajemen perakitan cloud yang dibangun di atas konsep dasar yang tercakup dalam bagian lain.
## Mengintegrasikan fitur
Contoh berikut menunjukkan cara menggabungkan sumber perakitan cloud, implementasi host io kustom, dan opsi penerapan:
```
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'
}
}
});
```
## Melacak kemajuan penerapan
Lacak kemajuan penerapan dengan pembaruan status terperinci:
```
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;
}
}
```
## Menangani kesalahan dengan pemulihan
Menerapkan penanganan kesalahan yang kuat dengan strategi pemulihan:
```
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);
}
```
## Mengintegrasikan dengan pipa CI/CD
Integrasikan Perpustakaan Toolkit CDK ke dalam pipeline CI/CD:
```
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');
});
```
## Sumber daya tambahan
Untuk informasi lebih rinci tentang komponen spesifik yang digunakan dalam contoh ini, lihat:
+ [Mengelola sumber perakitan cloud](toolkit-library-configure-ca.md) - Pelajari cara membuat dan mengelola sumber perakitan cloud.
+ [Mengkonfigurasi pesan dan interaksi](toolkit-library-configure-messages.md) - Panduan terperinci tentang menyesuaikan antarmuka. `IIoHost`