Meneruskan parameter ke deployment Anda

Dengan Cloud Deploy, Anda dapat meneruskan parameter untuk rilis, dan nilai tersebut diberikan ke manifes sebelum manifes tersebut diterapkan ke targetnya masing-masing. Penggantian ini dilakukan setelah manifes dirender, sebagai langkah terakhir dalam operasi render Cloud Deploy. Nilai diberikan ke semua manifes yang diidentifikasi dalam file skaffold.yaml yang berisi placeholder yang sesuai.

Yang perlu Anda lakukan adalah menyertakan placeholder dalam manifes, dan menetapkan nilai untuk placeholder tersebut di pipeline pengiriman Cloud Deploy atau konfigurasi target, atau saat Anda membuat rilis.

Artikel ini menjelaskan cara melakukannya.

Mengapa menggunakan parameter deploy?

Penggunaan umum untuk hal ini adalah menerapkan nilai yang berbeda ke manifes untuk target yang berbeda dalam pen-deployment paralel. Namun, Anda dapat menggunakan parameter deployment untuk apa pun yang memerlukan penggantian key-value pair pasca-render dalam manifes.

Cara kerjanya

Langkah-langkah berikut menjelaskan proses umum untuk mengonfigurasi parameter deployment dan memberikan nilai:

  1. Anda mengonfigurasi parameter deployment, seperti yang dijelaskan di sini.

    Ini mencakup hal-hal berikut:

    • Tambahkan placeholder ke manifes Anda.

    • Tambahkan nilai untuk placeholder tersebut.

      Ada tiga cara untuk melakukannya, yang dijelaskan di sini.

  2. Saat Anda membuat rilis, manifes akan dirender.

    Jika Anda memulai dengan manifes template, nilai sekarang diterapkan untuk variabel template. Jika Anda memulai dengan manifes mentah, manifes tersebut tidak akan berubah. Rendering ini dilakukan oleh Skaffold.

    Namun, Anda dapat memiliki variabel tambahan dalam manifes yang nilainya tidak diterapkan pada waktu render. Ini adalah parameter deployment yang dijelaskan dalam dokumen ini.

    Saat pembuatan rilis, semua parameter deployment dikompilasi ke dalam kamus, yang digunakan untuk mengganti nilai sebelum manifes diterapkan.

  3. Setelah merender, Cloud Deploy akan mengganti nilai untuk parameter deployment.

    Ini adalah nilai yang Anda konfigurasikan di langkah pertama.

    Proses rendering telah menerapkan nilai ke template manifes, mengganti beberapa nilai, dan menambahkan label khusus untuk Cloud Deploy. Namun, nilai untuk parameter deployment ini diganti setelah rendering. Perbedaan antara template manifes dan parameter deployment dijelaskan di sini.

  4. Manifes diterapkan ke runtime target, untuk men-deploy aplikasi Anda.

    Ini mencakup nilai yang diganti pada waktu render, dan nilai untuk parameter deployment apa pun

Berbagai cara untuk meneruskan nilai

Anda dapat memberikan parameter dan nilai untuk parameter tersebut dengan tiga cara:

  • Dalam definisi pipeline pengiriman

    Anda memberikan parameter dan nilainya dalam definisi untuk suatu tahap dalam progres pipeline pengiriman. Parameter diteruskan ke target yang diwakili oleh tahap tersebut. Jika tahap tersebut mereferensikan multi-target, nilai yang ditetapkan di sini akan digunakan untuk semua target turunan.

    Metode ini memungkinkan Anda mengganti nilai untuk semua rilis dalam pipeline tertentu, untuk semua target yang terpengaruh. Parameter yang ditentukan untuk suatu tahap mengidentifikasi label, dan target yang sesuai untuk tahap tersebut harus memiliki label yang cocok.

  • Dalam definisi target

    Anda mengonfigurasi parameter dan nilainya dalam definisi untuk target itu sendiri. Metode ini memungkinkan Anda mengganti nilai untuk target tersebut untuk semua rilis.

  • Di command line, saat Anda membuat rilis

    Anda menyertakan parameter dan nilainya menggunakan flag --deploy-parameters pada perintah gcloud deploy releases create.

    Metode ini memungkinkan Anda mengganti nilai pada waktu pembuatan rilis, menerapkan nilai tersebut ke manifes dari semua target yang terpengaruh.

Konfigurasi untuk hal ini dijelaskan secara lebih mendetail di sini.

Dapatkah saya menggunakan lebih dari satu metode ini?

Ya, Anda dapat menyertakan parameter deployment di tahap pipeline, dalam konfigurasi target, dan di command line. Hasilnya adalah semua parameter diterima dan ditambahkan ke kamus. Namun, jika parameter tertentu diteruskan di lebih dari satu tempat, tetapi dengan nilai yang berbeda, perintah gcloud deploy releases create akan gagal dengan error.

