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 de 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 de IAM de Acessador de secrets do Gerenciador de secrets ao secret da conta de serviço do Cloud 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. Na caixa de texto Novos principais, insira o endereço de e-mail da sua conta de serviço do Cloud Build no formato PROJECT_NUMBER@cloudbuild.gserviceaccount.com, em que PROJECT_NUMBER é o número do projeto: onde você está executando os builds. Encontre esse número na página de configurações do projeto.

  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 prefixada com $$.

    O seguinte arquivo de configuração da compilação mostra como fazer login no Docker usando o nome de usuário e a senha do Docker armazenados no Secret Manager e como executar uma imagem privada.

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

    Substitua os valores dos marcadores nos comandos acima pelo seguinte:

    • PROJECT_ID: o ID do projeto do Google Cloud em que você armazenou as chaves secretas.
    • 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 de onde você está extraindo 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 enviar imagens ao Docker Hub

Para enviar imagens públicas e particulares ao 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 prefixada com $$.

    No exemplo de arquivo de configuração de build a seguir, mostramos como fazer login no Docker, criar uma imagem com o código-fonte armazenado localmente e enviá-la para o repositório Docker.

    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 as chaves secretas.
    • 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 do cliente do Docker

O builder do Docker compatível com 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, ele enviará apenas a imagem com a tag latest. Se a tag latest não existir, o envio falhará.

Para enviar uma imagem com uma tag específica para o Docker, especifique essa tag na etapa de criação docker push. O exemplo a seguir envia uma imagem marcada com 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 na etapa de criação docker push:

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"
      ],
  }
  ...
}

Você pode 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