החלפת ערכי משתנים

משתמשים ב-substitutions בקובץ התצורה של ה-build כדי להחליף משתנים ספציפיים בזמן ה-build.

החלפות שימושיות למשתנים שהערך שלהם לא ידוע עד משך זמן של תהליך build, או לשימוש חוזר בבקשת בנייה קיימת עם ערכים שונים של משתנים.

‫Cloud Build מספק החלפות מובנות, או שאתם יכולים להגדיר החלפות משלכם. משתמשים ב-substitutions ב-steps וב-images של ה-build כדי לפתור את הערכים שלהם בזמן ה-build.

בדף הזה מוסבר איך להשתמש בהחלפות ברירת מחדל או להגדיר החלפות משלכםsubstitutions.

שימוש בהחלפות ברירת המחדל

‫Cloud Build מספק את החלפות ברירת המחדל הבאות לכל הבנייה:

• ‫$PROJECT_ID: מזהה הפרויקט בענן
• ‫$BUILD_ID: המזהה של הגרסה
• ‫$PROJECT_NUMBER: מספר הפרויקט
• ‫$LOCATION: האזור שמשויך ל-build

‫Cloud Build מספק את החלפות ברירת המחדל הבאות עבור בנייה שהופעלה על ידי טריגרים:

• ‫$TRIGGER_NAME: השם שמשויך לטריגר
• ‫$COMMIT_SHA: מזהה הקומיט שמשויך ל-build
• ‫$REVISION_ID: מזהה הקומיט שמשויך ל-build
• ‫$SHORT_SHA : שבעת התווים הראשונים של COMMIT_SHA
• ‫$REPO_NAME: השם של המאגר
• ‫$REPO_FULL_NAME: השם המלא של המאגר, כולל המשתמש או הארגון
• $BRANCH_NAME: השם של הענף
• ‫$TAG_NAME: השם של התג
• ‫$REF_NAME: השם של הענף או התג
• ‫$TRIGGER_BUILD_CONFIG_PATH: הנתיב לקובץ הגדרות ה-build שבו נעשה שימוש במהלך ההפעלה של ה-build. אחרת, מחרוזת ריקה אם ה-build מוגדר בשורה בטריגר או אם נעשה בו שימוש ב-Dockerfile או ב-Buildpack.
• ‫$SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שבו אתם משתמשים לבנייה. זהו חשבון שירות שמוגדר כברירת מחדל או חשבון שירות שצוין על ידי המשתמש.
• ‫$SERVICE_ACCOUNT: שם המשאב של חשבון השירות, בפורמט projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

הערה: גם $COMMIT_SHA וגם $REVISION_ID מייצגים את מזהה השמירה (commit) שמשויך לבנייה שלכם. יש תמיכה בשני סוגי ההחלפות.

‫Cloud Build מספק את ההחלפות הבאות שספציפיות ל-GitHub וזמינות לטריגרים של בקשות משיכה:

• ‫$_HEAD_BRANCH : ענף ה-head של ה-pull request
• ‫$_BASE_BRANCH : ענף הבסיס של ה-pull request
• ‫$_HEAD_REPO_URL : כתובת ה-URL של מאגר הראשי של בקשת משיכה
• ‫$_PR_NUMBER : מספר ה-pull request

אם אין תחליף שמוגדר כברירת מחדל (למשל, בבנייה ללא מקור או בבנייה שמשתמשת במקור אחסון), המערכת מחליפה את המופעים של המשתנה החסר במחרוזת ריקה.

כשמתחילים בנייה באמצעות gcloud builds submit, אפשר לציין משתנים שבדרך כלל מגיעים מבנייה מופעלת באמצעות הארגומנט --substitutions. באופן ספציפי, אתם יכולים לספק ערכים באופן ידני למאפיינים הבאים:

• $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

לדוגמה, הפקודה הבאה משתמשת בהחלפה TAG_NAME:

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

בדוגמה הבאה נעשה שימוש בהחלפות ברירת המחדל $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER ו-$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"
  ]
}

בדוגמה הבאה מוצגת בקשת build באמצעות שלב ה-build‏ docker ליצירת קובץ אימג', ואז העברת קובץ האימג' ל-Artifact Registry באמצעות החלפת ברירת המחדל $PROJECT_ID:

בדוגמה הזו:

