Como substituir valores variáveis

Use substitutions em seu arquivo de configuração da build para substituir variáveis específicas no momento da build.

As substituições são úteis para variáveis ​​cujo valor não é conhecido até o momento da criação ou para reutilizar uma solicitação de versão existente com diferentes valores variáveis.

O Cloud Build fornece substituições integradas ou você pode definir as próprias substituições. Use substitutions no steps e no images do build para resolver os valores no tempo da compilação.

Nesta página, explicamos como usar substituições padrão ou definir sua própria substitutions.

Como usar substituições padrão

O Cloud Build fornece as seguintes substituições padrão para todas as versões:

  • $PROJECT_ID: ID do projeto do Cloud
  • $BUILD_ID: ID da sua versão
  • $PROJECT_NUMBER: o ID do seu projeto
  • $LOCATION: a região associada ao build.

O Cloud Build fornece as seguintes substituições padrão para versões invocadas por gatilhos:

  • $TRIGGER_NAME: o nome associado ao gatilho
  • $COMMIT_SHA: o ID de confirmação associado à sua versão
  • $REVISION_ID: o ID de confirmação associado à sua versão
  • $SHORT_SHA: os primeiros sete caracteres de COMMIT_SHA
  • $REPO_NAME: o nome do seu repositório
  • $BRANCH_NAME: o nome da sua ramificação
  • $TAG_NAME: o nome da sua tag
  • $TRIGGER_BUILD_CONFIG_PATH: o caminho para o arquivo de configuração do build usado durante a execução; caso contrário, uma string vazia se o build estiver configurado inline no gatilho ou usar um Dockerfile ou Buildpack

O Cloud Build fornece as seguintes substituições padrão específicas do GitHub disponíveis para acionadores de solicitação de envio:

  • $_HEAD_BRANCH: head branch da solicitação de envio
  • $_BASE_BRANCH: base branch da solicitação de envio
  • $_HEAD_REPO_URL: url da head repo da solicitação de envio
  • $_PR_NUMBER : número da solicitação de envio

Se uma substituição padrão não estiver disponível, como versões sem código-fonte ou versões que usam um código-fonte do armazenamento, as ocorrências em que as variáveis estão ausentes serão substituídas por uma string vazia.

Ao iniciar uma versão usando gcloud builds submit, é possível especificar variáveis que normalmente viriam de versões acionadas com o --substitutionsargumento. Mais especificamente, você pode fornecer manualmente valores para:

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

Por exemplo, o seguinte comando usa a substituição TAG_NAME:

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

O exemplo a seguir usa as substituições padrão $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER e $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"
  ]
}

No exemplo abaixo, mostramos o uso da etapa de criação docker por uma solicitação de versão para criar uma imagem e transmiti-la para o Container Registry usando a substituição padrão $PROJECT_ID:

Neste exemplo:

  • A solicitação de versão tem uma etapa de criação que usa docker em gcr.io/cloud-builders para criar a imagem do Docker.
    • Os argumentos que serão passados para o comando docker são especificados pelo campo args. Neste caso, build -t gcr.io/my-project/cb-demo-img . será invocado depois da substituição de $PROJECT_ID pelo ID do projeto.

  • O campo images contém o nome da imagem. Se a versão for bem-sucedida, a imagem resultante será transmitida para o Container Registry. Se a versão não criar a imagem corretamente, ela falhará.

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

Como usar substituições definidas pelo usuário

Você também pode definir suas próprias substituições. As substituições definidas pelo usuário precisam obedecer às seguintes regras:

  • É obrigatório que as substituições comecem com um sublinhado (_) e que sejam usadas somente letras maiúsculas e números (respeitando a expressão regular _[A-Z0-9_]+). Isso evita conflitos com substituições integradas. Para usar uma expressão que comece com $, use $$. Sendo assim,
    • $FOO é inválido porque não é uma substituição integrada.
    • $$FOO avalia de acordo com a string literal $FOO.
  • O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro é limitado a 100 bytes e o comprimento de um valor de parâmetro é limitado a 4000 bytes.

