Como criar e depurar localmente

Nesta página, explicamos como usar o Cloud Build na máquina local. Usando o criador local, você pode:

  • iterar versões mais rapidamente na sua máquina local;
  • usar uma simulação para limpar seu arquivo de configuração.

Antes de começar

  1. Instale e inicialize o Google Cloud SDK.

  2. Instale o Docker. É uma prática recomendada usar a mesma versão do Docker do Cloud Build.

  3. Você precisa de um código-fonte para compilar, um arquivo de configuração da versão e acesso da sua máquina local a quaisquer ferramentas e dependências exigidas pelas etapas de compilação.

  4. Se a versão precisar acessar um registro particular, instale e configure o auxiliar de credencial do Docker para o Cloud Build com a execução dos seguintes comandos:

    gcloud components install docker-credential-gcr
    
    docker-credential-gcr configure-docker
    

Instale o criador local

O criador local é um componente da ferramenta gcloud do Google Cloud SDK. Você pode instalá-lo usando o comando gcloud, apt-get ou yum, dependendo do sistema.

Para instalar o criador local, execute este comando:

gcloud

gcloud components install cloud-build-local

apt-get

sudo apt-get install google-cloud-sdk-cloud-build-local

yum

sudo yum install google-cloud-sdk-cloud-build-local

Depois que o criador local estiver instalado, para visualizar:

  • a ajuda para a linha de comando, execute:

    cloud-build-local --help
    
  • a versão instalada do criador local, execute:

    cloud-build-local --version
    

Criar localmente

Aviso: execute uma versão por vez na sua máquina local. A execução de várias versões em paralelo causará falha no criador local.

Se ainda não tiver um projeto configurado, você poderá testar o construtor local usando a configuração do Guia de início rápido.

Para criar localmente, execute este comando:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --push [SOURCE_CODE]

em que:

  • [BUILD_CONFIG] é o caminho e o nome do seu arquivo de configuração.
    • Por exemplo, se o arquivo de configuração estiver no diretório de trabalho e se chamar cloudbuild.json, use a sinalização --config=cloudbuild.json.
    • O valor padrão é cloudbuild.yaml. Portanto, se o arquivo de configuração estiver no diretório de trabalho e se chamar cloudbuild.yaml, não será necessário adicionar esta sinalização.
  • [SOURCE_CODE] é o caminho para seu código-fonte.
    • Assim como acontece com o Cloud Build, será possível usar . para a origem se o código-fonte estiver no diretório de trabalho atual.
    • Se a versão não precisar de código-fonte, use a sinalização --no-source no lugar de [SOURCE_CODE].
  • --dryrun=false permite que sua versão seja executada. A sinalização --dryrun é verdadeira por padrão. A execução com o valor padrão lança seu arquivo de configuração, mas não executa comandos de versão. Você precisa definir --dryrun=false explicitamente para executar sua versão.
  • --push enviará as imagens resultantes para o repositório definido pelo campo images no arquivo de configuração. Por padrão, as imagens são criadas, mas não são enviadas para o registro.

Depois que a versão for concluída, as imagens criadas estarão disponíveis na sua máquina local por meio do Docker. Se você adicionou --push ao comando de versão, elas estarão disponíveis no repositório especificado.

Preservar artefatos intermediários

Durante uma criação, artefatos intermediários são colocados em um diretório chamado workspace. Por padrão, o criador exclui o espaço de trabalho e os conteúdos dele no final de uma versão.

Para executar uma versão e preservar os artefatos do espaço de trabalho, execute o comando:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --write-workspace=[LOCAL_DIRECTORY_PATH] [SOURCE_CODE]

em que:

  • [BUILD_CONFIG] é o caminho para seu arquivo de configuração;
  • [SOURCE_CODE] é o caminho para seu código-fonte;
  • [LOCAL_DIRECTORY_PATH] é o diretório local em que você quer que o espaço de trabalho seja armazenado na máquina local. Esse diretório não pode residir no diretório [SOURCE_CODE].

A preservação do espaço de trabalho permite que você:

  • analise os artefatos intermediários ao depurar uma versão;
  • acesse um resultado de versão, como um binário, que o criador gerou no espaço de trabalho.

Usar substituições na sua versão

Para usar substituições na sua versão, use a sinalização --substitutions com o par key=value que você quer substituir. É possível especificar valores para determinadas variáveis padrão, bem como variáveis definidas.

Por exemplo:

cloud-build-local --config=[BUILD_CONFIG] --dryrun=false --substitutions _KEY=value,_FOO=foo [SOURCE_CODE]

em que:

  • [BUILD_CONFIG] é o caminho para seu arquivo de configuração;
  • [SOURCE_CODE] é o caminho para seu código-fonte;
  • neste exemplo, _KEY será substituído por value, e _FOO será substituído por foo.

Para saber mais detalhes sobre substituições, incluindo a sintaxe exigida, consulte Substituições.

Depurar sua versão localmente

Para depurar sua versão, é possível:

As versões locais são executadas com as permissões disponíveis no ambiente de execução no seu host local. No Cloud Build, a etapa de versão é executada com as permissões da conta de serviço do seu projeto. Caso você esteja depurando um problema de permissões, não se esqueça de configurar as permissões de acordo com as da conta de serviço do Cloud Build. Dessa maneira, as versões locais estão em um ambiente mais próximo possível do ambiente do Cloud Build.

Verificar a versão com uma simulação

Uma simulação da versão limpará o arquivo de configuração e produzirá erros se detectar algum problema. Uma simulação não executa a versão. Portanto, você pode verificar o arquivo de configuração sem a sobrecarga da execução da versão. Usar o criador local é a única maneira de fazer uma simulação de uma versão.

  1. Faça uma simulação da versão usando o comando:

    cloud-build-local --config=[BUILD_CONFIG] [SOURCE_CODE]
    

    em que:

    • [BUILD_CONFIG] é o caminho para seu arquivo de configuração;
    • [SOURCE_CODE] é o caminho para seu código-fonte.
  2. Revise todas as mensagens de erro e corrija quaisquer problemas no seu arquivo de configuração.

Restrições e limitações

  • O criador local pode criar apenas em Linux ou macOS.
  • O criador local executa uma versão por vez em um determinado host. A execução de várias versões em paralelo fará com que o criador local apresente falha.

Diferenças entre o criador local e o Cloud Build

O criador local foi projetado para imitar o Cloud Build. Uma versão executada com sucesso no criador local será executada com o mesmo comportamento no Cloud Build.

Diferenças que existem entre os dois criadores:

  • O criador local é executado na máquina local, e o Cloud Build é executado no Google Cloud Platform.
  • Para executar a versão, o criador local usa sua conta pessoal, e o Cloud Build usa a conta de serviço do cloudbuild [PROJECT_ID]@cloudbuild.gserviceaccount.com. Se você definir quaisquer permissões na sua conta pessoal para o criador local, talvez seja necessário replicá-las na conta de serviço do cloudbuild. Para saber mais detalhes, consulte Como configurar permissões da conta de serviço.
  • A versão do Docker usada pelos criadores pode ser diferente. Durante a execução, o criador local imprime um aviso sempre que a versão do Docker instalada for diferente da usada no Cloud Build. É uma prática recomendada usar a mesma versão do Docker utilizada pelo Cloud Build.

A seguir

Enviar comentários sobre…