Este documento ha sido traducido utilizando tecnología de traducción automática. Si bien nos esforzamos por proporcionar traducciones precisas, no ofrecemos garantías sobre la integridad, precisión o confiabilidad del contenido traducido. En caso de discrepancia, la versión original en inglés prevalecerá y constituirá el texto autorizado.

Configuración del Registro Privado

Containerd se puede configurar para conectarse a registros privados y utilizarlos para obtener imágenes según lo requiera el kubelet.

Al iniciar, K3s comprobará si /etc/rancher/k3s/registries.yaml existe. Si es así, la configuración del registro contenida en este archivo se utiliza al generar la configuración de containerd.

  • Si deseas utilizar un registro privado como espejo de un registro público como docker.io, necesitarás configurar registries.yaml en cada nodo que desees usar el espejo.

  • Si tu registro privado requiere autenticación, utiliza certificados TLS personalizados, o no utiliza TLS, necesitarás configurar registries.yaml en cada nodo que descargará imágenes de tu registro.

Ten en cuenta que, por defecto, los nodos del servidor son programables. Si no has marcado los nodos del servidor y vas a ejecutar cargas de trabajo en ellos, por favor asegúrate de crear también el archivo registries.yaml en cada servidor.

Recuperación del endpoint predeterminado

Containerd tiene un "endpoint predeterminado" implícito para todos los registros. El endpoint predeterminado siempre se intenta como último recurso, incluso si hay otros endpoints listados para ese registro en registries.yaml. Las reescrituras no se aplican a las descargas contra el endpoint predeterminado. Por ejemplo, al descargar registry.example.com:5000/rancher/mirrored-pause:3.6, containerd utilizará un endpoint predeterminado de https://registry.example.com:5000/v2.

  • El endpoint predeterminado para docker.io es https://index.docker.io/v2.

  • El endpoint predeterminado para todos los demás registros es https://<REGISTRY>/v2, donde <REGISTRY> es el nombre del host del registro y el puerto opcional.

Para ser reconocido como un registro, el primer componente del nombre de la imagen debe contener al menos un punto o dos puntos (:) Por razones históricas, las imágenes sin un registro especificado en su nombre se identifican implícitamente como provenientes de docker.io.

Puerta de Versión

La opción --disable-default-registry-endpoint está disponible a partir de las versiones de enero de 2024: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1

Los nodos pueden iniciarse con la opción --disable-default-registry-endpoint. Cuando esto está configurado, containerd no volverá al punto final del registro predeterminado y solo extraerá de los puntos finales de espejo configurados, junto con el registro distribuido si está habilitado.

Esto puede ser deseado si tu clúster se encuentra en un entorno verdaderamente aislado donde el registro de origen no está disponible, o si deseas que solo algunos nodos extraigan del registro de origen.

Deshabilitar el punto final del registro predeterminado se aplica solo a los registros configurados a través de registries.yaml. Si el registro no está configurado explícitamente mediante una entrada de espejo en registries.yaml, se seguirá utilizando el comportamiento de reserva predeterminado.

Archivo de Configuración de Registros

El archivo consta de dos claves de nivel superior, con subclaves 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>

Espejos

La sección de espejos define los nombres y puntos finales de los registros, por ejemplo:

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

Cada espejo debe tener un nombre y un conjunto de puntos finales. Al extraer una imagen de un registro, containerd intentará estas URL de puntos finales, además del punto final predeterminado, y utilizará el primero que funcione.

Redirecciones

Si el registro privado se utiliza como un espejo para otro registro, como cuando se configura un cache de extracción, las extracciones de imágenes se redirigen de manera transparente a los puntos finales listados. El nombre del registro original se pasa al punto final del espejo a través del parámetro de consulta ns.

Por ejemplo, si tienes un espejo configurado para docker.io:

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

Entonces, al extraer docker.io/rancher/mirrored-pause:3.6, se extraerá la imagen de manera transparente como registry.example.com:5000/rancher/mirrored-pause:3.6.

Reescrituras

Cada espejo puede tener un conjunto de reescrituras, que utilizan expresiones regulares para coincidir y transformar el nombre de una imagen cuando se extrae de un espejo. Esto es útil si la estructura de organización/proyecto en el registro privado es diferente a la del registro que está reflejando. Las reescrituras coinciden y transforman solo el nombre de la imagen, NO la etiqueta.

Por ejemplo, la siguiente configuración extraerá de forma transparente la imagen docker.io/rancher/mirrored-pause:3.6 como registry.example.com:5000/mirrorproject/rancher-images/mirrored-pause:3.6:

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
    rewrite:
      "^rancher/(.*)": "mirrorproject/rancher-images/$1"
Puerta de Versión

Las reescrituras ya no se aplican al Endpoint Predeterminado a partir de las versiones de enero de 2024: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1. Antes de estas versiones, las reescrituras también se aplicaban al endpoint predeterminado, lo que impediría que K3s extrajera del registro de origen si la imagen no podía ser extraída de un endpoint espejo, y la imagen no estaba disponible bajo el nombre modificado en el registro de origen.

