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 deCOMMIT_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 uneDockerfile
ou uneBuildpack
.$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 formatprojects/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
dansgcr.io/cloud-builders
pour compiler l'image Docker.- Le champ
args
de l'étape définit les arguments à transmettre à la commandedocker
. 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
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
.
- La valeur
- 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
surtrue
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
surtrue
à 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
surtrue
au niveau de la compilation, puis définissez le même champ surfalse
à 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, carautomapSubstitutions
est défini surfalse
à 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
- Découvrez comment Utiliser des liaisons de charge utile et des extensions de paramètres bash dans les substitutions.
- Découvrez comment créer un fichier de configuration de compilation de base.
- Découvrez comment créer et gérer des déclencheurs de compilation.
- Découvrez comment exécuter des compilations manuellement dans Cloud Build.