Tentang target kustom

Dokumen ini menjelaskan cara kerja target kustom di Cloud Deploy.

Cloud Deploy menyertakan dukungan bawaan untuk berbagai lingkungan runtime sebagai target. Namun, daftar jenis target yang didukung bersifat terbatas. Dengan target kustom, Anda dapat men-deploy ke sistem lain selain runtime yang didukung.

Target kustom adalah target yang merepresentasikan lingkungan output arbitrer selain runtime yang didukung Cloud Deploy.

Halaman Membuat target kustom menjelaskan proses menentukan jenis target kustom dan menerapkannya sebagai target dalam pipeline penayangan.

Apa yang termasuk dalam target kustom?

Setiap target kustom terdiri dari komponen berikut:

• Tindakan kustom, ditetapkan di skaffold.yaml

  Hal ini mirip dengan cara Anda menentukan hook deployment. Dalam file skaffold.yaml, Anda menentukan customActions, dengan setiap tindakan kustom mengidentifikasi image container yang akan digunakan, dan perintah yang akan dijalankan di container tersebut.

  Dengan cara ini, target kustom hanyalah tindakan atau serangkaian tindakan yang ditentukan secara kustom.

  Untuk jenis target kustom apa pun, Anda mengonfigurasi tindakan rendering kustom dan tindakan deployment kustom. Tindakan ini menggunakan nilai yang disediakan oleh Cloud Deploy dan harus memenuhi serangkaian output yang diperlukan.

  Tindakan render kustom bersifat opsional, tetapi Anda harus membuatnya kecuali target kustom Anda akan berfungsi dengan benar jika dirender oleh skaffold render, yang merupakan default untuk Cloud Deploy.

• Definisi jenis target kustom

  CustomTargetType adalah resource Cloud Deploy yang mengidentifikasi tindakan kustom (ditetapkan secara terpisah di skaffold.yaml) yang digunakan target jenis ini untuk aktivitas rendering rilis dan deployment peluncuran.

• Definisi target

  Definisi target untuk target kustom sama dengan jenis target lainnya, kecuali mencakup properti customTarget, yang nilainya adalah nama CustomTargetType.

Dengan adanya komponen tersebut, Anda dapat menggunakan target seperti target lainnya, merujuknya dari progres pipeline pengiriman, dan memanfaatkan sepenuhnya fitur Cloud Deploy, seperti promosi dan persetujuan, serta rollback.

Misalnya

Panduan memulai Tentukan dan gunakan jenis target kustom membuat jenis target kustom yang mencakup perintah sederhana untuk dijalankan pada image penampung—satu perintah untuk render dan satu untuk deployment. Perintah, dalam hal ini, hanya menambahkan teks ke file output yang diperlukan untuk merender dan men-deploy.

Untuk contoh lainnya, lihat Contoh target kustom.

Input dan output yang diperlukan

Jenis target kustom yang ditentukan untuk Cloud Deploy harus memenuhi persyaratan input dan output, baik untuk rendering maupun deployment. Bagian ini mencantumkan input dan output yang diperlukan, serta cara penyediaannya.

Cloud Deploy menyediakan input yang diperlukan, baik untuk rendering maupun deployment, sebagai variabel lingkungan. Bagian berikut mencantumkan input ini, serta output yang harus ditampilkan oleh tindakan render dan deployment kustom Anda.

Men-deploy parameter sebagai variabel lingkungan

Selain variabel lingkungan yang tercantum di bagian ini, Cloud Deploy dapat meneruskan parameter deployment yang telah Anda tetapkan ke container kustom Anda.

Pelajari lebih lanjut.

Input untuk merender tindakan

Untuk tindakan render kustom, Cloud Deploy menyediakan input berikut sebagai variabel lingkungan. Untuk peluncuran multi-fase (deployment canary), Cloud Deploy menyediakan variabel ini untuk setiap fase.