Si deseas aplicar reescrituras al extraer directamente de un registro – cuando no se utiliza como espejo para un registro de origen diferente – debes proporcionar un endpoint espejo que no coincida con el endpoint predeterminado. Los endpoints espejo en registries.yaml que coinciden con el endpoint predeterminado se ignoran; el endpoint predeterminado siempre se intenta al final sin reescrituras, si la opción de reserva no ha sido desactivada.

Por ejemplo, si tienes un registro en https://registry.example.com/, y deseas aplicar reescrituras al extraer explícitamente registry.example.com/rancher/mirrored-pause:3.6, puedes añadir un endpoint espejo con el puerto listado. Debido a que el endpoint espejo no coincide con el endpoint predeterminado - "https://registry.example.com:443/v2" != "https://registry.example.com/v2" - el endpoint es aceptado como espejo y se aplican las reescrituras, a pesar de que sea efectivamente lo mismo que el predeterminado.

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

Ten en cuenta que al usar espejos y reescrituras, las imágenes seguirán almacenándose bajo el nombre original. Por ejemplo, crictl image ls mostrará docker.io/rancher/mirrored-pause:3.6 como disponible en el nodo, incluso si la imagen fue extraída de un espejo con un nombre diferente.

Configuraciones

La sección configs define la configuración de TLS y credenciales para cada espejo. Para cada espejo puedes definir auth y/o tls.

La parte tls consiste en:

Directiva Descripción

cert_file

La vía del certificado del cliente que se utilizará para autenticar con el registro

key_file

La vía de la clave del cliente que se utilizará para autenticar con el registro

ca_file

Define la vía del certificado CA que se utilizará para verificar el archivo de certificado del servidor del registro

insecure_skip_verify

Booleano que define si se debe omitir la verificación TLS para el registro

La parte auth consiste en un nombre de usuario/contraseña o testigo de autenticación:

Directiva Descripción

username

nombre de usuario de la autenticación básica del registro privado

password

contraseña de usuario del registro privado de autenticación básica

auth

testigo de autenticación del registro privado de autenticación básica

A continuación se presentan ejemplos básicos de uso de registros privados en diferentes modos:

Soporte de comodines

Puerta de Versión

El soporte de comodines está disponible a partir de las versiones de marzo de 2024: v1.26.15+k3s1, v1.27.12+k3s1, v1.28.8+k3s1, v1.29.3+k3s1

La entrada de comodín "*" se puede utilizar en las secciones mirrors y configs para proporcionar una configuración predeterminada para todos los registros. La configuración predeterminada solo se utilizará si no hay una entrada específica para ese registro. Tenga en cuenta que el asterisco DEBE estar entre comillas.

En el siguiente ejemplo, se utilizará un espejo de registro local para todos los registros. La verificación TLS se desactivará para todos los registros, excepto docker.io.

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

Con TLS

A continuación se presentan ejemplos que muestran cómo puede configurar /etc/rancher/k3s/registries.yaml en cada nodo al usar TLS.

  • Con Autenticación

  • Sin Autenticación

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

Sin TLS

A continuación se presentan ejemplos que muestran cómo puede configurar /etc/rancher/k3s/registries.yaml en cada nodo cuando no utiliza TLS.

  • Con Autenticación

  • Sin Autenticación

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"

En caso de no haber comunicación TLS, necesitas especificar http:// para los puntos finales, de lo contrario, se predeterminará a https.

Para que los cambios en el registro surtan efecto, necesitas reiniciar K3s en cada nodo.

Solución de problemas de extracción de imágenes

Cuando Kubernetes experimenta problemas al extraer una imagen, el error mostrado por el kubelet puede reflejar únicamente el error terminal devuelto por el intento de extracción realizado contra el punto final predeterminado, haciendo que parezca que los puntos finales configurados no se están utilizando.

Revisa el registro de containerd en el nodo en /var/lib/rancher/k3s/agent/containerd/containerd.log para obtener información detallada sobre la causa raíz de la falla. Ten en cuenta que debes mirar los registros en el nodo donde se programa el pod. Puedes comprobar en qué nodo se programa tu pod emitiendo kubectl get pod -o wide -n NAMESPACE POD y revisando la columna NODE.

Añadiendo imágenes al registro privado

La replicación de imágenes a un registro privado requiere un host con Docker u otras herramientas de terceros que sean capaces de extraer y enviar imágenes.
Los pasos a continuación suponen que tienes un host con dockerd y las herramientas de línea de comandos de Docker, y acceso tanto a docker.io como a tu registro privado.

  1. Obtén el archivo k3s-images.txt de GitHub para la versión con la que estás trabajando.

  2. Extrae cada una de las imágenes de K3s listadas en el archivo k3s-images.txt desde docker.io.
    Ejemplo: docker pull docker.io/rancher/mirrored-pause:3.6

  3. Reetiqueta las imágenes para el registro privado.
    Ejemplo: docker tag docker.io/rancher/mirrored-pause:3.6 registry.example.com:5000/rancher/mirrored-pause:3.6

  4. Envía las imágenes al registro privado.
    Ejemplo: docker push registry.example.com:5000/rancher/mirrored-pause:3.6