Usar um espelho de registro para imagens de contêiner

Nesta página, explicamos como criar e fazer upgrade de clusters usando imagens extraídas de um espelho de registro, em vez de um registro público, como gcr.io. Esse recurso pode ser ativado ou desativado a qualquer momento no ciclo de vida do cluster.

Esta página é destinada a operadores e especialistas em armazenamento que configuram e gerenciam o desempenho, o uso e os gastos de armazenamento. Para saber mais sobre papéis comuns e tarefas de exemplo referenciados no conteúdo do Google Cloud , consulte Tarefas e funções de usuário comuns do GKE.

Um espelho de registro é uma cópia local de um registro público que copia ou espelha a estrutura do arquivo de registro público. Por exemplo, suponha que o caminho para o espelho de registro local seja 172.18.0.20:5000. Quando containerd encontra uma solicitação para extrair uma imagem como gcr.io/kubernetes-e2e-test-images/nautilus:1.0, containerd tenta extrair essa imagem, não de gcr.io, mas do seu registro local no seguinte caminho: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0. Se a imagem não estiver nesse caminho de registro local, ela será extraída automaticamente do registro público gcr.io.

Usar um espelho de registro oferece os seguintes benefícios:

• Protege você contra falhas temporárias de registro público.
• Acelera a criação de pods.
• Permite que você faça a própria verificação de vulnerabilidades.
• Evita limites impostos por registros públicos sobre a frequência com que você pode emitir comandos para eles.

Antes de começar

• É preciso ter um servidor do Artifact Registry configurado na rede.
• Se o servidor de registro executar um certificado TLS particular, você precisará ter o arquivo de autoridade de certificação (CA, na sigla em inglês).
• Se o servidor de registros precisar de autenticação, você precisará ter as credenciais de login adequadas ou o arquivo de configuração do Docker.
• Se você estiver usando um registro do Red Hat Quay, talvez seja necessário criar manualmente a estrutura de diretórios do registro local.
• Para usar um espelho de registro, defina o ambiente de execução do contêiner como containerd.
• Verifique se você tem espaço em disco suficiente na estação de trabalho do administrador para fazer upload de imagens. O comando de upload de imagens, bmctl push images, descompacta o arquivo de pacote de imagens baixado e extrai todos os arquivos de imagem localmente antes de fazer o upload deles. Você precisa ter pelo menos três vezes mais espaço em disco do que o tamanho do arquivo de pacote de imagens baixadas para acomodar o upload de imagens. Por exemplo, o arquivo compactado bmpackages_1.31.200-gke.59.tar.xz ocupa aproximadamente 8,5 GB de espaço em disco. Portanto, você precisa ter pelo menos 25,5 GB de espaço livre antes de fazer o download.

Faça o download de todas as imagens necessárias para o Google Distributed Cloud

Faça o download da versão mais recente da ferramenta bmctl e do pacote de imagens na página Downloads.

Fazer upload de imagens de contêiner no servidor de registro

Quando você usa bmctl push images para fazer upload de imagens de contêiner no servidor do repositório, o bmctl executa as seguintes etapas em ordem:

1. Descompacte um pacote de imagens baixado compactado em um arquivo tar, como bmpackages_1.32.200-gke.104.tar.xz em bmpackages_1.32.200-gke.104.tar.

2. Extraia todas as imagens do arquivo tar descompactado para um diretório chamado bmpackages_1.32.200-gke.104.

3. Envie cada arquivo de imagem para o registro particular especificado.

   O bmctl usa valores --username e --password para autenticação básica e envia as imagens para seu registro particular.

As seções a seguir ilustram algumas variações comuns do comando bmctl push images para fazer upload de imagens no servidor do repositório.

Autentique-se no seu registro e compartilhe o certificado TLS

O comando a seguir inclui as flags --username e --password para autenticação do usuário com o servidor de registro. O comando também inclui a flag --cacert para transmitir o certificado TLS (Transport Layer Security) da CA, que é usado para comunicação segura com o servidor de registro, incluindo pushes e pulls de imagens. Essas flags oferecem segurança básica para o servidor de registro.

