Meneruskan parameter ke deployment Anda

Dengan Cloud Deploy, Anda dapat meneruskan parameter untuk rilis, dan nilai tersebut diberikan ke manifes atau 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.

Anda hanya perlu menyertakan placeholder dalam manifes, dan menetapkan nilai untuk placeholder tersebut baik dalam pipeline pengiriman Cloud Deploy atau konfigurasi target, atau saat membuat rilis.

Artikel ini menjelaskan cara melakukannya.

Mengapa menggunakan parameter deploy?

Umumnya hal ini adalah menerapkan nilai yang berbeda ke manifes untuk berbagai target dalam deployment paralel. Namun, Anda dapat menggunakan parameter deployment untuk apa pun yang memerlukan substitusi 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.

   • Tambahkan nilai untuk placeholder tersebut.

     Ada tiga cara untuk melakukannya, yang dijelaskan di sini.

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

   Jika Anda memulai dengan manifes dengan 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 render. Berikut adalah parameter deploy yang dijelaskan dalam dokumen ini.

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

   Catatan: Jika parameter deploy tertentu (kunci) diberi lebih dari satu nilai, rilis akan gagal.

3. Setelah rendering, Cloud Deploy menggantikan nilai untuk parameter deployment.

   Ini adalah nilai yang Anda konfigurasikan pada langkah pertama.

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

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

   Ini termasuk nilai yang diganti pada waktu render, dan nilai untuk setiap parameter deploy

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 perkembangan pipeline pengiriman. Parameter ini diteruskan ke target yang direpresentasikan 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 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 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 dari semua target yang terpengaruh.

Konfigurasi untuk ini dijelaskan secara lebih mendetail di sini.

Dapatkah saya menggunakan lebih dari satu metode ini?

Ya, Anda dapat menyertakan parameter deployment pada 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 menampilkan error.

Men-deploy parameter dengan target kustom

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

Apa bedanya ini dengan template manifes

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

Teknik	Waktu pergantian pemain	Berlaku untuk
Template manifes	Fase rendering	Rilis tertentu; target spesifik
Di command line	Pasca-rendering	Rilis tertentu; semua target
Pipeline saat pengiriman	Pasca-rendering	Semua rilis; target spesifik (menurut label)
Sesuai target	Pasca-rendering	Semua rilis; target spesifik

Dokumen ini hanya membahas parameter untuk men-deploy (pada command line, pipeline, dan target), bukan manifes template.

Batasan

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

• Target turunan juga dapat mewarisi hingga 25 parameter dari multi-target induknya, hingga maksimum 100 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 pengecualian untuk hal ini adalah saat Anda menggunakan parameter deploy 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 boleh memiliki dua kunci dengan nama yang sama yang diterapkan ke target yang sama.

• Nilai boleh kosong, tetapi memiliki maksimum 512 karakter.

Mengonfigurasi parameter deploy

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

Selain mengonfigurasi key-value pair tersebut, Anda juga 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 dapat menambahkan placeholder untuk setiap nilai yang ingin diganti setelah rendering.

Sintaksis

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 dalam manifes Kubernetes atau YAML layanan Cloud Run.

• DEFAULT_VALUE

  Merupakan nilai yang akan digunakan jika tidak ada nilai yang diberikan untuk properti ini pada command line, pada pipeline atau konfigurasi target.

• # from-param:

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

• ${VAR_NAME}

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

Sintaksis khusus Helm

Jika Anda menggunakan perender Helm dengan Skaffold, gunakan sintaksis berikut di template Helm untuk menambahkan placeholder:

[PROPERTY]:  {{ .Values.VAR_NAME }} 

Menambahkan parameter ke tahap pipeline

Anda dapat menambahkan key-value pair ke suatu 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. Konfigurasi pipeline pengiriman Anda agar 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 dalam tahapan.

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

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

   Jika Anda menghapus matchTargetLabels, values yang ditetapkan 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 menambahkan nilai untuk setiap variabel ke dalam manifes yang dirender.

Menambahkan parameter ke konfigurasi target

Anda dapat menambahkan key-value pair ke target. Jika Anda menggunakan parameter deploy untuk membedakan di antara beberapa target turunan, konfigurasikan parameter pada target turunan tersebut, bukan pada multi-target.

1. Konfigurasi manifes Kubernetes atau definisi layanan Cloud Run menggunakan parameter sebagai pengganti nilai yang ingin ditetapkan 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 untuk menyertakan deployParameters.

   Untuk setiap parameter yang disertakan, Anda mengidentifikasi hal berikut:

   • Nama kunci, yang namanya 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 deploy 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 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. Konfigurasi manifes Kubernetes atau definisi layanan Cloud Run menggunakan parameter sebagai pengganti nilai yang ingin ditetapkan 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 di 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 mengambil daftar key-value pair yang dipisahkan koma, dengan kuncinya 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.

Melihat semua parameter untuk rilis

Anda dapat melihat parameter yang telah ditetapkan untuk rilis tertentu. Laporan ini ditampilkan dalam tabel di halaman Detail rilis dan 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 deploy yang telah ditetapkan untuk rilis ini ditampilkan dalam tabel, dengan nama dan nilai variabel dalam satu kolom, dan target atau target yang terpengaruh di kolom lainnya.

Langkah selanjutnya

• Coba panduan memulai: Menggunakan parameter deploy.

• Cari tahu lebih lanjut cara menggunakan deployment paralel.