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 steps
y images
de la compilación para resolver sus valores en el tiempo 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.$LOCATION
: Es la región asociada con tu compilación.
Cloud Build proporciona las siguientes sustituciones predeterminadas para las compilaciones que invocan los activadores:
$TRIGGER_NAME
: Es el nombre asociado con el activador.$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 deCOMMIT_SHA
.$REPO_NAME
: El nombre de tu repositorio.$REPO_FULL_NAME
: Es el nombre completo del repositorio, incluido el usuario o la organización.$BRANCH_NAME
: El nombre de tu rama.$TAG_NAME
: El nombre de tu etiqueta.$REF_NAME
: el nombre de la rama o etiqueta$TRIGGER_BUILD_CONFIG_PATH
: Es la ruta de acceso al archivo de configuración de compilación que se usa durante la ejecución de la compilación. De lo contrario, es una string vacía si tu compilación está configurada de forma intercalada en el activador o si usaDockerfile
oBuildpack
.$SERVICE_ACCOUNT_EMAIL
: Es el correo electrónico de la cuenta de servicio que usas para la compilación. Esta es una cuenta de servicio predeterminada o una especificada por el usuario.$SERVICE_ACCOUNT
: Es el nombre del recurso de la cuenta de servicio, en el formatoprojects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
.
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:
$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
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 tiene un paso de compilación, que usa el paso de compilación
docker
engcr.io/cloud-builders
para compilar la imagen de Docker.- El campo
args
del paso especifica los argumentos que se deben pasar al comandodocker
. 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
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 comience con$
, debes usar$$
. Entonces:$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 200. 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.
Puedes especificar variables de una de las siguientes dos maneras: $_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 sustituciones como${_FOO}BAR
.$$
te permite incluir una$
literal en la plantilla. Entonces:$_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 de variables de sustitución predeterminados, excepto $PROJECT_ID
y $BUILD_ID
. Con el comando siguiente, 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:
substitutionOption: 'ALLOW_LOOSE'
JSON
{
"steps": [
{
"name": "ubuntu",
"args": [
"echo",
"hello world"
]
}
],
"substitutions": {
"_SUB_VALUE": "unused"
},
"options": {
"substitution_option": "ALLOW_LOOSE"
}
}
Si la compilación se invoca mediante un activador, la opción ALLOW_LOOSE
se configura 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 se puede anular la opción ALLOW_LOOSE
para compilaciones invocadas por activadores.
Si no se especifica la opción ALLOW_LOOSE
, las claves no coincidentes en tu solicitud de compilación o asignación de sustituciones generarán 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.
Las siguientes variables de sustitución siempre contienen un valor predeterminado de cadena vacía, incluso si no configuras la opción ALLOW_LOOSE
:
$REPO_NAME
$REPO_FULL_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA
Cuando defines una variable de sustitución, no estás limitado a las strings estáticas. También tienes acceso a la carga útil del evento que invocó el activador. Están disponibles como vinculaciones de carga útil. También puedes aplicar las 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.
Sustituciones dinámicas
Puedes hacer referencia al valor de otra variable dentro de una sustitución definida por el usuario si configuras la opción dynamicSubstitutions
como true
en el archivo de configuración de compilación. Si un activador invoca a tu compilación, el campo dynamicSubstitutions
siempre se establece en true
y no es necesario especificar en tu archivo de configuración de compilación. Si tu compilación se invoca de forma manual, debes configurar el campo dynamicSubstitutions
como true
para que las expansiones de los parámetros de bash se interpreten cuando se ejecuta tu compilación.
En el siguiente archivo de configuración de compilación, se muestra la variable de sustitución ${_IMAGE_NAME}
que hace referencia a la variable, ${PROJECT_ID}
. El campo dynamicSubstitutions
se establece en true
para que se aplique la referencia cuando se invoca una compilación de forma manual:
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
}
}
Para obtener más información, consulta Aplica expansiones de parámetros de Bash.
Asigna sustituciones a variables de entorno
Las secuencias de comandos no admiten directamente sustituciones, pero admiten variables de entorno. Puedes asignar sustituciones a las variables de entorno, ya sea de forma automática todas a la vez o de forma manual si defines cada variable de entorno por tu cuenta.
Asigna sustituciones automáticamente
A nivel de la compilación: Para asignar automáticamente todas las sustituciones a las variables de entorno, que estarán disponibles durante toda la compilación, configura
automapSubstitutions
comotrue
como opción a nivel de compilación. Por ejemplo, en el siguiente archivo de configuración de compilación, se muestra la sustitución definida por el usuario$_USER
y la sustitución predeterminada$PROJECT_ID
asignadas a las variables de entorno: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" } }
En el nivel del paso. Para asignar automáticamente todas las sustituciones y hacer que estén disponibles como variables de entorno en un solo paso, establece el campo
automapSubstitutions
entrue
en ese paso. En el siguiente ejemplo, solo el segundo paso mostrará las sustituciones de forma correcta, ya que es el único que tiene habilitada la asignación de sustituciones automáticas: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" }
Además, puedes hacer que las sustituciones estén disponibles como variables de entorno en toda la compilación y, luego, ignorarlas en un paso. Configura
automapSubstitutions
comotrue
en el nivel de compilación y, luego, establece el mismo campo enfalse
en el paso en el que deseas ignorar las sustituciones. En el siguiente ejemplo, aunque las sustituciones de asignación están habilitadas en el nivel de compilación, el ID del proyecto no se imprimirá en el segundo paso, ya queautomapSubstitutions
se establece enfalse
en ese paso: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" }
Asigna sustituciones manualmente
Puedes asignar las sustituciones a las variables de entorno de forma manual. Cada variable de entorno se define a nivel del paso con el campo env
, y el alcance de las variables se restringe al paso en el que se definen. Este campo toma una lista de claves y valores.
En el siguiente ejemplo, se muestra cómo asignar la sustitución $PROJECT_ID
a la variable de entorno BAR
:
YAML
steps:
- name: 'ubuntu'
env:
- 'BAR=$PROJECT_ID'
script: 'echo $BAR'
JSON
{
"steps": [
{
"name": "ubuntu",
"env": [
"BAR=$PROJECT_ID"
],
"script": "echo $BAR"
}
]
}
¿Qué sigue?
- Aprende a usar vinculaciones de carga útil y expansiones de parámetros de bash en sustituciones.
- Obtén más información sobre cómo crear un archivo de configuración de compilación básico.
- Obtén más información sobre cómo crear y administrar activadores de compilación.
- Obtén información en Ejecuta las compilaciones de forma manual en Cloud Build.