Como substituir valores variáveis

Use substitutions no seu arquivo de configuração de versão para substituir variáveis ​​específicas no tempo de execução. As substituições são úteis para variáveis com um valor que não é conhecido até o momento da versão ou para reutilizar uma solicitação de versão existente com valores variáveis diferentes.

O Cloud Build fornece substituições integradas ou você pode definir as próprias substituições. Use o campo substitutions nos campos steps e images da versão para resolver os valores deles no momento da criação.

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

Como usar substituições padrão

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

  • $PROJECT_ID: build.ProjectId
  • $BUILD_ID: build.BuildId
  • $COMMIT_SHA: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha (disponível somente para versões acionadas)
  • $SHORT_SHA: os primeiros sete caracteres de COMMIT_SHA (somente disponíveis para versões acionadas)
  • $REPO_NAME: build.Source.RepoSource.RepoName (disponível somente para versões acionadas)
  • $BRANCH_NAME: build.Source.RepoSource.Revision.BranchName (disponível somente para versões acionadas)
  • $TAG_NAME: build.Source.RepoSource.Revision.TagName (disponível somente para versões acionadas)
  • $REVISION_ID: build.SourceProvenance.ResolvedRepoSource.Revision.CommitSha (disponível somente para versões acionadas)

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 argumento --substitutions. 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"

O exemplo a seguir usa 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 a seguir, mostramos uma solicitação de versão usando a etapa de versão docker para criar uma imagem, que é enviada para o Container Registry usando a substituição $PROJECT_ID padrão:

Neste exemplo:

  • A solicitação de versão tem uma única etapa de versão, que usa a etapa de versão docker em gcr.io/cloud-builders para criar a imagem do Docker.
    • O campo args na etapa especifica os argumentos que precisam ser transmitidos ao comando docker. Nesse caso, build -t gcr.io/my-project/cb-demo-img . será chamado depois que $PROJECT_ID for substituído pelo código do seu 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:

  • As substituições precisam começar com um sublinhado (_) e usar apenas letras maiúsculas e números (respeitando a expressão regular _[A-Z0-9_]+). Isso evita conflitos com substituições incorporadas.
  • As chaves sem correspondência no modelo resultarão em um erro. Por exemplo, caso uma solicitação de versão inclua $_FOO e o mapa de substituições não defina _FOO.
  • As chaves sem correspondência na lista de parâmetros resultarão em um erro. Por exemplo, se um mapa de substituições definir _FOO, mas a solicitação de versão incluir $_FOO.
  • O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro e o comprimento de um valor de parâmetro são limitados a 100 caracteres.

É possível definir variáveis de três maneiras: $_FOO, ${_FOO} ou $$_FOO:

  • Tanto $_FOO quanto ${_FOO} avaliam o valor de _FOO. No entanto, ${} faz a substituição funcionar sem espaços, o que permite substituições como ${_FOO}BAR.
  • $$_FOO permite incluir uma variável literal no modelo. Ou seja, $$_FOO avalia para o caractere literal $ seguido do valor de _FOO.

Para usar as substituições, use o argumento --substitutions no comando gcloud ou especifique-as 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 substituir o valor de substituição especificado no arquivo de configuração de versã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 seguinte comando substitui o valor padrão de _NODE_VERSION_1 especificado no arquivo de configuração de versã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 houver uma variável de substituição ausente ou uma substituição ausente. No entanto, você pode definir a opção ALLOW_LOOSE para ignorar 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"
    }
}

Próximas etapas

Enviar comentários sobre…