Remplacer les valeurs des variables

Utilisez substitutions dans le fichier de configuration de compilation pour remplacer des variables spécifiques au moment de la compilation.

Les substitutions sont utiles pour les variables dont la valeur n'est pas connue avant la compilation ou pour réutiliser une demande de compilation existante avec différentes valeurs de variable.

Cloud Build propose des substitutions intégrées, mais vous avez également la possibilité de définir vos propres substitutions. Utilisez substitutions dans steps et images de votre compilation pour résoudre leurs valeurs au moment de la compilation.

Cette page explique comment utiliser les substitutions par défaut ou définir vos propres substitutions.

Utiliser des substitutions par défaut

Cloud Build fournit les substitutions par défaut suivantes pour toutes les compilations :

  • $PROJECT_ID : ID de votre projet Cloud
  • $BUILD_ID : ID de votre compilation
  • $PROJECT_NUMBER : votre numéro de projet
  • $LOCATION: région associée à votre build

Cloud Build fournit les substitutions par défaut suivantes pour les compilations appelées par des déclencheurs :

  • $TRIGGER_NAME : nom associé à votre déclencheur
  • $COMMIT_SHA : ID de commit associé à votre compilation
  • $REVISION_ID : ID de commit associé à votre compilation
  • $SHORT_SHA : les sept premiers caractères de COMMIT_SHA
  • $REPO_NAME : le nom de votre dépôt
  • $REPO_FULL_NAME: nom complet de votre dépôt, y compris l'utilisateur ou l'organisation
  • $BRANCH_NAME : le nom de votre agence
  • $TAG_NAME : le nom de votre tag
  • $REF_NAME: nom de votre branche ou de votre tag
  • $TRIGGER_BUILD_CONFIG_PATH: chemin d'accès au fichier de configuration de compilation utilisé lors de l'exécution de la compilation. Sinon, une chaîne vide est utilisée si votre build est configuré de manière intégrée sur le déclencheur, ou s'il utilise une Dockerfile ou une Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: adresse e-mail du compte de service que vous utilisez pour la compilation. Il s'agit d'un compte de service par défaut ou d'un compte de service spécifié par l'utilisateur.
  • $SERVICE_ACCOUNT: nom de ressource du compte de service au format projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL.

Cloud Build fournit les substitutions par défaut suivantes propres à GitHub disponibles pour les déclencheurs de demande d'extraction :

  • $_HEAD_BRANCH : branche principale de la demande d'extraction
  • $_BASE_BRANCH : branche principale de la demande d'extraction
  • $_HEAD_REPO_URL : URL du dépôt principal de la demande d'extraction
  • $_PR_NUMBER : numéro de la demande d'extraction

Si une substitution par défaut n'est pas disponible (par exemple, avec des compilations sans source ou avec des compilations qui utilisent une source de stockage), les occurrences de la variable manquante sont remplacées par une chaîne vide.

Lorsque vous démarrez une compilation à l'aide de gcloud builds submit, vous pouvez spécifier des variables qui proviendraient normalement de compilations déclenchées avec l'argument --substitutions. Plus précisément, vous pouvez indiquer des valeurs manuellement pour :

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

Par exemple, la commande suivante utilise la substitution TAG_NAME :

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

L'exemple suivant utilise les substitutions par défaut $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER et $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"
  ]
}

L'exemple ci-dessous présente une demande de compilation utilisant l'étape de compilation docker pour compiler une image, puis envoie l'image à Container Registry à l'aide de la substitution $PROJECT_ID par défaut :

Dans cet exemple :

  • La demande de compilation comporte une étape de compilation, qui utilise l'étape de compilation docker dans gcr.io/cloud-builders pour compiler l'image Docker.
    • Le champ args de l'étape définit les arguments à transmettre à la commande docker. Dans ce cas, build -t gcr.io/my-project/cb-demo-img . est appelé (une fois $PROJECT_ID remplacé par l'ID de projet).

  • Le champ images contient le nom de l'image. En cas de réussite de la compilation, l'image obtenue est envoyée à Container Registry. En cas d'échec de la création de l'image par la compilation, cette dernière échoue.

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

Utiliser des substitutions définies par l'utilisateur

Vous pouvez également définir vos propres substitutions. Les substitutions définies par l'utilisateur doivent être conformes aux règles suivantes :

  • Les substitutions doivent commencer par un trait de soulignement (_) et contenir seulement des lettres majuscules et des chiffres (en respectant l'expression régulière _[A-Z0-9_]+). Cela évite les conflits avec les substitutions intégrées. Pour utiliser une expression commençant par $, vous devez utiliser $$. Ainsi :
    • La valeur $FOO n'est pas valide, car il ne s'agit pas d'une substitution intégrée.
    • $$FOO renvoie la chaîne littérale $FOO.
  • Le nombre de paramètres est limité à 200. La longueur d'une clé de paramètre est limitée à 100 octets et la longueur d'une valeur de paramètre est limitée à 4 000 octets.

Vous pouvez spécifier des variables de deux manières, $_FOO ou ${_FOO} :

  • $_FOO et ${_FOO} équivalent à _FOO. Cependant, ${} permet à la substitution de fonctionner sans espaces, ce qui permet des substitutions comme ${_FOO}BAR.
  • $$ vous permet d'inclure un $ littéral dans le modèle. Ainsi :
    • $_FOO renvoie la valeur _FOO.
    • $$_FOO renvoie la chaîne littérale $_FOO.
    • $$$_FOO renvoie la chaîne littérale $ suivie par la valeur de _FOO.

Pour utiliser les substitutions, utilisez l'argument --substitutions de la commande gcloud ou spécifiez-les dans le fichier de configuration.

L'exemple suivant montre une configuration de compilation comportant deux substitutions définies par l'utilisateur nommées _NODE_VERSION_1 et _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}"
    ]
}

