Membuat target kustom

Dokumen ini menjelaskan cara membuat jenis target Cloud Deploy kustom dan menggunakan jenis target kustom tersebut sebagai target di pipeline pengiriman Cloud Deploy.

Berikut adalah proses tingkat tinggi untuk membuat jenis target kustom dan menggunakannya dalam pipeline pengiriman Anda:

1. Buat aplikasi dalam container atau aplikasi yang menyertakan fungsi untuk di-deploy ke target kustom Anda, dan yang memenuhi persyaratan Cloud Deploy untuk jenis target kustom.

2. Tentukan tindakan kustom di skaffold.yaml yang mereferensikan container tersebut dan menentukan perintah atau perintah yang akan dijalankan pada container tersebut.

3. Buat definisi CustomTargetType yang merujuk tindakan kustom dari langkah sebelumnya, lalu daftarkan sebagai resource Cloud Deploy.

4. Tentukan target baru dengan properti customTarget yang mengidentifikasi jenis target kustom baru Anda.

5. Rujuk target dari progres pipeline pengiriman Anda.

6. Buat rilis.

Setiap langkah ini dijelaskan secara mendetail di bagian lain dokumen ini.

Membuat aplikasi dalam container

Fungsi yang akan di-deploy ke target kustom ditentukan dalam aplikasi dalam container, yang Anda sediakan ke Cloud Deploy dengan mereferensikannya dari file skaffold.yaml. Saat pipeline pengiriman Anda menyertakan target yang menggunakan jenis target kustom, Cloud Deploy akan memanggil container tindakan kustom yang ditentukan untuk jenis target kustom tersebut, di Skaffold, untuk menjalankan tindakan render dan deploy yang telah Anda tentukan.

Anda dapat menentukan perilaku aplikasi. Namun, metode ini harus menggunakan variabel lingkungan input yang disediakan oleh Cloud Deploy, dan harus menampilkan output yang diperlukan.

Pada umumnya, Anda akan membuat satu penampung untuk tindakan render dan satu lagi untuk tindakan deploy, untuk setiap jenis target kustom yang Anda buat. Tindakan render bersifat opsional, tetapi jika Anda tidak menyediakannya, Cloud Deploy menggunakan skaffold render default.

Menentukan tindakan kustom di Skaffold

Dengan menerapkan image atau image container tindakan kustom, Anda mereferensikannya dari file konfigurasi skaffold.yaml.

Anda mengonfigurasi setiap tindakan kustom untuk target kustom dalam stanza customActions. Untuk jenis target kustom apa pun, Anda membuat tindakan kustom, di Skaffold, untuk render dan satu lagi untuk deploy. Definisi CustomTargetType mengidentifikasi tindakan kustom mana yang digunakan untuk render dan mana yang digunakan untuk deployment.

Catatan: Perender kustom tidak diperlukan jika target kustom Anda dapat menggunakan manifes yang dibuat oleh perender default (skaffold render). Dalam hampir semua kasus, Anda akan memerlukan tindakan render kustom.

Berikut adalah konfigurasi untuk tindakan render dan deploy kustom di skaffold.yaml:

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

Dalam konfigurasi Skaffold ini:

• customActions.name

  Adalah nama arbitrer untuk tindakan deploy atau render kustom. Definisi CustomTargetType merujuk pada nama ini, di properti renderAction atau properti deployAction.

• Stanza containers menyertakan referensi Anda, serta perintah untuk menjalankan penampung tersebut.

  Stanza containers mengizinkan lebih dari satu penampung, tetapi Google merekomendasikan agar Anda hanya menggunakan satu penampung.

• customActions.containers.name

  Adalah nama arbitrer untuk container tertentu yang Anda gunakan untuk tindakan ini. Sebagai praktik terbaik, nama container ini harus selalu memenuhi syarat SHA.

• image

  Merupakan jalur ke image container.

• command

  Merupakan perintah atau beberapa perintah yang akan dijalankan pada container.

• args

  Adalah kumpulan argumen untuk command.

Lihat referensi YAML Skaffold untuk mendapatkan dokumentasi mendetail tentang properti konfigurasi yang digunakan dalam customActions.

Catatan: Anda juga dapat menentukan konfigurasi Skaffold dan menyimpannya di repositori Git atau di bucket Cloud Storage, serta mereferensikan konfigurasi tersebut dari definisi jenis target kustom Anda.

Menentukan jenis target khusus Anda