Perbedaannya dengan template manifes

Parameter deployment, seperti yang dijelaskan dalam artikel ini, dibedakan dari placeholder dalam manifes template dengan sintaksis. Namun, jika Anda bertanya-tanya mengapa Anda memerlukan parameter deployment, bukan hanya menggunakan teknik standar untuk manifes bertemplate, tabel berikut menunjukkan tujuan yang berbeda:

Teknik Waktu penggantian Berlaku untuk
Template manifes Fase rendering Rilis tertentu; target tertentu
Di command line Pasca-rendering Rilis tertentu; semua target
Di pipeline pengiriman Pasca-rendering Semua rilis; target tertentu (menurut label)
Sesuai target Pasca-rendering Semua rilis; target tertentu

Dokumen ini hanya membahas parameter deployment (di command line, pipeline, dan target), bukan manifes dengan template.

Batasan

  • Untuk setiap jenis parameter, Anda dapat membuat maksimum 25 parameter.

  • Target turunan juga dapat mewarisi hingga 25 parameter dari multi-target induknya, hingga maksimum 100 parameter pada target, termasuk parameter yang ditetapkan pada tahap pipeline.

  • Nama kunci dibatasi hingga maksimum 63 karakter, dan ekspresi reguler berikut:

    ^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$

    Satu pengecualian untuk hal ini adalah saat Anda menggunakan parameter deployment sebagai variabel lingkungan di target kustom, Anda harus menggunakan garis miring di antara kata kunci customTarget dan nama variabel (customTarget/VAR_NAME). Lihat Input dan output yang diperlukan untuk sintaksis yang didukung.

  • Awalan CLOUD_DEPLOY_ dicadangkan, dan tidak dapat digunakan untuk nama kunci.

  • Anda tidak dapat memiliki dua kunci dengan nama yang sama yang diterapkan ke target yang sama.

  • Nilai dapat kosong, tetapi memiliki maksimum 512 karakter.

  • Placeholder Deploy Parameters tidak dapat digunakan untuk nilai konfigurasi Helm, tetapi harus diteruskan menurut konvensi.

Mengonfigurasi parameter deployment

Bagian ini menjelaskan cara mengonfigurasi parameter value deployment yang akan diterapkan ke manifes Kubernetes, layanan Cloud Run, atau template Helm Anda.

Selain mengonfigurasi pasangan nilai kunci tersebut, Anda perlu menambahkan placeholder atau placeholder ke manifes, seperti yang dijelaskan di bagian ini.

Menambahkan placeholder ke manifes

Dalam manifes Kubernetes (untuk GKE) atau YAML layanan (untuk Cloud Run), Anda menambahkan placeholder untuk nilai apa pun yang ingin digantikan setelah rendering.

Sintaks

Untuk rilis yang tidak menggunakan perender Helm dengan Skaffold, gunakan sintaksis berikut untuk placeholder Anda:

[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}

Di baris ini...

  • PROPERTY:

    Adalah properti konfigurasi dalam manifes Kubernetes atau YAML layanan Cloud Run.

  • DEFAULT_VALUE

    Adalah nilai yang akan digunakan jika tidak ada nilai yang diberikan untuk properti ini di command line atau di pipeline atau konfigurasi target.

  • # from-param:

    Menggunakan karakter komentar untuk memicu perintah deploy-parameters Cloud Deploy, dan from-param: memberi tahu Cloud Deploy bahwa placeholder deploy-parameters akan mengikutinya.

  • ${VAR_NAME}

    Adalah placeholder yang akan diganti. Ini harus cocok dengan kunci pasangan nilai kunci yang disediakan di pipeline pengiriman atau konfigurasi target, atau saat pembuatan rilis.

Anda juga dapat menggunakan beberapa parameter dalam satu baris, dan menggunakan parameter sebagai bagian dari string yang lebih panjang, misalnya:

image: my-image # from-param: ${artifactRegion}-docker.pkg.dev/my-project/my-repo/my-image@sha256:${imageSha}

Parameter ini dapat berasal dari beberapa sumber. Pada contoh sebelumnya, ${artifactRegion} mungkin akan ditentukan pada target atau tahap pipeline pengiriman, sedangkan ${imageSha} akan berasal dari command line pada waktu pembuatan rilis.

Parameter untuk nilai diagram Helm

Jika Anda merender diagram Helm yang menerima nilai konfigurasi, dan Anda ingin menetapkan nilai tersebut menggunakan parameter deployment, parameter deployment harus memiliki nama yang cocok dengan nilai konfigurasi Helm yang ingin Anda tetapkan. Semua parameter deployment diteruskan ke Helm sebagai argumen --set pada waktu render, tanpa perlu mengubah skaffold.yaml Anda.

