Sustituye valores de variables

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

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: La región asociada a 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 de COMMIT_SHA.
• $REPO_NAME: El nombre de tu repositorio.
• $REPO_FULL_NAME: El nombre completo de tu 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 tu 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 cadena vacía si la compilación está configurada intercalada en el activador o usa Dockerfile o Buildpack.
• $SERVICE_ACCOUNT_EMAIL: Es el correo electrónico de la cuenta de servicio que usas para la compilación. Puede ser una cuenta de servicio predeterminada o una cuenta de servicio especificada por el usuario.
• $SERVICE_ACCOUNT: Es el nombre del recurso de la cuenta de servicio, en el formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL.

Nota: $COMMIT_SHA y $REVISION_ID representan el ID de confirmación asociado con tu compilación. Hay asistencia para ambas sustituciones disponibles.

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', '${_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"
  ]
}

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 Artifact 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 se realiza correctamente, la imagen resultante se envía a Artifact 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", "${_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"
  ]
}

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 $$. For example:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO que evalúa la cadena 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.
• $$ lets you include a literal $ in the template. For example:
  • $_FOO evaluates to the value of _FOO.
  • $$_FOO evalúa la string literal $_FOO.
  • $$$_FOO evaluates to the literal string $ followed by the value of _FOO.

To use the substitutions, use the --substitutions argument in the gcloud command or specify them in the config file.

The following example shows a build config with two user-defined substitutions called _NODE_VERSION_1 and _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}"
    ]
}

To override the substitution value you specified in the build config file, use the --substitutions flag in the gcloud builds submit command. Note that substitutions are a mapping of variables to values rather than arrays or sequences. You can override default substitution variable values except for $PROJECT_ID and $BUILD_ID. The following command overrides the default value for _NODE_VERSION_1 specified in the previous build config file:

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

By default, the build returns an error if there's a missing substitution variable or a missing substitution. However, you can set the ALLOW_LOOSE option to skip this check.

The following snippet prints "hello world" and defines an unused substitution. Because the ALLOW_LOOSE substitution option is set, the build will be successful despite the missing substitution.

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

If your build is invoked by a trigger, the ALLOW_LOOSE option is set by default. In this case, your build won't return an error if there is a missing substitution variable or a missing substitution. You cannot override the ALLOW_LOOSE option for builds invoked by triggers.

If the ALLOW_LOOSE option is not specified, unmatched keys in your substitutions mapping or build request will result in error. For example, if your build request includes $_FOO and the substitutions mapping doesn't define _FOO, you will receive an error after running your build or invoking a trigger if your trigger includes substitution variables.

The following substitution variables always contain a default empty-string value even if you don't set the ALLOW_LOOSE option:

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

When defining a substitution variable, you aren't limited to static strings. You also have access to the event payload that invoked your trigger. These are available as payload bindings. You can also apply bash parameter expansions on substitution variables and store the resulting string as a new substitution variable. To learn more, see Using payload bindings and bash parameter expansions in substitutions.

Dynamic substitutions

You can reference the value of another variable within a user-defined substitution by setting the dynamicSubstitutions option to true in your build config file. If your build is invoked by a trigger, the dynamicSubstitutions field is always set to true and does not need to be specified in your build config file. If your build is invoked manually, you must set the dynamicSubstitutions field to true for bash parameter expansions to be interpreted when running your build.

The following build config file shows the substitution variable ${_IMAGE_NAME} referencing the variable, ${PROJECT_ID}. The dynamicSubstitutions field is set to true so the reference is applied when invoking a build manually:

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

For more information, see Applying bash parameter expansions.

Secret substitutions

You can substitute secrets from Secret Manager in Cloud Build. To do so, include your substitution variable in the value of the versionName field in your build config file.

The following example shows how to define a substitution for a secret version.

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
  secretEnv: ['USERNAME', 'PASSWORD']

availableSecrets:
  secretManager:
  - versionName: projects/$PROJECT_ID/secrets/my-docker-password/versions/$_SECRET_VERSION
    env: 'PASSWORD'
  - versionName: projects/$PROJECT_ID/secrets/my-docker-username/versions/latest
    env: 'USERNAME'

substitutions:
    _SECRET_VERSION: '1' #Default value for the secret version

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "entrypoint": "bash",
      "args": [
        "-c",
        "docker login --username=$$USERNAME --password=$$PASSWORD"
      ],
      "secretEnv": [
        "USERNAME",
        "PASSWORD"
      ]
    }
  ],
  "availableSecrets": {
    "secretManager": [
      {
        "versionName": "projects/$PROJECT_ID/secrets/my-docker-password/versions/$_SECRET_VERSION",
        "env": "PASSWORD"
      },
      {
        "versionName": "projects/$PROJECT_ID/secrets/my-docker-username/versions/latest",
        "env": "USERNAME"
      }
    ]
  },
  "substitutions": {
    "_SECRET_VERSION": "1"
  }
}


Para obtener más información sobre los secretos en Cloud Build, consulta Usa secretos de Secret Manager en la documentación de Cloud Build.

Asigna sustituciones a variables de entorno

Las secuencias de comandos no admiten sustituciones directamente, pero sí admiten variables de entorno. Puedes asignar sustituciones a variables de entorno, ya sea de forma automática y simultánea, o bien manualmente definiendo cada variable de entorno por tu cuenta.

Sustituye mapas automáticamente

A nivel de la compilación Para asignar automáticamente todas las sustituciones a variables de entorno, que estarán disponibles durante toda la compilación, establece automapSubstitutions en true como una opción a nivel de la compilación. Por ejemplo, el siguiente archivo de configuración de compilación muestra la sustitución definida por el usuario $_USER y la sustitución predeterminada $PROJECT_ID asignadas a 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"
  }
}


A nivel del paso Para asignar automáticamente todas las sustituciones y hacerlas disponibles como variables de entorno en un solo paso, configura el campo automapSubstitutions como true en ese paso. En el siguiente ejemplo, solo el segundo paso mostrará las sustituciones correctamente, 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. Establece automapSubstitutions en true a nivel de la compilación y, luego, establece el mismo campo en false en el paso en el que deseas ignorar las sustituciones. En el siguiente ejemplo, aunque las sustituciones de asignación estén habilitadas a nivel de la compilación, el ID del proyecto no se imprimirá en el segundo paso, ya que automapSubstitutions se establece en false 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"
  }



Sustituye el mapa de forma manual

Puedes asignar manualmente las sustituciones a las variables de entorno. 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.