Anda menentukan target kustom dengan membuat jenis target kustom terlebih dahulu menggunakan konfigurasi CustomTargetType. Anda dapat membuat CustomTargetType dalam file yang sama dengan definisi pipeline pengiriman, atau dengan definisi target, atau dalam file terpisah.

Definisi CustomTargetType adalah sebagai berikut:

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

Dari mana

• CUSTOM_TARGET_TYPE_NAME

  Adalah nama arbitrer yang Anda berikan untuk definisi jenis target kustom ini. Nama ini direferensikan dalam definisi target untuk semua target yang menggunakan jenis target kustom yang Anda tentukan.

• RENDER_ACTION_NAME

  Adalah nama tindakan render kustom. Nilai ini adalah customAction.name yang ditentukan di skaffold.yaml untuk tindakan render.

• DEPLOY_ACTION_NAME

  Adalah nama tindakan deploy kustom. Nilai ini adalah customAction.name yang ditentukan di skaffold.yaml untuk tindakan deploy.

• includeSkaffoldModules

  Merupakan stanza opsional untuk digunakan jika Anda menggunakan konfigurasi Skaffold jarak jauh. Properti dalam stanza ini ditampilkan di bagian Menggunakan konfigurasi Skaffold jarak jauh.

Menggunakan konfigurasi Skaffold jarak jauh

Anda dapat menyimpan konfigurasi Skaffold di repositori Git publik atau di bucket Cloud Storage, dan mereferensikan konfigurasi tersebut dari definisi jenis target kustom Anda.

Menggunakan konfigurasi Skaffold jarak jauh berarti skaffold.yaml yang Anda berikan pada waktu rilis tidak perlu menentukan tindakan kustom. Hal ini memungkinkan Anda membagikan tindakan kustom di seluruh organisasi.

Untuk menggunakan konfigurasi Skaffold jarak jauh:

1. Membuat konfigurasi Skaffold dengan tindakan atau tindakan kustom Anda.

2. Simpan konfigurasi di repositori Git atau di bucket Cloud Storage.

3. Dalam definisi jenis target kustom Anda, tambahkan stanza customActions.includeSkaffoldModules.

