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

Instale e inicialize o Google Cloud SDK.
Instale o Docker. É recomendado usar a mesma versão do Docker do Cloud Build.
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.
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
gcloud auth configure-docker
```

Instale o criador local

O builder local é um componente da ferramenta gcloud do SDK do Google Cloud. Instale-o usando o comando gcloud, apt-get ou yum, dependendo do seu sistema.

Para instalar o builder 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 builder local estiver instalado, para visualizar:

a ajuda para a linha de comando, execute:
```
cloud-build-local --help
```
a versão instalada do builder 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 seu arquivo de configuração estiver no diretório de trabalho e for denominado cloudbuild.json, use a sinalização --config=cloudbuild.json.
- O valor padrão é cloudbuild.yaml. Portanto, se seu arquivo de configuração estiver no diretório de trabalho e for nomeado cloudbuild.yaml, você não precisará adicionar essa 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 o build não precisar do código-fonte, use a sinalização --no-source em vez de [SOURCE_CODE].
--dryrun=false permite que sua compilaçã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 explicitamente --dryrun=false para executar o build.
--push envia as imagens ou os artefatos resultantes para o destino definido pelo campo images ou artifacts no arquivo de configuração. Por padrão, imagens e artefatos são criados, mas não são enviados.

Após a conclusão da versão, as imagens criadas estão disponíveis na sua máquina local por meio do Docker. Se você adicionar --push ao comando de build, eles estarão disponíveis no repositório especificado.

Preservar artefatos intermediários

Durante uma compilação, os artefatos intermediários são colocados em um diretório denominado 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]

Onde:

[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 compilação

Para usar substituições no build, 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 mais detalhes sobre substituições, incluindo a sintaxe exigida, consulte Substituições.

Depurar sua versão localmente

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

verificar se o arquivo de configuração está correto fazendo uma simulação da versão;
inspecionar os artefatos intermediários criados no espaço de trabalho durante a versão. Para fazer isso, consulte Preservar artefatos intermediários acima.

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.

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.
Analise todas as mensagens de erro e corrija quaisquer problemas no seu arquivo de configuração.

Restrições e limitações

O builder 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 o build, o builder local usa sua conta pessoal, e o Cloud Build usa a conta de serviço 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

Saiba mais sobre como criar com o Cloud Build.