Questa pagina è stata tradotta dall'API Cloud Translation.

Sostituzione dei valori delle variabili

Utilizza substitutions nel file di configurazione della build per sostituire variabili specifiche in fase di build.

Le sostituzioni sono utili per le variabili il cui valore non è noto fino al momento della compilazione o per riutilizzare una richiesta di build esistente con valori di variabile diversi.

Cloud Build fornisce sostituzioni integrate oppure puoi definire le tue sostituzioni. Utilizza substitutions nel steps e nel images della build per risolvere i relativi valori al momento della creazione.

Questa pagina spiega come utilizzare sostituzioni predefinite o personalizzate substitutions.

Utilizzo delle sostituzioni predefinite

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

$PROJECT_ID: l'ID del tuo progetto Cloud
$BUILD_ID: l'ID della build
$PROJECT_NUMBER: il numero di progetto
$LOCATION: la regione associata alla build

Cloud Build fornisce le seguenti sostituzioni predefinite per le build richiamate dai trigger:

$TRIGGER_NAME: il nome associato al trigger
$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 ramo
$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; in caso contrario, una stringa vuota se la build è configurata inline nel trigger o utilizza un Dockerfile o un Buildpack.
$SERVICE_ACCOUNT_EMAIL: l'email del account di servizio che utilizzi per la build. Si tratta di un account di servizio predefinito o di un service account specificato dall'utente.
$SERVICE_ACCOUNT: il nome della risorsa del account di servizio, nel formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

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

$_HEAD_BRANCH : il ramo di intestazione della richiesta di pull
$_BASE_BRANCH : il ramo di base della richiesta di pull
$_HEAD_REPO_URL : URL del repository principale 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 variabili che normalmente provengono da 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', '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/my-image', '.']

# my-image is pushed to Artifact Registry
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/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 creare un'immagine, quindi esegue il push dell'immagine ad Artifact Registry utilizzando la sostituzione $PROJECT_ID predefinita:

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 passare al comando docker, in questo caso verrà richiamato build -t gcr.io/my-project/cb-demo-img . (dopo che $PROJECT_ID è stato sostituito con l'ID progetto).
Il campo images contiene il nome dell'immagine. Se la build ha esito positivo, l'immagine risultante viene inviata ad Artifact Registry. Se l'immagine non viene creata correttamente dalla build, la build non andrà a buon fine.

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
images:
- '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img'

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img", "."]
    }],
  "images": [
    "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/cb-demo-img"
  ]
}

Utilizzo di sostituzioni definite dall'utente

Puoi anche definire sostituzioni personalizzate. Le sostituzioni definite dall'utente devono rispettare le 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 $$. For example:
- $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 unvalore parametroo è limitata a 4000 byte.

Puoi specificare le variabili in due modi: $_FOO o ${_FOO}:

Sia $_FOO che ${_FOO} restituiscono il valore _FOO. Tuttavia, ${} consente la sostituzione senza spazi circostanti, il che permette sostituzioni come ${_FOO}BAR.

$$ lets you include a literal $ in the template. For example:

$_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, utilizza l'argomento --substitutions nel comando gcloud o specificale nel file di configurazione.

L'esempio seguente mostra una configurazione di build con due sostituzioni definite dall'utente denominate _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',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
          '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
          '--build-arg',
          'node_version=${_NODE_VERSION_2}',
          '-t',
          '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}',
          '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}',
    '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

JSON

{
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1",
        "_NODE_VERSION_2": "v6.9.2",
    },
    "images": [
        "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/build-substitutions-nodejs-${_NODE_VERSION_2}"
    ]
}

Per sostituire il 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 di variabili a valori anziché 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 di _NODE_VERSION_1 specificato nel file di configurazione della build precedente:

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 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:
    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 per impostazione predefinita. In questo caso, la build non restituirà un errore se manca una variabile di sostituzione o una sostituzione. Non puoi ignorare l'opzione ALLOW_LOOSE per le build richiamate dai trigger.

Se l'opzione ALLOW_LOOSE non è specificata, le chiavi non corrispondenti nel mapping delle sostituzioni o nella richiesta di build genereranno un errore. Ad esempio, se la richiesta di build include $_FOO e il mapping delle sostituzioni non definisce _FOO, riceverai un errore dopo l'esecuzione della build o la chiamata di un trigger se il trigger 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 sei limitato alle stringhe statiche. Hai anche accesso al payload dell'evento che ha richiamato il trigger. Questi sono disponibili come binding del payload. Puoi anche applicare le espansioni dei parametri bash alle variabili di sostituzione e archiviare 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 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 viene richiamata una build manualmente:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: '${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/test-image'
options:
    dynamicSubstitutions: true

JSON

{
    "steps": [
      {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
            "build",
            "-t",
            "${_IMAGE_NAME}",
            "."
          ]
      }
    ],
    "substitutions": {
      "_IMAGE_NAME": "${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPOSITORY}/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 in una volta o manualmente definendo ogni variabile di ambiente personalmente.

Mappare automaticamente le sostituzioni

A livello di build. Per mappare automaticamente tutte le sostituzioni alle variabili di ambiente, che saranno disponibili durante l'intera build, imposta automapSubstitutions su true 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 $PROJECT_ID predefinita 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 unico passaggio, imposta il campo automapSubstitutions su true in questo passaggio. Nell'esempio seguente, solo il secondo passaggio mostrerà le sostituzioni correttamente, perché è l'unico con la mappatura delle sostituzioni automatiche attivata:

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, quindi ignorarle in un unico passaggio. Imposta automapSubstitutions su true a livello di build, quindi imposta lo stesso campo su false nel passaggio in cui vuoi ignorare le sostituzioni. Nell'esempio seguente, anche se le sostituzioni del mapping 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 manualmente le sostituzioni

Puoi mappare manualmente le sostituzioni alle variabili di ambiente. Ogni variabile di ambiente è 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 di parametri bash nelle sostituzioni.
Scopri come creare un file di configurazione della build di base.
Scopri come creare e gestire i trigger di build.
Scopri come eseguire le build manualmente in Cloud Build.

Sostituzione dei valori delle variabili Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Utilizzo delle sostituzioni predefinite

YAML

JSON

YAML

JSON

Utilizzo di sostituzioni definite dall'utente

YAML

JSON

YAML

JSON

Sostituzioni dinamiche

YAML

JSON

Mappatura delle sostituzioni alle variabili di ambiente

Mappare automaticamente le sostituzioni

YAML

JSON

YAML

JSON

YAML

JSON

Mappare manualmente le sostituzioni

YAML

JSON

Passaggi successivi

Sostituzione dei valori delle variabili