• CLOUD_DEPLOY_PROJECT

  Nomor project Google Cloud untuk project tempat target kustom dibuat.

• CLOUD_DEPLOY_PROJECT_ID

  ID project Google Cloud untuk project.

• CLOUD_DEPLOY_LOCATION

  Google Cloud Wilayah untuk jenis target kustom.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  Nama pipeline pengiriman Cloud Deploy yang mereferensikan jenis target kustom.

• CLOUD_DEPLOY_RELEASE

  Nama rilis yang operasi renderingnya dipanggil.

• CLOUD_DEPLOY_TARGET

  Nama target Cloud Deploy yang menggunakan jenis target kustom.

• CLOUD_DEPLOY_PHASE

  Fase peluncuran yang sesuai dengan rendering.

• CLOUD_DEPLOY_REQUEST_TYPE

  Untuk tindakan rendering kustom, ini selalu RENDER.

• CLOUD_DEPLOY_FEATURES

  Daftar fitur Cloud Deploy yang dipisahkan koma yang harus didukung oleh penampung kustom. Variabel ini diisi berdasarkan fitur yang dikonfigurasi di pipeline pengiriman Anda.

  Jika penerapan Anda tidak mendukung fitur dalam daftar ini, sebaiknya penerapan tersebut gagal selama rendering.

  Untuk deployment standar, kolom ini kosong. Untuk deployment uji coba, nilainya adalah CANARY. Jika nilai yang diberikan oleh Cloud Deploy adalah CANARY, tindakan rendering Anda akan dipanggil untuk setiap fase dalam canary. Persentase canary untuk setiap fase disediakan dalam variabel lingkungan CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  Persentase deployment yang terkait dengan operasi rendering ini. Jika variabel lingkungan CLOUD_DEPLOY_FEATURES disetel ke CANARY, tindakan render kustom Anda dipanggil untuk setiap fase, dan variabel ini disetel ke persentase canary untuk setiap fase. Untuk deployment standar dan untuk deployment canary yang telah mencapai fase stable, ini adalah 100.

• CLOUD_DEPLOY_STORAGE_TYPE

  Penyedia penyimpanan. Selalu GCS.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  Jalur Cloud Storage untuk arsip file render yang ditulis saat rilis dibuat.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  Jalur Cloud Storage tempat container render kustom diharapkan mengupload artefak yang akan digunakan untuk deployment. Perhatikan bahwa tindakan render harus mengupload file bernama results.json yang berisi hasil operasi render ini. Untuk mengetahui informasi selengkapnya, lihat Output dari tindakan render.

Output dari tindakan render

Tindakan rendering kustom Anda harus memberikan informasi yang dijelaskan di bagian ini. Informasi ini harus disertakan dalam file hasil, yang diberi nama results.json, yang berada di bucket Cloud Storage yang disediakan oleh Cloud Deploy.

• File konfigurasi yang dirender

• File results.json, yang berisi informasi berikut:

  • Indikasi status berhasil atau gagal dari tindakan kustom.

    Nilai yang valid adalah SUCCEEDED dan FAILED.

  • (Opsional) pesan error yang dihasilkan oleh tindakan kustom.

  • Jalur Cloud Storage untuk file konfigurasi atau file yang dirender.

    Jalur untuk semua file konfigurasi yang dirender adalah URI lengkap. Anda mengisinya sebagian menggunakan nilai yang diberikan oleh Cloud Deploy CLOUD_DEPLOY_OUTPUT_GCS_PATH.

    Anda harus memberikan file konfigurasi yang dirender, meskipun kosong. Isi file dapat berupa apa saja, dalam format apa pun, asalkan dapat digunakan oleh tindakan deployment kustom Anda. Sebaiknya file ini dapat dibaca oleh manusia, sehingga Anda dan pengguna lain di organisasi Anda dapat melihat file ini di pemeriksa rilis.

  • (Opsional) peta metadata yang ingin Anda sertakan

    Target kustom Anda membuat metadata ini. Metadata ini disimpan di rilis, di kolom custom_metadata.

