Variablenwerte ersetzen

Verwenden Sie substitutions in Ihrer Build-Konfigurationsdatei dazu, bestimmte Variablen zum Build-Zeitpunkt zu ersetzen.

Substitutionen sind für Variablen geeignet, deren Wert bis zur Erstellung des Builds nicht bekannt ist. Mit Substitutionen können Sie auch eine vorhandene Build-Anfrage mit anderen Variablenwerten wieder verwenden.

Mit Cloud Build können Sie die bereits integrierten Substitutionen verwenden oder eigene Substitutionen definieren. Verwenden Sie substitutions in der steps und images Ihres Builds, um deren Werte bei der Build-Erstellung aufzulösen.

Auf dieser Seite wird erläutert, wie Sie Standardsubstitutionen verwenden oder Ihre eigenen substitutions definieren.

Standardsubstitutionen

Cloud Build bietet die folgenden Standardsubstitutionen für alle Builds:

• $PROJECT_ID: ID Ihres Cloudprojekts
• $BUILD_ID: ID Ihres Builds
• $PROJECT_NUMBER: Ihre Projektnummer
• $LOCATION: die mit Ihrem Build verknüpfte Region

Cloud Build bietet die folgenden Standardsubstitutionen für Builds, die von Triggern aufgerufen werden:

• $TRIGGER_NAME: der mit dem Trigger verknüpfte Name
• $COMMIT_SHA: die mit Ihrem Build verknüpfte Commit-ID
• $REVISION_ID: die mit Ihrem Build verknüpfte Commit-ID
• $SHORT_SHA : die ersten sieben Zeichen von COMMIT_SHA
• $REPO_NAME: der Name Ihres Repositorys
• $REPO_FULL_NAME: der vollständige Name Ihres Repositorys, einschließlich Nutzer oder Organisation
• $BRANCH_NAME: der Name Ihres Branch
• $TAG_NAME: der Name Ihres Tags
• $REF_NAME: der Name Ihres Zweigs oder Tags
• $TRIGGER_BUILD_CONFIG_PATH: Der Pfad zu Ihrer Build-Konfigurationsdatei, die während der Build-Ausführung verwendet wird. Andernfalls ein leerer String, wenn Ihr Build inline im Trigger konfiguriert ist oder ein Dockerfile- oder Buildpack-Element verwendet.
• $SERVICE_ACCOUNT_EMAIL ist die E-Mail-Adresse des Dienstkontos, das Sie für den Build verwenden. Dies ist entweder ein Standarddienstkonto oder ein benutzerdefiniertes Dienstkonto.
• $SERVICE_ACCOUNT: der Ressourcenname des Dienstkontos im Format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

Hinweis: Sowohl $COMMIT_SHA als auch $REVISION_ID stehen für die Commit-ID, die Ihrem Build zugeordnet ist. Beide Substitutionen werden unterstützt.

Cloud Build bietet die folgenden GitHub-spezifischen Standardsubstitutionen, die für Pull-Anfrage-Trigger verfügbar sind:

• $_HEAD_BRANCH: oberster Zweig der Pull-Anfrage
• $_BASE_BRANCH: Basiszweig der Pull-Anfrage
• $_HEAD_REPO_URL: URL des Head-Repositorys der Pull-Anfrage
• $_PR_NUMBER: Nummer der Pull-Anfrage

Wenn keine Standardsubstitution verfügbar ist, z. B. in Builds ohne Quelle oder in Builds, die eine Speicherquelle verwenden, werden fehlende Variablen durch einen leeren String ersetzt.

Wenn Sie einen Build mit gcloud builds submit starten, können Sie mit dem Argument --substitutions Variablen angeben, die normalerweise aus ausgelösten Builds übergeben werden. Insbesondere haben Sie die Möglichkeit, manuell Werte für folgende Variablen bereitzustellen:

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

Der folgende Befehl verwendet beispielsweise die Substitution TAG_NAME:

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

Im folgenden Beispiel werden die Standardersetzungen $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER und $REVISION_ID verwendet.

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

Das folgende Beispiel zeigt, wie eine Build-Anfrage den Build-Schritt docker verwendet, um ein Image zu erstellen, und das Image dann mit der Standardsubstitution $PROJECT_ID per Push in Container Registry überträgt:

In diesem Beispiel:

• Die Build-Anfrage enthält einen Build-Schritt, der den Build-Schritt docker in gcr.io/cloud-builders verwendet, um das Docker-Image zu erstellen.
  • Das Feld args im Build-Schritt definiert die Argumente, die an den docker-Befehl übergeben werden sollen. In diesem Fall wird build -t gcr.io/my-project/cb-demo-img . aufgerufen (nachdem $PROJECT_ID durch Ihre Projekt-ID ersetzt wurde).

• Das Feld images enthält den Namen des Images. Wenn der Build erfolgreich ist, wird das resultierende Image per Push in Container Registry übertragen. Wenn das Image während des Build-Prozesses nicht erstellt wird, schlägt der Build fehl.

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

Benutzerdefinierte Substitutionen verwenden

Sie können außerdem Ihre eigenen Substitutionen definieren. Benutzerdefinierte Substitutionen müssen folgende Kriterien erfüllen:

• Substitutionen müssen mit einem Unterstrich (_) beginnen und dürfen entsprechend dem regulären Ausdruck _[A-Z0-9_]+ nur Großbuchstaben und Ziffern enthalten. Dadurch werden Konflikte mit integrierten Substitutionen verhindert. Zum Verwenden eines Ausdrucks, der mit $ beginnt, müssen Sie $$ verwenden. Das heißt:
  • $FOO ist ungültig, da es sich nicht um eine integrierte Substitution handelt.
  • $$FOO ergibt den Literalstring $FOO.
• Die Anzahl der Parameter ist auf 200 Parameter beschränkt. Die Länge des Parameterschlüssels ist auf 100 Byte und die Länge des Parameterwerts auf 4.000 Byte begrenzt.

Sie können Variablen auf zwei Arten angeben: $_FOO oder ${_FOO}:

• Sowohl $_FOO als auch ${_FOO} ergeben den Wert _FOO. ${} lässt jedoch die Ersetzung ohne umgebende Leerzeichen zu, damit Substitutionen wie ${_FOO}BAR möglich sind.
• Mit $$ können Sie eine Literal $ in die Vorlage einfügen. Das heißt:
  • $_FOO wird mit dem Wert von _FOO ausgewertet.
  • $$_FOO ergibt den Literalstring $_FOO.
  • $$$_FOO ergibt den Literalstring $, gefolgt vom Wert von _FOO.

Wenn Sie Substitutionen verwenden möchten, fügen Sie dem gcloud-Befehl das Argument --substitutions hinzu oder geben die Substitutionen in der Konfigurationsdatei an.

Das folgende Beispiel zeigt eine Build-Konfiguration mit den beiden benutzerdefinierten Substitutionen _NODE_VERSION_1 und _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}"
    ]
}

Verwenden Sie zum Überschreiben des in der Build-Konfigurationsdatei angegebenen Substitutionswerts im Befehl gcloud builds submit das Flag --substitutions. Beachten Sie, dass Substitutionen eine Zuordnung von Variablen zu Werten sind, nicht zu Arrays oder Sequenzen. Sie können die Werte der standardmäßigen Substitutionsvariablen außer $PROJECT_ID und $BUILD_ID überschreiben. Der folgende Befehl überschreibt den Standardwert für _NODE_VERSION_1, der in der Build-Konfigurationsdatei oben angegeben wurde:

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

Standardmäßig gibt der Build einen Fehler zurück, wenn eine Substitutionsvariable oder eine Substitution fehlt. Sie können jedoch diese Überprüfung mit der Option ALLOW_LOOSE überspringen.

Das folgende Snippet gibt "Hello World" aus und definiert eine nicht verwendete Substitution. Da die Substitutionsoption ALLOW_LOOSE festgelegt ist, wird der Build trotz der fehlenden Substitution ausgeführt.

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

Wenn Ihr Build von einem Trigger aufgerufen wird, ist die Option ALLOW_LOOSE standardmäßig festgelegt. In diesem Fall gibt der Build keinen Fehler zurück, wenn eine Substitutionsvariable oder eine Substitution fehlt. Sie können die Option ALLOW_LOOSE für Builds, die durch Trigger aufgerufen werden, nicht überschreiben.

Wenn die Option ALLOW_LOOSE nicht angegeben ist, führen nicht übereinstimmende Schlüssel in der Substitutionszuordnung oder Build-Anfrage zu einem Fehler. Wenn beispielsweise in Ihrer Build-Anfrage $_FOO enthalten ist und _FOO in der Substitutionszuordnung nicht definiert ist, wird nach dem Ausführen des Builds oder beim Aufrufen eines Triggers ein Fehler ausgegeben, falls der Trigger Substitutionsvariablen enthält.

