Cette page a été traduite par l'API Cloud Translation.
Switch to English

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

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

  • $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
  • $BRANCH_NAME : le nom de votre agence
  • $TAG_NAME : le nom de votre tag

Cloud Build fournit les substitutions par défaut suivantes propres à GitHub disponibles pour les déclencheurs de demandes 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 :

  • $COMMIT_SHA
  • $REVISION_ID
  • $SHORT_SHA
  • $REPO_NAME
  • $BRANCH_NAME
  • $TAG_NAME

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 suivantes : $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 $$. Par exemple :
    • 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é à 100. 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:
    substitution_option: '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.

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. Celles-ci sont disponibles en tant que liaisons de charge utile. Vous pouvez également appliquer des extensions de paramètres bash sur les variables de substitution et stocker la chaîne obtenue en tant que nouvelle variable de substitution. Pour en savoir plus, consultez la page Utiliser des liaisons de charge utile et des extensions de paramètres bash dans les substitutions.

Étape suivante