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 target masing-masing. Substitusi ini dilakukan setelah manifes rendered, sebagai langkah terakhir dalam operasi render Cloud Deploy. Nilai diberikan ke semua manifes yang diidentifikasi dalam file skaffold.yaml Anda 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 deployment?

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

Cara kerjanya

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

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

    Ini mencakup hal-hal berikut:

    • Tambahkan placeholder ke manifes Anda, termasuk nilai default untuk setiap placeholder.

    • Tambahkan nilai untuk placeholder tersebut.

      Ada tiga cara untuk melakukannya, yang dijelaskan di sini.

  2. Saat Anda membuat rilis, manifes Anda akan rendered.

    Jika Anda memulai dengan manifes yang dibuat dari template, nilai akan diterapkan sekarang 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 rendering. Berikut adalah parameter deployment yang dijelaskan dalam dokumen ini.

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

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

    Ini adalah nilai yang Anda konfigurasi di langkah pertama.

    Proses rendering telah menerapkan nilai ke template manifes, menggantikan 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 target runtime, untuk men-deploy aplikasi Anda.

    Ini mencakup nilai yang diganti pada waktu rendering, 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 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 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 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, dengan menerapkan nilai tersebut ke manifes semua target yang terpengaruh.

Konfigurasi untuk ini dijelaskan 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, semua parameter akan 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.

Apa bedanya dengan template manifes

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

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

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

Batasan

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

  • Target turunan juga dapat mewarisi hingga 50 parameter dari multi-target induknya, hingga maksimum 200 parameter pada target, termasuk 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-satunya pengecualian adalah saat Anda menggunakan parameter deployment sebagai variabel lingkungan dalam 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 boleh kosong, tetapi maksimum 512 karakter.

  • Placeholder Parameter deployment tidak dapat digunakan untuk nilai konfigurasi Helm, tetapi harus diteruskan berdasarkan konvensi.

Mengonfigurasi parameter deployment

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

Selain mengonfigurasi pasangan nilai kunci tersebut, Anda perlu menambahkan 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 diganti 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:

    Apakah properti konfigurasi ada di manifes Kubernetes atau YAML layanan Cloud Run Anda.

  • DEFAULT_VALUE

    Adalah nilai yang akan digunakan jika tidak ada nilai yang diberikan untuk properti ini di command line atau dalam pipeline atau konfigurasi target. Nilai default diperlukan, tetapi dapat berupa string kosong ("").

  • # from-param:

    Menggunakan karakter komentar untuk memisahkan direktif Cloud Deploy deploy-parameters, dan from-param: memberi tahu Cloud Deploy bahwa placeholder deploy-parameters akan mengikuti.

  • ${VAR_NAME}

    Adalah placeholder yang akan diganti. Ini harus cocok dengan kunci pasangan nilai kunci yang diberikan 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 ditentukan pada tahap target atau 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 rendering, tanpa perlu memodifikasi skaffold.yaml Anda.

Misalnya, jika skaffold.yaml Anda menginstal Helm chart yang memerlukan parameter konfigurasi webserver.port untuk menentukan port tempat server web akan dimulai, dan Anda ingin menyetelnya 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 dari {{ .Values.VAR_NAME }} di template Helm Anda.

Misalnya, jika kita telah mengonfigurasi parameter deployment webserver.port, kita dapat memanfaatkannya 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 penayangan. Hal ini berguna untuk deployment paralel, untuk membedakan 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. Konfigurasi 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 mencakup dua values, yang masing-masing memiliki hal berikut:

    • Nama variabel, yang merupakan nama yang sama dengan variabel yang Anda tetapkan di manifest

    • 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 dalam tahap.

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

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

    Jika Anda menghilangkan matchTargetLabels, values yang Anda tetapkan di 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 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. Konfigurasi 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
   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. Konfigurasi target Anda agar menyertakan deployParameters.

    Untuk setiap parameter yang Anda sertakan, Anda mengidentifikasi hal berikut:

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

    • 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 pada 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 manifes tersebut menyertakan kunci terkait.

Meneruskan parameter saat pembuatan rilis

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

  1. Konfigurasi 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 bernama ${git-sha}. Nilai untuk ini diteruskan saat pembuatan rilis, menggunakan opsi --deploy-parameters=, seperti yang terlihat di langkah berikutnya.

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

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

    --deploy-parameters menggunakan daftar pasangan nilai kunci yang dipisahkan koma, dengan kuncinya adalah placeholder yang ditambahkan 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 manifes tersebut 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 Anda mereferensikan parameter deployment sebagai variabel lingkungan:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Dengan VAR_NAME adalah nama setelah garis miring di nama parameter deploy. Misalnya, jika Anda menentukan parameter deployment bernama customTarget/vertexAIModel, rujuk sebagai CLOUD_DEPLOY_customTarget_vertexAIModel.

Men-deploy parameter dengan hook deployment

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

Parameter deployment 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 ini ditampilkan dalam tabel di halaman Detail rilis dan di command line (gcloud deploy releases describe).

  1. Dari halaman utama Cloud Deploy, klik delivery pipeline 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 dalam satu kolom, serta target yang terpengaruh dalam kolom lainnya.

parameter dan nilai yang di-deploy ditampilkan di konsol Google Cloud

Langkah berikutnya