Pour remplacer la valeur de substitution définie dans le fichier de configuration de compilation, utilisez l'option --substitutions dans la commande gcloud builds submit. Notez que les substitutions sont une mise en correspondance de variables avec des valeurs plutôt que des tableaux ou des séquences. Vous pouvez remplacer les valeurs des variables de substitution par défaut, à l'exception de $PROJECT_ID et $BUILD_ID. La commande suivante remplace la valeur par défaut de _NODE_VERSION_1 spécifiée dans le fichier de configuration de compilation ci-dessus :

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

Par défaut, la compilation renvoie une erreur si une variable de substitution ou une substitution est manquante. Toutefois, vous pouvez définir l'option ALLOW_LOOSE pour ignorer cette vérification.

L'extrait de code suivant imprime "hello world" et définit une substitution non utilisée. L'option de substitution ALLOW_LOOSE étant définie, la compilation réussit malgré la substitution manquante.

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

Si votre compilation est appelée par un déclencheur, l'option ALLOW_LOOSE est définie par défaut. Dans ce cas, votre compilation ne renverra pas d'erreur s'il manque une variable de substitution ou une substitution. Vous ne pouvez pas remplacer l'option ALLOW_LOOSE pour les compilations appelées par des déclencheurs.

Si l'option ALLOW_LOOSE n'est pas spécifiée, les clés sans correspondance de votre mappage de substitution ou votre requête de compilation génèrent une erreur. Par exemple, si votre requête de compilation inclut $_FOO et que le mappage des substitutions ne définit pas _FOO, vous recevrez une erreur après avoir exécuté la compilation ou appelé un déclencheur si votre déclencheur inclut des variables de substitution.

Les variables de substitution suivantes contiennent toujours une valeur de chaîne vide par défaut, même si vous ne définissez pas l'option ALLOW_LOOSE:

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

Lorsque vous définissez une variable de substitution, vous n'êtes pas limité aux chaînes statiques. Vous avez également accès à la charge utile de l'événement qui a appelé votre déclencheur. Ces éléments sont disponibles sous forme de liaisons de charge utile. Vous pouvez également appliquer des extensions de paramètres bash aux variables de substitution et stocker la chaîne obtenue en tant que nouvelle variable de substitution. Pour en savoir plus, consultez la section Utiliser des liaisons de charge utile et des extensions de paramètres bash dans les substitutions.

Substitutions dynamiques

Vous pouvez référencer la valeur d'une autre variable dans une substitution définie par l'utilisateur en définissant l'option dynamicSubstitutions sur true dans le fichier de configuration de compilation. Si votre compilation est appelée par un déclencheur, le champ dynamicSubstitutions est toujours défini sur true et n'a pas besoin d'être spécifié dans le fichier de configuration de compilation. Si votre compilation est appelée manuellement, vous devez définir le champ dynamicSubstitutions sur true pour que les extensions de paramètres bash soient interprétées lors de l'exécution de la compilation.

Le fichier de configuration de compilation suivant affiche la variable de substitution ${_IMAGE_NAME} qui fait référence à la variable ${PROJECT_ID}. Comme le champ dynamicSubstitutions est défini sur true, la référence est appliquée lors de l'appel manuel d'une compilation:

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

Pour en savoir plus, consultez la section Appliquer des extensions de paramètres bash.

Mapper des substitutions avec des variables d'environnement

Les scripts ne sont pas directement compatibles avec les substitutions, mais acceptent les variables d'environnement. Vous pouvez mapper les substitutions à des variables d'environnement soit automatiquement en une seule fois, soit manuellement en définissant vous-même chaque variable d'environnement.

Mapper automatiquement les substitutions

  • Au niveau de la compilation : Pour mapper automatiquement toutes les substitutions à des variables d'environnement, qui seront disponibles tout au long de la compilation, définissez automapSubstitutions sur true comme option au niveau de la compilation. Par exemple, le fichier de configuration de compilation suivant montre la substitution $_USER définie par l'utilisateur et la substitution par défaut $PROJECT_ID mappées sur les variables d'environnement:

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

  • Au niveau des pas : Pour mapper automatiquement toutes les substitutions et les rendre disponibles en tant que variables d'environnement en une seule étape, définissez le champ automapSubstitutions sur true à cette étape. Dans l'exemple suivant, seule la deuxième étape affichera correctement les substitutions, car c'est la seule pour laquelle le mappage automatique des substitutions est activé:

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

    De plus, vous pouvez rendre les substitutions disponibles en tant que variables d'environnement dans l'ensemble de la compilation, puis les ignorer en une seule étape. Définissez automapSubstitutions sur true au niveau de la compilation, puis définissez le même champ sur false à l'étape où vous souhaitez ignorer les substitutions. Dans l'exemple suivant, même si les substitutions de mappage sont activées au niveau de la compilation, l'ID du projet ne sera pas imprimé à la deuxième étape, car automapSubstitutions est défini sur false à cette étape:

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

Mapper manuellement les substitutions

Vous pouvez mapper manuellement les substitutions à des variables d'environnement. Chaque variable d'environnement est définie au niveau de l'étape à l'aide du champ env, et le champ d'application des variables est limité à l'étape où elles sont définies. Ce champ accepte une liste de clés et de valeurs.

L'exemple suivant montre comment mapper la substitution $PROJECT_ID à la variable d'environnement BAR:

YAML 

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

JSON 

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

Étapes suivantes