Rancher es una plataforma de código abierto para gestionar varios clústeres Kubernetes desde una única interfaz web: usuarios y permisos, despliegue de aplicaciones, catálogo de charts de Helm y creación de clústeres nuevos. Rancher se ejecuta a su vez dentro de un clúster Kubernetes. En este tutorial montarás un clúster K3s de un nodo en Ubuntu 24.04, instalarás Rancher con Helm y un certificado de Let's Encrypt, y conectarás un clúster existente para gestionarlo.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS dedicado a Rancher, con al menos 4 vCPU y 8 GB de RAM, por ejemplo un VPS de CubePath.
  • Un usuario no root con privilegios sudo.
  • Un nombre de dominio con un registro DNS A, por ejemplo rancher.your_domain, apuntando a la IP pública del servidor (your_server_ip). Let's Encrypt lo necesita para emitir el certificado.
  • Los puertos 80 y 443 accesibles desde Internet.
  • Opcional: otro clúster Kubernetes que quieras gestionar desde Rancher (paso 7).

Paso 1: Configurar el cortafuegos

Abre SSH, HTTP y HTTPS en UFW. K3s también necesita que el tráfico entre pods (10.42.0.0/16) y servicios (10.43.0.0/16) no se bloquee:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable

Si vas a administrar este K3s con kubectl desde tu equipo, abre también el puerto de la API solo para tu IP:

sudo ufw allow from your_admin_ip to any port 6443 proto tcp

Comprueba las reglas:

sudo ufw status

Paso 2: Instalar K3s

K3s es una distribución ligera de Kubernetes que se instala con un único binario e incluye Traefik como controlador de Ingress, que Rancher usará para publicarse. Descarga el instalador y revísalo antes de ejecutarlo:

curl -sfL https://get.k3s.io -o k3s-install.sh
less k3s-install.sh

Ejecuta el instalador fijando el canal de versiones 1.33:

sudo INSTALL_K3S_CHANNEL=v1.33 sh k3s-install.sh

El instalador crea el servicio k3s en systemd y lo arranca. Configura kubectl para tu usuario copiando el kubeconfig de K3s:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$USER": ~/.kube/config
chmod 600 ~/.kube/config
echo 'export KUBECONFIG=$HOME/.kube/config' >> ~/.bashrc
source ~/.bashrc

Comprueba que el nodo está listo:

kubectl get nodes

NAME      STATUS   ROLES                  AGE   VERSION
rancher   Ready    control-plane,master   1m    v1.33.4+k3s1

Paso 3: Instalar Helm

Rancher y cert-manager se distribuyen como charts de Helm. Instala Helm desde Snap:

sudo snap install helm --classic

Comprueba la versión:

helm version --short

v3.18.6+g...

Paso 4: Instalar cert-manager

Rancher delega en cert-manager la solicitud y renovación del certificado de Let's Encrypt. Añade el repositorio de Jetstack e instala el chart con sus CRD:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

Comprueba que los tres componentes están en ejecución:

kubectl get pods -n cert-manager

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c9d8879fd-7xk2p              1/1     Running   0          60s
cert-manager-cainjector-6cc9b5f678-jq4zl   1/1     Running   0          60s
cert-manager-webhook-7bb7b75848-mrt6d      1/1     Running   0          60s

Paso 5: Instalar Rancher

Añade el repositorio estable de Rancher y crea su namespace:

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update
kubectl create namespace cattle-system

Instala Rancher. Sustituye rancher.your_domain por tu dominio, your_email por un correo donde recibir avisos de Let's Encrypt y your_bootstrap_password por una contraseña temporal que solo usarás en el primer acceso:

helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --set hostname=rancher.your_domain \
  --set bootstrapPassword=your_bootstrap_password \
  --set replicas=1 \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=your_email \
  --set letsEncrypt.ingress.class=traefik

Estas opciones hacen lo siguiente:

  • replicas=1: el chart despliega 3 réplicas por defecto, pensadas para un clúster de 3 nodos. En un solo nodo basta con una.
  • ingress.tls.source=letsEncrypt: cert-manager pide el certificado a Let's Encrypt mediante el reto HTTP-01.
  • letsEncrypt.ingress.class=traefik: el reto HTTP-01 se sirve a través del Traefik que incluye K3s.

