Sustituir valores de variables

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

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

Cloud Build proporciona sustituciones predefinidas, pero también puedes definir tus propias sustituciones. Usa substitutions en los archivos steps y images de tu compilación para resolver sus valores en tiempo de compilación.

En esta página se explica cómo usar las sustituciones predeterminadas o definir las suyas propiassubstitutions.

Usar 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: tu número de proyecto
  • $LOCATION: la región asociada a tu compilación

Cloud Build proporciona las siguientes sustituciones predeterminadas para las compilaciones invocadas por activadores:

  • $TRIGGER_NAME: el nombre asociado a tu activador
  • $COMMIT_SHA: el ID de la confirmación asociado a tu compilación
  • $REVISION_ID: el ID de la confirmación asociado a tu compilación
  • $SHORT_SHA : los siete primeros 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 sucursal
  • $TAG_NAME: el nombre de la etiqueta
  • $REF_NAME: el nombre de tu rama o etiqueta
  • $TRIGGER_BUILD_CONFIG_PATH: la ruta al archivo de configuración de compilación que se usa durante la ejecución de la compilación. De lo contrario, se usará una cadena vacía si la compilación se configura de forma insertada en el activador o usa un Dockerfile o un Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: correo de la cuenta de servicio que estás usando para la compilación. Puede ser una cuenta de servicio predeterminada o una cuenta de servicio especificada por el usuario.
  • $SERVICE_ACCOUNT: el nombre del recurso de la cuenta de servicio, con el formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

Cloud Build proporciona las siguientes sustituciones predeterminadas específicas de GitHub que están 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 no hay una sustitución predeterminada disponible (por ejemplo, en compilaciones sin fuente o en compilaciones que usan una fuente de almacenamiento), las instancias de la variable que falte se sustituirán por una cadena vacía.

Al iniciar una compilación con gcloud builds submit, puedes especificar variables que normalmente proceden de compilaciones activadas con el argumento --substitutions. En concreto, puede proporcionar manualmente los valores de los siguientes atributos:

  • $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 siguiente comando 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 ejemplo siguiente se muestra una solicitud de compilación que usa el paso de compilación docker para compilar una imagen y, a continuación, la inserta en Container Registry mediante 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 en gcr.io/cloud-builders para compilar la imagen Docker.
    • El campo args del paso especifica los argumentos que se deben transferir al comando docker. En este caso, se invocará build -t gcr.io/my-project/cb-demo-img . (después de sustituir $PROJECT_ID por el ID de tu proyecto).

  • El campo images contiene el nombre de la imagen. Si la compilación se realiza correctamente, la imagen resultante se envía a Container Registry. Si la compilación no crea la imagen correctamente, 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"
  ]
}

Usar sustituciones definidas por el usuario

