Sostituzione dei valori delle variabili

Utilizza substitutions nel file di configurazione della build per sostituire variabili specifiche al momento della compilazione.

Le sostituzioni sono utili per le variabili il cui valore non è noto fino a quando ora della build oppure per riutilizzare una richiesta di build esistente con variabili diverse e i relativi valori.

Cloud Build fornisce sostituzioni integrate oppure puoi definirne di personalizzate le sostituzioni. Utilizza substitutions nelle risorse steps e images della build per risolvere i relativi valori al momento della creazione.

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

Utilizzo delle sostituzioni predefinite

Cloud Build fornisce le seguenti sostituzioni predefinite per tutte le compilazioni:

  • $PROJECT_ID: ID del progetto Cloud
  • $BUILD_ID: ID della build
  • $PROJECT_NUMBER: il numero del progetto
  • $LOCATION: la regione associata alla tua build

Cloud Build fornisce le seguenti sostituzioni predefinite per le build richiamati 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 di COMMIT_SHA
  • $REPO_NAME: il nome del repository
  • $REPO_FULL_NAME: il nome completo del repository, incluso l'utente o l'organizzazione
  • $BRANCH_NAME: il nome del tuo ufficio
  • $TAG_NAME: il nome del tag
  • $REF_NAME: il nome del ramo o tag
  • $TRIGGER_BUILD_CONFIG_PATH: il percorso del file di configurazione della build utilizzato durante l'esecuzione della build; altrimenti una stringa vuota configurato in linea sul trigger oppure utilizza un Dockerfile o Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: indirizzo email dell'account di servizio che utilizzi per creare. Questo è un account di servizio predefinito o un servizio specificato dall'utente .
  • $SERVICE_ACCOUNT: il nome della risorsa dell'account di servizio, nel formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

Cloud Build fornisce il seguente valore predefinito specifico per GitHub sostituzioni disponibili per i trigger delle richieste di pull:

  • $_HEAD_BRANCH: ramo principale della richiesta di pull
  • $_BASE_BRANCH: ramo base della richiesta di pull
  • $_HEAD_REPO_URL: URL del repository principale della richiesta pull
  • $_PR_NUMBER: numero della richiesta di pull

Se non è disponibile una sostituzione predefinita (ad esempio con le build senza origine o con le build che utilizzano l'origine dello spazio 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 dalle build attivate con l'argomento --substitutions. Nello specifico, 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 che utilizza il passaggio di build docker per la creazione di un'immagine, quindi ne esegue il push in Container Registry utilizzando il metodo Sostituzione $PROJECT_ID:

In questo esempio:

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

  • La images contiene il nome dell'immagine. Se la build ha esito positivo, viene eseguito il push dell'immagine in Container Registry. Se l'immagine non viene creata correttamente la build non riesce.

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 le tue sostituzioni. 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 utilizzare $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO che restituisce la stringa letterale $FOO.
  • Il numero di parametri è limitato a 200. La lunghezza di una chiave del parametro è limitata a 100 byte e la lunghezza di un valore del 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 di _FOO. Tuttavia, ${} consente la sostituzione senza spazi circostanti, il che consente sostituzioni come ${_FOO}BAR.
    • $$ allows you to include a literal $ in the template. Thus:
      • $_FOO evaluates to the value of _FOO.
      • $$_FOO restituisce la stringa letterale $_FOO.
      • $$$_FOO restituisce la stringa letterale $ seguita dal valore di _FOO.

      Per utilizzare le sostituzioni, usa --substitutions nel comando gcloud o specificarle 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 della 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 di variabili a valori anziché ad 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 di compilazione 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 compilazione 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 stampa "hello world" e definisce una sostituzione inutilizzata. Poiché l'opzione di sostituzione ALLOW_LOOSE è impostata, la compilazione 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 build viene richiamata da un trigger, l'opzione ALLOW_LOOSE è impostata da predefinito. In questo caso, la build non restituirà un errore se è presente o una variabile di sostituzione mancante. Non puoi eseguire l'override dell'opzione ALLOW_LOOSE per le build richiamate dagli attivatori.

      Se non viene specificata l'opzione ALLOW_LOOSE, le chiavi non corrispondenti nella mappatura delle sostituzioni o nella richiesta di compilazione causeranno un errore. Ad esempio, se la tua richiesta di build include $_FOO e la mappatura delle sostituzioni non definisce _FOO, tu riceveranno un errore dopo aver eseguito la build o aver richiamato un trigger se 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
      • $REPO_FULL_NAME
      • $BRANCH_NAME
      • $TAG_NAME
      • $COMMIT_SHA
      • $SHORT_SHA

      Quando definisci una variabile di sostituzione, non sei limitato alle stringhe statiche. Hai anche accesso al payload dell'evento che ha richiamato il tuo trigger. Questi parametri sono disponibili come associazioni del payload. Puoi anche applicare espansioni dei parametri bash sulle variabili di sostituzione e archivia la stringa risultante come nuova variabile di sostituzione. Per saperne di più, consulta la sezione 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 dynamicSubstitutions su true nel file di configurazione della build. Se la compilazione viene invocata da un attivatore, il campo dynamicSubstitutions è sempre impostato su true e non deve essere specificato nel file di configurazione della compilazione. Se la compilazione viene invocata manualmente, devi impostare il campo dynamicSubstitutions su true affinché le espansioni dei parametri bash siano interpretate durante l'esecuzione della compilazione.

      Il seguente file di configurazione di compilazione mostra la variabile di sostituzione ${_IMAGE_NAME} che fa riferimento alla variabile ${PROJECT_ID}. La Il campo dynamicSubstitutions è impostato su true, quindi il riferimento viene applicata quando richiami 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 ulteriori informazioni, 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, in modo automatico tutte contemporaneamente o manualmente definendo personalmente ogni variabile di ambiente.

      Sostituzioni mappa automaticamente

      • A livello di build. Per mappare automaticamente tutte le sostituzioni a le variabili di ambiente, che saranno disponibili durante tutta la build, imposta automapSubstitutions su true come opzione a livello di build. Per Ad esempio, il seguente file di configurazione di compilazione mostra sostituzione $_USER e sostituzione predefinita $PROJECT_ID mappata a 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 rendere disponibili come variabili di ambiente in un solo passaggio, automapSubstitutions a true in questo passaggio. Nell'esempio seguente, solo il secondo passaggio mostrerà le sostituzioni correttamente, perché è l'unico con la mappatura delle sostituzioni automatiche abilitata:

        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 ambiente variabili nell'intera build, per poi ignorarle in un unico passaggio. Imposta automapSubstitutions su true a livello di compilazione, quindi imposta lo stesso campo su false nel passaggio in cui vuoi ignorare le sostituzioni. Nella nell'esempio seguente, anche se le sostituzioni di mappatura sono abilitate a livello di build, l'ID progetto non verrà stampato nel secondo passaggio perché automapSubstitutions è impostato su false in questo passaggio:

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

      Mappare 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