Espera a que el despliegue termine. Rancher tarda unos minutos en arrancar:

kubectl -n cattle-system rollout status deploy/rancher

deployment "rancher" successfully rolled out

Comprueba que el certificado se ha emitido:

kubectl get certificate -n cattle-system

NAME                  READY   SECRET                AGE
tls-rancher-ingress   True    tls-rancher-ingress   3m

Por último, prueba el acceso HTTPS desde el propio servidor:

curl -sI https://rancher.your_domain | head -n 1

HTTP/2 200

Paso 6: Acceder a Rancher por primera vez

Abre https://rancher.your_domain en el navegador. Rancher pide la contraseña de arranque que definiste con bootstrapPassword. Si no la recuerdas, recupérala del Secret que crea el chart:

kubectl get secret bootstrap-secret -n cattle-system -o go-template='{{.data.bootstrapPassword | base64decode}}{{"\n"}}'

Tras iniciar sesión, el asistente te pide:

  1. Una contraseña nueva y robusta para el usuario admin. La de arranque deja de ser válida.
  2. Confirmar la Server URL (https://rancher.your_domain). Los clústeres gestionados usarán esta URL para conectarse a Rancher, así que debe ser accesible desde ellos.
  3. Aceptar los términos de uso.

Al terminar verás el panel Home con un clúster llamado local: es el propio K3s donde corre Rancher. No despliegues cargas de trabajo en él; úsalo solo para Rancher.

Paso 7: Importar un clúster existente

Rancher puede gestionar cualquier clúster Kubernetes que tenga salida a Internet hacia rancher.your_domain por el puerto 443. Para importarlo:

  1. En el menú lateral, abre Cluster Management.
  2. Pulsa Import Existing y elige Generic.
  3. Escribe un nombre para el clúster, por ejemplo produccion, y pulsa Create.
  4. Rancher muestra un comando kubectl apply con una URL de registro única. Cópialo.

Ejecuta ese comando con un kubectl que apunte al clúster que quieres importar (no al K3s de Rancher). Tendrá esta forma:

kubectl apply -f https://rancher.your_domain/v3/import/your_import_token.yaml

El manifiesto crea el namespace cattle-system en el clúster importado y despliega el agente que abre una conexión saliente hacia Rancher. Comprueba que el agente arranca:

kubectl get pods -n cattle-system

NAME                                    READY   STATUS    RESTARTS   AGE
cattle-cluster-agent-6d8c5b7c9f-2hl4w   1/1     Running   0          90s

En la interfaz de Rancher, el clúster pasará de Pending a Active en uno o dos minutos. Desde ese momento puedes ver sus nodos, desplegar cargas de trabajo, instalar charts desde Apps y dar acceso a otros usuarios con roles por clúster o por proyecto.

Solución de problemas

  • El certificado se queda en READY False: Let's Encrypt no llega al reto HTTP-01. Revisa que el registro A apunta a your_server_ip, que el puerto 80 está abierto y el detalle del reto con kubectl describe challenge -A.
  • helm install falla con un error de kubeVersion: la versión de K3s no está soportada por esa versión de Rancher. Reinstala K3s con un canal soportado según la matriz de Rancher.
  • El navegador muestra 404 page not found: Traefik no encuentra un Ingress para ese nombre. Comprueba que el dominio que usas coincide exactamente con el hostname del chart con kubectl get ingress -n cattle-system.
  • El clúster importado se queda en Pending: el agente no llega a Rancher. Revisa kubectl logs -n cattle-system deploy/cattle-cluster-agent en el clúster importado; suele ser un problema de DNS o de salida al puerto 443.

Conclusión

Tienes Rancher funcionando sobre K3s con un certificado válido de Let's Encrypt y un primer clúster importado bajo su gestión. Como siguientes pasos, instala el operador Rancher Backups desde Apps para programar copias de seguridad de Rancher, conecta un proveedor de identidad (LDAP, GitHub u OIDC) en Users & Authentication, y si Rancher pasa a ser crítico, migra a un clúster K3s de 3 nodos con replicas=3.