Se o servidor de registro exigir autenticação e você não usar as flags --username e --password, será necessário informar as credenciais ao executar bmctl push images. Você pode digitar sua senha ou escolher o arquivo de configuração do Docker que contém as credenciais.

Para fazer upload de imagens com autenticação e um certificado de CA particular, use um comando como este:

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --username USERNAME \
    --password PASSWORD \
    --cacert CERT_PATH

Substitua:

• IMAGES_TAR_FILE_PATH: o caminho do arquivo tar do pacote de imagens baixadas, como bmpackages_1.32.200-gke.104.tar.xz.

• REGISTRY_IP:PORT: o endereço IP e a porta do servidor de registro privado.

• USERNAME: o nome de usuário de um usuário com permissões de acesso para fazer upload de imagens no servidor de registro.

• PASSWORD: a senha do usuário para autenticação com o servidor de registro.

• CERT_PATH: o caminho do arquivo de certificado de CA, se o servidor de registro usar um certificado TLS particular.

Exemplo:

bmctl push images \
    --source bmpackages_1.32.200-gke.104.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --username alex --password pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

Fazer upload de imagens sem autenticação ou certificados do usuário

Se o servidor de registro não exigir credenciais, como nome de usuário e senha, especifique --need-credential=false no comando bmctl. Se o servidor de registro usar um certificado TLS público, não será necessário usar a flag --cacert. Esse tipo de comando de upload é mais adequado para ambientes de teste, em que a segurança é menos importante do que na produção.

Para fazer upload de imagens sem autenticação ou um certificado de CA particular, use um comando como este:

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --need-credential=false

Exemplo:

bmctl push images \
    --source bmpackages_1.32.200-gke.104.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

Ajustar o número de linhas de execução

O upload de imagens pode levar tempo devido ao tamanho e à quantidade de imagens de contêiner no arquivo tar do pacote de imagens. Aumentar o número de linhas de execução paralelas faz com que a rotina seja executada mais rapidamente. Use a flag --threads para mudar o número de linhas de execução paralelas usadas pelo bmctl push images.

Por padrão, a rotina de upload de imagens usa quatro linhas de execução. Se os uploads de imagens levarem muito tempo, aumente esse valor. Como comparativo, em um ambiente de teste do Google, o upload de imagens de uma estação de trabalho com 4 CPUs leva aproximadamente 10 minutos com 8 linhas de execução paralelas.

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --cacert CERT_PATH \
    --threads NUM_THREADS

Substitua NUM_THREADS pelo número de linhas de execução paralelas usadas para processar os envios de imagens. Por padrão, bmctl push images usa quatro linhas de execução paralelas.

O comando a seguir aumenta o número de linhas de execução do upload de 4 para 8 e reduz o tempo de upload:

bmctl push images \
    --source bmpackages_1.32.200-gke.104.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem \
    --threads 8

Fazer upload pelo proxy

Se você precisar de um proxy para fazer upload das imagens da estação de trabalho para o servidor de registro, adicione os detalhes do proxy antes do comando bmctl:

HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT \
    --cacert=CERT_PATH

Substitua:

• PROXY_IP:PORT: o endereço IP e a porta do proxy.

• IMAGES_TAR_FILE_PATH: o caminho do arquivo tar do pacote de imagens baixadas, como bmpackages_1.32.200-gke.104.tar.xz.

• REGISTRY_IP:PORT: o endereço IP e a porta do servidor de registro privado.

• CERT_PATH: o caminho do arquivo de certificado de CA, se o servidor de registro usar um certificado TLS particular.

Digite seu nome de usuário e senha quando solicitado ou selecione um arquivo de configuração do Docker.

O comando a seguir faz upload de imagens por um proxy:

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.32.200-gke.104.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem

Usar seu próprio namespace com bmctl push images

