Sustituye valores de variables

Usa substitutions en tu archivo de configuración de compilación para sustituir variables específicas en el entorno de ejecució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 el campo substitutions en tus steps de compilación y los campos images para resolver tus valores en el momento de la compilación.

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

Usa sustituciones predeterminadas

Cloud Build proporciona las sustituciones predeterminadas siguientes:

  • $PROJECT_ID: build.ProjectId
  • $BUILD_ID: build.BuildId
  • $COMMIT_SHA: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha (solo disponible para compilaciones activadas)
  • $SHORT_SHA: los primeros siete caracteres de COMMIT_SHA (solo disponibles para compilaciones activadas)
  • $REPO_NAME: build.Source.RepoSource.RepoName (solo disponible para compilaciones activadas)
  • $BRANCH_NAME: build.Source.RepoSource.Revision.BranchName (solo disponible para compilaciones activadas)
  • $TAG_NAME: build.Source.RepoSource.Revision.TagName (solo disponible para compilaciones activadas)
  • $REVISION_ID: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha (solo disponible para compilaciones activadas)

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 variables que, por lo general, provendrían de las compilaciones activadas con el argumento --substitutions. En particular, puedes proporcionar valores de forma manual para estos elementos:

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

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

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

El ejemplo siguiente usa las sustituciones predeterminadas $BUILD_ID, $PROJECT_ID 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=$PROJECT_ID'
  - '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=$PROJECT_ID",
        "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 con el paso de compilación docker para compilar una imagen, luego, envía la imagen a Container Registry mediante la sustitución predeterminada $PROJECT_ID:

En este ejemplo, sucede lo siguiente:

  • 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 de Docker.
    • El campo args en el paso especifica los argumentos que deben pasar al comando docker, en este caso, build -t gcr.io/my-project/cb-demo-img . se invocará (después de que $PROJECT_ID se sustituya con tu 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 un guion bajo (_) y usar solo letras mayúsculas y números (deben respetar la expresión regular _[A-Z0-9_]+). Esto evita conflictos con las sustituciones integradas.
  • Las claves no coincidentes en la plantilla causarán un error (por ejemplo, si una solicitud de compilación incluye $_FOO y el mapa de sustituciones no define _FOO).
  • Las claves no coincidentes en la lista de parámetros generarán un error (por ejemplo, si un mapa de sustituciones define _FOO, pero la solicitud de compilación no incluye $_FOO).
  • La cantidad de parámetros está limitado a 100. La longitud de una clave de parámetro y la longitud de un valor del parámetro están limitadas a 100 caracteres.

Puedes definir las variables de una de las tres formas siguientes: $_FOO, ${_FOO} o $$_FOO:

  • Tanto $_FOO como ${_FOO} evalúan el valor de _FOO. Sin embargo, ${} hace que la sustitución funcione sin espacios, lo que permite realizar sustituciones como ${_FOO}BAR.
  • $$_FOO permite incluir una variable literal en la plantilla. Es decir, $$_FOO evalúa el carácter literal $ seguido del valor de _FOO.

Para usar las sustituciones, usa el argumento --substitutions en el comando de gcloud o especifícalo 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 en el comando gcloud builds submit. Ten en cuenta que las sustituciones son una asignación de variables a valores, en lugar de arreglos o secuencias. 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:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "unused"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

Pasos siguientes

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...