Utilizza substitutions
nel file di configurazione della build per sostituire variabili specifiche in fase di compilazione.
Le sostituzioni sono utili per le variabili il cui valore non è noto fino al momento della build oppure per riutilizzare una richiesta di build esistente con valori di variabili diversi.
Cloud Build offre sostituzioni integrate oppure puoi definire sostituzioni personalizzate. Utilizza substitutions
in steps
e images
della build per risolvere i relativi valori al momento della build.
In questa pagina viene spiegato come utilizzare le sostituzioni predefinite o definire una substitutions
personalizzata.
Utilizzare le sostituzioni predefinite
Cloud Build fornisce le seguenti sostituzioni predefinite per tutte le build:
$PROJECT_ID
: ID del tuo progetto Cloud$BUILD_ID
: ID della build$PROJECT_NUMBER
: il numero del tuo progetto$LOCATION
: la regione associata alla tua build
Cloud Build fornisce le seguenti sostituzioni predefinite per le build richiamate dai trigger:
$TRIGGER_NAME
: il nome associato all'attivatore$COMMIT_SHA
: l'ID commit associato alla build$REVISION_ID
: l'ID commit associato alla build$SHORT_SHA
: i primi sette caratteri diCOMMIT_SHA
$REPO_NAME
: il nome del repository$REPO_FULL_NAME
: il nome completo del repository, inclusi l'utente o l'organizzazione$BRANCH_NAME
: il nome della filiale$TAG_NAME
: il nome del tag$REF_NAME
: il nome del ramo o del tag$TRIGGER_BUILD_CONFIG_PATH
: il percorso del file di configurazione della build utilizzato durante l'esecuzione della build; altrimenti, una stringa vuota se la build è configurata in linea nel trigger o utilizza unDockerfile
oBuildpack
.$SERVICE_ACCOUNT_EMAIL
: indirizzo email dell'account di servizio che utilizzi per la build. Si tratta di un account di servizio predefinito o di un account di servizio specificato dall'utente.$SERVICE_ACCOUNT
: il nome della risorsa dell'account di servizio nel formatoprojects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
Cloud Build fornisce le seguenti sostituzioni predefinite specifiche di GitHub disponibili per i trigger di richieste di pull:
$_HEAD_BRANCH
: ramo head della richiesta di pull$_BASE_BRANCH
: ramo di base della richiesta di pull$_HEAD_REPO_URL
: URL del repository head della richiesta di pull$_PR_NUMBER
: numero della richiesta di pull
Se non è disponibile una sostituzione predefinita (ad esempio con build senza origine o con build che utilizzano l'origine di archiviazione), le occorrenze della variabile mancante vengono sostituite con una stringa vuota.
Quando avvii una build utilizzando gcloud builds submit
, puoi specificare le variabili che normalmente provengono da build attivate con l'argomento --substitutions
. In particolare,
puoi fornire manualmente i valori per:
$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
Ad esempio, il seguente comando utilizza la sostituzione TAG_NAME
:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=TAG_NAME="test"
L'esempio seguente utilizza le sostituzioni predefinite $BUILD_ID
, $PROJECT_ID
, $PROJECT_NUMBER
e $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'esempio seguente mostra una richiesta di build utilizzando il passaggio di build docker
per creare un'immagine, quindi ne esegue il push in Container Registry utilizzando la sostituzione predefinita $PROJECT_ID
:
In questo esempio:
- La richiesta di build include un passaggio di build che utilizza il passaggio di build
docker
ingcr.io/cloud-builders
per creare l'immagine Docker.- Il campo
args
nel passaggio specifica gli argomenti da passare al comandodocker
, in questo caso verrà richiamato il comandobuild -t gcr.io/my-project/cb-demo-img .
(dopo che$PROJECT_ID
viene sostituito con l'ID progetto).
- Il campo
Il campo
images
contiene il nome dell'immagine. Se la build ha esito positivo, viene eseguito il push dell'immagine risultante su Container Registry. Se l'immagine non viene creata correttamente dalla build, la build avrà esito negativo.
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"
]
}
Utilizzo di sostituzioni definite dall'utente
Puoi anche definire sostituzioni personalizzate. Le sostituzioni definite dall'utente devono essere conformi alle seguenti regole:
- Le sostituzioni devono iniziare con un trattino basso (
_
) e utilizzare solo lettere maiuscole e numeri (rispettando l'espressione regolare_[A-Z0-9_]+
). In questo modo si evitano conflitti con le sostituzioni integrate. Per utilizzare un'espressione che inizia con$
, devi usare$$
. Di conseguenza:$FOO
non è valido perché non è una sostituzione integrata.$$FOO
restituisce la stringa letterale$FOO
.
- Il numero massimo di parametri è 200. La lunghezza di una chiave parametro è limitata a 100 byte, mentre la lunghezza di un valore parametro è limitata a 4000 byte.
Puoi specificare le variabili in uno dei due modi seguenti: $_FOO
o ${_FOO}
:
- Sia
$_FOO
che${_FOO}
restituiscono il valore_FOO
. Tuttavia,${}
consente la sostituzione senza spazi circostanti, il che consente sostituzioni come${_FOO}BAR
. $$
consente di includere un valore letterale$
nel modello. Di conseguenza:$_FOO
restituisce il valore di_FOO
.$$_FOO
restituisce la stringa letterale$_FOO
.$$$_FOO
restituisce la stringa letterale$
seguita dal valore di_FOO
.
Per utilizzare le sostituzioni, utilizza l'argomento --substitutions
nel comando gcloud
o specificale nel file di configurazione.
L'esempio seguente mostra una configurazione di compilazione con due sostituzioni definite dall'utente
chiamate _NODE_VERSION_1
e _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}"
]
}
Per eseguire l'override del valore di sostituzione specificato nel file di configurazione della build, utilizza il flag --substitutions
nel comando gcloud builds submit
. Tieni presente che le sostituzioni sono una mappatura delle variabili a valori anziché a array o sequenze. Puoi sostituire i valori predefiniti delle variabili di sostituzione,
tranne che per $PROJECT_ID
e $BUILD_ID
. Il seguente comando sostituisce il valore predefinito di _NODE_VERSION_1
specificato nel file di configurazione della build riportato sopra:
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .
Per impostazione predefinita, la build restituisce un errore se manca una variabile di sostituzione o una sostituzione. Tuttavia, puoi impostare l'opzione ALLOW_LOOSE
per saltare questo controllo.
Lo snippet seguente visualizza "hello world" e definisce una sostituzione inutilizzata.
Poiché l'opzione di sostituzione ALLOW_LOOSE
è impostata, la build andrà a buon fine nonostante la sostituzione mancante.
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"
}
}
Se la tua build viene richiamata da un trigger, l'opzione ALLOW_LOOSE
è impostata per impostazione predefinita. In questo caso, la build non restituirà un errore se manca una variabile di sostituzione o una sostituzione. Non puoi eseguire l'override dell'opzione ALLOW_LOOSE
per le build richiamate dai trigger.
Se l'opzione ALLOW_LOOSE
non è specificata, le chiavi senza corrispondenza nella mappatura delle sostituzioni o nella richiesta di build causeranno un errore. Ad esempio, se la richiesta di build include $_FOO
e la mappatura delle sostituzioni non definisce _FOO
, riceverai un errore dopo aver eseguito la build o aver richiamato un trigger se l'attivatore include variabili di sostituzione.
Le seguenti variabili di sostituzione contengono sempre un valore di stringa vuota predefinito, anche se non imposti l'opzione ALLOW_LOOSE
:
$REPO_NAME
$REPO_FULL_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA
Quando definisci una variabile di sostituzione, non devi limitarti alle stringhe statiche. Hai anche accesso al payload dell'evento che ha richiamato il tuo trigger. Questi sono disponibili come associazioni di payload. Puoi anche applicare espansioni dei parametri bash alle variabili di sostituzione e archiviare la stringa risultante come nuova variabile di sostituzione. Per scoprire di più, consulta Utilizzare le associazioni di payload e le espansioni dei parametri bash nelle sostituzioni.
Sostituzioni dinamiche
Puoi fare riferimento al valore di un'altra variabile in una sostituzione definita dall'utente impostando l'opzione dynamicSubstitutions
su true
nel file di configurazione della build. Se la tua build viene richiamata da un trigger, il campo dynamicSubstitutions
è sempre impostato su true
e non deve essere specificato nel file di configurazione della build. Se la build viene richiamata manualmente, devi impostare il campo dynamicSubstitutions
su true
affinché le espansioni dei parametri bash vengano interpretate durante l'esecuzione della build.
Il seguente file di configurazione della build mostra la variabile di sostituzione ${_IMAGE_NAME}
che fa riferimento alla variabile ${PROJECT_ID}
. Il campo dynamicSubstitutions
è impostato su true
, quindi il riferimento viene applicato quando si chiama manualmente una build:
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
}
}
Per saperne di più, consulta la sezione Applicare le espansioni dei parametri bash.
Mappatura delle sostituzioni alle variabili di ambiente
Gli script non supportano direttamente le sostituzioni, ma supportano le variabili di ambiente. Puoi mappare le sostituzioni alle variabili di ambiente, automaticamente tutte insieme o manualmente, definendo personalmente ogni variabile di ambiente.
Sostituzioni della mappa automaticamente
A livello di build. Per mappare automaticamente tutte le sostituzioni alle variabili di ambiente, che saranno disponibili nell'intera build, imposta
automapSubstitutions
sutrue
come opzione a livello di build. Ad esempio, il seguente file di configurazione della build mostra la sostituzione$_USER
definita dall'utente e la sostituzione predefinita$PROJECT_ID
mappate alle variabili di ambiente: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" } }
A livello di passaggio. Per mappare automaticamente tutte le sostituzioni e renderle disponibili come variabili di ambiente in un singolo passaggio, imposta il campo
automapSubstitutions
sutrue
nel passaggio in questione. Nell'esempio seguente, solo il secondo passaggio mostrerà correttamente le sostituzioni, perché è l'unico per cui è abilitato il mapping delle sostituzioni automatiche: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" }
Inoltre, puoi rendere disponibili le sostituzioni come variabili di ambiente nell'intera build e quindi ignorarle in un solo passaggio. Imposta
automapSubstitutions
sutrue
a livello di build, quindi imposta lo stesso campo sufalse
nel passaggio in cui vuoi ignorare le sostituzioni. Nell'esempio seguente, anche se le sostituzioni della mappatura sono abilitate a livello di build, l'ID progetto non verrà stampato nel secondo passaggio perché in quel passaggioautomapSubstitutions
è impostato sufalse
: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" }
Mappa le sostituzioni manualmente
Puoi mappare manualmente le sostituzioni alle variabili di ambiente. Ogni variabile di ambiente viene definita a livello di passaggio utilizzando il campo env
e l'ambito delle variabili è limitato al passaggio in cui sono definite. Questo campo accetta un elenco di chiavi e valori.
L'esempio seguente mostra come mappare la sostituzione $PROJECT_ID
alla
variabile di ambiente BAR
:
YAML
steps:
- name: 'ubuntu'
env:
- 'BAR=$PROJECT_ID'
script: 'echo $BAR'
JSON
{
"steps": [
{
"name": "ubuntu",
"env": [
"BAR=$PROJECT_ID"
],
"script": "echo $BAR"
}
]
}
Passaggi successivi
- Scopri come utilizzare le associazioni di payload e le espansioni dei parametri bash nelle sostituzioni.
- Scopri come creare un file di configurazione di compilazione di base.
- Scopri come creare e gestire i trigger di build.
- Scopri come eseguire le build manualmente in Cloud Build.