Misalnya, jika skaffold.yaml Anda menginstal diagram Helm yang menggunakan parameter konfigurasi webserver.port untuk menentukan port tempat server web akan dimulai, dan Anda ingin menetapkannya secara dinamis dari parameter deployment, Anda harus membuat parameter deployment dengan nama webserver.port dengan nilai yang Anda inginkan untuk port server web.

Oleh karena itu, jika Anda tidak hanya mereferensikan template Helm di skaffold.yaml, tetapi juga menulisnya, Anda dapat menggunakan sintaksis variabel Helm standar {{ .Values.VAR_NAME }} di template Helm.

Misalnya, jika kita memiliki parameter deployment webserver.port yang dikonfigurasi, kita dapat menggunakannya seperti ini:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webserver
spec:
  replicas: 3
  selector:
    matchLabels:
      app: webserver
  template:
    metadata:
      labels:
        app: webserver
    spec:
      containers:
      - name: webserver
        image: gcr.io/example/webserver:latest
        ports:
        - containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
          name: web
        env:
        - name: WEBSERVER_PORT
          value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.

Menambahkan parameter ke tahap pipeline

Anda dapat menambahkan pasangan nilai kunci ke tahap dalam progres pipeline pengiriman. Hal ini berguna untuk deployment paralel, untuk membedakan antara target turunan.

  1. Tambahkan placeholder ke manifes Kubernetes atau layanan Cloud Run, seperti yang dijelaskan di sini.

    Berikut contohnya:

    apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 labels:
   app: nginx
spec:
 replicas: 1 # from-param: ${deploy_replicas}
 selector:
   matchLabels:
     app: nginx
 template:
   metadata:
     labels:
       app: nginx
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2
       ports:
       - containerPort: 80

  2. Konfigurasikan pipeline pengiriman Anda untuk menyertakan deployParameters untuk tahap pipeline yang berlaku.

    YAML berikut adalah konfigurasi untuk tahap pipeline yang targetnya adalah multi-target, yang dalam hal ini memiliki dua target turunan:

    serialPipeline:
 stages:
   - targetId: dev
     profiles: []
   - targetId: prod  # multi-target
     profiles: []
     deployParameters:
       - values:
           deploy_replicas: 1
           log_level: "NOTICE"
         matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
           my-app: "post-render-config-1"
       - values:
           deploy_replicas: 2
           log_level: "WARNING"
         matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
           my-app: "post-render-config-2"

    Dalam konfigurasi pipeline pengiriman ini, stanza deployParameters menyertakan dua values, yang masing-masing memiliki hal berikut:

    • Nama variabel, yang sama dengan nama variabel yang Anda tetapkan dalam manifes

    • Nilai untuk variabel tersebut

    • Satu atau beberapa label (opsional) untuk dicocokkan dengan label khusus target

      Jika Anda tidak menentukan label, dalam stanza matchTargetLabels, nilai tersebut akan digunakan untuk semua target di tahap.

  3. Jika menyertakan matchTargetLabels , Anda juga harus menyertakan label pada target, untuk mencocokkannya. Dengan cara ini, Anda mengidentifikasi nilai yang akan ditetapkan ke target turunan mana.

    Target harus cocok dengan semua label yang ditetapkan dalam stanza values.

    Jika Anda menghilangkan matchTargetLabels, values yang Anda tetapkan pada pipeline akan diterapkan ke semua target turunan. Namun, jika Anda menetapkan lebih dari satu nilai untuk parameter yang sama, rilis akan gagal.

Setelah setiap manifes dirender, Cloud Deploy akan menambahkan nilai untuk setiap variabel ke dalam manifes yang dirender.

Menambahkan parameter ke konfigurasi target

Anda dapat menambahkan pasangan nilai kunci ke target. Jika Anda menggunakan parameter deployment untuk membedakan beberapa target turunan, konfigurasikan parameter tersebut di target turunan tersebut, bukan di multi-target.

  1. Konfigurasikan manifes Kubernetes atau definisi layanan Cloud Run menggunakan parameter, bukan nilai yang ingin Anda tetapkan pada waktu deployment.

    Berikut contohnya:

    apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 labels:
   app: nginx
spec:
 selector:
   matchLabels:
     app: nginx
 template:
   metadata:
     labels:
       app: nginx
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2
       env:
       - name: envvar1
         value: example1 # from-param: ${application_env1}
       - name: envvar2
         value: example2 # from-param: ${application_env2}

    Dalam manifes ini, parameter envvar1 disetel ke default example1, dan envvar2 disetel ke default example2.

  2. Konfigurasikan target untuk menyertakan deployParameters.

    Untuk setiap parameter yang disertakan, Anda harus mengidentifikasi hal berikut:

    • Nama kunci, yang merupakan nama yang sama dengan kunci (variabel) yang Anda tetapkan dalam manifes.

    • Nilai untuk kunci tersebut. Jika Anda tidak memberikan nilai, nilai default yang ditetapkan dalam manifes akan digunakan.

    YAML berikut adalah konfigurasi untuk dua target. Setiap target menyertakan stanza deployParameters yang menetapkan nilai. Setiap target juga menyertakan label, yang akan dicocokkan dengan parameter deployment yang dikonfigurasi di tahap pipeline.

    apiVersion: deploy.cloud.google.com/v1beta1