Se você quiser usar seu próprio namespace no servidor de registros em vez do namespace raiz, containerd poderá extrair desse namespace se você fornecer o endpoint da API para seu registro particular no campo registryMirrors.endpoint do arquivo de configuração do cluster. O endpoint geralmente está no formato <REGISTRY_IP:PORT>/v2/<NAMESPACE>. Consulte o guia do usuário do seu registro particular para detalhes específicos. Para mais informações, consulte Sobre o uso de v2 no endpoint do registro.

bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT/NAMESPACE \
    --cacert=CERT_PATH

Substitua NAMESPACE pelo nome do namespace no servidor de registro em que você quer fazer upload de imagens.

Por exemplo, se você só tiver acesso a 198.51.20:5000/test-namespace/, poderá usar um comando como o seguinte para fazer upload de todas as imagens no namespace test-namespace:

bmctl push images \
    --source=./bmpackages_1.32.200-gke.104.tar.xz \
    --private-registry=198.51.20:5000/test-namespace \
    --username=alex \
    --password=pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

Em seguida, no arquivo de configuração do cluster, adicione o seguinte para fazer o containerd extrair do namespace test-namespace:

registryMirrors:
  - endpoint: https://198.51.20:5000/v2/test-namespace

Para mais informações sobre o comando bmctl push images, consulte a referência do comando bmctl.

Configurar clusters para usar um espelho de registro

É possível configurar um espelho de registro para um cluster na criação dele ou sempre que você atualizar um cluster atual. O método de configuração usado depende do tipo de cluster e, para clusters de usuário, se você está criando ou atualizando um cluster. As duas seções a seguir descrevem os dois métodos disponíveis para configurar espelhos de registro.

Usar a seção de cabeçalho no arquivo de configuração do cluster

Com o Google Distributed Cloud, é possível especificar espelhos de registro fora da especificação do cluster, na seção de cabeçalho do arquivo de configuração do cluster:

• Para clusters de administrador, híbridos e autônomos, a única maneira de configurar um espelho de registro é usar a seção de cabeçalho no arquivo de configuração do cluster. Esse método se aplica à criação ou atualização de clusters.

• Para clusters de usuário, use esse método para configurar um espelho de registro somente durante a criação do cluster. Como alternativa, para configurar um espelho de registro para um cluster de usuário atual, use a seção nodeConfig.registryMirrors na especificação do cluster.

No exemplo de arquivo de configuração de cluster a seguir, as imagens devem ser extraídas de um espelho de registro local com o endpoint https://198.51.20:5000. Alguns dos campos que aparecem no início desse arquivo de configuração são descritos nas seções a seguir.

# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
  - endpoint: https://198.51.20:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
spec:
  nodeConfig:
    containerRuntime: containerd
...

Use a seção nodeConfig.registryMirrors na especificação do cluster

Esse método de criação ou atualização de um espelho de registro se aplica apenas a clusters de usuário. Como é possível compartilhar os secrets criados para o cluster de gerenciamento com o cluster de usuário, use o nodeConfig.registryMirrors do cluster de administrador ou híbrido de gerenciamento para especificar o espelho do registro na especificação do cluster de usuário.

Para configurar um cluster de usuário para usar o mesmo espelho de registro que o cluster de administrador, siga estas etapas:

1. Receba a seção nodeConfig.registryMirror, incluindo referências secretas, de nodeConfig.registryMirrors do recurso de cluster de administrador:

   kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \
       --kubeconfig ADMIN_KUBECONFIG \
       -o yaml
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster de administrador ou híbrido que gerencia o cluster de usuário.

   • CLUSTER_NAMESPACE: o nome do namespace do cluster de gerenciamento.

   • ADMIN_KUBECONFIG: o caminho do arquivo kubeconfig do cluster gerenciado.

