Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Sustituir valores de variables

Usa substitutions en el archivo de configuración de compilación para sustituir variables específicas cuando se compila.

Las sustituciones son útiles para las variables cuyo valor no se conoce hasta el momento de la compilación o si quieres volver a usar una solicitud de compilación existente con diferentes valores de variable.

Cloud Build proporciona sustituciones integradas, aunque también puedes definir tus propias sustituciones. Usa substitutions en el steps y en images de tu compilación para resolver sus valores en el momento de compilación.

En esta página, se explica cómo usar las sustituciones predeterminadas o definir tus substitutions propias.

Usa sustituciones predeterminadas

Cloud Build proporciona las siguientes sustituciones predeterminadas para todas las compilaciones:

  • $PROJECT_ID: ID de tu proyecto de Cloud
  • $BUILD_ID: ID de tu compilación
  • $PROJECT_NUMBER: Es el número de tu proyecto.

Cloud Build proporciona las siguientes sustituciones predeterminadas para las compilaciones que invocan activadores:

  • $COMMIT_SHA: el ID de confirmación asociado a tu compilación
  • $REVISION_ID: El ID de confirmación asociado a tu compilación.
  • $SHORT_SHA: Los primeros siete caracteres de COMMIT_SHA.
  • $REPO_NAME: El nombre de tu repositorio.
  • $BRANCH_NAME: El nombre de tu rama.
  • $TAG_NAME: El nombre de tu etiqueta.

Cloud Build proporciona las siguientes sustituciones predeterminadas específicas de GitHub disponibles para los activadores de solicitudes de extracción:

  • $_HEAD_BRANCH: Rama principal de la solicitud de extracción
  • $_BASE_BRANCH: Rama base de la solicitud de extracción
  • $_HEAD_REPO_URL: URL del repositorio principal de la solicitud de extracción
  • $_PR_NUMBER: Número de la solicitud de extracción

Si una sustitución predeterminada no está disponible (como en las compilaciones sin fuente o en las compilaciones que usan una fuente de almacenamiento), las ocurrencias de la variable que falta se reemplazan con una string vacía.

Cuando inicias una compilación con gcloud builds submit, puedes especificar con el argumento --substitutions las variables que, por lo general, provienen de compilaciones activadas. En particular, puedes proporcionar valores de forma manual para estos elementos:

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

Por ejemplo, el comando siguiente usa la sustitución TAG_NAME:

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

En el siguiente ejemplo, se usan las sustituciones predeterminadas $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER y $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"
  ]
}

En el siguiente ejemplo, se muestra una solicitud de compilación en la que se compila una imagen con el paso de compilación docker y, luego, se la envía a Container Registry con la sustitución $PROJECT_ID predeterminada:

En este ejemplo:

  • La solicitud de compilación consta de un solo paso de compilación, que usa el paso de compilación docker de gcr.io/cloud-builders para compilar la imagen de Docker.
    • El campo args del paso especifica los argumentos que se deben pasar al comando docker. En este caso, se invocará build -t gcr.io/my-project/cb-demo-img . (después de que $PROJECT_ID se reemplace por el ID del proyecto).
  • El campo images contiene el nombre de la imagen. Si la compilación tiene éxito, la imagen resultante se envía a Container Registry. Si la compilación no crea la imagen con éxito, la compilación fallará.

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

Usa sustituciones definidas por el usuario

También puedes definir tus propias sustituciones. Estas deben cumplir con las reglas siguientes:

  • Las sustituciones deben comenzar con guion bajo (_) y usar solo letras mayúsculas y números (acorde a la expresión regular _[A-Z0-9_]+). Esto evita los conflictos con las sustituciones integradas. Para usar una expresión que comienza con $, debes usar $$. Por lo tanto:
    • $FOO no es válido, ya que no es una sustitución integrada.
    • $$FOO evalúa la string literal $FOO.
  • La cantidad de parámetros está limitada a 100. La longitud de la clave de parámetro se limita a 100 bytes y la longitud del valor de parámetro se limita a 4,000 bytes.

Hay dos maneras de especificar variables: $_FOO o ${_FOO}:

  • $_FOO y ${_FOO} evalúan el valor de _FOO. Sin embargo, ${} permite que la sustitución funcione sin espacios circundantes, lo que permite realizar sustituciones como ${_FOO}BAR.
  • $$ te permite incluir un $ literal en la plantilla. Por lo tanto:
    • $_FOO evalúa el valor de _FOO.
    • $$_FOO evalúa la string literal $_FOO.
    • $$$_FOO evalúa la string literal $ seguida del valor de _FOO.

Para usar las sustituciones, usa el argumento --substitutions del comando de gcloud o especifícalas en el archivo de configuración.

En el ejemplo siguiente, se muestra una configuración de compilación con dos sustituciones definidas por el usuario llamadas _NODE_VERSION_1 y _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}"
    ]
}

Para anular el valor de sustitución que especificaste en el archivo de configuración de compilación, usa la marca --substitutions del comando gcloud builds submit. Ten en cuenta que las sustituciones son una asignación de variables a valores, en lugar de arreglos o secuencias. Puedes anular los valores predeterminados de las variables de sustitución, excepto $PROJECT_ID y $BUILD_ID. Con el siguiente comando, se anula el valor predeterminado para _NODE_VERSION_1, especificado en el archivo de configuración de compilación anterior:

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .

De forma predeterminada, la compilación muestra un error si falta una sustitución o una variable de sustitución. Sin embargo, puedes configurar la opción ALLOW_LOOSE para omitir esta comprobación.

El fragmento siguiente imprime "hello world" y define una sustitución sin usar. Debido a que la opción de sustitución ALLOW_LOOSE está establecida, la compilación tendrá éxito a pesar de la sustitución faltante.

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

Si un activador invoca tu compilación, la opción ALLOW_LOOSE se establece de forma predeterminada. En este caso, tu compilación no mostrará un error si falta una variable de sustitución o una sustitución. No puedes anular la opción ALLOW_LOOSE para las compilaciones que invocan activadores.

Si no se especifica la opción ALLOW_LOOSE, las claves no coincidentes de tu solicitud de asignación o asignación de sustituciones generarán un error. Por ejemplo, si tu solicitud de compilación incluye $_FOO y la asignación de sustituciones no define _FOO, recibirás un error después de ejecutar tu compilación o invocar un activador si tu activador incluye variables de sustitución.

Cuando defines una variable de sustitución, no estás limitado a strings estáticas. También tienes acceso a la carga útil del evento que invocó tu activador. Están disponibles como vinculaciones de carga útil. También puedes aplicar expansiones de parámetros de Bash en variables de sustitución y almacenar la string resultante como una nueva variable de sustitución. Para obtener más información, consulta Usa vinculaciones de carga útil y expansiones de parámetros de Bash en sustituciones.

¿Qué sigue?