Ini adalah Panduan Pengembang AWS CDK v2. CDKV1 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.
Migrasi dari AWS CDK v1 ke v2 AWS CDK
Versi 2 AWS Cloud Development Kit (AWS CDK) dirancang untuk membuat infrastruktur penulisan sebagai kode dalam bahasa pemrograman pilihan Anda lebih mudah. Topik ini menjelaskan perubahan antara v1 dan v2 dari. AWS CDK
Perubahan utama dari AWS CDK v1 ke CDK v2 adalah sebagai berikut.
-
AWS CDK v2 mengkonsolidasikan bagian stabil dari AWS Construct Library, termasuk pustaka inti, ke dalam satu paket,.
aws-cdk-lib
Pengembang tidak perlu lagi menginstal paket tambahan untuk AWS layanan individual yang mereka gunakan. Pendekatan paket tunggal ini juga berarti bahwa Anda tidak perlu menyinkronkan versi dari berbagai paket CDK perpustakaan.Konstruksi L1 (CfnXXXX), yang mewakili sumber daya yang tepat yang tersedia di AWS CloudFormation, selalu dianggap stabil dan termasuk dalam.
aws-cdk-lib
-
Modul eksperimental, di mana kami masih bekerja dengan komunitas untuk mengembangkan konstruksi L2 atau L3 baru, tidak termasuk dalam.
aws-cdk-lib
Sebaliknya, mereka didistribusikan sebagai paket individual. Paket eksperimental diberi nama denganalpha
akhiran dan nomor versi semantik. Nomor versi semantik cocok dengan versi pertama dari AWS Construct Library yang kompatibel dengannya, juga dengan akhiran.alpha
Konstruksi pindah keaws-cdk-lib
setelah ditunjuk stabil, memungkinkan Perpustakaan Konstruksi utama untuk mematuhi versi semantik yang ketat.Stabilitas ditentukan pada tingkat layanan. Misalnya, jika kita mulai membuat satu atau lebih konstruksi L2 untuk Amazon AppFlow, yang pada tulisan ini hanya memiliki konstruksi L1, mereka pertama kali muncul dalam modul bernama.
@aws-cdk/aws-appflow-alpha
Kemudian, mereka pindah keaws-cdk-lib
ketika kita merasa bahwa konstruksi baru memenuhi kebutuhan mendasar pelanggan.Setelah modul ditetapkan stabil dan dimasukkan ke dalam
aws-cdk-lib
, baru APIs ditambahkan menggunakan konvensi “BETan” yang dijelaskan dalam bullet berikutnya.Versi baru dari setiap modul eksperimental dirilis dengan setiap rilis AWS CDK. Namun, untuk sebagian besar, mereka tidak perlu disinkronkan. Anda dapat memutakhirkan
aws-cdk-lib
atau modul eksperimental kapan pun Anda mau. Pengecualiannya adalah ketika dua atau lebih modul eksperimental terkait bergantung satu sama lain, mereka harus versi yang sama. -
Untuk modul stabil yang fungsionalitas baru ditambahkan, baru APIs (apakah konstruksi yang sama sekali baru atau metode atau properti baru pada konstruksi yang ada) menerima
Beta1
sufiks saat pekerjaan sedang berlangsung. (Diikuti olehBeta2
Beta3
,, dan seterusnya ketika melanggar perubahan diperlukan.) Versi API tanpa akhiran ditambahkan ketika API ditunjuk stabil. Semua metode kecuali yang terbaru (baik beta atau final) kemudian tidak digunakan lagi.Misalnya, jika kita menambahkan metode baru
grantPower()
ke konstruksi, awalnya muncul sebagaigrantPowerBeta1()
. Jika perubahan yang melanggar diperlukan (misalnya, parameter atau properti baru yang diperlukan), versi metode berikutnya akan diberi namagrantPowerBeta2()
, dan seterusnya. Ketika pekerjaan selesai dan diselesaikan, metodegrantPower()
(tanpa akhiran) ditambahkan, dan metode BETan tidak digunakan lagi. APISemua beta APIs tetap berada di Perpustakaan Konstruksi hingga rilis versi utama berikutnya (3.0), dan tanda tangannya tidak akan berubah. Anda akan melihat peringatan penghentian jika Anda menggunakannya, jadi Anda harus pindah ke versi final secepat mungkin. API Namun, tidak ada rilis AWS CDK 2.x future yang akan merusak aplikasi Anda.
-
Construct
Kelas telah diekstraksi dari AWS CDK ke dalam perpustakaan terpisah, bersama dengan jenis terkait. Hal ini dilakukan untuk mendukung upaya penerapan Construct Programming Model ke domain lain. Jika Anda menulis konstruksi Anda sendiri atau menggunakan terkaitAPIs, Anda harus mendeklarasikanconstructs
modul sebagai ketergantungan dan membuat perubahan kecil pada impor Anda. Jika Anda menggunakan fitur-fitur canggih, seperti menghubungkan ke siklus hidup CDK aplikasi, lebih banyak perubahan mungkin diperlukan. Untuk detail selengkapnya, lihat RFC. -
Properti, metode, dan tipe yang tidak digunakan lagi di AWS CDK v1.x dan Perpustakaan Konstruksinya telah dihapus sepenuhnya dari v2. CDK API Dalam sebagian besar bahasa yang didukung, ini APIs menghasilkan peringatan di bawah v1.x, jadi Anda mungkin telah bermigrasi ke pengganti. APIs Daftar lengkap usang APIs
di CDK v1.x tersedia di. GitHub -
Perilaku yang dijaga oleh flag fitur di AWS CDK v1.x diaktifkan secara default di CDK v2. Bendera fitur sebelumnya tidak lagi diperlukan, dan dalam banyak kasus mereka tidak didukung. Beberapa masih tersedia untuk memungkinkan Anda kembali ke perilaku CDK v1 dalam keadaan yang sangat spesifik. Untuk informasi selengkapnya, lihat Memperbarui bendera fitur.
-
Dengan CDK v2, lingkungan yang Anda terapkan harus di-bootstrap menggunakan tumpukan bootstrap modern. Tumpukan bootstrap lama (default di bawah v1) tidak lagi didukung. CDKv2 selanjutnya membutuhkan versi baru dari tumpukan modern. Untuk meng-upgrade lingkungan yang ada, re-bootstrap mereka. Tidak perlu lagi mengatur flag fitur atau variabel lingkungan apa pun untuk menggunakan tumpukan bootstrap modern.
penting
Template bootstrap modern secara efektif memberikan izin yang tersirat oleh --cloudformation-execution-policies
ke AWS akun mana pun dalam daftar. --trust
Secara default, ini memperluas izin untuk membaca dan menulis ke sumber daya apa pun di akun bootstrap. Pastikan untuk mengonfigurasi tumpukan bootstrap dengan kebijakan dan akun tepercaya yang nyaman bagi Anda.
Prasyarat baru
Sebagian besar persyaratan untuk AWS CDK v2 sama dengan untuk AWS CDK v1.x. Persyaratan tambahan tercantum di sini.
-
Untuk TypeScript pengembang, TypeScript 3.8 atau yang lebih baru diperlukan.
-
Versi baru dari CDK Toolkit diperlukan untuk digunakan dengan CDK v2. Sekarang CDK v2 tersedia secara umum, v2 adalah versi default saat menginstal CDK Toolkit. Ini kompatibel dengan proyek CDK v1, jadi Anda tidak perlu menginstal versi sebelumnya kecuali Anda ingin membuat proyek v1. CDK Untuk meningkatkan, masalah
npm install -g aws-cdk
.
Upgrade dari AWS CDK v2 Developer Preview
Jika Anda menggunakan Pratinjau Pengembang CDK v2, Anda memiliki dependensi dalam proyek Anda pada versi Kandidat Rilis AWS CDK, seperti. 2.0.0-rc1
Perbarui ini ke2.0.0
, lalu perbarui modul yang diinstal di proyek Anda.
Setelah memperbarui dependensi Anda, masalah npm update -g aws-cdk
untuk memperbarui CDK Toolkit ke versi rilis.
Migrasi dari AWS CDK v1 ke v2 CDK
Untuk memigrasikan aplikasi Anda ke AWS CDK v2, perbarui flag fitur terlebih dahulu. cdk.json
Kemudian perbarui dependensi dan impor aplikasi Anda seperlunya untuk bahasa pemrograman yang ditulisnya.
Memperbarui ke v1 terbaru
Kami melihat sejumlah pelanggan meningkatkan dari versi lama AWS CDK v1 ke versi terbaru v2 dalam satu langkah. Meskipun tentu saja mungkin untuk melakukan itu, Anda berdua akan meningkatkan beberapa tahun perubahan (yang sayangnya mungkin tidak semua memiliki jumlah pengujian evolusi yang sama yang kita miliki saat ini), serta meningkatkan seluruh versi dengan default baru dan organisasi kode yang berbeda.
Untuk pengalaman upgrade yang paling aman dan untuk lebih mudah mendiagnosis sumber dari setiap perubahan yang tidak terduga, kami sarankan Anda memisahkan dua langkah tersebut: pertama upgrade ke versi v1 terbaru, kemudian beralih ke v2 sesudahnya.
Memperbarui bendera fitur
Hapus flag fitur v1 berikut dari cdk.json
jika ada, karena ini semua aktif secara default di AWS CDK v2. Jika efek lama mereka penting untuk infrastruktur Anda, Anda perlu membuat perubahan kode sumber. Lihat daftar bendera GitHub
-
@aws-cdk/core:enableStackNameDuplicates
-
aws-cdk:enableDiffNoFail
-
@aws-cdk/aws-ecr-assets:dockerIgnoreSupport
-
@aws-cdk/aws-secretsmanager:parseOwnedSecretName
-
@aws-cdk/aws-kms:defaultKeyPolicies
-
@aws-cdk/aws-s3:grantWriteWithoutAcl
-
@aws-cdk/aws-efs:defaultEncryptionAtRest
Beberapa flag fitur v1 dapat diatur untuk kembali ke false
perilaku AWS CDK v1 tertentu; lihat Kembali ke perilaku v1 atau daftar untuk referensi lengkap. GitHub
Untuk kedua jenis flag, gunakan cdk diff
perintah untuk memeriksa perubahan pada template yang disintesis untuk melihat apakah perubahan pada salah satu flag ini memengaruhi infrastruktur Anda.
CDKKompatibilitas Toolkit
CDKv2 membutuhkan v2 atau yang lebih baru dari CDK Toolkit. Versi ini kompatibel dengan CDK aplikasi v1. Oleh karena itu, Anda dapat menggunakan satu versi CDK Toolkit yang diinstal secara global dengan semua AWS CDK proyek Anda, apakah mereka menggunakan v1 atau v2. Pengecualian adalah bahwa CDK Toolkit v2 hanya membuat proyek CDK v2.
Jika Anda perlu membuat CDK proyek v1 dan v2, jangan instal CDK Toolkit v2 secara global. (Hapus jika Anda sudah menginstalnya:npm remove -g aws-cdk
.) Untuk memanggil CDK Toolkit, gunakan npx untuk menjalankan v1 atau v2 dari CDK Toolkit sesuai keinginan.
npx aws-cdk@1.x init app --language typescript npx aws-cdk@2.x init app --language typescript
Tip
Siapkan alias baris perintah sehingga Anda dapat menggunakan cdk1 perintah cdk dan untuk memanggil versi Toolkit yang diinginkan. CDK
Memperbarui dependensi dan impor
Perbarui dependensi aplikasi Anda, lalu instal paket baru. Terakhir, perbarui impor dalam kode Anda.
Menguji aplikasi yang dimigrasi sebelum menerapkan
Sebelum menerapkan tumpukan Anda, gunakan cdk diff
untuk memeriksa perubahan tak terduga pada sumber daya. Perubahan logis IDs (menyebabkan penggantian sumber daya) tidak diharapkan.
Perubahan yang diharapkan termasuk tetapi tidak terbatas pada:
-
Perubahan
CDKMetadata
sumber daya. -
Hash aset yang diperbarui.
-
Perubahan yang terkait dengan sintesis tumpukan gaya baru. Berlaku jika aplikasi Anda menggunakan synthesizer stack lama di v1. (CDKv2 tidak mendukung synthesizer tumpukan lama.)
-
Penambahan
CheckBootstrapVersion
aturan.
Perubahan tak terduga biasanya tidak disebabkan oleh peningkatan ke AWS CDK v2 itu sendiri. Biasanya, ini adalah hasil dari perilaku usang yang sebelumnya diubah oleh flag fitur. Ini adalah gejala peningkatan dari versi CDK lebih awal dari sekitar 1.85.x. Anda akan melihat perubahan yang sama ditingkatkan ke rilis v1.x terbaru. Anda biasanya dapat menyelesaikan ini dengan melakukan hal berikut:
-
Tingkatkan aplikasi Anda ke rilis v1.x terbaru
-
Hapus bendera fitur
-
Merevisi kode Anda seperlunya
-
Deploy
-
Tingkatkan ke v2
Saat Anda siap untuk menerapkan tumpukan di aplikasi Anda, pertimbangkan untuk menerapkan salinan terlebih dahulu sehingga Anda dapat mengujinya. Cara termudah untuk melakukannya adalah dengan menyebarkannya ke Wilayah yang berbeda. Namun, Anda juga dapat mengubah IDs tumpukan Anda. Setelah pengujian, pastikan untuk menghancurkan salinan pengujian dengancdk destroy.
Pemecahan Masalah
TypeScript 'from' expected
atau ';' expected
kesalahan dalam impor
Upgrade ke TypeScript 3.8 atau yang lebih baru.
Jalankan 'cdk bootstrap'
Jika Anda melihat kesalahan seperti berikut:
❌ MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html) at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13) at processTicksAndRejections (internal/process/task_queues.js:97:5) MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
AWS CDK v2 membutuhkan tumpukan bootstrap yang diperbarui, dan selanjutnya, semua penerapan v2 memerlukan sumber daya bootstrap. (Dengan v1, Anda dapat menerapkan tumpukan sederhana tanpa bootstrap.) Untuk detail lengkap, lihat AWS CDK bootstrap.
Menemukan tumpukan v1
Saat memigrasikan CDK aplikasi Anda dari v1 ke v2, Anda mungkin ingin mengidentifikasi AWS CloudFormation tumpukan yang diterapkan yang dibuat menggunakan v1. Untuk melakukan ini, jalankan perintah berikut:
npx awscdk-v1-stack-finder
Untuk detail penggunaan, lihat README