2. Adicione a configuração nodeConfig.registryMirrors do cluster de administrador ao arquivo de configuração do cluster de usuário.

   A seção registryMirrors no arquivo de configuração do cluster de usuário deve ser semelhante ao exemplo a seguir:

   ---
   gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
   sshPrivateKeyPath: /root/ssh-key/id_rsa
   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: cluster-user1
   ---
   apiVersion: baremetal.cluster.gke.io/v1
   kind: Cluster
   metadata:
     name: user1
     namespace: cluster-user1
   spec:
     nodeConfig:
       containerRuntime: containerd
       registryMirrors:
       -   caCertSecretRef:
           name: the-secret-created-for-the-admin-cluster
           namespace: anthos-creds
         endpoint: https://172.18.0.20:5000
         hosts:
           -   somehost.io
           -   otherhost.io
         pullCredentialSecretRef:
           name: the-image-pull-creds-created-for-the-admin-cluster
           namespace: anthos-creds
   ...
   

Para fazer mudanças subsequentes na configuração do espelho de registro do cluster de usuário, edite o nodeConfig.registryMirrors no arquivo de configuração do cluster de usuário e aplique as mudanças com bmctl update.

Não é possível usar a seção de cabeçalho do arquivo de configuração do cluster para atualizar a configuração de espelhos de registro de um cluster de usuário.

Campo hosts

containerd verifica a seção hosts do arquivo de configuração do cluster para descobrir quais hosts são espelhados localmente. Esses hosts são mapeados para o endpoint do espelho de registro especificado no arquivo de configuração do cluster (registryMirror.endpoint). No arquivo de configuração de exemplo da seção anterior, os registros públicos listados na seção hosts são somehost.io e otherhost.io. Como esses registros públicos aparecem na seção hosts, o containerd verifica primeiro o espelho de registro particular quando encontra solicitações de extração para imagens de somehost.io ou otherhost.io.

Por exemplo, suponha que containerd receba um comando pull para somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Como somehost.io está listado como um dos hosts na seção hosts do arquivo de configuração do cluster, containerd procura no espelho local do registro a imagem kubernetes-e2e-test-images/nautilus:1.0. Se somehost.io não estiver listado na seção hosts, containerd não saberá que um espelho local de somehost.io existe. Nesse caso, o containerd não verifica o espelho da imagem e extrai a imagem do registro público somehost.io.

Por padrão, o Google Distributed Cloud espelha automaticamente imagens de gcr.io. Portanto, não é necessário listar gcr.io como um host na seção hosts.

Os valores hosts e endpoint não podem se sobrepor. Por exemplo, a amostra de configuração a seguir mostra um host, europe-docker.pkg.dev, que corresponde à parte do domínio do valor do endpoint. Nesse caso, não é necessário especificar um valor de hosts:

...
registryMirrors:
  ...
  endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
  hosts:
    - europe-docker.pkg.dev
    ...

Campo gcrKeyPath

Se você quiser que o Google Distributed Cloud use automaticamente o Artifact Registry (gcr.io) para extrair imagens que não aparecem no registro local, especifique o caminho para a chave da conta de serviço do Artifact Registry. O Google Distributed Cloud não tem um mecanismo para fornecer chaves a outros registros públicos.

Se você não planeja usar o recurso em que as imagens são extraídas de gcr.io quando elas não aparecem no seu registro local, não é necessário adicionar um gcrKeyPath ao arquivo de configuração do cluster.

Campo caCertPath

Se o registro exigir um certificado Transport Layer Security (TLS), esse campo usará o caminho para o arquivo de certificado da CA raiz do servidor. Esse arquivo de certificado precisa estar na estação de trabalho do administrador, a máquina que executa os comandos bmctl. Se o registro não exigir um certificado TLS particular, deixe o campo caCertPath em branco.

Campo pullCredentialConfigPath

Se o servidor de registro não exigir um arquivo de configuração do Docker de autenticação, deixe o campo pullCredentialConfigPath em branco. Esse é o caminho para o arquivo de configuração na máquina que executa os comandos bmctl.

Usar um espelho de registro com clusters de usuário

