Membuat target kustom

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

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

1. Buat aplikasi dalam penampung 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 penampung tersebut dan menentukan perintah atau perintah yang akan dijalankan di dalamnya.

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

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

5. Referensikan target tersebut 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 penampung, yang Anda berikan ke Cloud Deploy dengan mereferensikannya dari file skaffold.yaml. Saat pipeline pengiriman Anda menyertakan target yang menggunakan jenis target kustom, Cloud Deploy akan memanggil penampung tindakan kustom yang ditentukan untuk jenis target kustom tersebut, di Skaffold, untuk menjalankan tindakan render dan deployment yang telah Anda tentukan.

Anda bebas menentukan perilaku aplikasi. Namun, fungsi 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 deployment, untuk setiap jenis target kustom yang Anda buat. Tindakan render bersifat opsional, tetapi jika Anda tidak memberikannya, Cloud Deploy akan menggunakan skaffold render default.

Menentukan tindakan kustom di Skaffold

Dengan image container tindakan kustom yang sudah ada, Anda mereferensikannya dari file konfigurasi skaffold.yaml.

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

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

Berikut adalah konfigurasi untuk tindakan render dan deployment 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 render atau deployment kustom. Definisi CustomTargetType mereferensikan nama ini, di properti renderAction atau properti deployAction.

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

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

• customActions.containers.name

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

• image

  Adalah jalur ke image container.

• command

  Adalah perintah atau perintah yang akan dijalankan di penampung.

• args

  Merupakan kumpulan argumen ke command.

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

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

Menentukan jenis target kustom

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 ke definisi jenis target kustom ini. Nama ini direferensikan dalam definisi target untuk setiap target yang menggunakan jenis target kustom yang Anda tentukan.

• RENDER_ACTION_NAME

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

• DEPLOY_ACTION_NAME

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

• includeSkaffoldModules

  Adalah stanza opsional yang akan 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, bucket Cloud Storage, atau repositori Cloud Build generasi ke-2 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 berbagi tindakan kustom di seluruh organisasi Anda.

Untuk menggunakan konfigurasi Skaffold jarak jauh:

1. Buat konfigurasi Skaffold dengan tindakan kustom Anda.

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

3. Dalam definisi jenis target kustom, tambahkan bait customActions.includeSkaffoldModules.

4. Di bagian includeSkaffoldModules, tentukan hal berikut:

   • Secara opsional, satu atau beberapa elemen configs:

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

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

   • Stanza googleCloudStorage, git, atau googleCloudBuildRepo.

     Untuk Cloud Storage:

     googleCloudStorage:
       source: PATH_TO_GCS_BUCKET
       path: FILENAME
     

     Untuk Git:

     git:
       repo: REPO_URL
       path: PATH_TO_FILE
       ref: BRANCH_NAME
     

     Untuk Repositori Cloud Build (generasi ke-2):

      googleCloudBuildRepo:
       repository: PATH_TO_GCB_REPO
       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.

     PATH_TO_GCB_REPO adalah jalur ke repositori Cloud Build generasi ke-2 tempat konfigurasi Skaffold disimpan. Jalur memiliki bentuk berikut: projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}. Skaffold mendownload semua file dalam direktori ini, lalu menemukan file Skaffold, 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 di repositori tersebut ke file yang berisi konfigurasi Skaffold.

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

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 tempat Anda menentukan jenis target kustom ini.

PROJECT adalah project Google Cloud tempat 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.

Dengan 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.

Menentukan target

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 multi-target 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 menggunakan jenis target yang didukung. Artinya, tidak ada perbedaan dalam progres pipeline penayangan antara target 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 deployment di 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.

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

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

Setelah pembuatan rilis, tindakan render kustom Anda akan dieksekusi untuk setiap target di pipeline pengiriman, termasuk pemrosesan parameter deployment yang dikonfigurasi pada rilis, target, atau pipeline pengiriman. Cloud Deploy menyediakan parameter deploy sebagai input ke container render kustom.

Melihat output target kustom

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 Cloud Deploy Delivery pipelines untuk melihat pipeline pengiriman Anda.

   Buka halaman Delivery pipelines

2. Klik nama pipeline pengiriman Anda.

   Visualisasi pipeline menampilkan status deployment aplikasi, dan rilis Anda dicantumkan di tab Releases pada bagian Delivery pipeline details.

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 dicantumkan, termasuk skaffold.yaml yang dirender dan file manifes yang dirender yang dihasilkan oleh perender kustom. Anda juga dapat mengklik link Storage location di samping setiap file untuk membuka bucket Cloud Storage guna melihat file tersebut.

   Anda juga dapat mengklik link Lihat artefak untuk melihat file tersebut berdasarkan rilis, target, atau fase, menggunakan pemeriksa rilis.

Langkah selanjutnya

• Coba panduan memulai: Menentukan dan menggunakan jenis target kustom

• Lihat contoh jenis target kustom yang tersedia.

• Buat target dan pipeline pengiriman.

• Pelajari lebih lanjut cara mengonfigurasi target Cloud Deploy