Como interagir com imagens do Docker Hub

Use as imagens de contêiner do Docker Hub para executar as tarefas no Cloud Build. Se o build produz imagens, é possível também enviá-las ao Docker Hub. Nesta página, descrevemos como gravar arquivos de configuração de build para enviar e extrair imagens do Docker Hub. Para uma visão geral de todos os campos disponíveis em um arquivo de configuração de build, consulte Visão geral da configuração de build.

Como extrair imagens públicas do Docker Hub

É possível extrair imagens oficiais do Docker, imagens certificadas pelo Docker e imagens personalizadas armazenadas no Docker Hub na etapa de criação ao especificar o nome da imagem no campo name. Primeiro, o Cloud Build extrairá a imagem especificada do Docker Hub e a usará para executar a etapa de criação.

No exemplo abaixo, o Cloud Build extrai a imagem do Docker para maven para executar o comando mvn especificado em args:

YAML 

steps:
- name: "maven"
  args: ["mvn", "--version"]

JSON 

{
   "steps": [
      {
         "name": "maven",
         "args": [
            "mvn",
            "--version"
         ]
      }
   ]
}

Como armazenar credenciais do Docker no Gerenciador de secrets

Para extrair imagens privadas e enviar imagens públicas e privadas para o Docker Hub, o Cloud Build precisa ser autenticado no Docker com suas credenciais. Para incluir credenciais do Docker nos seus builds, primeiro você precisa armazenar suas credenciais no Gerenciador de secrets e, em seguida, conceder permissão para que o Cloud Build acesse o secret do Secret Manager.

Para armazenar credenciais do Docker no Gerenciador de secrets:

  1. Acesse a página do Secret Manager no console do Google Cloud:

    Acessar a página "Gerenciador de secrets"

  2. Na página Gerenciador de secrets, clique em Criar secret.

  3. Na página Criar secret, em Nome, digite docker-username.

  4. No campo Valor do secret, insira seu nome de usuário do Docker.

  5. Deixe a seção Regiões inalterada.

  6. Clique no botão Criar secret.

Repita as etapas acima para armazenar a senha do Docker no Gerenciador de secrets.

Para conceder o papel do IAM de Acessador de secrets do Secret Manager ao secret da conta de serviço que você está usando para o build:

  1. Abra a página do Secret Manager no console do Google Cloud:

    Acessar a página "Gerenciador de secrets"

  2. Marque a caixa de seleção do secret correspondente ao seu nome de usuário e senha do Docker.

  3. Se ela ainda não estiver aberta, clique em Mostrar painel de informações para abrir o painel.

  4. No painel, em Permissões, clique em Adicionar principal.

  5. No campo Novos principais, insira o endereço de e-mail do seu conta de serviço.

  6. Na caixa suspensa Selecionar um papel, selecione o papel Acessador de secrets do Gerenciador de secrets.

  7. Clique em Save.

Como extrair imagens particulares do Docker Hub

Para extrair imagens particulares do Docker Hub:

  1. Certifique-se de ter armazenado as credenciais do Docker no Secret Manager e concedido permissões para que o Cloud Build acesse o secret.

  2. No arquivo de configuração de build:

    • Depois de todo o build steps, adicione um campo availableSecrets especificando a versão secreta e a variável do ambiente para o nome de usuário e a senha do Docker.
    • Na etapa de criação, em que você quer especificar o nome de usuário e a senha:
      • Adicione um campo entrypoint que aponte para bash para usar a ferramenta bash na etapa de versão. Isso é necessário para fazer referência à variável de ambiente do secret.
      • Adicione um campo secretEnv especificando a variável de ambiente para nome de usuário e senha.
      • No campo args, adicione uma sinalização -c como primeiro argumento. Qualquer string que você passar depois de -c será tratada como um comando. Para mais informações sobre como executar comandos bash com -c, consulte a documentação do bash.
      • Ao especificar o secret no campo args, especifique-o usando a variável de ambiente com o prefixo $$.

    The following build config file shows how to login to Docker using the Docker username and password stored in Secret Manager, and run a private image.

    YAML 

     steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: "gcr.io/cloud-builders/docker"
   entrypoint: 'bash'
   args: ['-c', 'docker run $$USERNAME/REPOSITORY:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   secretManager:
   - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
     env: 'PASSWORD'
   - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
     env: 'USERNAME'
.

     JSON 
    {
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker run $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "secretManager": [{
      "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
     }]
  }
}

    Replace the placeholder values in the above commands with the following:

    • PROJECT_ID: The ID of the Google Cloud project where you've stored your secrets.
    • DOCKER_USERNAME_SECRET_NAME: The secret name corresponding to your Docker username.
    • DOCKER_USERNAME_SECRET_VERSION: The secret version of your Docker username.
    • DOCKER_PASSWORD_SECRET_NAME: The secret name corresponding to your Docker password.
    • DOCKER_PASSWORD_SECRET_VERSION: The secret version of your Docker password.
    • REPOSITORY: The name of your Docker repository from where you're pulling the image.
    • TAG: The tag name of your image.

  3. Use the build config file to manually start a build or to automate builds using triggers.