Jika perlu memeriksa file results.json, misalnya untuk proses debug, Anda dapat menemukan Cloud Storage URI-nya di log Cloud Build.

Contoh file hasil render

Berikut adalah contoh output file results.json dari tindakan render kustom:

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Input untuk men-deploy tindakan

Untuk tindakan deployment kustom, Cloud Deploy menyediakan input berikut, sebagai variabel lingkungan:

• CLOUD_DEPLOY_PROJECT

  Nomor project Google Cloud untuk project tempat target kustom dibuat.

• CLOUD_DEPLOY_PROJECT_ID

  ID project Google Cloud untuk project.

• CLOUD_DEPLOY_LOCATION

  Google Cloud Wilayah untuk jenis target kustom.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  Nama pipeline pengiriman Cloud Deploy yang mereferensikan target yang menggunakan jenis target kustom.

• CLOUD_DEPLOY_RELEASE

  Nama rilis yang operasi deployment-nya dipanggil.

• CLOUD_DEPLOY_ROLLOUT

  Nama peluncuran Cloud Deploy yang menjadi tujuan deployment ini.

• CLOUD_DEPLOY_TARGET

  Nama target Cloud Deploy yang menggunakan jenis target kustom.

• CLOUD_DEPLOY_PHASE

  Fase peluncuran yang sesuai dengan deployment.

• CLOUD_DEPLOY_REQUEST_TYPE

  Untuk tindakan deployment kustom, nilai ini selalu DEPLOY.

• CLOUD_DEPLOY_FEATURES

  Daftar fitur Cloud Deploy yang dipisahkan koma yang harus didukung oleh penampung kustom. Variabel ini diisi berdasarkan fitur yang dikonfigurasi di pipeline pengiriman Anda.

  Jika penerapan Anda tidak mendukung fitur dalam daftar ini, sebaiknya penerapan tersebut gagal selama rendering.

  Untuk deployment standar, kolom ini kosong. Untuk deployment uji coba, nilainya adalah CANARY. Jika nilai yang diberikan oleh Cloud Deploy adalah CANARY, tindakan rendering Anda akan dipanggil untuk setiap fase dalam canary. Persentase canary untuk setiap fase disediakan dalam variabel lingkungan CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  Persentase deployment yang terkait dengan operasi deployment ini. Jika variabel lingkungan CLOUD_DEPLOY_FEATURES disetel ke CANARY, tindakan deployment kustom Anda dipanggil untuk setiap fase, dan variabel ini disetel ke persentase canary untuk setiap fase. Tindakan deployment Anda harus dijalankan untuk setiap fase.

• CLOUD_DEPLOY_STORAGE_TYPE

  Penyedia penyimpanan. Selalu GCS.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  Jalur Cloud Storage tempat perender kustom menulis file konfigurasi yang dirender.

• CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

  Jalur Cloud Storage ke konfigurasi Skaffold yang dirender.

• CLOUD_DEPLOY_MANIFEST_GCS_PATH

  Jalur Cloud Storage ke file manifes yang dirender.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  Jalur ke direktori Cloud Storage tempat container deployment kustom diharapkan mengupload artefak deployment. Untuk mengetahui informasi selengkapnya, lihat Output dari tindakan deployment.

Output dari tindakan deployment

Tindakan deployment kustom Anda harus menulis file output results.json. File ini harus berada di bucket Cloud Storage yang disediakan oleh Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

File harus menyertakan hal berikut:

• Indikasi status berhasil atau gagal dari tindakan deployment kustom.

  Berikut adalah status yang valid:

  • SUCCEEDED

  • FAILED

  • SKIPPED

  Ini untuk deployment canary di mana fase canary dilewati, untuk langsung menuju stable.

