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.
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 Anda tidak perlu menyinkronkan versi berbagai paket pustaka CDK.Konstruksi L1 (CFNXXxx), yang mewakili sumber daya 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 saat API ditetapkan 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 API diselesaikan, metodegrantPower()
(tanpa akhiran) ditambahkan, dan metode BETan tidak digunakan lagi.Semua 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 API secepatnya. 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 terkait APIs, Anda harus mendeklarasikanconstructs
modul sebagai ketergantungan dan membuat perubahan kecil pada impor Anda. Jika Anda menggunakan fitur-fitur canggih, seperti menghubungkan ke siklus hidup aplikasi CDK, 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 CDK v2 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 di
CDK APIs 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. CDK v2 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 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 CDK v1. Untuk meningkatkan, masalah
npm install -g aws-cdk
.
Memutakhirkan dari AWS CDK Pratinjau Pengembang v2
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.
npm install
atau yarn install
Setelah memperbarui dependensi Anda, masalah npm update -g aws-cdk
untuk memperbarui CDK Toolkit ke versi rilis.
Migrasi dari AWS CDK v1 ke CDK v2
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.
Kompatibilitas CDK Toolkit
CDK v2 membutuhkan v2 atau yang lebih baru dari CDK Toolkit. Versi ini kompatibel dengan aplikasi CDK 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 proyek CDK v1 dan v2, jangan instal CDK Toolkit v2 secara global. (Hapus jika Anda sudah menginstalnya:npm remove -g aws-cdk
.) Untuk menjalankan 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
Memperbarui dependensi dan impor
Perbarui dependensi aplikasi Anda, lalu instal paket baru. Terakhir, perbarui impor dalam kode Anda.
Aplikasi
Untuk aplikasi CDK, perbarui package.json
sebagai berikut. Hapus dependensi pada modul stabil individual bergaya v1 dan buat versi terendah yang aws-cdk-lib
Anda perlukan untuk aplikasi Anda (2.0.0 di sini).
Konstruksi eksperimental disediakan dalam paket terpisah, berversi independen dengan nama yang diakhiri alpha
dan nomor versi alfa. Nomor versi alfa sesuai aws-cdk-lib
dengan rilis pertama yang kompatibel. Di sini, kami telah menyematkan aws-codestar
ke v2.0.0-alpha.1.
{
"dependencies": {
"aws-cdk-lib": "^2.0.0",
"@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
"constructs": "^10.0.0"
}
}
Membangun perpustakaan
Untuk membangun pustaka, buat versi terendah yang aws-cdk-lib
Anda perlukan untuk aplikasi Anda (2.0.0 di sini) dan perbarui sebagai berikut. package.json
Perhatikan yang aws-cdk-lib
muncul baik sebagai ketergantungan rekan dan ketergantungan dev.
{
"peerDependencies": {
"aws-cdk-lib": "^2.0.0",
"constructs": "^10.0.0"
},
"devDependencies": {
"aws-cdk-lib": "^2.0.0",
"constructs": "^10.0.0",
"typescript": "~3.9.0"
}
}
catatan
Anda harus melakukan bump versi utama pada nomor versi perpustakaan Anda saat merilis pustaka yang kompatibel dengan v2, karena ini adalah perubahan besar bagi konsumen perpustakaan. Tidak mungkin mendukung CDK v1 dan v2 dengan satu pustaka. Untuk terus mendukung pelanggan yang masih menggunakan v1, Anda dapat mempertahankan rilis sebelumnya secara paralel, atau membuat paket baru untuk v2.
Terserah Anda berapa lama Anda ingin terus mendukung pelanggan AWS CDK v1. Anda mungkin mengambil isyarat dari siklus hidup CDK v1 itu sendiri, yang memasuki pemeliharaan pada 1 Juni 2022 dan akan mencapai end-of-life pada 1 Juni 2023. Untuk detail selengkapnya, lihat Kebijakan AWS CDK
Pemeliharaan
Pustaka dan aplikasi
Instal dependensi baru dengan menjalankan npm install
atau. yarn install
Ubah impor Anda untuk mengimpor Construct
dari constructs
modul baru, tipe inti seperti App
dan Stack
dari tingkat atasaws-cdk-lib
, dan modul Construct Library yang stabil untuk layanan yang Anda gunakan dari ruang nama di bawah. aws-cdk-lib
import { Construct } from 'constructs';
import { App, Stack } from 'aws-cdk-lib'; // core constructs
import { aws_s3 as s3 } from 'aws-cdk-lib'; // stable module
import * as codestar from '@aws-cdk/aws-codestar-alpha'; // experimental module
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.
-
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 aplikasi CDK 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 awscdk-v1-stack-finder README.