kind: Target
metadata:
  name: prod1
  labels:
    my-app: "post-render-config-1"
description: development cluster
deployParameters:
  application_env1: "newValue1"
---

apiVersion: deploy.cloud.google.com/v1beta1
kind: target
metadata:
  name: prod2
  labels:
    my-app: "post-render-config-2"
description: development cluster
deployParameters:
  application_env1: "newValue2"

Saat rilis dibuat, tetapi setelah manifes dirender, Cloud Deploy akan menambahkan nilai ini ke manifes yang dirender jika menyertakan kunci terkait.

Meneruskan parameter saat pembuatan rilis

Ikuti langkah-langkah berikut untuk meneruskan parameter dan nilai ke rilis:

  1. Konfigurasikan manifes Kubernetes atau definisi layanan Cloud Run menggunakan parameter sebagai pengganti nilai yang ingin Anda tetapkan pada waktu deployment.

    Berikut contohnya:

    apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 labels:
   app: nginx
spec:
 selector:
   matchLabels:
     app: nginx
 template:
   metadata:
     labels:
       app: nginx
   annotations:
     commit: defaultShaValue # from-param: ${git-sha}
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2

    Dalam contoh ini, SHA commit ditetapkan sebagai variabel yang disebut ${git-sha}. Nilai untuk ini diteruskan saat pembuatan rilis, menggunakan opsi --deploy-parameters=, seperti yang terlihat pada langkah berikutnya.

    Sintaksis untuk variabel ini adalah $ ditambah nama variabel dalam tanda kurung kurawal. Dalam contoh ini, parameternya adalah ${git-sha}.

  2. Saat Anda membuat rilis, sertakan opsi --deploy-parameters pada perintah gcloud deploy releases create.

    --deploy-parameters menggunakan daftar pasangan nilai kunci yang dipisahkan koma, dengan kunci adalah placeholder yang Anda tambahkan ke manifes.

    Perintahnya akan terlihat seperti ini:

    gcloud deploy releases create test-release-001 \
--project=my-example-project \
--region=us-central1 \
--delivery-pipeline=my-params-demo-app-1 \
--images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \
--deploy-parameters="git-sha=f787cac"

Saat rilis dibuat, tetapi setelah rendering manifes, Cloud Deploy memberikan nilai ke manifes yang dirender jika menyertakan kunci terkait.

Men-deploy parameter dengan target kustom

Anda dapat menggunakan parameter deployment apa pun sebagai variabel lingkungan di target kustom. Saat melakukannya, gunakan sintaksis yang ditentukan untuk target kustom.

Parameter deployment yang dimaksudkan sebagai input untuk target kustom dapat diawali dengan customTarget/, misalnya customTarget/vertexAIModel. Jika Anda menggunakan awalan ini, gunakan sintaksis berikut saat mereferensikan parameter deployment sebagai variabel lingkungan:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Dengan VAR_NAME adalah nama yang mengikuti garis miring dalam nama parameter deployment. Misalnya, jika Anda menentukan parameter deployment bernama customTarget/vertexAIModel, referensikan sebagai CLOUD_DEPLOY_customTarget_vertexAIModel.

Men-deploy parameter dengan hook deploy

Anda dapat menggunakan parameter deployment apa pun sebagai variabel lingkungan dalam hook deployment.

Men-deploy parameter dengan verifikasi deployment

Anda dapat menggunakan parameter deployment apa pun sebagai variabel lingkungan dalam verifikasi deployment.

Melihat semua parameter untuk rilis

Anda dapat melihat parameter yang telah ditetapkan untuk rilis tertentu. Informasi tersebut ditampilkan dalam tabel di halaman Detail rilis dan di command line (gcloud deploy releases describe).

  1. Dari halaman utama Cloud Deploy, klik pipeline pengiriman yang menyertakan rilis yang ingin Anda lihat.

  2. Di halaman Detail rilis, pilih tab Artefak.

Semua parameter deployment yang telah ditetapkan untuk rilis ini ditampilkan dalam tabel, dengan nama dan nilai variabel di satu kolom, dan target atau target yang terpengaruh di kolom lain.

parameter dan nilai deployment yang ditampilkan di konsol Google Cloud

Langkah selanjutnya