Pushing images to Docker Hub

To push public and private images to Docker Hub:

  1. Make sure you've stored your Docker credentials in Secret Manager and granted permissions for Cloud Build to access the secret.

  2. In the build config file:

    • After all the build steps, add an availableSecrets field specifying the secret version and the env variable for the Docker username and password.
    • In the build step where you want to specify the username and password:
      • Add an entrypoint field pointing to bash to use the bash tool in the build step. This is required to refer to the environment variable for the secret.
      • Add a secretEnv field specifying the environment variable for username and password.
      • In the args field, add a -c flag as the first argument. Any string you pass after -c is treated as a command. For more information on running bash commands with -c, see the bash documentation.
      • When specifying the secret in the args field, specify it using the environment variable prefixed with $$.

    The following example build config file shows how to login to Docker, build an image with source code stored locally, and then push the image to Docker repository.

    YAML 

     steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker build -t $$USERNAME/REPOSITORY:TAG .']
   secretEnv: ['USERNAME']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker push $$USERNAME/REPOSITORY:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   secretManager:
   - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
     env: 'PASSWORD'
   - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
     env: 'USERNAME'

    JSON 

    {
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker build -t $$USERNAME/REPOSITORY:TAG ."
     ],
     "secretEnv": [
      "USERNAME"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker push $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "secretManager": [{
      "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
     }]
  }
}

    Substitua os valores dos marcadores nos comandos acima pelo seguinte:

    • PROJECT_ID: o ID do projeto do Google Cloud em que você armazenou os secrets.
    • DOCKER_USERNAME_SECRET_NAME: o nome do secret correspondente ao seu nome de usuário do Docker.
    • DOCKER_USERNAME_SECRET_VERSION: a versão do secret do seu nome de usuário do Docker.
    • DOCKER_PASSWORD_SECRET_NAME: o nome do secret correspondente à sua senha do Docker.
    • DOCKER_PASSWORD_SECRET_VERSION: a versão do secret da sua senha do Docker.
    • REPOSITORY: o nome do repositório do Docker para o qual você está enviando a imagem.
    • TAG: o nome da tag da imagem.

  3. Use o arquivo de configuração de build para iniciar manualmente um build ou para automatizar builds usando acionadores.

Como trabalhar com versões de cliente do Docker

O builder do Docker com suporte para o Cloud Build, gcr.io/cloud-builders/docker, usa o Docker 20.10.14. Com essa versão, se você não especificar uma tag ao enviar uma imagem para o Docker, o Docker vai enviar apenas a imagem com a tag latest. Se a tag latest não existir, o push vai falhar.

Para enviar uma imagem com uma tag específica ao Docker, defina essa tag no docker push etapa de build. O exemplo a seguir envia uma imagem com a tag prod:

YAML 

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON 

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push", 
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

Para enviar todas as tags de uma imagem para o Docker, adicione a sinalização -a à lista de argumentos no docker push etapa de build:

YAML 

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '-a', '$$USERNAME/myrepo']
...

JSON 

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push",
      "-a",
      "$$USERNAME/myrepo"
      ],
  }
  ...
}

É possível usar o cliente Docker 19.03.9 marcando a versão no builder do Docker:

YAML 

steps:
...
- name: 'gcr.io/cloud-builders/docker:19.03.9'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON 

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker:19.03.9",
    "args": [
      "docker",
      "push",
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

A seguir