Die folgenden Ersatzvariablen enthalten immer einen leeren Standardstringwert, auch wenn Sie die Option ALLOW_LOOSE nicht festlegen:

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

Beim Definieren einer Substitutionsvariable sind Sie nicht auf statische Strings beschränkt. Sie haben auch Zugriff auf die Ereignisnutzlast, die den Trigger ausgelöst hat. Diese sind als Nutzlastbindungen verfügbar. Sie können auch Bash-Parametererweiterungen auf Substitutionsvariablen anwenden und den resultierenden String als neue Substitutionsvariable speichern. Weitere Informationen finden Sie unter Nutzlastbindungen und Bash-Parametererweiterungen in Substitutionen verwenden.

Dynamische Substitutionen

Sie können in einer benutzerdefinierten Substitution auf den Wert einer anderen Variablen verweisen. Setzen Sie dazu die Option dynamicSubstitutions in der Build-Konfigurationsdatei auf true. Wenn Ihr Build von einem Trigger aufgerufen wird, ist das Feld dynamicSubstitutions immer auf true gesetzt und muss nicht in der Build-Konfigurationsdatei angegeben werden. Wenn Ihr Build manuell aufgerufen wird, müssen Sie das Feld dynamicSubstitutions auf true setzen, damit die Bash-Parametererweiterungen beim Ausführen des Builds interpretiert werden.

Die folgende Build-Konfigurationsdatei zeigt die Substitutionsvariable ${_IMAGE_NAME}, die auf die Variable ${PROJECT_ID} verweist. Das Feld dynamicSubstitutions ist auf true gesetzt, sodass der Verweis angewendet wird, wenn ein Build manuell aufgerufen wird:

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

Weitere Informationen finden Sie unter Bash-Parametererweiterungen anwenden.

Substitutionen zu Umgebungsvariablen zuordnen

Skripts unterstützen Substitutionen nicht direkt, aber Umgebungsvariablen. Sie können Substitutionen Umgebungsvariablen zuordnen, entweder automatisch alle auf einmal oder manuell, indem Sie jede Umgebungsvariablen selbst definieren.

Automatische Ersetzung von Karten

• Auf Build-Ebene: Wenn alle Substitutionen automatisch Umgebungsvariablen zugeordnet werden sollen, die im gesamten Build verfügbar sind, legen Sie auf Build-Ebene für automapSubstitutions die Option true fest. Die folgende Build-Konfigurationsdatei zeigt beispielsweise die benutzerdefinierte Substitution $_USER und die Standardersetzung $PROJECT_ID, die Umgebungsvariablen zugeordnet sind:

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

• Auf Schrittebene: Wenn Sie alle Substitutionen automatisch zuordnen und als Umgebungsvariablen in einem Schritt verfügbar machen möchten, setzen Sie das Feld automapSubstitutions in diesem Schritt auf true. Im folgenden Beispiel werden die Substitutionen nur im zweiten Schritt korrekt angezeigt, da die automatische Substitutionszuordnung nur hier aktiviert ist:

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

  Außerdem können Sie die Substitutionen als Umgebungsvariablen im gesamten Build verfügbar machen und dann in einem Schritt ignorieren. Setzen Sie automapSubstitutions auf Build-Ebene auf true und setzen Sie dann dasselbe Feld in dem Schritt, in dem Sie die Substitutionen ignorieren möchten, auf false. Im folgenden Beispiel wird die Projekt-ID im zweiten Schritt nicht ausgegeben, obwohl die Zuordnung von Substitutionen auf Build-Ebene aktiviert ist, da automapSubstitutions in diesem Schritt auf false gesetzt ist:

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

Manuelle Kartenersetzungen

Sie können die Substitutionen Umgebungsvariablen manuell zuordnen. Jede Umgebungsvariable wird auf Schrittebene mit dem Feld env definiert und der Umfang der Variablen wird auf den Schritt beschränkt, in dem sie definiert werden. Dieses Feld enthält eine Liste mit Schlüsseln und Werten.

Das folgende Beispiel zeigt, wie die Substitution $PROJECT_ID der Umgebungsvariablen BAR zugeordnet wird:

YAML

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

JSON

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

Nächste Schritte

• Nutzlastbindungen und Bash-Parametererweiterungen in Substitutionen verwenden.
• Einfache Build-Konfigurationsdatei erstellen
• Weitere Informationen finden Sie unter Build-Trigger erstellen und verwalten.
• Builds manuell in Cloud Build starten