Usar um espelho de registro para criar clusters

Nesta página, explicamos como criar clusters usando imagens extraídas de um espelho de registro em vez de um registro público, como gcr.io.

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, vamos supor que o caminho para o espelho de registro local é 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, a imagem 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 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 GKE em Bare Metal

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 registros 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 ver 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

Criar clusters do espelho de registro

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://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
...

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, digamos que containerd receba um comando pull para somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Comosomehost.io está listado como um dos hosts na seçãohosts do arquivo de configuração do cluster, containerd procura no espelho local do registro a imagemkubernetes-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.

Vale observar que, por padrão, o GKE em Bare Metal 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 GKE em Bare Metal use o Container Registry (gcr.io) automaticamente 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 GKE em Bare Metal 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.

Criar um cluster de usuário a partir do espelho do registro

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 Criar clusters a partir do 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

Nesta seção, descrevemos dois métodos que podem ser usados para verificar se containerd está extraindo imagens do espelho do registro local, e não de um registro público.

Método no 1: comparar resumos do repositório

Esse método envolve comparar resumos de repositórios para determinar se uma imagem foi extraída do espelho do registro.

Lembre-se de que um registro tem um identificador exclusivo chamado resumo do repositório e uma imagem tem um identificador exclusivo chamado resumo por e-mail do contêiner. Duas imagens idênticas têm o mesmo resumo de imagens de contêiner, mesmo que elas venham de registros diferentes. No entanto, se as imagens vierem de registros diferentes, elas terão resumos de repositório diferentes.

  1. Faça login em um nó do cluster usando SSH.

  2. Escolha uma imagem com a origem que você quer verificar.

  3. Extraia a imagem do registro público que você usa executando o seguinte comando:

    crictl pull PUBLIC_ENDPOINT

    Substitua PUBLIC_ENDPOINT pelo caminho da imagem no registro público. Por exemplo, gcr.io/anthos-baremetal-release/kube-rbac-proxy:v0.6.0-gke.0.

  4. Extraia a mesma imagem do seu espelho de registro executando o seguinte comando:

    crictl pull MIRROR_ENDPOINT

    Substitua MIRROR_ENDPOINT pelo caminho da imagem no espelho do registro. Por exemplo, 10.168.15.224:5007/test-namespace/anthos-baremetal-release/kube-rbac-proxy:v0.6.0-gke.0.

  5. Execute o comando a seguir para exibir os resumos de repositório das duas imagens que você extraiu nas etapas anteriores:

    crictl inspecti PUBLIC_OR_MIRROR_ENDPOINT | grep -A 3 repoDigests

    Substitua PUBLIC_OR_MIRROR_ENDPOINT pelo endpoint público da imagem ou pelo endpoint do espelho do registro da imagem. Qualquer um desses valores é aceitável porque o comando crictl inspecti analisa o resumo da imagem do contêiner do argumento que você transmite a ele. Como a imagem do registro público é idêntica à do espelho de registro, ambas têm o mesmo resumo de imagem do contêiner.

    A resposta ao comando pode ser assim:

     "repoDigests": [
   "gcr.io/anthos-baremetal-release/kube-rbac-proxy@sha256:27be66fb9140d83c4af8794a234b998c90e844e3414108ce72db603f4f6ea0b3",
   "10.168.15.224:5007/test-namespace/anthos-baremetal-release/kube-rbac-proxy@sha256:27be66fb9140d83c4af8794a234b998c90e844e3414108ce72db603f4f6ea0b3"
 ],

  6. Compare os resumos do repositório que aparecem em negrito na saída da etapa anterior. Se os resumos forem idênticos, os nós no cluster serão extraídos do espelho do registro. Caso contrário, os nós do cluster estão extraindo imagens de um registro público.

Método no 2: examinar o arquivo config.toml

É 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. Veja 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.