Use um espelho de registo para imagens de contentores

Esta página explica como criar e atualizar clusters usando imagens extraídas de um espelho do registo, em vez de um registo público, como o gcr.io. Esta funcionalidade pode ser ativada ou desativada em qualquer altura no ciclo de vida do cluster.

Esta página destina-se a operadores e especialistas em armazenamento que configuram e gerem o desempenho, a utilização e as despesas de armazenamento. Para saber mais sobre as funções comuns e as tarefas de exemplo a que fazemos referência no Google Cloud conteúdo, consulte o artigo Funções e tarefas comuns do utilizador do GKE.

Um espelho de registo é uma cópia local de um registo público que copia ou reflete a estrutura de ficheiros do registo público. Por exemplo, suponha que o caminho para o seu espelho de registo local é 172.18.0.20:5000. Quando o containerd encontra um pedido para extrair uma imagem, como gcr.io/kubernetes-e2e-test-images/nautilus:1.0, o containerd tenta extrair essa imagem, não do gcr.io, mas do seu registo local no seguinte caminho: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0. Se a imagem não estiver neste caminho do registo local, a imagem é extraída automaticamente do gcr.ioregisto público.

A utilização de uma imagem espelhada do registo oferece as seguintes vantagens:

  • Protege o utilizador contra indisponibilidades do registo público.
  • Acelera a criação de podcasts.
  • Permite-lhe realizar a sua própria análise de vulnerabilidades.
  • Evita os limites impostos pelos registos públicos sobre a frequência com que pode emitir comandos para os mesmos.

Antes de começar

  • Tem de ter um servidor do Artifact Registry configurado na sua rede.
  • Se o servidor de registo executar um certificado TLS privado, tem de ter o ficheiro da autoridade de certificação (AC).
  • Se o seu servidor de registo precisar de autenticação, tem de ter as credenciais de início de sessão adequadas ou o ficheiro de configuração do Docker.
  • Se estiver a usar um registo do Red Hat Quay, pode ser necessário criar manualmente a estrutura de diretórios do registo local.
  • Para usar um espelho do registo, tem de definir o tempo de execução do contentor como containerd.

  • Certifique-se de que tem espaço suficiente no disco na estação de trabalho do administrador para carregar imagens. O comando de carregamento de imagens, bmctl push images, descomprime o ficheiro do pacote de imagens transferido e, em seguida, extrai todos os ficheiros de imagens localmente antes de os carregar. Precisa de, pelo menos, três vezes o tamanho do ficheiro do pacote de imagens transferido no espaço em disco para o carregamento de imagens.

    Por exemplo, o ficheiro bmpackages_1.33.0-gke.799.tar.xz comprimido ocupa aproximadamente 12 GB de espaço no disco, pelo que deve ter, pelo menos, 36 GB de espaço no disco livre antes de transferir o ficheiro.

    Se estiver a fazer uma atualização ignorada (atualizar duas versões secundárias numa única operação), tem de carregar imagens de ficheiros de pacote de imagens para a versão de destino (N+2) e a versão intermédia (N+1). Com base neste exemplo, precisa de aproximadamente 72 GB de espaço em disco disponível para o carregamento de imagens. Para mais informações sobre a versão intermédia, consulte o artigo Requisito adicional para espelhos de registo.

Transfira todas as imagens necessárias para o Google Distributed Cloud

Transfira a versão mais recente da bmctl ferramenta e do pacote de imagens na página Transferências.

Carregue imagens de contentores para o servidor de registo

Quando usa bmctl push images para carregar imagens de contentores para o servidor do repositório, bmctl executa os seguintes passos pela ordem indicada:

  1. Descomprima um pacote de imagens transferido como um ficheiro TAR comprimido, como bmpackages_1.33.100-gke.89.tar.xz em bmpackages_1.33.100-gke.89.tar.

  2. Extraia todas as imagens do ficheiro TAR descomprimido para um diretório denominado bmpackages_1.33.100-gke.89.

  3. Envie cada ficheiro de imagem para o registo privado especificado.

    O bmctl usa os valores --username e --password para a autenticação básica para enviar as imagens para o seu registo privado.

As secções seguintes ilustram algumas variações comuns do comando bmctl push images para carregar imagens para o servidor do repositório.

Autentique-se no seu registo e partilhe o certificado TLS

