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
• $REPO_FULL_NAME: o nome completo do repositório, incluindo o usuário ou a organização
• $BRANCH_NAME: o nome da sua ramificação
• $TAG_NAME: o nome da sua tag
• $REF_NAME: o nome da ramificação ou tag
• $TRIGGER_BUILD_CONFIG_PATH: o caminho para o arquivo de configuração do build usado durante a execução da versão. Caso contrário, uma string vazia se o build for configurado inline no gatilho ou usando Dockerfile ou Buildpack.
• $SERVICE_ACCOUNT_EMAIL: e-mail da conta de serviço que você está usando para o build. Essa é uma conta de serviço padrão ou uma conta de serviço especificada pelo usuário.
• $SERVICE_ACCOUNT: o nome do recurso da conta de serviço, no formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL.

Observação: $COMMIT_SHA e $REVISION_ID representam o ID de confirmação associado ao build. As duas substituições estão disponíveis.

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
• $REPO_FULL_NAME
• $BRANCH_NAME
• $TAG_NAME
• $REF_NAME
• $TRIGGER_BUILD_CONFIG_PATH
• $SERVICE_ACCOUNT_EMAIL
• $SERVICE_ACCOUNT

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 200. 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:
    substitutionOption: '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 seguintes variáveis de substituição sempre contêm um valor de string vazia padrão, mesmo que você não defina a opção ALLOW_LOOSE:

• $REPO_NAME
• $REPO_FULL_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 dynamicSubstitutions para true no arquivo de configuração do build. Se o build for invocado por um gatilho, o campo dynamicSubstitutions 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 dynamicSubstitutions para true para que as expansões de parâmetro bash sejam interpretadas ao executar o build.

O arquivo de configuração de build a seguir mostra a variável de substituição ${_IMAGE_NAME} referenciando a variável, ${PROJECT_ID}. O campo dynamicSubstitutions é definido como true para que a referência seja aplicada ao invocar um build manualmente:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
    dynamicSubstitutions: 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 mais informações, consulte Como aplicar expansões de parâmetro bash.

Como mapear substituições para variáveis de ambiente

Os scripts não aceitam diretamente substituições, mas aceitam variáveis de ambiente. É possível mapear as substituições para variáveis de ambiente de maneira automática de uma só vez ou manualmente, definindo cada variável de ambiente por conta própria.

Substituições de mapas automaticamente

• No nível de build. Para mapear automaticamente todas as substituições para variáveis de ambiente, que estarão disponíveis em todo o build, defina automapSubstitutions como true como uma opção no nível do build. Por exemplo, o arquivo de configuração de build a seguir mostra a substituição definida pelo usuário $_USER e a substituição padrão $PROJECT_ID mapeada para variáveis de ambiente:

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
  options:
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'"
      }
    ],
    "options": {
      "automap_substitutions": true
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  }
  

• No nível da etapa. Para mapear automaticamente todas as substituições e disponibilizá-las como variáveis de ambiente em uma única etapa, defina o campo automapSubstitutions como true nessa etapa. No exemplo a seguir, apenas a segunda etapa mostrará as substituições corretamente, porque é a única com o mapeamento automático de substituições ativado:

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
        "automap_substitutions": true
      }
    ],
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  

  Além disso, é possível disponibilizar as substituições como variáveis de ambiente em toda a compilação e ignorá-las em uma etapa. Defina automapSubstitutions como true no nível da versão e, em seguida, defina o mesmo campo como false na etapa em que você quer ignorar as substituições. No exemplo a seguir, mesmo que as substituições de mapeamento estejam ativadas no nível da versão, o ID do projeto não será impresso na segunda etapa, porque automapSubstitutions está definido como false:

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: false
  options:
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
        "automap_substitutions": false
      }
    ],
    "options": {
      "automap_substitutions": true
    },
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  

Substituições de mapas manualmente

É possível mapear manualmente as substituições para variáveis de ambiente. Cada variável de ambiente é definida no nível da etapa usando o campo env, e o escopo das variáveis é restrito à etapa em que são definidas. Esse campo usa uma lista de chaves e valores.

O exemplo a seguir mostra como mapear a substituição $PROJECT_ID para a variável de ambiente BAR:

YAML

steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

A seguir

• Saiba como usar vinculações de payload e expansões de parâmetros bash em substituições.
• Saiba como criar um arquivo de configuração de compilação básico.
• Saiba como criar e gerenciar gatilhos de compilação.
• Saiba como executar builds manualmente no Cloud Build.