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.

Espelho de Registro Embutido

Portão de Versão

O Espelho de Registro Embutido está disponível como um recurso experimental 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 e como GA a partir das versões de dezembro de 2024: v1.29.12+k3s1, v1.30.8+k3s1, v1.31.4+k3s1.

K3s incorpora Spegel, um espelho de registro OCI distribuído sem estado que permite o compartilhamento peer-to-peer de imagens de contêiner entre nós em um cluster Kubernetes. O espelho de registro distribuído está desativado por padrão. Para que o K3s o utilize, você deve habilitar tanto o Espelho de Registro OCI Distribuído quanto o Espelhamento de Registro conforme explicado nas subseções a seguir.

Habilitando o Espelho de Registro OCI Distribuído

Para habilitar o espelho de registro embutido, os nós do servidor devem ser iniciados com a flag --embedded-registry ou com embedded-registry: true no arquivo de configuração. Esta opção habilita o espelho embutido para uso em todos os nós do cluster.

Quando habilitado em nível de cluster, todos os nós hospedarão um registro OCI local na porta 6443 e publicarão uma lista de imagens disponíveis via uma rede peer-to-peer na porta 5001. Qualquer imagem disponível no armazenamento de imagens containerd em qualquer nó pode ser puxada por outros membros do cluster sem acesso a um registro externo. Imagens importadas via arquivos tar de imagem air gap são fixadas no containerd para garantir que permaneçam disponíveis e não sejam removidas pela coleta de lixo do Kubelet.

A porta peer-to-peer pode ser alterada de 5001 definindo a variável de ambiente K3S_P2P_PORT para o serviço K3s. A porta deve ser definida com o mesmo valor em todos os nós. Alterar a porta não é suportado e não é recomendado.

Requisitos

Quando o espelho de registro embutido está habilitado, todos os nós devem ser capazes de se alcançar via seus endereços IP internos, nas portas TCP 5001 e 6443. Se os nós não puderem se alcançar, pode demorar mais para as imagens serem puxadas, pois o registro distribuído será tentado primeiro pelo containerd, antes de voltar para outros pontos finais.

Habilitando o Espelhamento de Registro

Habilitar o espelhamento para um registro permite que um nó puxe imagens desse registro de outros nós e compartilhe as imagens do registro com outros nós. Se um registro estiver habilitado para espelhamento em alguns nós, mas não em outros, apenas os nós com o registro habilitado trocarão imagens desse registro.

Para habilitar o espelhamento de imagens de um registro de contêiner upstream, os nós devem ter uma entrada na seção mirrors de registries.yaml para esse registro. O registro não precisa ter nenhum endpoint listado, apenas precisa estar presente. Por exemplo, para habilitar o espelhamento distribuído de imagens de docker.io e registry.k8s.io, configure registries.yaml com o seguinte conteúdo em todos os nós do cluster:

mirrors:
  docker.io:
  registry.k8s.io:

Endpoints para espelhos de registro também podem ser adicionados como de costume. Na configuração a seguir, as tentativas de puxar imagens primeiro tentarão o espelho embutido, depois mirror.example.com, e finalmente docker.io:

mirrors:
  docker.io:
    endpoint:
      - https://mirror.example.com

Se você estiver usando um registro privado diretamente, em vez de como um espelho para um registro upstream, pode habilitar o espelhamento distribuído da mesma forma que os registros públicos são habilitados - listando-o na seção de espelhos:

mirrors:
  mirror.example.com:

Portão de Versão

O suporte a curingas 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 espelho curinga "*" pode ser usada para habilitar o espelhamento distribuído de todos os registros. Observe que o asterisco DEVE ser colocado entre aspas:

mirrors:
  "*":

Se nenhum registro estiver habilitado para espelhamento em um nó, esse nó não participa do registro distribuído de nenhuma forma.

Para mais informações sobre a estrutura do arquivo registries.yaml, consulte Configuração de Registro Privado.

Fallback de Endpoint Padrão

Por padrão, o containerd irá recorrer ao endpoint padrão ao puxar de registros com endpoints de espelho configurados. Se você quiser desabilitar isso e apenas puxar imagens dos espelhos configurados e/ou do espelho embutido, consulte a seção Fallback de Endpoint Padrão da documentação de Configuração de Registro Privado.

