Como substituir valores variáveis

Use substitutions no seu arquivo de configuração da versão para substituir variáveis específicas no ambiente de execução. As substituições são úteis para variáveis que tenham um 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, mas você também pode definir as próprias substituições. Use o campo substitutions nos campos steps e images da sua versão para resolver os valores no momento da criaçã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

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

  • $COMMIT_SHA: 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
  • $REVISION_ID: o ID de confirmação que se refere à revisão no repositório

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

  • $_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:

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

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

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

No exemplo a seguir, são usadas as substituições padrão $BUILD_ID, $PROJECT_ID 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=$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"
  ]
}

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.
  • Chaves sem correspondência no modelo causam um erro, por exemplo, se uma solicitação de versão incluir $_FOO e o mapa de substituições não definir _FOO.
  • Na lista de parâmetros, as chaves sem correspondência resultarão em um erro, por exemplo, se um mapa de substituições definir _FOO, mas a solicitação de versão não incluir $_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. 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"
    }
}

A seguir