• (Opsional) daftar file artefak deployment, dalam bentuk jalur Cloud Storage

  Jalur adalah URI lengkap. Anda mengisinya sebagian menggunakan nilai CLOUD_DEPLOY_OUTPUT_GCS_PATH yang diberikan oleh Cloud Deploy.

  File yang tercantum di sini diisi di resource run tugas sebagai artefak deployment.

• (Opsional) pesan kegagalan, jika tindakan deployment kustom tidak berhasil (menampilkan status FAILED)

  Pesan ini digunakan untuk mengisi failure_message pada job run untuk tindakan deployment ini.

• (Opsional) pesan lewati, untuk memberikan informasi tambahan jika tindakan menampilkan status SKIPPED.

• (Opsional) peta metadata yang ingin Anda sertakan

  Target kustom Anda membuat metadata ini. Metadata ini disimpan di jalankan tugas dan di peluncuran, di kolom custom_metadata.

Jika perlu memeriksa file results.json, misalnya untuk proses debug, Anda dapat menemukan Cloud Storage URI untuk file tersebut di log rendering rilis Cloud Build.

Contoh file hasil deployment

Berikut adalah contoh output file results.json dari tindakan deployment kustom:

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Informasi lebih lanjut tentang tindakan kustom

Berikut beberapa hal yang perlu diingat saat menyiapkan dan menggunakan jenis target kustom.

Menjalankan tindakan kustom

Tindakan rendering dan deployment kustom Anda berjalan di lingkungan eksekusi Cloud Deploy. Anda tidak dapat mengonfigurasi tindakan kustom untuk dijalankan di cluster Google Kubernetes Engine.

Menggunakan konfigurasi Skaffold jarak jauh yang dapat digunakan kembali

Seperti yang dijelaskan dalam dokumen ini, Anda mengonfigurasi tindakan kustom di file skaffold.yaml yang diberikan saat pembuatan rilis. Namun, Anda juga dapat menyimpan konfigurasi Skaffold di repositori Git atau di bucket Cloud Storage dan mereferensikannya dari definisi jenis target kustom Anda. Dengan begitu, Anda dapat menggunakan tindakan kustom yang ditentukan dan disimpan di satu lokasi bersama, bukan menyertakan tindakan kustom dengan file skaffold.yaml setiap rilis.

Target kustom dan strategi deployment

Target kustom didukung sepenuhnya untuk deployment standar.

Cloud Deploy mendukung deployment canary selama renderer dan deployer kustom mendukung fitur canary.

Anda harus menggunakan konfigurasi canary kustom. Canary otomatis dan otomatis kustom tidak didukung dengan target kustom.

Target kustom dan parameter deployment

Anda dapat menggunakan parameter deployment dengan target kustom. Anda dapat menyetelnya di tahap pipeline penayangan, di target yang menggunakan jenis target kustom, atau di rilis.

Parameter deployment diteruskan ke container render dan deployment kustom Anda, sebagai variabel lingkungan, selain parameter yang sudah diberikan.

Contoh target kustom

Repositori cloud-deploy-samples berisi serangkaian contoh penerapan target kustom. Contoh berikut tersedia:

• GitOps

• Vertex AI

• Terraform

• Infrastructure Manager

• Helm

Setiap contoh mencakup panduan memulai cepat.

Contoh ini bukan produk yang didukung Google Cloud , dan tidak tercakup dalam kontrak dukungan Google Cloud . Untuk melaporkan bug atau meminta fitur di produk, hubungi dukungan. Google Cloud Google Cloud

Langkah berikutnya

• Setelah Anda mengetahui target kustom, cari tahu cara mengonfigurasi dan menggunakannya.

• Coba panduan memulai: Menentukan dan menggunakan jenis target kustom.

• Pelajari lebih lanjut cara mengonfigurasi target Cloud Deploy.

• Pelajari lingkungan eksekusi Cloud Deploy.