Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official.

Configuração de Registro Privado

O Containerd pode ser configurado para se conectar a registros privados e usá-los para puxar imagens conforme necessário pelo kubelet.

Ao iniciar, o K3s verificará se /etc/rancher/k3s/registries.yaml existe. Se sim, a configuração do registro contida neste arquivo é usada ao gerar a configuração do containerd.

  • Se você quiser usar um registro privado como um espelho para um registro público, como o docker.io, será necessário configurar registries.yaml em cada nó que deseja usar o espelho.

  • Se o seu registro privado exigir autenticação, usar certificados TLS personalizados ou não usar TLS, será necessário configurar registries.yaml em cada nó que puxará imagens do seu registro.

Observe que os nós do servidor são agendáveis por padrão. Se você não aplicou taint nos nós do servidor e estiver executando cargas de trabalho neles, certifique-se de criar também o arquivo registries.yaml em cada servidor.

Fallback do Endpoint Padrão

O Containerd tem um "endpoint padrão" implícito para todos os registros. O endpoint padrão é sempre tentado como último recurso, mesmo que haja outros endpoints listados para esse registro em registries.yaml. Reescritas não são aplicadas a puxadas contra o endpoint padrão. Por exemplo, ao puxar registry.example.com:5000/rancher/mirrored-pause:3.6, o containerd usará um endpoint padrão de https://registry.example.com:5000/v2.

  • O endpoint padrão para docker.io é https://index.docker.io/v2.

  • O endpoint padrão para todos os outros registros é https://<REGISTRY>/v2, onde <REGISTRY> é o nome do host do registro e a porta opcional.

Para ser reconhecido como um registro, o primeiro componente do nome da imagem deve conter pelo menos um ponto ou dois-pontos. Por razões históricas, imagens sem um registro especificado em seu nome são implicitamente identificadas como sendo de docker.io.

Portão de Versão

A opção --disable-default-registry-endpoint está disponível a partir das versões de janeiro de 2024: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1

Os nós podem ser iniciados com a opção --disable-default-registry-endpoint. Quando isso está configurado, o containerd não irá recorrer ao endpoint de registro padrão e irá puxar apenas dos endpoints de espelho configurados, junto com o registro distribuído, se estiver habilitado.

Isso pode ser desejável se seu cluster estiver em um ambiente verdadeiramente air-gapped, onde o registro upstream não está disponível, ou se você desejar que apenas alguns nós puxem do registro upstream.

Desabilitar o endpoint de registro padrão se aplica apenas a registros configurados via registries.yaml. Se o registro não estiver explicitamente configurado via entrada de espelho em registries.yaml, o comportamento padrão de fallback ainda será utilizado.

Arquivo de Configuração de Registros

O arquivo consiste em duas chaves de nível superior, com subchaves para cada registro:

mirrors:
  <REGISTRY>:
    endpoint:
      - https://<REGISTRY>/v2
configs:
  <REGISTRY>:
    auth:
      username: <BASIC AUTH USERNAME>
      password: <BASIC AUTH PASSWORD>
      token: <BEARER TOKEN>
    tls:
      ca_file: <PATH TO SERVER CA>
      cert_file: <PATH TO CLIENT CERT>
      key_file: <PATH TO CLIENT KEY>
      insecure_skip_verify: <SKIP TLS CERT VERIFICATION BOOLEAN>

Espelhos

A seção de espelhos define os nomes e endpoints dos registros, por exemplo:

mirrors:
  registry.example.com:
    endpoint:
      - "https://registry.example.com:5000"

Cada espelho deve ter um nome e um conjunto de endpoints. Ao puxar uma imagem de um registro, o containerd tentará essas URLs de endpoint, além do endpoint padrão, e usará o primeiro que funcionar.

Redirecionamentos

Se o registro privado for usado como um espelho para outro registro, como ao configurar um cache de pull, os pulls de imagens são redirecionados de forma transparente para os endpoints listados. O nome do registro original é passado para o endpoint do espelho via parâmetro de consulta ns.

Por exemplo, se você tiver um espelho configurado para docker.io:

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"

Então puxar docker.io/rancher/mirrored-pause:3.6 irá puxar a imagem de forma transparente como registry.example.com:5000/rancher/mirrored-pause:3.6.

Reescritas

Cada espelho pode ter um conjunto de reescritas, que usam expressões regulares para corresponder e transformar o nome de uma imagem quando é puxada de um espelho. Isso é útil se a estrutura da organização/projeto no registro privado for diferente do registro que está sendo espelhado. As reescritas correspondem e transformam apenas o nome da imagem, NÃO a tag.

Por exemplo, a seguinte configuração puxaria a imagem docker.io/rancher/mirrored-pause:3.6 como registry.example.com:5000/mirrorproject/rancher-images/mirrored-pause:3.6 de forma transparente:

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
    rewrite:
      "^rancher/(.*)": "mirrorproject/rancher-images/$1"
Portão de Versão

As reescritas não são mais aplicadas ao Endpoint Padrão a partir das versões de janeiro de 2024: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1. Antes dessas versões, as reescritas também eram aplicadas ao endpoint padrão, o que impediria o K3s de puxar do registro upstream se a imagem não pudesse ser puxada de um endpoint de espelho, e a imagem não estivesse disponível sob o nome modificado no upstream.

