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 Branches oder Tags
  • $TRIGGER_BUILD_CONFIG_PATH: Der Pfad zu Ihrer Build-Konfigurationsdatei, der während der Build-Ausführung verwendet wird. Andernfalls ein leerer String, wenn der Build inline am Trigger konfiguriert ist oder einen Dockerfile oder Buildpack verwendet.
  • $SERVICE_ACCOUNT_EMAIL: E-Mail-Adresse des Dienstkontos, das Sie für den Build verwenden. Dies ist entweder ein Standarddienstkonto oder ein vom Nutzer angegebenes Dienstkonto.
  • $SERVICE_ACCOUNT: Ressourcenname des Dienstkontos im Format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

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 Standardsubstitutionen $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 genau einen Build-Schritt, der den docker-Build-Schritt in gcr.io/cloud-builders dazu verwendet, 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 $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO verwenden. $$. Thus:
      • $FOO is invalid since it is not a built-in substitution.
      • $$FOO ergibt den Literalstring $FOO.
    • Es sind maximal 200 Parameter zulässig. 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.
      • $$ allows you to include a literal $ in the template. Thus:
        • $_FOO evaluates to the value of _FOO.
        • $$_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 Substitutionsvariablen enthalten immer einen standardmäßigen leeren Stringwert, 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.

        In der folgenden Build-Konfigurationsdatei wird die Substitutionsvariable ${_IMAGE_NAME} gezeigt, die auf die Variable ${PROJECT_ID} verweist. Das Feld dynamicSubstitutions ist auf true gesetzt, sodass die Referenz 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.

        Ersetzen von Variablen durch Umgebungsvariablen

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

        Ersetzungen automatisch zuordnen

        • Auf Buildebene Wenn Sie alle Substitutionen automatisch Umgebungsvariablen zuordnen möchten, die während des gesamten Builds verfügbar sind, legen Sie auf Buildebene die Option automapSubstitutions auf true fest. In der folgenden Build-Konfigurationsdatei sind beispielsweise die benutzerdefinierte Substitution $_USER und die Standardsubstitution $PROJECT_ID auf Umgebungsvariablen zugeordnet:

          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 in einem einzigen Schritt als Umgebungsvariablen verfügbar machen möchten, setzen Sie das Feld automapSubstitutions in diesem Schritt auf true. Im folgenden Beispiel werden die Ersetzungen nur im zweiten Schritt korrekt angezeigt, da dort die automatische Zuordnung von Ersetzungen 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 Ersetzungen als Umgebungsvariablen im gesamten Build verfügbar machen und sie dann in einem Schritt ignorieren. Legen Sie auf Build-Ebene automapSubstitutions auf true fest und dann dasselbe Feld in dem Schritt auf false, in dem Sie die Ersetzungen ignorieren möchten. Im folgenden Beispiel wird die Projekt-ID im zweiten Schritt nicht ausgegeben, obwohl die Zuordnungssubstitutionen auf Buildebene aktiviert sind, da automapSubstitutions in diesem Schritt auf false festgelegt 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"
  }

        Substitutionen manuell zuordnen

        Sie können die Ersetzungen manuell Umgebungsvariablen zuordnen. Jede Umgebungsvariable wird auf Schrittebene mithilfe des Felds env definiert. Der Gültigkeitsbereich der Variablen ist auf den Schritt beschränkt, in dem sie definiert sind. Dieses Feld nimmt eine Liste von Schlüsseln und Werten an.

        Im folgenden Beispiel wird gezeigt, 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