Como substituir valores de 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 da tag
  • $TRIGGER_BUILD_CONFIG_PATH: o caminho para o arquivo de configuração do build usado durante a execução do build. caso contrário, uma string vazia se o build for configurada in-line no gatilho ou usa um Dockerfile ou Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: e-mail da conta de serviço que você está usando para o build. É uma conta de serviço padrão ou um serviço especificado pelo usuário do Compute Engine.
  • $SERVICE_ACCOUNT: o nome do recurso da conta de serviço, no formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

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"

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 começa com $, é necessário usar $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO para avaliar 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.
    • $$ allows you to include a literal $ in the template. Thus:
      • $_FOO evaluates to the value of _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 variáveis de substituição a seguir sempre contêm um valor padrão de string vazia, 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 do build a seguir mostra a variável de substituição ${_IMAGE_NAME} que referencia 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âmetros bash.

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

      Os scripts não oferecem suporte direto a substituições, mas dão suporte ao ambiente variáveis. É possível mapear substituições para variáveis de ambiente da seguinte forma: automaticamente de uma só vez ou manualmente definindo cada variável de ambiente você mesmo.

      As substituições de mapas são automáticas

      • No nível do 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. Para exemplo, o arquivo de configuração de build a seguir mostra as instâncias definidas pelo usuário A substituição $_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 fazer como variáveis de ambiente em uma única etapa, defina automapSubstitutions como true. Nos seguintes exemplo, somente a segunda etapa mostrará as substituições corretamente, porque é o único com mapeamento de substituições automáticas 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 código variáveis em todo o build e as ignorar em uma etapa. Definir automapSubstitutions como true no nível do build e, em seguida, defina os mesmos como false na etapa em que você quer ignorar as substituições. No exemplo abaixo, mesmo que as substituições de mapeamento estejam ativadas no nível de build, o ID do projeto não será impresso na segunda etapa porque automapSubstitutions está definido como false nessa etapa:

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

      Mapear substituições manualmente

      É possível mapear manualmente as substituições para as variáveis de ambiente. Todas é definida no nível da etapa usando o variável de ambiente env campo, e o escopo das variáveis fica restrito à etapa onde eles são definidos. Esse campo recebe uma lista de chaves e valores.

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

      YAML 

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

      JSON 

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

      A seguir