Alibaba Cloud CLI:Migrasi dari CLI Alibaba Cloud versi lama ke versi berbasis plugin

Contoh perbandingan

Menggunakan API DescribeRegions sebagai contoh, perintah berbasis plugin adalah:

aliyun ecs describe-regions --accept-language zh-CN

Perintah lama adalah:

aliyun ecs DescribeRegions --AcceptLanguage zh-CN

Dalam contoh ini, satu-satunya perbedaan adalah konvensi penamaan. Namun, untuk perintah yang lebih kompleks, versi berbasis plugin mungkin sepenuhnya mendesain ulang nama parameternya. Misalnya, beberapa perintah menggunakan --biz-region-id alih-alih --region-id, yang bukan sekadar konversi huruf dari --RegionId versi lama. Saat melakukan migrasi, selalu periksa nama parameter yang benar dengan menjalankan <command> --help atau mencari di OpenAPI Explorer.

Perbedaan utama

Jalankan perintah berikut untuk memeriksa nomor versi Anda. Jika versinya 3.3.0 atau lebih baru, CLI Anda mendukung perintah berbasis plugin. Jika versinya sebelum 3.3.0, Anda harus meningkatkan CLI terlebih dahulu.

aliyun version

Untuk memeriksa apakah perintah tertentu menggunakan versi berbasis plugin atau versi lama, jalankan aliyun <command> <sub-command> --help:

• Versi berbasis plugin: Output bantuan mencakup bagian parameter global, dan nama parameter biasanya menggunakan gaya kebab-case (misalnya, --region-id).

• Versi lama: Output bantuan hanya mencakup bagian parameter, dan nama parameter biasanya menggunakan gaya PascalCase (misalnya, --RegionId).

Cari menggunakan OpenAPI Explorer

Saat Anda mengetahui nama perintah lama (yang merupakan nama tindakan API), ini adalah pendekatan paling langsung:

1. Buka OpenAPI Explorer.

2. Di kotak pencarian, masukkan nama perintah lama (misalnya, DescribeInstances). Hasil pencarian akan menampilkan daftar API yang sesuai.

3. Klik API target untuk membuka halaman detailnya, isi nilai parameter yang diperlukan, lalu beralih ke tab CLI Example di sebelah kanan.

4. Perintah berbasis plugin ditampilkan di bawah CLI Style (New), sedangkan perintah lama ditampilkan di bawah API Native Style (Old). Salin perintah baru untuk menggantikan perintah lama di skrip Anda.

Jelajahi halaman utama CLI

Halaman utama CLI di OpenAPI Explorer mencantumkan semua perintah berbasis plugin yang didukung, dikelompokkan berdasarkan layanan cloud, lengkap dengan deskripsi parameternya.

Temukan perintah dengan --help

Setelah menginstal plugin layanan cloud, gunakan --help di setiap tingkat untuk menjelajahi perintah dan parameter yang tersedia. Misalnya, untuk melihat semua perintah plugin ECS:

aliyun ecs --help

Untuk melihat penggunaan dan parameter perintah tertentu:

aliyun ecs describe-instances --help

Kueri menggunakan CLI Skills

Kunjungi CLI Skills, instal skill tersebut, lalu jelaskan kebutuhan Anda dalam bahasa alami melalui agen untuk mendapatkan perintah berbasis plugin yang sesuai.

Langkah 1: Tingkatkan CLI

Periksa versi saat ini:

aliyun version

Jika versinya sebelum 3.3.0, lihat Instal dan perbarui Alibaba Cloud CLI untuk melakukan peningkatan. Anda tidak perlu menguninstal versi lama—konfigurasi kredensial yang ada (~/.aliyun/config.json) tidak terpengaruh.

Setelah ditingkatkan, perintah lama tetap berfungsi dan skrip yang ada tidak terpengaruh. Dukungan fitur baru, pembaruan, dan perbaikan keamanan hanya tersedia di versi berbasis plugin.

Langkah 2: Instal plugin

Instal plugin layanan cloud yang Anda butuhkan:

# Instal satu plugin
aliyun plugin install --name ecs

# Instal beberapa plugin
aliyun plugin install --names ecs oss vpc

Atau, aktifkan instalasi otomatis melalui variabel lingkungan. Saat Anda menjalankan perintah berbasis plugin yang plugin-nya belum terinstal, CLI akan mengunduh dan menginstalnya secara otomatis:

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Langkah 3: Verifikasi perintah

Jalankan perintah berbasis plugin untuk memverifikasi bahwa semuanya berfungsi:

