Nesta página, descrevemos como enviar e extrair imagens de contêiner com o Docker. Ela também
fornece informações sobre como extrair imagens com a ferramenta crictl
se você estiver
solucionando problemas no Google Kubernetes Engine.
Para informações sobre como implantar em ambientes de execução do Google Cloud, consulte Implantar no Google Cloud.
Para instruções sobre como listar, incluir tags e excluir imagens, consulte Como gerenciar imagens.
Antes de começar
- Se não existir um repositório de destino, crie um novo repositório.
- É preciso ter pelo menos o access de Gravador do Artifact Registry ao repositório.
- Instale o Docker se ele ainda não estiver instalado.
Funções exigidas
Para receber as permissões necessárias para enviar e extrair imagens, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:
-
Extrair imagens:
Leitor do Artifact Registry (
roles/artifactregistry.reader
) -
Marque e envie imagens:
Gravador do Artifact Registry (
roles/artifactregistry.writer
)
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
Como autenticar em um repositório
Faça a autenticação em repositórios sempre que usar o Docker ou outro cliente de terceiros com um repositório do Docker. Nesta seção, você vê um resumo rápido do que é necessário para autenticar com êxito. Para instruções detalhadas, consulte Como configurar a autenticação para o Docker.
Como usar um auxiliar de credenciais
Para o auxiliar de credenciais da CLI gcloud ou , os hosts do Artifact Registry que você usa precisam estar no arquivo de configuração do Docker.
O Artifact Registry não adiciona automaticamente todos os hosts de registro ao arquivo de configuração do Docker. O tempo de resposta do Docker é significativamente mais lento quando há um grande número de registros configurados. Para minimizar o número de registros no arquivo de configuração, você adiciona os hosts necessários ao arquivo.
Para confirmar quais hosts estão configurados, execute o seguinte comando para exibir o conteúdo do arquivo de configuração:
- Linux:
cat ~/.docker/config.json
- Windows:
cat %USERPROFILE%\.docker\config.json
A seção credHelpers
lista os hosts configurados do Docker do Artifact Registry.
Os nomes de host terminam em -docker.pkg.dev
. O exemplo a seguir mostra alguns hosts
configurados para o auxiliar de credencial da CLI gcloud.
"credHelpers": {
"asia.gcr.io": "gcloud",
"eu.gcr.io": "gcloud",
"gcr.io": "gcloud",
"marketplace.gcr.io": "gcloud",
"northamerica-northeast1-docker.pkg.dev": "gcloud",
"us-central1-docker.pkg.dev": "gcloud",
"us-east1-docker.pkg.dev": "gcloud",
"us.gcr.io": "gcloud"
}
Se um host que você quer usar não estiver na lista, execute o auxiliar de credencial novamente
para adicioná-lo. Por exemplo, o comando a seguir adiciona
us-east1-docker.pkg.dev
.
Auxiliar de credenciais da CLI gcloud:
gcloud auth configure-docker us-east1-docker.pkg.dev
Auxiliar de credenciais independente
docker-credential-gcr configure-docker us-east1-docker.pkg.dev
usar um token de acesso;
Para a autenticação do token de acesso, gere um token e use-o como uma senha com o comando docker login
. Os tokens são válidos por 60 minutos. Portanto, você precisa autenticar um pouco antes de marcar, enviar ou extrair imagens.
O exemplo a seguir gera um token de acesso usando a
representação da conta de serviço e, em seguida,
faz a autenticação no Artifact Registry. É necessário ter permissões no papel Criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator
) para gerar um token dessa maneira.
Linux
gcloud auth print-access-token \
--impersonate-service-account ACCOUNT | docker login \
-u oauth2accesstoken \
--password-stdin https://LOCATION-docker.pkg.dev
Windows
gcloud auth print-access-token \
--impersonate-service-account ACCOUNT
ya29.8QEQIfY_...
docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev
Se você não tiver permissões para representar uma conta de serviço, ative a conta de serviço na sessão da CLI gcloud e receba um token. Para mais detalhes, consulte as instruções sobre como configurar a autenticação do token de acesso.
Como usar uma chave de conta de serviço
Para uma chave de conta de serviço, use-a como senha com o comando docker login
.
Por exemplo, o comando a seguir usa a chave da conta de serviço codificada em base64
no arquivo key.json
para autenticar em us-east1-docker.pkg.dev
.
Linux
cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-east1-docker.pkg.dev
Windows
docker login -u _json_key_base64 --password-stdin https://us-east1-docker.pkg.dev < key.json
Veja mais detalhes nas instruções de configuração da autenticação da chave da conta de serviço.
Como enviar uma imagem
Modos de repositório: padrão
Para enviar uma imagem local a um repositório padrão do Docker, marque-a com o nome do repositório e envie a imagem.
Se a imutabilidade de tags estiver ativada no repositório Docker do Artifact Registry, uma tag precisará sempre fazer referência ao mesmo resumo de imagem no repositório. Não é possível usar a tag em outra versão da mesma imagem enviada ao repositório. Para mais informações sobre resumos de imagens, tags e imutabilidade de tags, consulte Versões de imagens de contêiner.
Para imagens grandes, os seguintes limites se aplicam:
- Tempo de upload
- Se você autenticar no Artifact Registry usando um token de acesso, o token só será válido por 60 minutos. Se você espera que o tempo de upload exceda 60 minutos, use outro método de autenticação.
- Tamanho da imagem
- O tamanho máximo do artefato é 5 TB.
- O Artifact 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. Use uploads monolíticos para enviar imagens ao Artifact Registry.
Como marcar a imagem local
Verifique se você está autenticado no repositório.
Determine o nome da imagem. O formato do nome completo de uma imagem é:
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
Substitua os seguintes valores:
LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada, por exemplo,
us-east1
ouus
.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.REPOSITORY é o nome do repositório em que a imagem está armazenada.
IMAGE é o nome da imagem. Ele pode ser diferente do nome local da imagem.
Por exemplo, considere uma imagem com as seguintes características:
- Local do repositório:
us-east1
- Nome do repositório:
my-repo
- ID do projeto:
my-project
- Nome da imagem local:
my-image
- Nome da imagem de destino:
test-image
O nome da imagem deste exemplo é:
us-east1-docker.pkg.dev/my-project/my-repo/test-image
Para detalhes sobre o formato do nome da imagem, incluindo o gerenciamento de projetos com escopo de domínio, consulte Nomes de repositório e imagens.
Marque a imagem local com o nome do repositório.
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
Substitua SOURCE-IMAGE pelo nome da imagem local ou pelo ID da imagem e TAG pela tag. Se você não especificar uma tag, o Docker aplicará a tag
latest
padrão.Se a configuração de tags de imagem imutável estiver ativada (pré-lançamento), as tags precisarão ser exclusivas para cada versão de imagem, incluindo a tag
latest
. Não é possível enviar uma imagem para o repositório se a tag já estiver sendo usada por outra versão da mesma imagem no repositório. Para verificar se a configuração está ativada no repositório, execute o comando:gcloud artifacts repositories describe REPOSITORY \ --project=PROJECT-ID \ --location=LOCATION
No exemplo de imagem da etapa anterior, use o comando a seguir se a imagem local
my-image
estiver no diretório atual:docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image
Se você quiser aplicar uma tag específica, use o comando:
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
Para usar a tag
staging
com a imagem de exemplo, adicione:staging
ao comando:docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
Envie a imagem marcada para o Artifact Registry
Verifique se você está autenticado no repositório.
Se você usou
gcloud auth configure-docker
oudocker-credential-gcr configure-docker
para configurar o cliente do Docker, verifique se o nome do host de destino está no arquivo de configuração do Docker.Envie a imagem marcada com o comando:
docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/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 LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
Quando você envia uma imagem, ela é armazenada no repositório especificado.
Depois de enviar a imagem, você pode:
Acesse o console do Google Cloud para visualizar a imagem.
Execute o comando
gcloud
para visualizar as tags da imagem e o resumo gerado automaticamente:gcloud artifacts docker images list \ LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
A saída de exemplo a seguir mostra resumos de imagens truncados, mas o comando sempre retorna o resumo de imagem completo.
IMAGE DIGEST CREATE_TIME UPDATE_TIME us-east1-docker.pkg.dev/my-project/my-repo/my-image sha256:85f... 2019-04-10T15:08:45 2019-04-10T15:08:45 us-east1-docker.pkg.dev/my-project/my-repo/my-image sha256:238... 2019-04-10T17:23:53 2019-04-10T17:23:53 us-east1-docker.pkg.dev/my-project/my-repo/my-image sha256:85f... 2019-04-10T15:08:46 2019-04-10T15:08:46
Como extrair imagens com o Docker
Modos de repositório:padrão, remoto, virtual
Verifique se você está autenticado no repositório.
Se você usou
gcloud auth configure-docker
oudocker-credential-gcr configure-docker
para configurar o cliente do Docker, verifique se o nome do host de destino está no arquivo de configuração do Docker.Para extrair de um repositório, use o comando:
docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
ou
docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
Substitua os seguintes valores:
- LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada, por exemplo,
us-east1
ouus
. - PROJECT é o ID do projeto
do console do Google Cloud.
Caso o ID do projeto contenha dois pontos (
:
), consulte Projetos com escopo de domínio. - REPOSITORY é o nome do repositório em que a imagem está armazenada.
- IMAGE é o nome da imagem no repositório.
- TAG é a tag da versão de imagem que você quer extrair.
- IMAGE-DIGEST é o valor de hash sha256 do conteúdo da imagem. Cada versão de uma imagem tem um resumo de imagem exclusivo. No console do Google Cloud, clique na imagem específica para ver os metadados dela. O resumo é listado como Resumo da imagem.
Por exemplo, considere uma imagem com as seguintes características:
- Local do repositório:
us-east1
- Nome do repositório:
my-repo
- ID do projeto:
my-project
- Nome da imagem:
test-image
- Tag:
staging
Use este comando para extrair a imagem:
docker pull us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
- LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada, por exemplo,
O Docker faz o download da imagem especificada.
Se você solicitar uma imagem de um repositório remoto, o repositório remoto fará o download e armazenará em cache a imagem da origem upstream se não houver uma cópia em cache.
Se você solicitar uma imagem de um repositório virtual, o Artifact Registry vai pesquisar repositórios upstream para a imagem solicitada. Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry escolherá um repositório upstream para usar com base nas configurações de prioridade definidas para o repositório virtual.
Por exemplo, considere um repositório virtual com as seguintes configurações de prioridade para repositórios upstream:
main-repo
: prioridade definida como100
secondary-repo1
: prioridade definida como80
.secondary-repo2
: prioridade definida como80
.test-repo
: prioridade definida como20
.
main-repo
tem o valor de prioridade mais alto. Portanto, o repositório virtual
sempre o pesquisa primeiro.
Tanto secondary-repo1
quanto secondary-repo2
têm prioridade definida como 80
. Se uma
imagem solicitada não estiver disponível em main-repo
, o Artifact Registry
vai pesquisar esses repositórios em seguida. Como ambos têm o mesmo valor de prioridade,
o Artifact Registry pode optar por exibir uma imagem de qualquer um dos repositórios
se a versão estiver disponível em ambos.
test-repo
tem o menor valor de prioridade e veiculará um artefato armazenado se
nenhum dos outros repositórios upstream o tiver.
Extraindo imagens com crictl
crictl
é uma ferramenta de linha de comando útil para desenvolvedores de ambiente de execução de CRI depurarem o ambiente de execução sem precisar configurar os componentes do Kubernetes. Se os
nós do Google Kubernetes Engine usarem um ambiente de execução do containerd, será possível extrair imagens do
Artifact Registry usando crictl
.
Como crictl
é principalmente uma ferramenta de solução de problemas, alguns comandos do Docker, como envio ou inclusão de tags em imagens, não estão disponíveis.
Para extrair uma imagem do Artifact Registry:
No Console do Google Cloud, acesse a página Instâncias de VMs.
Conecte-se por SSH ao nó com o problema em questão.
Consiga um token de acesso para autenticação com o repositório.
curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"
Extraia a imagem usando
crictl pull --creds
e o valoraccess_token
crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
ou
crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
A saída será assim:
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
A seguir
- Saiba mais sobre como gerenciar tags e excluir imagens.
- Saiba mais sobre como executar contêineres no Compute Engine.
- Use
crictl
para depurar nós do Kubernetes. - Saiba como usar
crictl
para extrair imagens de repositórios particulares do Artifact Registry. - Saiba mais sobre como configurar registros de imagem
crictl