Sostituzione dei valori delle variabili

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 creazione o per riutilizzare una richiesta di build esistente con valori della variabile diversi.

Cloud Build offre sostituzioni integrate oppure puoi definirne delle personalizzate. Utilizza substitutions in steps e images nella build per risolvere i relativi valori al momento della creazione.

Questa pagina spiega come utilizzare le sostituzioni predefinite o definirne di personalizzate substitutions.

Utilizzo di 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: numero del progetto
  • $LOCATION: l'area geografica associata alla tua build

Cloud Build fornisce le seguenti sostituzioni predefinite per le build richiamate da 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 di COMMIT_SHA
  • $REPO_NAME: il nome del repository
  • $BRANCH_NAME: il nome della filiale
  • $TAG_NAME: il nome 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 sull'attivatore o utilizza un Dockerfile o un Buildpack.

Cloud Build fornisce le seguenti sostituzioni predefinite specifiche per GitHub disponibili per i trigger per richieste di pull:

  • $_HEAD_BRANCH : ramo head della richiesta di pull
  • $_BASE_BRANCH : ramo 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 per le build senza codice sorgente o quelle che utilizzano l'origine di archiviazione), le occorrenze della variabile mancante vengono sostituite con una stringa vuota.

Quando inizi una build con gcloud builds submit, puoi specificare le variabili che in genere 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
  • $BRANCH_NAME
  • $TAG_NAME
  • $TRIGGER_BUILD_CONFIG_PATH

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 esegue il push dell'immagine a Container Registry utilizzando la sostituzione predefinita $PROJECT_ID:

In questo esempio:

  • La richiesta di build ha un passaggio di build, che utilizza il passaggio di build docker in gcr.io/cloud-builders per creare l'immagine Docker.
    • Il campo args nel passaggio specifica gli argomenti da trasmettere al comando docker, in questo caso build -t gcr.io/my-project/cb-demo-img ., verrà richiamato (dopo che $PROJECT_ID è stato sostituito con l'ID progetto).

  • Il campo images contiene il nome dell'immagine. Se la build ha esito positivo, viene eseguito il push dell'immagine risultante in Container Registry. Se l'immagine non viene creata correttamente dalla build, quest'ultima non riuscirà.

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 specificare 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 incorporate. Per usare un'espressione che inizia con $, devi utilizzare $$. Pertanto:
    • $FOO non è valido perché non è una sostituzione integrata.
    • $$FOO restituisce la stringa letterale $FOO.
  • Il numero di parametri è limitato a 100. 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 due modi: $_FOO o ${_FOO}:

  • Sia $_FOO sia ${_FOO} valutano il valore di _FOO. Tuttavia, ${} consente di effettuare la sostituzione senza includere spazi vuoti, il che consente sostituzioni come ${_FOO}BAR.
  • $$ consente di includere un valore letterale $ nel modello. Pertanto:
    • $_FOO restituisce il valore di _FOO.
    • $$_FOO restituisce la stringa letterale $_FOO.
    • $$$_FOO restituisce la stringa letterale $ seguita dal valore _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 sostituire il valore di sostituzione specificato nel file di configurazione di compilazione, 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 ad eccezione di $PROJECT_ID e $BUILD_ID. Il seguente comando sostituisce il valore predefinito per _NODE_VERSION_1 specificato nel file di configurazione della build sopra riportato:

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 se manca una sostituzione. Tuttavia, puoi impostare l'opzione ALLOW_LOOSE per saltare questo controllo.

Il seguente snippet stampa "hello world" e definisce una sostituzione inutilizzata. Poiché è impostata l'opzione di sostituzione ALLOW_LOOSE, la build avrà esito positivo nonostante la sostituzione mancante.

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

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 se manca una sostituzione. Non puoi sostituire l'opzione ALLOW_LOOSE per le build richiamate dagli attivatori.

Se l'opzione ALLOW_LOOSE non è specificata, le chiavi senza corrispondenza nella mappatura o nella richiesta di build di sostituzione restituiscono 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 richiamando un trigger se l'attivatore include variabili di sostituzione.

Le seguenti variabili di sostituzione contengono sempre un valore predefinito di stringa vuota anche se non imposti l'opzione ALLOW_LOOSE:

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

Quando definisci una variabile di sostituzione, non puoi limitare le 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 del parametro bash alle variabili di sostituzione e archiviare la stringa risultante come nuova variabile di sostituzione. Per ulteriori informazioni, consulta Utilizzo delle associazioni di payload e delle espansioni di parametri bash nelle sostituzioni.

Sostituzioni dinamiche

Puoi fare riferimento al valore di un'altra variabile all'interno di una sostituzione definita dall'utente impostando l'opzione dynamic_substitutions su true nel file di configurazione della build. Se la tua build viene richiamata da un trigger, il campo dynamic_substitutions viene 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 dynamic_substitutions su true per consentire l'interpretazione delle espansioni dei parametri bash 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 dynamic_substitutions è impostato su true, pertanto 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:
    dynamic_substitutions: 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 ulteriori informazioni, consulta Applicare le espansioni dei parametri bash.

Passaggi successivi