Os clusters de usuário não extrairão automaticamente as imagens de um espelho de registro se o cluster de administrador tiver sido configurado para fazer isso. Para que os clusters de usuário sejam extraídos de um espelho de registro, é necessário configurá-los individualmente, conforme descrito em Configurar clusters para usar um espelho de registro.

Atualizar endpoints de espelho de registro, certificados e credenciais de pull

Para atualizar endpoints de espelho do registro, certificados ou credenciais de pull:

1. No arquivo de configuração do cluster, atualize o endpoint, o arquivo de certificado de CA e o caminho do arquivo de configuração de credencial.

2. Aplique as alterações executando:

   bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
   

   Substitua:

   • CLUSTER_NAME pelo nome do cluster que você quer atualizar.

   • ADMIN_KUBECONFIG pelo caminho do arquivo de configuração do cluster de administrador.

Verificar se as imagens foram extraídas do espelho de registro

É possível determinar se containerd está extraindo imagens do seu registro local examinando o conteúdo de um arquivo config.toml, conforme mostrado nas seguintes etapas:

1. Faça login em um nó e examine o conteúdo do seguinte arquivo: /etc/containerd/config.toml

2. Verifique a seção plugins."io.containerd.grpc.v1.cri".registry.mirrors do arquivo config.toml para ver se o servidor de registro está listado no campo endpoint. Confira um trecho de um exemplo de arquivo config.toml em que o campo endpoint aparece em negrito:

   version = 2
   root = "/var/lib/containerd"
   state = "/run/containerd"
   ...
   [plugins."io.containerd.grpc.v1.cri".registry]
     [plugins."io.containerd.grpc.v1.cri".registry.configs]
       [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"]
         [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls]
           ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt'
     [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
       [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
         endpoint = ["http://privateregistry.io", "https://privateregistry2.io"]
   ...
   

   Se o espelho do registro aparecer no campo endpoint, o nó estará extraindo imagens do espelho do registro, em vez de um registro público.

Resolver problemas nas configurações de espelho de registro

Use o crictl, a ferramenta de linha de comando da interface de tempo de execução do contêiner, para testar as configurações do registro baixando arquivos de imagem individuais. Cada arquivo de imagem é marcado de forma independente com uma string de versão significativa. Por exemplo, a imagem do controlador da API do cluster é marcada com a versão do Google Distributed Cloud, e a imagem do etcd é marcada com a versão correspondente do etcd.

Para a versão 1.31.200-gke.59 do Google Distributed Cloud em bare metal, a imagem do controlador da API de cluster, cluster-api-controller, e a imagem do etcd, etcd, têm as seguintes tags:

• cluster-api-controller:1.31.200-gke.59
• etcd:v3.4.30-0-gke.1

Extrair uma imagem do espelho de registro

Se o espelho de registro não usar namespaces, use o seguinte comando para extrair uma imagem:

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

Extrair uma imagem de um espelho de registro que usa namespaces

Se o espelho de registro usar namespaces, use o seguinte comando para extrair uma imagem:

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

Sobre o uso de v2 no endpoint de registro

Quando o registro usa namespaces personalizados, é necessário adicionar o namespace ao endpoint do registro (registryMirror.endpoint) no arquivo de configuração do cluster com v2/. Se você não estiver usando namespaces, não use v2. Em qualquer caso, não use v2 no valor da flag --private-registry ou nos comandos de extração de imagens:

Sem namespaces

• Válido:
  • endpoint: https://172.18.0.20:5000
  • crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
• Inválido:
  • endpoint: https://172.18.0.20:5000/v2
  • crictl pull 172.18.0.20:5000/v2/anthos-baremetal-release/etcd:v3.4.30-0-gke.1

Com namespaces

• Válido:
  • endpoint: https://172.18.0.21:5000/v2/namespace
  • crictl 172.18.0.21:5000/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
• Inválido:
  • endpoint: https://172.18.0.21:5000/namespace
  • crictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1