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 mewakili 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 pengiriman.

Apa yang dimasukkan ke dalam target kustom?

Setiap target kustom terdiri dari komponen berikut:

  • Tindakan kustom, ditentukan di skaffold.yaml

    Hal ini mirip dengan cara Anda menentukan hook deployment. Dalam file skaffold.yaml, Anda menentukan customActions, tempat 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 render kustom dan tindakan deployment kustom. Tindakan ini menggunakan nilai yang disediakan oleh Cloud Deploy dan harus memenuhi kumpulan output yang diperlukan.

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

  • Definisi jenis target kustom

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

  • Definisi target

    Definisi target untuk target kustom sama dengan jenis target apa pun, kecuali bahwa definisi target ini menyertakan properti customTarget, yang nilainya adalah nama CustomTargetType.

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

Misalnya

Panduan memulai Menentukan dan menggunakan jenis target kustom membuat jenis target kustom yang menyertakan perintah sederhana untuk dijalankan di image penampung—satu perintah untuk rendering dan satu perintah 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

Setiap jenis target kustom yang ditentukan untuk Cloud Deploy harus memenuhi persyaratan untuk input dan output, baik untuk render maupun deploy. Bagian ini mencantumkan input dan output yang diperlukan, serta cara menyediakannya.

Cloud Deploy menyediakan input yang diperlukan, untuk rendering dan 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 ke penampung kustom Anda semua parameter deployment yang telah Anda tetapkan.

Pelajari lebih lanjut.

Input untuk merender tindakan

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

  • CLOUD_DEPLOY_PROJECT

    Project Google Cloud tempat jenis target kustom dibuat.

  • 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 rendernya dipanggil.

  • CLOUD_DEPLOY_TARGET

    Nama target Cloud Deploy yang menggunakan jenis target kustom.

  • CLOUD_DEPLOY_PHASE

    Fase peluncuran yang sesuai dengan render.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Untuk tindakan rendering kustom, nilai ini selalu RENDER.

  • CLOUD_DEPLOY_FEATURES

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

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

    Untuk deployment standar, kolom ini kosong. Untuk deployment canary, nilainya adalah CANARY. Jika nilai yang diberikan oleh Cloud Deploy adalah CANARY, tindakan render Anda akan dipanggil untuk setiap fase di 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 ditetapkan ke CANARY, tindakan render kustom Anda akan dipanggil untuk setiap fase, dan variabel ini ditetapkan 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 penampung 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 informasi selengkapnya, lihat Output dari tindakan render.

Output dari tindakan render

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

  • File konfigurasi yang dirender

  • File results.json, yang berisi informasi berikut:

    • Indikasi status keberhasilan atau kegagalan tindakan kustom.

      Nilai yang valid adalah SUCCEEDED dan FAILED.

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

    • Jalur Cloud Storage untuk file konfigurasi yang dirender.

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

      Anda harus menyediakan file konfigurasi yang dirender, meskipun kosong. Konten file dapat berupa apa saja, dalam format apa pun, selama dapat digunakan oleh tindakan deployment kustom Anda. Sebaiknya file ini dapat dibaca manusia, sehingga Anda dan pengguna lain di organisasi dapat melihat file ini di inspector 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 URI Cloud Storage untuk file tersebut 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 yang diperlukan berikut, sebagai variabel lingkungan:

  • CLOUD_DEPLOY_PROJECT

    Project Google Cloud tempat target kustom dibuat.

  • 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 tindakan deployment kustom, nilai ini selalu DEPLOY.

  • CLOUD_DEPLOY_FEATURES

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

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

    Untuk deployment standar, kolom ini kosong. Untuk deployment canary, nilainya adalah CANARY. Jika nilai yang diberikan oleh Cloud Deploy adalah CANARY, tindakan render Anda akan dipanggil untuk setiap fase di 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 akan dipanggil untuk setiap fase, dan variabel ini disetel ke persentase canary untuk setiap fase. Tindakan 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.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Jalur Cloud Storage ke file manifes yang dirender.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Jalur ke direktori Cloud Storage tempat penampung 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 keberhasilan atau kegagalan tindakan deployment kustom.

    Berikut adalah status yang valid:

    • SUCCEEDED

    • FAILED

    • SKIPPED (untuk deployment canary dengan fase canary dilewati untuk langsung 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 disediakan 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 eksekusi tugas 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 job run dan pada 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 render 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 diperhatikan saat menyiapkan dan menggunakan jenis target kustom.

Menjalankan tindakan kustom

Tindakan render dan deploy 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 disediakan 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. Dengan demikian, Anda dapat menggunakan tindakan kustom yang ditentukan dan disimpan di satu lokasi bersama, bukan menyertakan tindakan kustom dengan file skaffold.yaml setiap rilis.

Target dan strategi deployment kustom

Target kustom sepenuhnya didukung untuk deployment standar.

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

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

Target kustom dan parameter deployment

Anda dapat menggunakan parameter deployment dengan target kustom. Anda dapat menetapkannya di tahap pipeline pengiriman, pada target yang menggunakan jenis target kustom, atau pada rilis.

Parameter deployment diteruskan ke penampung render dan deployment kustom Anda, sebagai variabel lingkungan, selain yang sudah disediakan.

Contoh target kustom

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

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Setiap contoh menyertakan panduan memulai.

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

Langkah selanjutnya