Ajude a moldar o futuro da entrega de software e manifeste-se respondendo à pesquisa sobre o estado de DevOps 2202.

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

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

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

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, $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 gatilho inclui variáveis de substituição.

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. Você também pode aplicar expansões de parâmetros 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

É possível referenciar o valor de outra variável dentro de uma substituição definida pelo usuário definindo a opção dynamic_substitutions como true no arquivo de configuração da versão. Se a versão for invocada por um gatilho, o campo dynamic_substitutions será sempre definido como true e não precisará ser especificado no arquivo de configuração da criação. Se sua versão for invocada manualmente, defina o campo dynamic_substitutions como true para que as expansões de parâmetros bash sejam interpretadas ao executar sua versão. Para mais informações, consulte Como aplicar expansões de parâmetros bash.

A seguir