aliyun ecs describe-regions

Daftar JSON wilayah dalam output mengonfirmasi bahwa CLI berbasis plugin berfungsi dengan benar.

Langkah 4: Perbarui skrip Anda

Gantilah secara bertahap perintah lama di skrip Anda dengan sintaks berbasis plugin:

1. Identifikasi perintah lama di skrip Anda. Ciri umumnya adalah argumen kedua menggunakan PascalCase (misalnya, aliyun ecs DescribeInstances).

2. Cari nama perintah lama di OpenAPI Explorer untuk menemukan padanan berbasis plugin-nya.

3. Ganti perintah lama dengan padanan berbasis plugin, dan perbarui nama parameter yang sesuai.

4. Uji skrip yang telah diperbarui.

Perintah lama tetap berfungsi di versi baru, sehingga Anda dapat melakukan migrasi secara bertahap berdasarkan prioritas.

Pipeline CI/CD

Di lingkungan non-interaktif, CLI tidak akan menampilkan prompt untuk instalasi plugin. Tangani hal ini dengan salah satu cara berikut:

• Pra-instal plugin di skrip pipeline Anda:

  aliyun plugin install --names ecs oss vpc

• Atau, atur variabel lingkungan untuk mengaktifkan instalasi otomatis:

  export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Kami menyarankan menambahkan variabel lingkungan tersebut ke konfigurasi lingkungan global pipeline Anda (seperti blok environment di Jenkinsfile atau bagian env di GitHub Actions) agar berlaku untuk setiap build.

Skrip penguraian output

Output JSON dari perintah berbasis plugin mungkin berbeda dari versi lama. CLI lama mengembalikan tanggapan API mentah, sedangkan versi berbasis plugin mungkin memproses output tersebut. Jika skrip Anda menggunakan jq, grep, atau alat lain untuk mengurai output CLI, verifikasi format output setelah mengganti perintah.

Migrasi perintah kompleks

Perintah dengan parameter kompleks merupakan skenario paling rawan kesalahan selama migrasi.

aliyun slb AddBackendServers \
  --LoadBalancerId lb-xxx \
  --BackendServers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun slb add-backend-servers \
  --load-balancer-id lb-xxx \
  --backend-servers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun ecs run-instances \
  --region cn-hangzhou \
  --instance-type ecs.g7.large \
  --image-id ubuntu_22_04_x64_20G_alibase_20230China.vhd \
  --security-group-id sg-xxx \
  --vswitch-id vsw-xxx \
  --system-disk "$(cat <<'EOF'
{"Size":40,"Category":"cloud_essd","PerformanceLevel":"PL1"}
EOF
)"

aliyun ecs DescribeInstances --RegionId cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

# Versi berbasis plugin: pertama, periksa struktur output, lalu sesuaikan ekspresi jq.
aliyun ecs describe-instances --region cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

Menampilkan bantuan versi lama

Setelah menginstal plugin produk, aliyun <command> --help secara default menampilkan bantuan plugin. Untuk sementara waktu melihat bantuan versi lama, atur variabel lingkungan berikut:

export ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true

Apakah saya masih bisa menggunakan perintah PascalCase versi lama setelah peningkatan?

Ya. CLI versi 3.3.0 dan lebih baru kompatibel secara mundur. Namun, kami merekomendasikan peningkatan ke versi terbaru untuk mendapatkan dukungan terkini.

Apakah saya perlu mengonfigurasi ulang kredensial setelah migrasi?

Tidak. CLI berbasis plugin menggunakan konfigurasi kredensial yang sama (~/.aliyun/config.json) seperti versi lama. Semua entri profile yang telah dikonfigurasi dan kredensial variabel lingkungan tetap berfungsi setelah peningkatan.

Apakah saya bisa mencampur perintah lama dan berbasis plugin dalam skrip yang sama?

Ya. Kedua gaya perintah dapat digunakan bersama dalam skrip yang sama. Kami merekomendasikan mengganti perintah lama secara bertahap berdasarkan prioritas.

Apa yang harus dilakukan jika instalasi plugin gagal?

Lakukan pemecahan masalah dalam urutan berikut:

1. Periksa apakah jaringan Anda dapat mengakses aliyuncli.alicdn.com.

2. Verifikasi bahwa direktori instalasi plugin (~/.aliyun/plugins/) memiliki izin tulis.

3. Pastikan versi CLI Anda adalah 3.3.0 atau lebih baru (versi sebelumnya tidak mendukung plugin). Jalankan aliyun version untuk memeriksa.