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:

  • Tugas, yang menentukan cara merender dan men-deploy untuk jenis target kustom Anda

    Penerapan render kustom dan deployment kustom Anda menggunakan nilai yang disediakan oleh Cloud Deploy dan harus memenuhi kumpulan output yang diperlukan.

    Render kustom bersifat opsional, tetapi Anda harus membuatnya kecuali jika target kustom Anda akan berfungsi dengan benar jika dirender dengan perender bawaan Cloud Deploy.

  • Definisi jenis target kustom

    CustomTargetType adalah resource Cloud Deploy yang mengidentifikasi tugas 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.

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

Misalnya

Panduan memulai Menentukan dan menggunakan jenis target kustom membuat jenis target kustom yang menyertakan perintah untuk dijalankan pada image penampung—satu perintah untuk merender dan satu untuk men-deploy. Perintah, dalam hal ini, hanya menambahkan teks ke file output yang diperlukan untuk rendering dan deployment.

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 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 render kustom

Untuk 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

    Project ID Google Cloud untuk project.

  • CLOUD_DEPLOY_LOCATION

    Region Google Cloud 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 rendering kustom, nilai 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, 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, 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, nilainya 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 render harus mengupload file bernama results.json yang berisi hasil operasi render ini. Untuk mengetahui informasi selengkapnya, lihat Output dari render kustom.

Output dari render kustom

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

  • File konfigurasi yang dirender

  • File results.json, yang berisi informasi berikut:

    • Indikasi status berhasil atau gagalnya render kustom.

      Nilai yang valid adalah SUCCEEDED dan FAILED.

    • (Opsional) pesan error yang dihasilkan oleh render 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 CLOUD_DEPLOY_OUTPUT_GCS_PATH yang diberikan oleh Cloud Deploy.

      Anda harus memberikan file konfigurasi yang dirender, meskipun kosong. Isi file dapat berupa apa saja, dalam format apa pun, asalkan dapat digunakan oleh 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 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 deployment kustom

Untuk 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

    Project ID Google Cloud untuk project.

  • CLOUD_DEPLOY_LOCATION

    Region Google Cloud 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 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, deployment 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, deployment kustom Anda dipanggil untuk setiap fase, dan variabel ini disetel ke persentase canary untuk setiap fase. Deployment Anda harus berjalan 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. Jika Anda memberikan konfigurasi Skaffold dengan rilis Anda.

  • 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 deployment kustom.

Output dari deployment kustom

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 mencakup hal berikut:

  • Indikasi status keberhasilan atau kegagalan deployment kustom.

    Berikut adalah status yang valid:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Ini untuk deployment canary yang fase canary-nya dilewati, untuk langsung beralih ke 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 deployment kustom gagal (menampilkan status FAILED)

    Pesan ini digunakan untuk mengisi failure_message pada jalankan tugas untuk deployment ini.

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

  • (Opsional) peta metadata yang ingin Anda sertakan

    Target kustom Anda membuat metadata ini. Metadata ini disimpan di job run 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 Cloud Build.

Contoh file hasil deployment

Berikut adalah contoh output file results.json dari 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 target kustom

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

Menjalankan tugas

Tugas render dan deployment kustom Anda berjalan di lingkungan eksekusi Cloud Deploy. Anda tidak dapat mengonfigurasi tugas untuk dijalankan di cluster Google Kubernetes Engine.

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 Google Cloud , hubungi Google Clouddukungan.

Langkah berikutnya