Mengganti nilai variabel

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

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

Cloud Build menyediakan substitusi bawaan atau Anda dapat menentukan substitusi sendiri. Gunakan substitutions di steps dan images build Anda untuk menyelesaikan 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 Anda dikonfigurasi inline pada pemicu atau menggunakan Dockerfile atau Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: email akun layanan yang Anda gunakan untuk build. Ini adalah akun layanan default atau akun layanan yang ditentukan pengguna.
  • $SERVICE_ACCOUNT: nama resource akun layanan, dalam format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

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 utama permintaan pull
  • $_PR_NUMBER : nomor permintaan pull

Jika substitusi default tidak tersedia (seperti pada build tanpa sumber, atau dengan build yang menggunakan sumber penyimpanan), kemunculan variabel yang tidak ada 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', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/my-image', '.']

# my-image is pushed to Artifact Registry
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/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 berikut menunjukkan permintaan build menggunakan langkah build docker untuk membangun image, lalu mengirim image ke Artifact 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 membangun image Docker.
    • Kolom args dalam 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 image. Jika build berhasil, image yang dihasilkan akan dikirim ke Artifact Registry. Jika image tidak berhasil dibuat oleh build, build akan gagal.

YAML

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

JSON

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

Menggunakan substitusi buatan pengguna

Anda juga dapat menentukan substitusi sendiri. Substitusi buatan pengguna harus mematuhi aturan berikut:

  • Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mematuhi ekspresi reguler _[A-Z0-9_]+). Hal ini mencegah konflik dengan substitusi bawaan. Untuk menggunakan ekspresi yang dimulai dengan $ Anda harus menggunakan $$. For example:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO yang dievaluasi ke string literal $FOO.
  • Jumlah parameter dibatasi hingga 200 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

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

    • Both $_FOO and ${_FOO} dievaluasi ke nilai _FOO. Namun, ${} memungkinkan substitusi berfungsi tanpa spasi di sekitarnya, yang memungkinkan substitusi seperti ${_FOO}BAR.
    • $$ lets you include a literal $ in the template. For example:
      • $_FOO evaluates to the value of _FOO.
      • $$_FOO dievaluasi ke string literal $_FOO.
      • $$$_FOO dievaluasi ke string literal $ yang diikuti dengan nilai _FOO.

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

      Contoh berikut menunjukkan konfigurasi build dengan dua substitusi buatan 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',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
          '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
          '--build-arg',
          'node_version=${_NODE_VERSION_2}',
          '-t',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}',
          '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

      JSON 

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

      Untuk mengganti nilai substitusi yang Anda tentukan dalam file konfigurasi build, gunakan tanda --substitutions dalam perintah gcloud builds submit. Perhatikan bahwa substitusi adalah pemetaan variabel ke nilai, bukan array atau urutan. Anda dapat mengganti nilai variabel substitusi default, kecuali $PROJECT_ID dan $BUILD_ID. Perintah berikut mengganti nilai default untuk _NODE_VERSION_1 yang ditentukan dalam file konfigurasi build sebelumnya:

      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 yang 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 yang 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 substitusi atau permintaan build akan menghasilkan 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. Payload ini tersedia sebagai binding payload. Anda juga dapat menerapkan ekspansi parameter bash pada variabel substitusi dan menyimpan string yang dihasilkan sebagai variabel substitusi baru. Untuk mempelajari lebih lanjut, lihat Menggunakan binding payload dan ekspansi parameter bash dalam substitusi.

      Substitusi dinamis

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

      File konfigurasi build berikut menunjukkan 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: '${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image'
options:
    dynamicSubstitutions: true

      JSON 

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

      Untuk mengetahui informasi selengkapnya, lihat Menerapkan ekspansi parameter bash.

      Memetakan substitusi ke variabel lingkungan

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

      Memetakan substitusi secara otomatis

      • Di tingkat build. Untuk memetakan semua substitusi ke variabel lingkungan secara otomatis, yang akan tersedia di seluruh build, tetapkan automapSubstitutions ke true sebagai opsi di tingkat build. Misalnya, file konfigurasi build berikut menunjukkan substitusi buatan pengguna $_USER dan substitusi default $PROJECT_ID 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 membuatnya tersedia sebagai variabel lingkungan dalam satu langkah, tetapkan kolom automapSubstitutions ke true dalam langkah tersebut. Dalam contoh berikut, hanya langkah kedua yang akan menampilkan substitusi dengan benar, karena hanya langkah kedua 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 di langkah tempat Anda ingin mengabaikan substitusi. Dalam contoh berikut, meskipun substitusi pemetaan diaktifkan di tingkat 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 ke langkah tempat variabel tersebut ditentukan. 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 berikutnya