También puedes definir tus propias sustituciones. Las sustituciones definidas por el usuario deben cumplir las siguientes reglas:

  • Las sustituciones deben empezar por un guion bajo (_) e incluir solo letras mayúsculas y números (respetando la expresión regular _[A-Z0-9_]+). De esta forma, se evitan conflictos con las sustituciones integradas. Para usar una expresión que empiece por $, debes usar $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO, que se evalúa como la cadena literal $FOO.
  • El número de parámetros está limitado a 200. La longitud de una clave de parámetro es de 100 bytes como máximo y la de un valor de parámetro, de 4000 bytes.

    • Puedes especificar variables de dos formas: $_FOO o ${_FOO}:

    • Tanto $_FOO como ${_FOO} dan como resultado el valor de _FOO. Sin embargo, ${} permite que la sustitución funcione sin espacios alrededor, lo que permite sustituciones como ${_FOO}BAR.
    • $$ allows you to include a literal $ in the template. Thus:
      • $_FOO evaluates to the value of _FOO.
      • $$_FOO da como resultado la cadena literal $_FOO.
      • $$$_FOO se evalúa como la cadena literal $ seguida del valor de _FOO.

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

      En el siguiente ejemplo 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 has especificado en el archivo de configuración de compilación, usa la marca --substitutions en el comando gcloud builds submit. Ten en cuenta que las sustituciones son una asignación de variables a valores, no a matrices ni a secuencias. Puedes anular los valores predeterminados de las variables de sustitución, excepto $PROJECT_ID y $BUILD_ID. El siguiente comando anula el valor predeterminado de _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 devuelve un error si falta una variable de sustitución o una sustitución. Sin embargo, puedes seleccionar la opción ALLOW_LOOSE para saltarte esta comprobación.

      El siguiente fragmento imprime "hello world" y define una sustitución que no se usa. Como se ha definido la opción de sustitución ALLOW_LOOSE, la compilación se realizará correctamente a pesar de que falte la sustitución.

      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 una compilación se invoca mediante un activador, la opción ALLOW_LOOSE se define de forma predeterminada. En este caso, la compilación no devolverá un error si falta una variable de sustitución o una sustitución. No puedes anular la opción ALLOW_LOOSE en las compilaciones invocadas por activadores.

      Si no se especifica la opción ALLOW_LOOSE, se producirá un error si hay claves sin correspondencia en la asignación de sustituciones o en la solicitud de compilación. 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 la compilación o invocar un activador si este incluye variables de sustitución.

      Las siguientes variables de sustitución siempre contienen un valor predeterminado de cadena vacía, aunque no definas la opción ALLOW_LOOSE:

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

      Al definir una variable de sustitución, no tienes que limitarte a cadenas estáticas. También tienes acceso a la carga útil del evento que ha invocado el activador. Están disponibles como enlaces de carga útil. También puede aplicar expansiones de parámetros bash a variables de sustitución y almacenar la cadena resultante como una nueva variable de sustitución. Para obtener más información, consulta Usar vinculaciones de carga útil y expansiones de parámetros bash en sustituciones.

      Sustituciones dinámicas

      Puedes hacer referencia al valor de otra variable en una sustitución definida por el usuario configurando la opción dynamicSubstitutions como true en el archivo de configuración de compilación. Si una compilación se invoca mediante un activador, el campo dynamicSubstitutions siempre se define como true y no es necesario especificarlo en el archivo de configuración de la compilación. Si la compilación se invoca manualmente, debes asignar el valor true al campo dynamicSubstitutions para que las expansiones de parámetros de bash se interpreten al ejecutar la compilación.

      El siguiente archivo de configuración de compilación muestra la variable de sustitución ${_IMAGE_NAME} que hace referencia a la variable ${PROJECT_ID}. El campo dynamicSubstitutions se define como true para que la referencia se aplique al invocar una compilación manualmente:

      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 Aplicar expansiones de parámetros de bash.

      Asignar sustituciones a variables de entorno

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

      Asignar sustituciones automáticamente

      • A nivel de compilación. Para asignar automáticamente todas las sustituciones a variables de entorno, que estarán disponibles durante toda la compilación, define automapSubstitutions como true en las opciones de nivel de compilación. Por ejemplo, el siguiente archivo de configuración de compilación muestra la sustitución $_USER definida por el usuario y la sustitución $PROJECT_ID predeterminada 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 de paso. Para asignar automáticamente todas las sustituciones y hacerlas disponibles como variables de entorno en un solo paso, asigna el valor true al campo automapSubstitutions en ese paso. En el siguiente ejemplo, solo en el segundo paso se mostrarán 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, a continuación, ignorarlas en un solo paso. Define automapSubstitutions como true en el nivel de compilación y, a continuación, define el mismo campo como false en el paso en el que quieras ignorar las sustituciones. En el siguiente ejemplo, aunque las sustituciones de asignación estén habilitadas a nivel de compilación, el ID del proyecto no se imprimirá en el segundo paso porque automapSubstitutions se ha definido como 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"
  }

      Asignar sustituciones manualmente

      Puedes asignar manualmente las sustituciones a variables de entorno. Cada variable de entorno se define en el nivel del paso mediante el campo env, y el ámbito de las variables se limita al paso en el que se definen. Este campo acepta 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"
    }
  ]
}

      Siguientes pasos