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 tidak 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 penentuan jenis target kustom dan menerapkannya sebagai target dalam pipeline pengiriman.

Apa saja yang termasuk dalam target kustom?

Setiap target kustom terdiri dari komponen berikut:

  • Tindakan kustom, ditentukan dalam skaffold.yaml

    Ini mirip dengan cara Anda menentukan hook deploy. Dalam file skaffold.yaml, Anda menentukan customActions, dengan setiap tindakan kustom mengidentifikasi image container yang akan digunakan, dan perintah untuk dijalankan pada penampung tersebut.

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

    Untuk jenis target kustom apa pun, Anda dapat mengonfigurasi tindakan render kustom dan tindakan deploy 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 jika target kustom Anda 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 dalam skaffold.yaml) yang digunakan target jenis ini untuk aktivitas deployment dan peluncuran rilis.

  • Definisi target

    Definisi target untuk target kustom sama seperti jenis target apa pun, kecuali jika target tersebut menyertakan properti customTarget, yang nilainya adalah nama CustomTargetType.

Dengan komponen tersebut, Anda dapat menggunakan target seperti halnya target, 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 mencakup perintah sederhana untuk dijalankan pada image container—satu perintah untuk render dan satu untuk deployment. Dalam hal ini, perintahnya hanya menambahkan teks ke file output yang diperlukan untuk dirender dan di-deploy.

Untuk contoh lainnya, lihat Contoh target kustom.

Input dan output yang diperlukan

Jenis target kustom apa pun yang ditentukan untuk Cloud Deploy harus memenuhi persyaratan input dan output, baik untuk render 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 deploy kustom Anda.

Men-deploy parameter sebagai variabel lingkungan

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

Men-deploy parameter yang ditujukan sebagai input untuk target kustom harus diawali dengan customTarget/, misalnya customTarget/vertexAIModel. Saat mereferensikan parameter deployment sebagai variabel lingkungan, gunakan sintaksis berikut:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Dengan VAR_NAME adalah nama setelah garis miring dalam nama parameter deploy. Misalnya, jika Anda menentukan parameter deployment dengan nama customTarget/vertexAIModel, referensikan parameter tersebut sebagai CLOUD_DEPLOY_customTarget_vertexAIModel.

Input untuk tindakan render

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 merujuk ke jenis target kustom.

  • CLOUD_DEPLOY_RELEASE

    Nama rilis yang akan menjalankan operasi render.

  • 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 render kustom, nilainya selalu RENDER.

  • CLOUD_DEPLOY_FEATURES

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

    Jika implementasi Anda tidak mendukung fitur dalam daftar ini, sebaiknya 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 dalam canary. Persentase canary untuk setiap fase diberikan dalam variabel lingkungan CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Persentase deployment yang terkait dengan operasi render ini. Jika variabel lingkungan CLOUD_DEPLOY_FEATURES ditetapkan ke CANARY, tindakan rendering kustom Anda akan dipanggil untuk setiap fase, dan variabel ini disetel ke persentase canary untuk setiap fase. Untuk deployment standar dan deployment canary yang telah mencapai fase stable, tahap 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 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 mengetahui informasi selengkapnya, lihat Output dari tindakan render.

Output dari tindakan render

Tindakan render 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 atau file konfigurasi yang dirender

  • File results.json, yang berisi informasi berikut:

    • Indikasi status berhasil atau gagal tindakan kustom.

      Nilai yang valid adalah SUCCEEDED dan FAILED.

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

    • Jalur Cloud Storage untuk file atau 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 memberikan file konfigurasi yang dirender, meskipun file tersebut kosong. Konten file dapat berupa apa saja, dalam format apa pun, selama file tersebut dapat digunakan oleh tindakan deploy kustom Anda. Sebaiknya file ini dapat dibaca manusia, sehingga Anda dan pengguna lain di organisasi dapat melihat file ini di release inspector.

Jika Anda perlu memeriksa file results.json, misalnya untuk proses debug, Anda dapat menemukan URI Cloud Storage ke 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: ""
}

Input untuk men-deploy tindakan

Untuk tindakan deployment kustom, Cloud Deploy menyediakan input yang diperlukan berikut ini, 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 merujuk ke target yang menggunakan jenis target kustom.

  • CLOUD_DEPLOY_RELEASE

    Nama rilis yang digunakan untuk memanggil operasi deploy.

  • CLOUD_DEPLOY_ROLLOUT

    Nama peluncuran Cloud Deploy yang menjadi target 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 deploy kustom, nilainya selalu DEPLOY.

  • CLOUD_DEPLOY_FEATURES

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

    Jika implementasi Anda tidak mendukung fitur dalam daftar ini, sebaiknya 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 dalam canary. Persentase canary untuk setiap fase diberikan 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 ditetapkan ke CANARY, tindakan deployment kustom Anda akan dipanggil untuk setiap fase, dan variabel ini ditetapkan ke persentase canary untuk setiap fase. Tindakan deploy 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 deploy kustom diharapkan mengupload artefak deploy. Untuk mengetahui informasi selengkapnya, lihat Output dari tindakan deploy.

Output dari tindakan deploy

Tindakan deploy 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 tersebut harus mencakup hal berikut:

  • Indikasi status berhasil atau gagal dari tindakan deploy kustom.

    Berikut adalah status yang valid:

    • SUCCEEDED

    • FAILED

    • SKIPPED (untuk deployment canary dengan fase canary dilewati untuk langsung membuka stable.)

  • (Opsional) Daftar file artefak yang di-deploy, dalam bentuk jalur Cloud Storage

    Jalurnya 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 tugas run sebagai artefak deploy.

  • (Opsional) Pesan kegagalan, jika tindakan deploy kustom tidak berhasil (menampilkan status FAILED)

    Pesan ini digunakan untuk mengisi failure_message pada tugas dijalankan untuk tindakan deploy ini.

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

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

Contoh file hasil deployment

Berikut adalah contoh output file results.json dari tindakan deploy 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: ""
}

Informasi lebih lanjut tentang tindakan kustom

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

Menjalankan tindakan kustom

Tindakan render dan deploy kustom Anda dijalankan 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 dalam 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. Hal ini memungkinkan Anda menggunakan tindakan kustom yang ditentukan dan disimpan di satu lokasi bersama, bukan menyertakan tindakan kustom dengan setiap file skaffold.yaml rilis.

Target khusus dan strategi deployment

Target kustom didukung sepenuhnya 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 deploy

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

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

Contoh target kustom

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

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Setiap contoh menyertakan panduan memulai.

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

Langkah selanjutnya