Usar um espelho de registro para imagens de contêiner

Nesta página, explicamos como criar e atualizar 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 as despesas 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 Enterprise.

Um espelho de registro é uma cópia local de um registro público que copia ou espelha a estrutura de arquivos do 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 sua 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 Container 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.
  • Para usar um espelho de registro, defina o ambiente de execução do contêiner como containerd.

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

Faça upload das imagens do pacote de imagens para seu servidor de registro executando:

[HTTPS_PROXY=http://PROXY_IP:PORT] ./bmctl push images \
    --source=./bmpackages_VERSION.tar.xz \
    --private-registry=REGISTRY_IP:PORT \
    [--cacert=CERT_PATH] \
    [--need-credential=false]

Substitua:

  • PROXY_IP:PORT pelo endereço IP e pela porta do proxy se você precisar de um proxy para fazer upload das imagens da estação de trabalho para o servidor de registro.
  • VERSION com a versão do pacote de imagens que você transferiu por download da página Downloads.
  • REGISTRY_IP:PORT pelo endereço IP e pela porta do servidor de registro particular.
  • CERT_PATH pelo 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. Se o servidor de registro não exigir credenciais, especifique --need-credential=false.

Para mais informações sobre o comando bmctl push images, consulte:

bmctl push images --help

Usar seu próprio namespace

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 em registryMirrors.endpoint. O endpoint geralmente está no formato <REGISTRY_IP:PORT>/v2/<NAMESPACE>. Consulte o guia do usuário do seu registro particular para conferir detalhes específicos.

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

./bmctl push images \
    --source=./bmpackages_VERSION.tar.xz \
    --private-registry=172.18.0.20:5000/test-namespace \
    --username=<USERNAME> \
    --password=<PASSWORD> \
    --cacert <path/to/cert.crt>

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

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

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ê atualiza um cluster atual. O método de configuração usado depende do tipo de cluster e, no caso de 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

O Google Distributed Cloud permite 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ários, 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 existente, use a seção nodeConfig.registryMirrors na especificação do cluster.

O exemplo de arquivo de configuração de cluster a seguir especifica que as imagens devem ser extraídas de um espelho de registro local com o endpoint https://172.18.0.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://172.18.0.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ários. Como é possível compartilhar os segredos 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 de registro na especificação do cluster de usuário.

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

  1. Consiga a seção nodeConfig.registryMirror, incluindo referências de segredos, de nodeConfig.registryMirrors do recurso do 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 administrador.

    • 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 abaixo:

    ---
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 posteriores na configuração do espelho do 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 do 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. No arquivo de configuração de exemplo, 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, containerd verifica primeiro o espelho de registro particular quando encontra solicitações para extrair 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 apenas 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.

Campo gcrKeyPath

Se você quiser que o Google Distributed Cloud use automaticamente o Container 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 Container Registry. O Google Distributed Cloud não tem um mecanismo para fornecer chaves para 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ários

Os clusters de usuário não extraem 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 saber 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", "http://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.