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 compilation

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, chaîne vide si votre compilation est configurée de manière intégrée sur le déclencheur ou utilise un Dockerfile ou un Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: adresse e-mail du compte de service que vous utilisez pour le créer. 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 la 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 $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO, qui 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.
    • $$ allows you to include a literal $ in the template. Thus:
      • $_FOO evaluates to the value of _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 montre la variable de substitution ${_IMAGE_NAME} faisant référence à la variable ${PROJECT_ID}. La Le champ dynamicSubstitutions est défini sur true. La référence est appliqué 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 les substitutions avec les variables d'environnement

      Les scripts ne prennent pas directement en charge les substitutions, mais ils sont compatibles avec l'environnement variables. Vous pouvez mapper des substitutions avec des variables d'environnement : automatiquement simultanément, ou manuellement en définissant chaque variable d'environnement vous-même.

      Remplacements de carte automatiquement

      • Au niveau de la compilation : Pour mapper automatiquement toutes les substitutions sur des variables d'environnement, qui seront disponibles tout au long de la compilation, définissez automapSubstitutions sur true en tant qu'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ée sur des 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 de l'étape : Pour mapper automatiquement toutes les substitutions et faire disponibles comme variables d'environnement en une seule étape, définissez automapSubstitutions sur true à cette étape. Dans les Par exemple, seule la deuxième étape affiche les substitutions correctement, car il s'agit du seul pour lequel le mappage de substitutions automatiques 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"
  }

        Vous pouvez également rendre les substitutions disponibles en tant que variables d'environnement dans l'ensemble de la compilation, puis les ignorer en une seule étape. Définir automapSubstitutions sur true au niveau de la compilation, puis définissez le même 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 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 sur des variables d'environnement. Toutes les est définie au niveau de l'étape à l'aide de la variable d'environnement 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 sur 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"
    }
  ]
}

      Étape suivante