Mengganti nilai variabel

Gunakan substitutions di file konfigurasi build untuk mengganti variabel tertentu pada waktu build.

Penggantian berguna untuk variabel yang nilainya tidak diketahui hingga waktu build, atau untuk menggunakan kembali permintaan build yang ada dengan nilai variabel yang berbeda.

Cloud Build menyediakan substitusi bawaan atau Anda dapat menentukan substitusi Anda sendiri. Gunakan substitutions dalam steps dan images build Anda untuk me-resolve nilainya pada waktu build.

Halaman ini menjelaskan cara menggunakan substitusi default atau menentukan substitutions Anda sendiri.

Menggunakan substitusi default

Cloud Build menyediakan substitusi default berikut untuk semua build:

• $PROJECT_ID: ID project Cloud Anda
• $BUILD_ID: ID build Anda
• $PROJECT_NUMBER: nomor project Anda
• $LOCATION: region yang terkait dengan build Anda

Cloud Build menyediakan substitusi default berikut untuk build yang dipanggil oleh pemicu:

• $TRIGGER_NAME: nama yang terkait dengan pemicu Anda
• $COMMIT_SHA: ID commit yang terkait dengan build Anda
• $REVISION_ID: ID commit yang terkait dengan build Anda
• $SHORT_SHA : tujuh karakter pertama dari COMMIT_SHA
• $REPO_NAME: nama repositori Anda
• $REPO_FULL_NAME: nama lengkap repositori Anda, termasuk pengguna atau organisasi
• $BRANCH_NAME: nama cabang Anda
• $TAG_NAME: nama tag Anda
• $REF_NAME: nama cabang atau tag Anda
• $TRIGGER_BUILD_CONFIG_PATH: jalur ke file konfigurasi build yang digunakan selama eksekusi build; jika tidak, string kosong jika build dikonfigurasi secara inline pada pemicu atau menggunakan Dockerfile atau Buildpack.
• $SERVICE_ACCOUNT_EMAIL: email akun layanan yang Anda gunakan untuk build. Akun layanan dapat berupa akun layanan default atau akun layanan yang ditentukan pengguna.
• $SERVICE_ACCOUNT: nama resource akun layanan, dalam format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

Catatan: $COMMIT_SHA dan $REVISION_ID mewakili ID commit yang terkait dengan build Anda. Dukungan untuk kedua substitusi tersedia.

Cloud Build menyediakan substitusi default khusus GitHub berikut yang tersedia untuk pemicu permintaan pull:

• $_HEAD_BRANCH : cabang utama permintaan pull
• $_BASE_BRANCH : cabang dasar permintaan pull
• $_HEAD_REPO_URL : URL repositori head permintaan pull
• $_PR_NUMBER : jumlah permintaan pull

Jika substitusi default tidak tersedia (misalnya dengan build tanpa sumber, atau dengan build yang menggunakan sumber penyimpanan), kemunculan variabel yang hilang akan diganti dengan string kosong.

Saat memulai build menggunakan gcloud builds submit, Anda dapat menentukan variabel yang biasanya berasal dari build yang dipicu dengan argumen --substitutions. Secara khusus, Anda dapat memberikan nilai secara manual untuk:

• $TRIGGER_NAME
• $COMMIT_SHA
• $REVISION_ID
• $SHORT_SHA
• $REPO_NAME
• $REPO_FULL_NAME
• $BRANCH_NAME
• $TAG_NAME
• $REF_NAME
• $TRIGGER_BUILD_CONFIG_PATH
• $SERVICE_ACCOUNT_EMAIL
• $SERVICE_ACCOUNT

Misalnya, perintah berikut menggunakan substitusi TAG_NAME:

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

Contoh berikut menggunakan substitusi default $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER, dan $REVISION_ID.

YAML

steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
  args: ['bash', './myscript.sh']
  env:
  - 'BUILD=$BUILD_ID'
  - 'PROJECT_ID=$PROJECT_ID'
  - 'PROJECT_NUMBER=$PROJECT_NUMBER'
  - 'REV=$REVISION_ID'

# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.']

# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/my-image'

JSON