É possível especificar variáveis de duas maneiras: $_FOO ou ${_FOO}:

  • Tanto $_FOO quanto ${_FOO} avaliam o valor de _FOO. No entanto, ${} permite que a substituição funcione sem espaços ao redor, o que permite substituições como ${_FOO}BAR.
  • $$ permite que você inclua um $ literal no modelo. Sendo assim,
    • $_FOO avalia de acordo com o valor de _FOO.
    • $$_FOO avalia de acordo com a string literal $_FOO.
    • $$$_FOO é avaliado de acordo com a string literal $ seguida do valor de _FOO.

Nas substituições, use o argumento --substitutions no comando gcloud ou especifique-o no arquivo de configuração.

O exemplo a seguir mostra uma configuração de versão com duas substituições definidas pelo usuário, chamadas _NODE_VERSION_1 e _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 modificar o valor de substituição especificado no arquivo de configuração da criação, use a sinalização --substitutions no comando gcloud builds submit. As substituições são um mapeamento de variáveis para valores, em vez de matrizes ou sequências. É possível substituir os valores de variáveis de substituição padrão, exceto $PROJECT_ID e $BUILD_ID. O comando a seguir modifica o valor padrão de _NODE_VERSION_1 especificado no arquivo de configuração da criação acima:

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

Por padrão, a versão retornará um erro se faltar uma variável de substituição ou uma substituição. No entanto, é possível definir a opção ALLOW_LOOSE para pular essa verificação.

O snippet a seguir imprime "hello world" e define uma substituição não usada. Como a opção de substituição ALLOW_LOOSE está definida, a versão será bem-sucedida, mesmo considerando a substituição ausente.

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

se o build for invocado por um gatilho, a opção ALLOW_LOOSE será definida por padrão. Nesse caso, o build não retornará um erro se houver uma variável de substituição ausente ou uma substituição ausente. Não é possível modificar a opção ALLOW_LOOSE para builds invocados por acionadores.

Se a opção ALLOW_LOOSE não for especificada, as chaves sem correspondência no mapeamento de substituições ou na solicitação do build resultarão em erro. Por exemplo, se a solicitação de build incluir $_FOO e o mapeamento de substituições não definir _FOO, você receberá um erro depois de executar o build ou invocar um gatilho se o acionador inclui variáveis de substituição.

As variáveis de substituição a seguir sempre contêm um valor de string vazia padrão, mesmo que você não defina a opção ALLOW_LOOSE:

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

Ao definir uma variável de substituição, você não está limitado a strings estáticas. Você também tem acesso ao payload do evento que invocou o gatilho. Eles estão disponíveis como vinculações de payload. Também é possível aplicar expansões de parâmetro bash em variáveis de substituição e armazenar a string resultante como uma nova variável de substituição. Para saber mais, consulte Como usar vinculações de payload e expansões de parâmetros bash em substituições.

Substituições dinâmicas

Você pode referenciar o valor de outra variável em uma substituição definida pelo usuário configurando a opção dynamic_substitutions para true no arquivo de configuração do build. Se o build for invocado por um gatilho, o campo dynamic_substitutions será sempre definido para true e não precisará ser especificado no arquivo de configuração do build. Se a versão for invocada manualmente, defina o campo dynamic_substitutions para true para que as expansões de parâmetro bash sejam interpretadas ao executar o build.

O arquivo de configuração da compilação a seguir mostra a variável de substituição ${_IMAGE_NAME} que faz referência à variável ${PROJECT_ID}. O campo dynamic_substitutions está definido como true para que a referência seja aplicada ao invocar manualmente uma versão:

YAML 

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

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 ver mais informações, consulte Como aplicar expansões de parâmetros bash.

A seguir