Observe que se você estiver usando a opção --disable-default-registry-endpoint e quiser permitir puxar diretamente de um registro específico, enquanto desautoriza os demais, você pode fornecer explicitamente um endpoint para permitir que a puxada da imagem recorra ao próprio registro:

mirrors:
  docker.io:           # no default endpoint, pulls will fail if not available on a node
  registry.k8s.io:     # no default endpoint, pulls will fail if not available on a node
  mirror.example.com:  # explicit default endpoint, can pull from upstream if not available on a node
    endpoint:
      - https://mirror.example.com

Última Tag

Quando nenhuma tag é especificada para uma imagem de contêiner, a tag padrão implícita é latest. Essa tag é frequentemente atualizada para apontar para a versão mais recente da imagem. Como esta tag apontará para diferentes revisões de uma imagem dependendo de quando for puxada, o registro distribuído não puxará a latest tag de outros nós. Isso força o containerd a acessar um registro upstream ou um espelho de registro para garantir uma visão consistente do que a latest tag se refere.

Isso está alinhado com o comportamento especial imagePullPolicy padrão observado pelo Kubernetes ao usar a latest tag para uma imagem de contêiner.

O espelhamento da latest tag pode ser habilitado configurando a variável de ambiente K3S_P2P_ENABLE_LATEST=true para o serviço K3s. Isso não é suportado e não é recomendado, pelas razões discutidas acima.

Segurança

Autenticação

O acesso à API do registro do espelho embutido requer um certificado de cliente válido, assinado pela autoridade certificadora do cliente do cluster.

O acesso à rede peer-to-peer da tabela hash distribuída requer uma chave pré-compartilhada que é controlada pelos nós do servidor. Os nós se autenticam mutuamente usando tanto a chave pré-compartilhada quanto um certificado assinado pela autoridade certificadora do cluster.

Preocupações Potenciais

O registro distribuído é construído com base em princípios de peer-to-peer e assume um nível igual de privilégio e confiança entre todos os membros do cluster. Se isso não corresponder à postura de segurança do seu cluster, você não deve habilitar o registro distribuído embutido.

O registro embutido pode disponibilizar imagens que um nó pode não ter acesso de outra forma. Por exemplo, se algumas de suas imagens forem puxadas de um registro, projeto ou repositório que requer autenticação via Kubernetes Image Pull Secrets, ou credenciais em registries.yaml, o registro distribuído permitirá que outros nós compartilhem essas imagens sem fornecer credenciais ao registro upstream.

Usuários com acesso para enviar imagens para o armazenamento de imagens do containerd em um nó podem ser capazes de usar isso para 'envenenar' a imagem para outros nós do cluster, já que outros nós confiarão na tag anunciada pelo nó e a usarão sem verificar com o registro upstream. Se a integridade da imagem for importante, você deve usar digests de imagem em vez de tags, pois o digest não pode ser envenenado dessa maneira.

Compartilhando Imagens Air Gap ou Carregadas Manualmente

O compartilhamento de imagens é controlado com base no registro de origem. Imagens carregadas diretamente no containerd via arquivos tar air gap, pré-importadas ou carregadas diretamente no armazenamento de imagens do containerd usando a ferramenta de linha de comando ctr são compartilhadas entre os nós se forem marcadas como sendo de um registro que está habilitado para espelhamento.

Observe que o registro upstream do qual as imagens parecem vir não precisa realmente existir ou ser acessível. Por exemplo, você poderia marcar imagens como sendo de um registro upstream fictício e importar essas imagens para o armazenamento de imagens do containerd. Você poderá então puxar essas imagens de todos os membros do cluster, desde que esse registro esteja listado em registries.yaml

Enviando Imagens

O registro embutido é somente leitura e não pode ser enviado diretamente usando docker push ou outras ferramentas comuns que interagem com registros OCI.

As imagens podem ser disponibilizadas manualmente através do registro embutido executando ctr -n k8s.io image pull para puxar uma imagem, ou carregando arquivos de imagem criados por docker save através do comando ctr -n k8s.io image import ou do recurso pré-importação. Observe que o namespace k8s.io deve ser especificado ao gerenciar imagens via ctr para que elas sejam visíveis para o kubelet.