Se você quiser aplicar reescritas ao puxar diretamente de um registro - quando não estiver sendo usado como um espelho para um registro upstream diferente - você deve fornecer um endpoint de espelho que não corresponda ao endpoint padrão. Endpoints de espelho em registries.yaml que correspondem ao endpoint padrão são ignorados; o endpoint padrão é sempre tentado por último sem reescritas, se a opção de fallback não tiver sido desativada.

Por exemplo, se você tiver um registro em https://registry.example.com/, e quiser aplicar reescritas ao puxar explicitamente registry.example.com/rancher/mirrored-pause:3.6, você pode adicionar um endpoint de espelho com a porta listada. Como o endpoint de espelho não corresponde ao endpoint padrão - "https://registry.example.com:443/v2" != "https://registry.example.com/v2" - o endpoint é aceito como um espelho e as reescritas são aplicadas, apesar de ser efetivamente o mesmo que o padrão.

mirrors:
 registry.example.com
   endpoint:
     - "https://registry.example.com:443"
   rewrite:
     "^rancher/(.*)": "mirrorproject/rancher-images/$1"

Observe que ao usar espelhos e reescritas, as imagens ainda serão armazenadas sob o nome original. Por exemplo, crictl image ls mostrará docker.io/rancher/mirrored-pause:3.6 como disponível no nó, mesmo que a imagem tenha sido puxada de um espelho com um nome diferente.

Configs

A seção configs define a configuração de TLS e credenciais para cada espelho. Para cada espelho, você pode definir auth e/ou tls.

A parte tls consiste em:

Diretiva Descrição

cert_file

O caminho do certificado do cliente que será usado para autenticar com o registro

key_file

O caminho da chave do cliente que será usado para autenticar com o registro

ca_file

Define o caminho do certificado CA a ser usado para verificar o arquivo de certificado do servidor do registro

insecure_skip_verify

Booleano que define se a verificação TLS deve ser ignorada para o registro

A parte auth consiste em nome de usuário/senha ou token de autenticação:

Diretiva Descrição

username

nome de usuário da autenticação básica do registro privado

password

senha da autenticação básica do registro privado

auth

token de autenticação da autenticação básica do registro privado

Abaixo estão exemplos básicos de uso de registros privados em diferentes modos:

Suporte a coringas

Portão de Versão

O suporte a coringas está disponível a partir das versões de março de 2024: v1.26.15+k3s1, v1.27.12+k3s1, v1.28.8+k3s1, v1.29.3+k3s1

A entrada de coringa "*" pode ser usada nas seções mirrors e configs para fornecer configuração padrão para todos os registros. A configuração padrão só será usada se não houver uma entrada específica para aquele registro. Observe que o asterisco DEVE ser colocado entre aspas.

No exemplo a seguir, um espelho de registro local será usado para todos os registros. A verificação TLS será desativada para todos os registros, exceto docker.io.

mirrors:
  "*":
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "docker.io":
  "*":
    tls:
      insecure_skip_verify: true

Com TLS

Abaixo estão exemplos mostrando como você pode configurar /etc/rancher/k3s/registries.yaml em cada nó ao usar TLS.

  • Com Autenticação

  • Sem Autenticação

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry
mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry

Sem TLS

Abaixo estão exemplos mostrando como você pode configurar /etc/rancher/k3s/registries.yaml em cada nó quando não estiver usando TLS.

  • Com Autenticação

  • Sem Autenticação

mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"

Em caso de comunicação sem TLS, você precisa especificar http:// para os endpoints, caso contrário, será padrão para https.

Para que as alterações no registro tenham efeito, você precisa reiniciar o K3s em cada nó.

Solução de Problemas ao Puxar Imagens

Quando o Kubernetes enfrenta problemas ao puxar uma imagem, o erro exibido pelo kubelet pode refletir apenas o erro terminal retornado pela tentativa de pull feita contra o endpoint padrão, fazendo parecer que os endpoints configurados não estão sendo usados.

Verifique o log do containerd no nó em /var/lib/rancher/k3s/agent/containerd/containerd.log para obter informações detalhadas sobre a causa raiz da falha. Observe que você deve olhar os logs no nó onde o pod está agendado. Você pode verificar em qual nó seu pod está agendado emitindo kubectl get pod -o wide -n NAMESPACE POD e verificando a coluna NODE.

Adicionando Imagens ao Registro Privado

Espelhar imagens para um registro privado requer um host com Docker ou outras ferramentas de terceiros que sejam capazes de puxar e enviar imagens.
Os passos abaixo assumem que você tem um host com dockerd e as ferramentas CLI do docker, e acesso tanto ao docker.io quanto ao seu registro privado.

  1. Obtenha o arquivo k3s-images.txt do GitHub para a versão com a qual você está trabalhando.

  2. Puxe cada uma das imagens do K3s listadas no arquivo k3s-images.txt do docker.io.
    Exemplo: docker pull docker.io/rancher/mirrored-pause:3.6

  3. Reetiquete as imagens para o registro privado.
    Exemplo: docker tag docker.io/rancher/mirrored-pause:3.6 registry.example.com:5000/rancher/mirrored-pause:3.6

  4. Envie as imagens para o registro privado.
    Exemplo: docker push registry.example.com:5000/rancher/mirrored-pause:3.6