O comando seguinte inclui as flags --username e --password para autenticação do utilizador com o seu servidor de registo. O comando também inclui a flag --cacert para transmitir o certificado Transport Layer Security (TLS) da AC, que é usado para a comunicação segura com o servidor de registo, incluindo o envio e a obtenção de imagens. Estas flags oferecem segurança básica para o seu servidor de registo.

Se o seu servidor de registo exigir autenticação e não usar as flags --username e --password, deve ser-lhe pedido que introduza credenciais quando executar bmctl push images. Pode escrever a sua palavra-passe ou escolher o ficheiro de configuração do Docker que contém as credenciais.

Para carregar imagens com autenticação e um certificado de AC privado, use um comando como o seguinte:

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

Substitua o seguinte:

  • IMAGES_TAR_FILE_PATH: o caminho do ficheiro TAR do pacote de imagens transferido, como bmpackages_1.33.100-gke.89.tar.xz.

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

  • USERNAME: o nome de utilizador de um utilizador com autorizações de acesso para carregar imagens para o servidor de registo.

  • PASSWORD: a palavra-passe do utilizador para autenticação com o servidor de registo.

  • CERT_PATH: o caminho do ficheiro de certificado da AC, se o servidor de registo usar um certificado TLS privado.

Por exemplo:

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

Carregue imagens sem autenticação ou certificados do utilizador

Se o seu servidor de registo não exigir credenciais, como um nome de utilizador e uma palavra-passe, especifique --need-credential=false no comando bmctl. Se o seu servidor de registo usar um certificado TLS público, não precisa de usar a flag --cacert. Este tipo de comando de carregamento é mais adequado para ambientes de teste, onde a segurança é menos importante do que na produção.

Para carregar imagens sem autenticação ou um certificado de AC privado, use um comando como o seguinte:

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

Por exemplo:

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

Ajuste o número de discussões

A rotina de carregamento de imagens pode demorar algum tempo devido ao tamanho e à quantidade de imagens de contentores no ficheiro TAR do pacote de imagens. Aumentar o número de threads paralelos faz com que a rotina seja executada mais rapidamente. Pode usar a flag --threads para alterar o número de threads paralelos que o bmctl push images usa.

Por predefinição, a rotina de carregamento de imagens usa 4 threads. Se os carregamentos de imagens demorarem demasiado tempo, aumente este valor. Como referência, num ambiente de teste da Google, o carregamento de imagens a partir de uma estação de trabalho com 4 CPUs demora aproximadamente 10 minutos com 8 threads paralelos.

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 threads paralelos usados para processar os carregamentos de imagens. Por predefinição, o bmctl push images usa quatro threads paralelos.

O comando seguinte aumenta o número de threads para o carregamento de 4 para 8 para reduzir o tempo de carregamento:

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

Carregamento através de proxy

Se precisar de um proxy para carregar as imagens da sua estação de trabalho para o servidor de registo, pode adicionar 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 o seguinte:

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

  • IMAGES_TAR_FILE_PATH: o caminho do ficheiro TAR do pacote de imagens transferido, como bmpackages_1.33.100-gke.89.tar.xz.

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

  • CERT_PATH: o caminho do ficheiro de certificado da AC, se o servidor de registo usar um certificado TLS privado.

Introduza o nome de utilizador e a palavra-passe quando lhe for pedido ou selecione um ficheiro de configuração do Docker.

O comando seguinte carrega imagens através de um proxy:

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

Use o seu próprio espaço de nomes com o bmctl push images

Se quiser usar o seu próprio espaço de nomes no servidor de registo em vez do espaço de nomes raiz, o containerd pode extrair informações deste espaço de nomes se fornecer o ponto final da API para o seu registo privado no campo registryMirrors.endpoint do ficheiro de configuração do cluster. Normalmente, o ponto final está no formato <REGISTRY_IP:PORT>/v2/<NAMESPACE>. Consulte o guia do utilizador do seu registo privado para ver detalhes específicos. Para mais informações, consulte o artigo Acerca da utilização de v2 no ponto final do registo.

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

Substitua NAMESPACE pelo nome do espaço de nomes no servidor de registo para o qual quer carregar imagens.

Por exemplo, se só tiver acesso a 198.51.20:5000/test-namespace/, pode usar um comando como o seguinte para carregar todas as imagens no espaço de nomes test-namespace:

bmctl push images \
    --source=./bmpackages_1.33.100-gke.89.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 ficheiro de configuração do cluster, pode adicionar o seguinte para fazer com que o containerd extraia do espaço de nomes test-namespace:

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

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