• בקשת ה-build כוללת שלב build אחד, שמשתמש בשלב ה-build‏ docker ב-gcr.io/cloud-builders כדי ליצור את קובץ האימג' של Docker.
  • השדה args בשלב מציין את הארגומנטים שיועברו לפקודה docker, ובמקרה הזה הפקודה build -t gcr.io/my-project/cb-demo-img . תופעל (אחרי שהערך $PROJECT_ID יוחלף במזהה הפרויקט).

• השדה images מכיל את שם התמונה. אם הבנייה תצליח, התמונה שנוצרה תועבר אל Artifact Registry. אם התמונה לא נוצרת בהצלחה על ידי ה-build, ה-build ייכשל.

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"
  ]
}

שימוש בהחלפות שהוגדרו על ידי המשתמש

אפשר גם להגדיר החלפות משלכם. החלפות שהוגדרו על ידי המשתמש חייבות לעמוד בכללים הבאים:

• ההחלפות חייבות להתחיל בקו תחתון (_) ולהכיל רק אותיות רישיות ומספרים (בהתאם לביטוי הרגולרי _[A-Z0-9_]+). כך נמנעים עימותים עם החלפות מובנות. כדי להשתמש בביטוי שמתחיל ב-$, צריך להשתמש ב-$$. For example:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO שמוערך למחרוזת המילולית $FOO.
• מספר הפרמטרים מוגבל ל-200. אורך מפתח הפרמטר מוגבל ל-100 בייט, ואורך ערך הפרמטר מוגבל ל-4,000 בייט.

אפשר לציין משתנים באחת משתי דרכים: $_FOO או ${_FOO}:

• הפונקציות $_FOO ו-${_FOO} מחזירות את הערך של _FOO. עם זאת, ${} מאפשר להחליף בלי רווחים מסביב, כך שאפשר להחליף כמו ${_FOO}BAR.
• הפונקציה $$ lets you include a literal $ in the template. For example:
  • $_FOO evaluates to the value of _FOO.
  • $$_FOO מחזירה את מחרוזת הליטרל $_FOO.
  • הפונקציה $$$_FOO מחזירה את המחרוזת $ ואחריה את הערך של _FOO.

  כדי להשתמש בהחלפות, משתמשים בארגומנט --substitutions בפקודה gcloud או מציינים אותן בקובץ ההגדרות.

  הדוגמה הבאה מציגה קובץ הגדרות build עם שני משתני החלפה שהוגדרו על ידי המשתמש, שנקראים _NODE_VERSION_1 ו-_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}"
      ]
  }
  

  כדי לשנות את ערך ההחלפה שציינתם בקובץ הגדרות ה-build, משתמשים בדגל --substitutions בפקודה gcloud builds submit. הערה: ההחלפות הן מיפוי של משתנים לערכים ולא למערכים או לרצפים. אפשר לשנות את ערכי ברירת המחדל של משתני החלפה, חוץ מהערכים של $PROJECT_ID ו-$BUILD_ID. הפקודה הבאה משנה את ערך ברירת המחדל של _NODE_VERSION_1 שצוין בקובץ התצורה של ה-build הקודם:

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

  כברירת מחדל, אם חסר משתנה החלפה או החלפה, תהליך הבנייה מחזיר שגיאה. עם זאת, אפשר להגדיר את האפשרות ALLOW_LOOSE כדי לדלג על הבדיקה הזו.

  קטע הקוד הבא מדפיס את המחרוזת hello world ומגדיר החלפה שלא נעשה בה שימוש. מכיוון שהוגדרה אפשרות ההחלפה ALLOW_LOOSE, הבנייה תצליח למרות ההחלפה החסרה.

  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"
      }
  }
  

  אם ה-build מופעל על ידי טריגר, האפשרות ALLOW_LOOSE מוגדרת כברירת מחדל. במקרה כזה, אם חסר משתנה חלופי או חסר תחליף, הגרסה לא תחזיר שגיאה. אי אפשר לשנות את האפשרות ALLOW_LOOSE עבור גרסאות build שמופעלות על ידי טריגרים.

  אם לא מציינים את האפשרות ALLOW_LOOSE, מפתחות שלא תואמים למיפוי ההחלפות או לבקשת הבנייה יגרמו לשגיאה. לדוגמה, אם בקשת ה-build שלכם כוללת את $_FOO ומיפוי ההחלפות לא מגדיר את _FOO, תקבלו שגיאה אחרי שתפעילו את ה-build או תפעילו טריגר, אם הטריגר כולל משתני החלפה.

  משתני ההחלפה הבאים תמיד מכילים ערך ברירת מחדל של מחרוזת ריקה, גם אם לא מגדירים את האפשרות ALLOW_LOOSE:

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

  כשמגדירים משתנה חלופי, לא חייבים להשתמש במחרוזות סטטיות. יש לכם גם גישה למטען הייעודי (payload) של האירוע שהפעיל את הטריגר. הם זמינים כקישורי מטען ייעודי. אפשר גם להחיל הרחבות של פרמטרים ב-Bash על משתני החלפה ולאחסן את המחרוזת שמתקבלת כמשתנה החלפה חדש. למידע נוסף, אפשר לעיין במאמר בנושא שימוש בקישורי מטען ובהרחבות של פרמטרים ב-Bash בהחלפות.

  החלפות דינמיות

  כדי להפנות לערך של משתנה אחר בתוך החלפה מוגדרת על ידי המשתמש, צריך להגדיר את האפשרות dynamicSubstitutions לערך true בקובץ תצורת ה-build. אם ה-build מופעל על ידי טריגר, השדה dynamicSubstitutions תמיד מוגדר לערך true ואין צורך לציין אותו בקובץ התצורה של ה-build. אם ההפעלה של ה-build מתבצעת באופן ידני, צריך להגדיר את השדה dynamicSubstitutions לערך true כדי שהרחבות של פרמטרים של bash יפורשו בזמן הפעלת ה-build.

  בקובץ התצורה הבא של ה-build מוצג משתנה ההחלפה ${_IMAGE_NAME} שמפנה למשתנה ${PROJECT_ID}. השדה dynamicSubstitutions מוגדר לערך true, כך שההפניה מוחלת כשמפעילים בנייה באופן ידני:

  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
      }
  }
  

  מידע נוסף זמין במאמר בנושא החלת הרחבות של פרמטרים ב-Bash.

  מיפוי של תחליפים למשתני סביבה

  סקריפטים לא תומכים ישירות בהחלפות, אבל הם תומכים במשתני סביבה. אפשר למפות החלפות למשתני סביבה, באופן אוטומטי בבת אחת או באופן ידני על ידי הגדרה של כל משתנה סביבה.

  מיפוי אוטומטי של החלפות

  • ברמת ה-build. כדי למפות באופן אוטומטי את כל ההחלפות למשתני סביבה שיהיו זמינים לאורך כל תהליך ה-build, מגדירים את automapSubstitutions ל-true כאפשרות ברמת ה-build. לדוגמה, בקובץ הגדרות הבנייה הבא מוצג המיפוי של ההחלפה שהוגדרה על ידי המשתמש $_USER וההחלפה שמוגדרת כברירת מחדל $PROJECT_ID למשתני סביבה:

    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"
      }
    }
    

  • ברמת השלב. כדי למפות באופן אוטומטי את כל ההחלפות ולהפוך אותן למשתני סביבה בפעולה אחת, מגדירים את השדה automapSubstitutions לערך true בשלב הזה. בדוגמה הבאה, רק בשלב השני יוצגו ההחלפות בצורה נכונה, כי רק בו מופעל מיפוי אוטומטי של החלפות:

    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"
      }
    

    בנוסף, אפשר להגדיר את ההחלפות כמשתני סביבה בכל הבנייה, ואז להתעלם מהן בשלב אחד. מגדירים את automapSubstitutions ל-true ברמת ה-build, ואז מגדירים את אותו השדה ל-false בשלב שבו רוצים להתעלם מההחלפות. בדוגמה הבאה, למרות שהחלפות מיפוי מופעלות ברמת ה-build, מזהה הפרויקט לא יודפס בשלב השני, כי automapSubstitutions מוגדר ל-false בשלב הזה:

    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"
      }
    

  מיפוי ידני של החלפות

  אפשר למפות ידנית את ההחלפות למשתני סביבה. כל משתנה סביבה מוגדר ברמת השלב באמצעות השדה env, וההיקף של המשתנים מוגבל לשלב שבו הם מוגדרים. בשדה הזה צריך להזין רשימה של מפתחות וערכים.

  בדוגמה הבאה אפשר לראות איך ממפים את ההחלפה $PROJECT_ID למשתנה הסביבה BAR:

  YAML

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

  JSON

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

  המאמרים הבאים

  • איך משתמשים בהתאמות של מטען ייעודי (payload) ובהרחבות של פרמטרים ב-Bash כדי לבצע החלפות
  • איך יוצרים קובץ הגדרות בסיסי של בנייה
  • איך יוצרים ומנהלים טריגרים לבנייה
  • איך מריצים בנייה באופן ידני ב-Cloud Build