4. Di bagian includeSkaffoldModules, tentukan hal berikut:

   • Opsional, satu atau beberapa elemen configs:

     - configs: ["name1", "name2"]

     Nilai configs adalah daftar string yang cocok dengan properti metadata.name pada setiap konfigurasi Skaffold yang akan disertakan. Jika opsi ini dihilangkan, Cloud Deploy akan mengambil semua konfigurasi di jalur yang ditentukan.

   • Stanza googleCloudStorage atau stanza git.

     Untuk Cloud Storage:

     googleCloudStorage:
       source: PATH_TO_GCS_BUCKET
       path: FILENAME
     

     Untuk Git:

     git:
       repo: REPO_URL
       path: PATH_TO_FILE
       ref: BRANCH_NAME
     

     Dengan keterangan:

     PATH_TO_GCS_BUCKET adalah jalur ke direktori Cloud Storage, yang diakhiri dengan /*, tempat konfigurasi Skaffold disimpan. Skaffold mendownload semua file dalam direktori ini, lalu menemukan file Skaffold yang relevan dengan konfigurasi, berdasarkan jalur relatif yang dikonfigurasi.

     FILENAME adalah nama file yang menyertakan konfigurasi Skaffold. Properti path: ini bersifat opsional. Jika Anda tidak menentukannya, Cloud Deploy akan mengasumsikan skaffold.yaml. Jika tidak ada skaffold.yaml, atau jika nama file yang Anda tentukan tidak ada, pembuatan rilis akan gagal.

     REPO_URL adalah URL ke repositori Git.

     PATH_TO_FILE adalah jalur dalam repositori tersebut ke file yang berisi konfigurasi Skaffold.

     BRANCH_NAME adalah nama cabang (misalnya, main) tempat konfigurasi Skaffold akan diambil.

Contoh

YAML jenis target kustom berikut adalah stanza customActions dengan stanza includeSkaffoldModules, yang mengarah ke konfigurasi Skaffold yang disimpan di bucket Cloud Storage:

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

YAML berikut adalah konfigurasi Skaffold, yang dirujuk oleh tindakan kustom yang ditampilkan:

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

Mendaftarkan jenis target kustom

Setelah mengonfigurasi CustomTargetType, jalankan perintah gcloud deploy apply untuk mendaftarkan resource CustomTargetType di project Google Cloud:

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

Dengan keterangan:

FILE adalah nama file yang Anda gunakan untuk menentukan jenis target kustom ini.

PROJECT adalah project Google Cloud untuk membuat resource ini. CustomTargetType harus berada dalam project yang sama dengan resource Target yang mereferensikannya. Anda tidak perlu menentukan project jika telah menetapkannya sebagai project default untuk Google Cloud CLI.

REGION adalah region (misalnya, us-centra1) tempat membuat resource ini. CustomTargetType harus berada di region yang sama dengan resource Target yang mereferensikannya. Anda tidak perlu menentukan region jika telah menetapkannya sebagai region default untuk gcloud CLI.

Karena CustomTargetType yang kini dibuat sebagai resource Cloud Deploy, Anda kini dapat menggunakannya dalam definisi Target untuk membuat target kustom.

Untuk mengetahui informasi selengkapnya tentang definisi CustomTargetType, lihat referensi skema konfigurasi Cloud Deploy.

Tentukan target Anda

Satu-satunya perbedaan antara definisi target untuk jenis target yang didukung dan definisi target kustom adalah definisi target kustom menyertakan stanza customTarget. Sintaksis untuk customTarget adalah sebagai berikut:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Dengan CUSTOM_TARGET_TYPE_NAME adalah nilai dari properti name yang ditentukan dalam konfigurasi jenis target kustom.

Catatan: Anda dapat menggunakan multitarget dengan target turunan adalah target kustom. Dalam hal ini, semua target turunan harus memiliki CustomTargetType yang sama.

Menambahkan target ke pipeline pengiriman

Anda dapat menggunakan target kustom di pipeline pengiriman persis seperti saat Anda menggunakan jenis target yang didukung. Artinya, tidak ada perbedaan dalam progres pipeline pengiriman antara target dari jenis target yang didukung dan target kustom.

Semua target dalam pipeline pengiriman harus menggunakan jenis target yang sama. Misalnya, Anda tidak dapat memiliki pipeline pengiriman dengan beberapa target yang di-deploy ke Google Kubernetes Engine dan beberapa target kustom.

Seperti jenis target yang didukung, Anda dapat menyertakan parameter deploy pada tahap pipeline.

Membuat rilis

Catatan: Jika Anda tidak menggunakan konfigurasi Skaffold jarak jauh, file skaffold.yaml yang Anda berikan untuk rilis harus menentukan tindakan kustom yang diperlukan jenis target kustom.

Setelah jenis target kustom Anda sepenuhnya ditentukan dan target yang dibuat untuk menggunakan jenis tersebut, Anda kini dapat membuat rilis, dengan cara biasa:

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

Setelah pembuatan rilis, tindakan render kustom Anda akan dijalankan untuk setiap target dalam pipeline pengiriman Anda, termasuk memproses parameter deploy yang dikonfigurasi pada rilis, target, atau pipeline pengiriman. Cloud Deploy menyediakan parameter deploy sebagai input ke penampung render kustom.

Melihat hasil target kustom Anda

Jika tindakan kustom Anda memenuhi persyaratan untuk target kustom, Anda dapat menggunakan Konsol Google Cloud untuk melihat artefak yang dirender.

Ikuti langkah-langkah berikut untuk melihat output tindakan render kustom Anda.

1. Di konsol Google Cloud, buka halaman Delivery pipelines Cloud Deploy untuk melihat pipeline pengiriman Anda.

   Buka halaman Pipeline pengiriman

2. Klik nama pipeline pengiriman Anda.

   Visualisasi pipeline menunjukkan status deployment aplikasi, dan rilis Anda tercantum di tab Rilis di bagian Detail pipeline pengiriman.

3. Klik nama rilis.

   Halaman Detail rilis akan ditampilkan.

4. Klik tab Artefak.

5. Di bagian Target artefak, klik panah di samping Lihat artefak.

   Artefak yang dirender akan dicantumkan, termasuk skaffold.yaml yang dirender dan file manifes yang dirender yang dihasilkan oleh perender kustom. Anda juga dapat mengklik link Lokasi penyimpanan di samping setiap file untuk membuka bucket Cloud Storage guna melihat file tersebut.

   Anda juga dapat mengklik link View artists untuk melihat file tersebut menurut rilis, target, atau fase, menggunakan release inspector.

Langkah selanjutnya

• Coba panduan memulai: Menentukan dan menggunakan jenis target kustom

• Lihat contoh jenis target khusus yang tersedia.

• Membuat target dan pipeline pengiriman.

• Pelajari lebih lanjut cara mengonfigurasi target Cloud Deploy