Configure clusters para usar uma imagem espelhada do registo

Pode configurar um espelho do registo para um cluster na criação do cluster ou sempre que atualiza um cluster existente. O método de configuração que usa depende do tipo de cluster e, para clusters de utilizadores, se está a criar um cluster ou a atualizar um cluster. As duas secções seguintes descrevem os dois métodos disponíveis para configurar espelhos de registo.

Use a secção de cabeçalho no ficheiro de configuração do cluster

O Google Distributed Cloud permite-lhe especificar espelhos de registo fora da especificação do cluster, na secção de cabeçalho do ficheiro de configuração do cluster. Para clusters de administrador, híbridos e autónomos, este é o único método suportado para especificar espelhos de registo. Este método aplica-se à criação ou às atualizações de clusters.

Para clusters de utilizadores, recomendamos que use a secção nodeConfig.registryMirrors no recurso Cluster para especificar e manter configurações de espelho do registo. Embora possa usar a secção de cabeçalho no ficheiro de configuração do cluster para especificar espelhos de registo quando cria um cluster de utilizador, a especificação não é mantida nas atualizações.

O seguinte ficheiro de configuração do cluster de exemplo especifica que as imagens devem ser obtidas a partir de uma réplica local do registo cujo ponto final é https://198.51.20:5000. Alguns dos campos apresentados no início deste ficheiro de configuração são descritos nas secções seguintes.

# 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 secção nodeConfig.registryMirrors na especificação do cluster

Este método de criação ou atualização de uma réplica da base de dados de registo aplica-se apenas a clusters de utilizadores. Uma vez que pode partilhar os segredos criados para o cluster de gestão com o cluster de utilizadores, pode usar o nodeConfig.registryMirrors do cluster de gestão ou híbrido para especificar o espelho do registo na especificação do cluster para o cluster de utilizadores.

Para configurar um cluster de utilizadores para usar o mesmo espelho do registo que o cluster de administrador, siga estes passos:

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

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

    Substitua o seguinte:

    • CLUSTER_NAME: o nome do administrador ou do cluster híbrido que gere o cluster de utilizadores.

    • CLUSTER_NAMESPACE: o nome do espaço de nomes do cluster de gestão.

    • ADMIN_KUBECONFIG: o caminho do ficheiro kubeconfig do cluster de gestão.

  2. Adicione a configuração nodeConfig.registryMirrors do cluster de administrador ao ficheiro de configuração do cluster de utilizador.

    A secção registryMirrors no ficheiro de configuração do cluster de utilizadores deve ter um aspeto semelhante ao seguinte exemplo:

    ---
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 alterações subsequentes à configuração do espelho do registo para o cluster de utilizadores, edite o nodeConfig.registryMirrors no ficheiro de configuração do cluster de utilizadores e aplique as alterações com bmctl update.

Não pode usar a secção de cabeçalho do ficheiro de configuração do cluster para atualizar a configuração dos espelhos do registo para um cluster de utilizador.

hosts campo

containerd verifica a secção hosts do ficheiro de configuração do cluster para descobrir que anfitriões são duplicados localmente. Estes anfitriões são mapeados para o ponto final do espelho do registo especificado no ficheiro de configuração do cluster (registryMirror.endpoint). No ficheiro de configuração de exemplo da secção anterior, os registos públicos listados na secção hosts são somehost.io e otherhost.io. Uma vez que estes registos públicos aparecem na secção hosts, o containerd verifica primeiro a réplica do registo privado quando encontra pedidos de obtenção de imagens do somehost.io ou do otherhost.io.

Por exemplo, suponhamos que containerd recebe um comando pull para somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Como somehost.io está listado como um dos anfitriões na secção hosts do ficheiro de configuração do cluster, containerd procura a imagem kubernetes-e2e-test-images/nautilus:1.0 no espelho do registo local. Se somehost.io não estiver listado na secção hosts, significa que containerd não sabe que existe uma cópia local de somehost.io. Nesse caso, o containerd não verifica a imagem no espelho e extrai a imagem do registo público somehost.io.

Tenha em atenção que, por predefinição, o Google Distributed Cloud espelha automaticamente as imagens de gcr.io, pelo que não precisa de listar gcr.io como anfitrião na secção hosts.