{
  "steps": [{
      "name": "ubuntu",
      "args": [
        "bash",
        "./myscript.sh"
      ],
      "env": [
        "BUILD=$BUILD_ID",
        "PROJECT_ID=$PROJECT_ID",
        "PROJECT_NUMBER=$PROJECT_NUMBER",
        "REV=$REVISION_ID"
      ]
    }, {
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/my-image"
  ]
}

Contoh di bawah ini menunjukkan permintaan build yang menggunakan langkah build docker untuk mem-build image, lalu mengirim image ke Container Registry menggunakan substitusi $PROJECT_ID default:

Dalam contoh ini:

• Permintaan build memiliki satu langkah build, yang menggunakan langkah build docker di gcr.io/cloud-builders untuk mem-build image Docker.
  • Kolom args pada langkah ini menentukan argumen yang akan diteruskan ke perintah docker, dalam hal ini build -t gcr.io/my-project/cb-demo-img ., akan dipanggil (setelah $PROJECT_ID diganti dengan project ID Anda).

• Kolom images berisi nama gambar. Jika build berhasil, image yang dihasilkan akan dikirim ke Container Registry. Jika image tidak berhasil dibuat oleh build, build akan gagal.

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/cb-demo-img"
  ]
}

Menggunakan substitusi yang ditentukan pengguna

Anda juga dapat menentukan substitusi Anda sendiri. Substitusi yang ditentukan pengguna harus sesuai dengan aturan berikut:

• Substitusi harus dimulai dengan garis bawah (_) serta hanya menggunakan huruf besar dan angka (sesuai dengan ekspresi reguler _[A-Z0-9_]+). Hal ini mencegah konflik dengan substitusi bawaan. Untuk menggunakan ekspresi yang dimulai dengan $, Anda harus menggunakan $$. Jadi:
  • $FOO tidak valid karena bukan substitusi bawaan.
  • $$FOO mengevaluasi ke string literal $FOO.
• Jumlah parameter dibatasi hingga 200 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang parameter value dibatasi hingga 4.000 byte.

Anda dapat menentukan variabel dengan salah satu dari dua cara berikut: $_FOO atau ${_FOO}:

• $_FOO dan ${_FOO} dievaluasi ke nilai _FOO. Namun, ${} memungkinkan substitusi berfungsi tanpa spasi di sekitarnya, yang memungkinkan substitusi seperti ${_FOO}BAR.
• $$ memungkinkan Anda menyertakan $ literal dalam template. Jadi:
  • $_FOO bernilai _FOO.
  • $$_FOO mengevaluasi ke string literal $_FOO.
  • $$$_FOO mengevaluasi ke string literal $ yang diikuti dengan nilai _FOO.

Untuk menggunakan substitusi, gunakan argumen --substitutions dalam perintah gcloud atau tentukan dalam file konfigurasi.

Contoh berikut menunjukkan konfigurasi build dengan dua substitusi yang ditentukan pengguna yang disebut _NODE_VERSION_1 dan _NODE_VERSION_2:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_1}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
         '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_2}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
         '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

JSON

{
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1"
        "_NODE_VERSION_1": "v6.9.2"
    },
    "images": [
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
    ]
}

Untuk mengganti nilai substitusi yang Anda tentukan dalam file konfigurasi build, gunakan flag --substitutions pada perintah gcloud builds submit. Perlu diperhatikan bahwa substitusi adalah pemetaan variabel terhadap nilai, bukan array atau urutan. Anda dapat mengganti nilai variabel substitusi default, kecuali untuk $PROJECT_ID dan $BUILD_ID. Perintah berikut mengganti nilai default untuk _NODE_VERSION_1 yang ditentukan dalam file konfigurasi build di atas:

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .

Secara default, build akan menampilkan error jika ada variabel substitusi yang tidak ada atau substitusi tidak ada. Namun, Anda dapat menetapkan opsi ALLOW_LOOSE untuk melewati pemeriksaan ini.

Cuplikan berikut mencetak "hello world" dan menentukan substitusi yang tidak digunakan. Karena opsi substitusi ALLOW_LOOSE ditetapkan, build akan berhasil meskipun substitusi tidak ada.

YAML

steps:
- name: 'ubuntu'
  args: ['echo', 'hello world']
substitutions:
    _SUB_VALUE: unused
options:
    substitutionOption: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "unused"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

Jika build Anda dipanggil oleh pemicu, opsi ALLOW_LOOSE akan ditetapkan secara default. Dalam hal ini, build Anda tidak akan menampilkan error jika ada variabel substitusi yang tidak ada atau substitusi tidak ada. Anda tidak dapat mengganti opsi ALLOW_LOOSE untuk build yang dipanggil oleh pemicu.

Jika opsi ALLOW_LOOSE tidak ditentukan, kunci yang tidak cocok dalam pemetaan penggantian atau permintaan build akan menyebabkan error. Misalnya, jika permintaan build Anda menyertakan $_FOO dan pemetaan substitusi tidak menentukan _FOO, Anda akan menerima error setelah menjalankan build atau memanggil pemicu jika pemicu Anda menyertakan variabel substitusi.

Variabel substitusi berikut selalu berisi nilai string kosong default meskipun Anda tidak menetapkan opsi ALLOW_LOOSE:

• $REPO_NAME
• $REPO_FULL_NAME
• $BRANCH_NAME
• $TAG_NAME
• $COMMIT_SHA
• $SHORT_SHA

Saat menentukan variabel substitusi, Anda tidak dibatasi pada string statis. Anda juga memiliki akses ke payload peristiwa yang memanggil pemicu. Binding ini tersedia sebagai binding payload. Anda juga dapat menerapkan perluasan parameter bash pada variabel substitusi dan menyimpan string yang dihasilkan sebagai variabel substitusi baru. Untuk mempelajari lebih lanjut, lihat Menggunakan binding payload dan perluasan parameter bash dalam substitusi.

Substitusi dinamis

Anda dapat mereferensikan nilai variabel lain dalam substitusi yang ditentukan pengguna dengan menetapkan opsi dynamicSubstitutions ke true dalam file konfigurasi build Anda. Jika build Anda dipanggil oleh pemicu, kolom dynamicSubstitutions akan selalu ditetapkan ke true dan tidak perlu ditentukan dalam file konfigurasi build Anda. Jika build dipanggil secara manual, Anda harus menetapkan kolom dynamicSubstitutions ke true agar ekspansi parameter bash dapat ditafsirkan saat menjalankan build.

File konfigurasi build berikut menampilkan variabel substitusi ${_IMAGE_NAME} yang mereferensikan variabel, ${PROJECT_ID}. Kolom dynamicSubstitutions ditetapkan ke true sehingga referensi diterapkan saat memanggil build secara manual:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
    dynamicSubstitutions: true

JSON

{
   "steps": [
      {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
            "build",
            "-t",
            "${_IMAGE_NAME}",
            "."
         ]
      }
   ],
   "substitutions": {
      "_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image"
   },
   "options": {
      "dynamic_substitutions": true
   }
}

Untuk informasi selengkapnya, lihat Menerapkan perluasan parameter bash.

Memetakan substitusi ke variabel lingkungan

Skrip tidak secara langsung mendukung penggantian, tetapi mendukung variabel lingkungan. Anda dapat memetakan substitusi ke variabel lingkungan, baik secara otomatis sekaligus, atau secara manual dengan menentukan sendiri setiap variabel lingkungan.

Memetakan substitusi secara otomatis

• Di level build. Untuk otomatis memetakan semua substitusi ke variabel lingkungan, yang akan tersedia di seluruh build, tetapkan automapSubstitutions ke true sebagai opsi pada level build. Misalnya, file konfigurasi build berikut menampilkan $_USER substitusi yang ditentukan pengguna dan $PROJECT_ID substitusi default yang dipetakan ke variabel lingkungan:

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
  options:
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'"
      }
    ],
    "options": {
      "automap_substitutions": true
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  }
  

• Di tingkat langkah. Untuk memetakan semua substitusi secara otomatis dan menyediakannya sebagai variabel lingkungan dalam satu langkah, tetapkan kolom automapSubstitutions ke true pada langkah tersebut. Dalam contoh berikut, hanya langkah kedua yang akan menampilkan substitusi dengan benar, karena hanya langkah tersebut yang mengaktifkan pemetaan substitusi otomatis:

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
        "automap_substitutions": true
      }
    ],
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  

  Selain itu, Anda dapat membuat substitusi tersedia sebagai variabel lingkungan di seluruh build, lalu mengabaikannya dalam satu langkah. Tetapkan automapSubstitutions ke true di tingkat build, lalu tetapkan kolom yang sama ke false pada langkah yang Anda inginkan untuk mengabaikan substitusi. Dalam contoh berikut, meskipun substitusi pemetaan diaktifkan di level build, project ID tidak akan dicetak pada langkah kedua, karena automapSubstitutions ditetapkan ke false pada langkah tersebut:

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: false
  options:
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
        "automap_substitutions": false
      }
    ],
    "options": {
      "automap_substitutions": true
    },
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  

Memetakan substitusi secara manual

Anda dapat memetakan substitusi ke variabel lingkungan secara manual. Setiap variabel lingkungan ditentukan di tingkat langkah menggunakan kolom env, dan cakupan variabel dibatasi pada langkah yang menentukannya. Kolom ini mengambil daftar kunci dan nilai.

Contoh berikut menunjukkan cara memetakan substitusi $PROJECT_ID ke variabel lingkungan BAR:

YAML

steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

Langkah selanjutnya

• Pelajari cara menggunakan binding payload dan perluasan parameter bash dalam substitusi.
• Pelajari cara membuat file konfigurasi build dasar.
• Pelajari cara membuat dan mengelola pemicu build.
• Pelajari cara menjalankan build secara manual di Cloud Build.