Migrasi dari AWS CDK v1 ke v2 AWS CDK - AWS Cloud Development Kit (AWS CDK) v2

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 dengan alpha 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 ke aws-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 ke aws-cdk-lib ketika kita merasa bahwa konstruksi baru memenuhi kebutuhan mendasar pelanggan.

    Setelah modul ditetapkan stabil dan dimasukkan ke dalamaws-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 oleh Beta2Beta3,, 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, metode grantPower() (tanpa akhiran) ditambahkan, dan metode BETan tidak digunakan lagi. API

    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 secepat mungkin. API Namun, tidak ada rilis AWS CDK 2.x future yang akan merusak aplikasi Anda.

  • ConstructKelas 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 mendeklarasikan constructs 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, masalahnpm 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.

TypeScript

npm install atau yarn install

JavaScript

npm install atau yarn install

Python
python -m pip install -r requirements.txt
Java
mvn package
C#
dotnet restore
Go
go get

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 untuk informasi selengkapnya.

  • @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

macOS/Linux
alias cdk1="npx aws-cdk@1.x" alias cdk="npx aws-cdk@2.x"
Windows
doskey cdk1=npx aws-cdk@1.x $* doskey cdk=npx aws-cdk@2.x $*

Memperbarui dependensi dan impor

Perbarui dependensi aplikasi Anda, lalu instal paket baru. Terakhir, perbarui impor dalam kode Anda.

TypeScript
Aplikasi

Untuk CDK aplikasi, 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 perpustakaan. 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
JavaScript

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" } }

Instal dependensi baru dengan menjalankan npm install atau. yarn install

Ubah impor aplikasi Anda untuk melakukan hal berikut:

  • Impor Construct dari constructs modul baru

  • Impor jenis intiStack, seperti App dan, dari tingkat atas aws-cdk-lib

  • Impor modul AWS Construct Library dari ruang nama di bawah aws-cdk-lib

const { Construct } = require('constructs'); const { App, Stack } = require('aws-cdk-lib'); // core constructs const s3 = require('aws-cdk-lib').aws_s3; // stable module const codestar = require('@aws-cdk/aws-codestar-alpha'); // experimental module
Python

Perbarui requirements.txt atau install_requires definisi setup.py sebagai berikut. Hapus dependensi pada modul stabil individual bergaya v1.

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.0alpha1.

install_requires=[ "aws-cdk-lib>=2.0.0", "constructs>=10.0.0", "aws-cdk.aws-codestar-alpha>=2.0.0alpha1", # ... ],
Tip

Copot pemasangan versi AWS CDK modul lain yang sudah diinstal di lingkungan virtual aplikasi Anda menggunakanpip uninstall. Kemudian Instal dependensi baru dengan. python -m pip install -r requirements.txt

Ubah impor aplikasi Anda untuk melakukan hal berikut:

  • Impor Construct dari constructs modul baru

  • Impor jenis intiStack, seperti App dan, dari tingkat atas aws_cdk

  • Impor modul AWS Construct Library dari ruang nama di bawah aws_cdk

from constructs import Construct from aws_cdk import App, Stack # core constructs from aws_cdk import aws_s3 as s3 # stable module import aws_cdk.aws_codestar_alpha as codestar # experimental module # ... class MyConstruct(Construct): # ... class MyStack(Stack): # ... s3.Bucket(...)
Java

Dipom.xml, hapus semua software.amazon.awscdk dependensi untuk modul stabil dan ganti dengan dependensi pada software.constructs (for) dan. Construct software.amazon.awscdk

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.

<dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>aws-cdk-lib</artifactId> <version>2.0.0</version> </dependency><dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>code-star-alpha</artifactId> <version>2.0.0-alpha.1</version> </dependency> <dependency> <groupId>software.constructs</groupId> <artifactId>constructs</artifactId> <version>10.0.0</version> </dependency>

Instal dependensi baru dengan menjalankan. mvn package

Ubah kode Anda untuk melakukan hal berikut:

  • Impor Construct dari software.constructs pustaka baru

  • Impor kelas inti, seperti Stack danApp, dari software.amazon.awscdk

  • Impor konstruksi layanan dari software.amazon.awscdk.services

import software.constructs.Construct; import software.amazon.awscdk.Stack; import software.amazon.awscdk.StackProps; import software.amazon.awscdk.App; import software.amazon.awscdk.services.s3.Bucket; import software.amazon.awscdk.services.codestar.alpha.GitHubRepository;
C#

Cara paling mudah untuk meningkatkan dependensi CDK aplikasi C# adalah dengan mengedit file secara manual. .csproj Hapus semua referensi Amazon.CDK.* paket stabil dan ganti dengan referensi ke Constructs paket Amazon.CDK.Lib dan.

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.

<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0" /> <PackageReference Include="Amazon.CDK.AWS.Codestar.Alpha" Version="2.0.0-alpha.1" /> <PackageReference Include="Constructs" Version="10.0.0" />

Instal dependensi baru dengan menjalankan. dotnet restore

Ubah impor di file sumber Anda sebagai berikut.

using Constructs; // for Construct class using Amazon.CDK; // for core classes like App and Stack using Amazon.CDK.AWS.S3; // for stable constructs like Bucket using Amazon.CDK.Codestar.Alpha; // for experimental constructs
Go

Masalah go get untuk memperbarui dependensi Anda ke versi terbaru dan memperbarui file proyek Anda. .mod

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:

  1. Tingkatkan aplikasi Anda ke rilis v1.x terbaru

  2. Hapus bendera fitur

  3. Merevisi kode Anda seperlunya

  4. Deploy

  5. 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' expectedatau ';' 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 READMEawscdk-v1-stack-finder.