Skip to content

Registro Privado y Mirrors en RKE2

Objetivo

Configurar RKE2 para consumir imágenes desde un registro privado o mirror interno, con autenticación, TLS personalizado y comportamiento de fallback controlado en todos los nodos del clúster.

Prerequisitos

  • Clúster RKE2 multi-nodo activo
  • Un registro privado accesible: Harbor, GitLab Registry o Docker Registry
  • Acceso SSH a todos los nodos del clúster
  • Opcional: Ansible para distribución del archivo de configuración

Contexto

Cuando RKE2 arranca, el proceso rke2-server o rke2-agent lee el archivo /etc/rancher/rke2/registries.yaml y lo inyecta en la configuración de containerd. Este archivo debe existir en cada nodo que vaya a descargar imágenes. Si el archivo no existe, RKE2 usa los registros públicos por defecto.

Estructura del archivo registries.yaml

mirrors:
  docker.io:
    endpoint:
      - "https://harbor.lab.internal"
  registry.k8s.io:
    endpoint:
      - "https://harbor.lab.internal"

configs:
  "harbor.lab.internal":
    auth:
      username: "robot$rke2-puller"
      password: "token-secreto"
    tls:
      ca_file: "/etc/ssl/certs/harbor-ca.crt"
      # cert_file: "/etc/ssl/certs/client.crt"   # solo si Harbor requiere mTLS
      # key_file:  "/etc/ssl/certs/client.key"
      # insecure_skip_verify: true               # solo en laboratorio

Laboratorio

En esta práctica se usará únicamente Quay como registro de imágenes para validar la configuración de registries.yaml en RKE2. El objetivo no es montar un registro privado propio, sino aprender cómo RKE2 y containerd resuelven autenticación, mirrors y fallback usando un registro real ampliamente utilizado en el ecosistema Kubernetes.

Escenario

  • Registro utilizado: quay.io
  • Imagen de prueba sugerida: quay.io/prometheus/prometheus:latest
  • Validación desde todos los nodos que puedan ejecutar cargas
  • Reinicio del servicio RKE2 después de aplicar cambios

1. Crear registries.yaml en cada nodo

sudo mkdir -p /etc/rancher/rke2

sudo tee /etc/rancher/rke2/registries.yaml <<'EOF'
mirrors:
  quay.io:
    endpoint:
      - "https://quay.io"
disable-default-registry-endpoint: true
EOF

2. Reiniciar RKE2

En nodos server:

sudo systemctl restart rke2-server

En nodos agent:

sudo systemctl restart rke2-agent

3. Probar pull manual con crictl

sudo crictl pull quay.io/prometheus/prometheus:latest
sudo crictl images | grep prometheus

4. Desplegar un pod de prueba usando Quay

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: quay-test
  namespace: default
spec:
  containers:
  - name: prometheus
    image: quay.io/prometheus/prometheus:latest
    command: ["sleep","3600"]
EOF

5. Validar el estado del pod

kubectl get pod quay-test
kubectl describe pod quay-test

6. Revisar logs de containerd

Si el pull falla, revisar:

sudo tail -n 100 /var/lib/rancher/rke2/agent/containerd/containerd.log

7. Limpieza

kubectl delete pod quay-test

Resultado esperado

  • El nodo descarga la imagen desde quay.io
  • El pod entra en estado Running
  • El alumno confirma que RKE2 toma la configuración desde registries.yaml
  • El alumno identifica dónde revisar fallos de pull en containerd

Nota técnica

La opción disable-default-registry-endpoint: true evita que containerd intente usar otros endpoints implícitos para los registros configurados en registries.yaml. Esto es útil cuando se quiere controlar exactamente desde dónde se descargan imágenes.