Os valores de hosts e o valor de endpoint não devem sobrepor-se. Por exemplo, o seguinte exemplo de configuração mostra um anfitrião, europe-docker.pkg.dev, que corresponde à parte do domínio do valor do ponto final. Neste caso, não tem de especificar um valor de hosts:

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

gcrKeyPath campo

Se quiser que o Google Distributed Cloud use automaticamente o Artifact Registry (gcr.io) para obter imagens que não aparecem no seu registo local, tem de especificar 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 para outros registos públicos.

Se não planeia usar a funcionalidade em que as imagens são extraídas de gcr.io quando não aparecem no seu registo local, não precisa de adicionar um gcrKeyPath ao ficheiro de configuração do cluster.

caCertPath campo

Se o seu registo exigir um certificado de segurança da camada de transporte (TLS) privado, este campo recebe o caminho para o ficheiro do certificado da AC de raiz do servidor. Este ficheiro de certificado deve estar na estação de trabalho do administrador, na máquina que executa os comandos bmctl. Se o seu registo não exigir um certificado TLS privado, pode deixar o campo caCertPath em branco.

pullCredentialConfigPath campo

Se o seu servidor de registo não exigir um ficheiro de configuração do Docker de autenticação, pode deixar o campo pullCredentialConfigPath em branco. Tenha em atenção que este é o caminho para o ficheiro de configuração na máquina que executa os comandos bmctl.

Use um espelho de registo com clusters de utilizadores

Os clusters de utilizadores não extraem automaticamente imagens de um espelho do registo se o respetivo cluster de administrador tiver sido configurado para o fazer. Para que os clusters de utilizadores extraiam imagens de um espelho do registo, tem de os configurar individualmente, conforme descrito no artigo Configure clusters to use a registry mirror (Configure clusters to use a registry mirror).

Atualize os pontos finais do espelho do registo, os certificados e as credenciais de obtenção

Para atualizar os pontos finais, os certificados ou as credenciais de obtenção do espelho do registo:

  1. No ficheiro de configuração do cluster, atualize o ponto final, o ficheiro de certificado da AC e o caminho do ficheiro de configuração das credenciais de obtenção.

  2. Aplique as alterações executando o seguinte comando:

    bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG

    Substitua o seguinte:

    • CLUSTER_NAME com o nome do cluster que quer atualizar.

    • ADMIN_KUBECONFIG com o caminho do ficheiro de configuração do cluster de administrador.

Valide se as imagens são extraídas do espelho do registo

Pode determinar se o containerd está a extrair imagens do seu registo local examinando o conteúdo de um ficheiro config.toml, conforme mostrado nos passos seguintes:

  1. Inicie sessão num nó e examine o conteúdo do seguinte ficheiro: /etc/containerd/config.toml

  2. Verifique a secção plugins."io.containerd.grpc.v1.cri".registry.mirrors do ficheiro config.toml para ver se o seu servidor de registo está listado no campo endpoint. Segue-se um excerto de um ficheiro config.toml de exemplo no qual o campo endpoint aparece a 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 seu espelho do registo aparecer no campo endpoint, significa que o nó está a obter imagens do seu espelho do registo e não de um registo público.

Resolva problemas de definições de espelho do registo

Pode usar crictl, a ferramenta de linha de comando da interface de tempo de execução do contentor, para testar as definições do registo transferindo ficheiros de imagem individuais. Cada ficheiro de imagem é etiquetado de forma independente com uma string de versão significativa. Por exemplo, a imagem do controlador da API cluster é etiquetada com a versão de lançamento do Google Distributed Cloud e a imagem do etcd é etiquetada com a versão correspondente do etcd.

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

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

Extraia uma imagem do espelho do registo

Se o seu repositório espelhado não usar espaços de nomes, use o seguinte comando para extrair uma imagem:

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

Extraia uma imagem de uma réplica do registo que use espaços de nomes

Se o seu espelho do registo usar espaços de nomes, use o seguinte comando para extrair uma imagem:

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

Acerca da utilização de v2 no ponto final de registo

Quando o registo usa namespaces personalizados, tem de antepor o namespace no ponto final do registo (registryMirror.endpoint) no ficheiro de configuração do cluster com v2/. Se não estiver a usar espaços de nomes, não use v2. Em qualquer dos casos, não use v2 no valor da flag --private-registry nem nos comandos de obtenção de imagens:

Sem espaços de nomes

  • 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 espaços de nomes

  • 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