Enviar (fazer upload) e extrair (fazer download) imagens são duas das tarefas mais comuns do Container Registry. O foco deste documento é enviar e extrair imagens com o Docker.
Se você estiver usando o Cloud Build, consulte a documentação do Cloud Build para ver informações sobre como criar e enviar contêineres ao Container Registry.
Para instruções sobre como listar, marcar e excluir imagens, consulte Como gerenciar imagens.
Antes de começar
Certifique-se de que você:
Adicionar um registro
É possível adicionar os seguintes registros do Container Registry a um projeto:
Nome do host | Local de armazenamento |
---|---|
gcr.io |
Armazena imagens em data centers nos Estados Unidos |
asia.gcr.io |
Armazena imagens em data centers na Ásia. |
eu.gcr.io |
Armazena imagens em data centers nos estados membros da União Europeia. |
us.gcr.io |
Armazena imagens em data centers nos Estados Unidos |
A primeira imagem enviada para um nome de host aciona a criação do registro em um projeto e o bucket de armazenamento do Cloud Storage correspondente. Esse push inicial exige permissões em todo o projeto para criar buckets de armazenamento.
Depois que um host de registro existir no projeto, será possível configurar permissões no bucket para armazenar o acesso às imagens no registro.
Para adicionar um registro e configurar permissões:
Verifique se você tem as permissões necessárias. É necessário ter o papel Administrador do Storage (roles/storage.admin), ou um papel personalizado ou papel predefinido com as mesmas permissões.
Para ver instruções sobre como conceder o papel de administrador do Storage no nível do projeto, consulte a documentação do Cloud Storage.
Envie uma imagem inicial ao host. Por exemplo, os seguintes comandos:
- Extraia a imagem
busybox
do Docker Hub - Marque a imagem com o caminho de destino no Container Registry, incluindo o host do registro
gcr.io
e o ID do projetomy-project
- Enviar a imagem para o registro
docker pull busybox docker tag busybox gcr.io/my-project/busybox docker push gcr.io/my-project/busybox
- Extraia a imagem
O Container Registry adiciona o registro ao seu projeto, cria um bucket de armazenamento para o registro e armazena a imagem.
Agora é possível configurar o controle de acesso no bucket de armazenamento de registro para conceder acesso a outros usuários.
Como enviar uma imagem para um registro
Para enviar qualquer imagem local para o Container Registry usando o Docker ou outra ferramenta de terceiros, primeiro você precisa marcá-la com o nome do registro e depois enviar a imagem.
Os seguintes fatores podem afetar os uploads de imagens grandes:
- Tempo de upload
- Qualquer solicitação enviada ao Container Registry tem um tempo limite de duas horas. Se você se autenticar no Container Registry usando um token de acesso, o token expirará após 60 minutos. Se você espera que o tempo de upload exceda 60 minutos, use um método de autenticação diferente.
- Tamanho da imagem
- O Container Registry usa o Cloud Storage para o armazenamento de todos os registros. As cotas e limites do Cloud Storage se aplicam a cada registro, incluindo o tamanho máximo de 5 TB para um objeto no armazenamento.
- O Container Registry não é compatível com uploads em partes do Docker. Algumas ferramentas são compatíveis com o upload de imagens grandes, com uploads em partes ou um único upload monolítico. Você precisa usar uploads monolíticos para enviar imagens ao Container Registry.
Permissões necessárias
Para enviar uma imagem, é preciso ter um dos seguintes papéis do Cloud Storage ou um papel com as mesmas permissões:
- Enviar a primeira imagem para um registro no seu projeto
Papel: administrador do Storage (roles/storage.admin) no nível do projeto do Google Cloud. O papel de proprietário predefinido inclui essas permissões.
Na primeira vez que você envia uma imagem para um host de registro no seu projeto (como
gcr.io
), o Container Registry cria um bucket de armazenamento para o registro. O papel Administrador de armazenamento tem as permissões necessárias para criar o bucket de armazenamento.- Enviar imagens para um registro existente no seu projeto
Papel: gravador de bucket legado do Storage (roles/storage.objectAdmin) no bucket de armazenamento de registro.
Esse papel tem permissões para enviar e extrair imagens por host do registro no seu projeto. Por exemplo, se o projeto tiver apenas o registro
gcr.io
, um usuário com o papel de gravador de bucket legado do Storage poderá enviar imagens paragcr.io
, mas não poderá enviar imagens paraasia.gcr.io
.
Para mais informações sobre como conceder permissões a um registro, consulte Como configurar o controle de acesso.
Marcar a imagem local com o nome do registro
Para marcar uma imagem, faça o seguinte:
- Verifique se você configurou a autenticação no Container Registry.
Determine o nome do registro:
Escolha um nome de host, que especifica o local onde você armazenará a imagem.
gcr.io
hospeda imagens em data centers nos Estados Unidos, mas o local pode mudar no futurous.gcr.io
hospeda imagens em data centers nos Estados Unidos, em um bucket de armazenamento separado de imagens hospedadas porgcr.io
.eu.gcr.io
hospeda as imagens na União Europeiaasia.gcr.io
hospeda imagens em data centers na Ásia
Esses locais correspondem às multirregiões para os buckets de armazenamento do Cloud Storage. Quando você envia uma imagem para um registro com um novo nome do host, o Container Registry cria um bucket de armazenamento no local multirregional especificado. Esse bucket é o armazenamento subjacente para o registro. Em um projeto, todos os registros com o mesmo nome de host compartilham um bucket de armazenamento.
No console, o nome do host das imagens será listado em Local.
Escolha um nome de imagem, que pode ser diferente em sua máquina local.
Combine o nome do host, o ID do projeto do Console do Google Cloud e o nome da imagem:
HOSTNAME/PROJECT-ID/IMAGE
Caso o ID do projeto contenha dois pontos (
:
), consulte Projetos com escopo de domínio.
Marque a imagem local com o nome do registro usando o comando:
docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE
em que SOURCE_IMAGE é o nome da imagem local ou do ID da imagem.
Esse comando nomeia a imagem com o nome do registro e aplica a tag
latest
. Se você quiser aplicar uma tag diferente, use o comando:docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE:TAG
Enviar a imagem marcada para o Container Registry
Verifique se você configurou a autenticação no Container Registry.
Envie a imagem com tag ao Container Registry usando o comando:
docker push HOSTNAME/PROJECT-ID/IMAGE
Este comando envia a imagem que tem a tag
latest
. Se você quiser enviar uma imagem com uma tag diferente, use o comando:docker push HOSTNAME/PROJECT-ID/IMAGE:TAG
Quando você envia uma imagem para um registro que ainda não existe no seu projeto, o Container Registry cria um bucket de armazenamento.
Para visualizar a imagem que você enviou:
Acesse o Console do Cloud para ver o registro e a imagem.
Execute
gcloud container images list-tags
para ver a tag de imagem e o resumo gerado automaticamente:gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE
A resposta do comando é semelhante à seguinte:
DIGEST TAGS TIMESTAMP 44bde... test 2017-..-..
Como extrair imagens de um registro
A extração de uma imagem requer o Visualizador de objetos do Storage para o bucket de armazenamento do registro ou um papel com as mesmas permissões.
Para extrair do Container Registry, use o comando:
docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG
ou
docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST
onde:
- HOSTNAME está listado em Local no console É uma das
quatro opções:
gcr.io
,us.gcr.io
,eu.gcr.io
ouasia.gcr.io
. - PROJECT-ID é o ID do projeto do Console do Google Cloud.
Caso o ID do projeto contenha dois pontos (
:
), consulte Projetos com escopo de domínio. - IMAGE é o nome da imagem no Container Registry;
- TAG é a tag aplicada à imagem. Em um registro, as tags são exclusivas de uma imagem;
- IMAGE_DIGEST é o valor de hash sha256 do conteúdo da imagem. No Console do Cloud, clique na imagem específica para ver os metadados. O resumo é listado como Resumo da imagem.
Para receber o comando pull de uma imagem específica:
Clique no nome de uma imagem para acessar o registro específico.
No registro, marque a caixa ao lado da versão da imagem que você quer extrair.
Clique em EXIBIR COMANDO PULL na parte superior da página.
Copie o comando pull, que identifica a imagem usando a tag ou o resumo.
A seguir
- Saiba mais sobre como gerenciar imagens, incluindo a adição ou remoção de tags e a exclusão de imagens.
- Saiba mais sobre como configurar o controle de acesso.
- Leia mais sobre os componentes e recursos do Container Registry.
- Saiba mais sobre como executar contêineres no Compute Engine.