Guía práctica para Ubuntu 24.04 LTS: preparar, instalar, validar y desplegar una aplicación de prueba.
K3s empaqueta los componentes esenciales de Kubernetes en una distribución ligera. En una instalación de un solo nodo, el mismo Cloud Server ejecuta el plano de control, el runtime de contenedores y las cargas de trabajo. Esto reduce la complejidad inicial, pero también crea un único punto de falla: es apropiado para aprendizaje, laboratorios, desarrollo o cargas pequeñas que toleren una interrupción; no ofrece alta disponibilidad.
Resultado esperado. Al finalizar tendrás K3s activo como servicio de systemd, un nodo en estado Ready y una aplicación nginx accesible por el puerto TCP 30080 desde una dirección autorizada.
Que vas a aprender
Comprobar si el servidor cumple los requisitos mínimos y registrar una línea base.
Preparar el firewall sin perder el acceso SSH ni exponer la API de Kubernetes a Internet.
Instalar K3s desde el canal estable con cifrado de Secrets en reposo.
Validar el servicio, el nodo y los componentes del sistema antes de desplegar cargas.
Aplicar un manifiesto de prueba, verificar su recorrido de red y retirar los recursos de forma controlada.
Cómo queda la arquitectura
El nodo único contiene tanto el plano de control como el trabajador. La administración entra por SSH o por la API de Kubernetes; el tráfico de la aplicación sigue un camino distinto: firewall, puerto publicado, Service y Pod. K3s instala también containerd, Flannel, CoreDNS, Metrics Server y Traefik en su configuración predeterminada.
Figura 1. Arquitectura de un clúster K3s de un solo nodo.
Requisitos previos
Recurso | Mínimo de K3s | Recomendado para esta guía |
CPU | 2 núcleos para un server | 2 vCPU o más |
RAM | 2 GB para un server | 4 GB para trabajar con margen |
Disco | Depende de la carga | SSD y al menos 20 GB libres |
Sistema | Linux moderno x86_64, armhf o arm64 | Ubuntu Server 24.04 LTS x86_64 |
Acceso SSH mediante clave y un usuario con privilegios sudo.
Una consola de emergencia o acceso fuera de banda del proveedor, por si una regla de red corta la sesión.
Salida a Internet por HTTPS y resolución DNS para descargar K3s y las imágenes de contenedor.
Una IP pública o privada estable. Si administrarás el clúster desde otra máquina, conoce la IP de origen que autorizarás en el puerto 6443.
Snapshot o backup previo cuando el servidor ya contiene datos o servicios.
Importante. Los requisitos de 2 núcleos y 2 GB de RAM son la base del server K3s y sus componentes incluidos; no contemplan el consumo de tus aplicaciones. Para esta práctica se recomiendan 4 GB.
Flujo seguro de trabajo
La secuencia evita aplicar cambios a ciegas: primero se prepara y se revisa la red; después se instala; finalmente se valida el nodo antes de desplegar y probar la aplicación
Paso 1. Registrar el estado del servidor
Actualiza el índice de paquetes, instala las herramientas necesarias y registra hostname, CPU, memoria y espacio disponible. Cada nodo de un clúster K3s debe tener un hostname único.
sudo apt updatesudo apt install -y curl ca-certificateshostnamectl --staticnprocfree -hdf -h /
Comprueba que el hostname no sea localhost, que haya al menos 2 vCPU, 2 GB de RAM y espacio suficiente. Si cambias el hostname, abre una nueva sesión antes de continuar para confirmar que la resolución local sigue funcionando.
Paso 2. Configurar y validar el firewall
Mantener UFW activo aporta una capa de control en el host. Autoriza SSH antes de habilitarlo. Para administrar Kubernetes desde una estación remota, limita el puerto 6443 a la IP pública de esa estación; no lo abras a cualquier origen.
sudo ufw status verbosesudo ufw allow OpenSSH# Solo si usarás kubectl desde otra máquina:sudo ufw allow from TU_IP_PUBLICA to any port 6443 proto tcp comment 'K3s API'# Redes predeterminadas de Pods y Services de K3s:sudo ufw allow from 10.42.0.0/16 to anysudo ufw allow from 10.43.0.0/16 to anysudo ufw enablesudo ufw status numbered
Precaución. Mantén abierta la sesión SSH actual y confirma una segunda conexión antes de continuar. En un proveedor cloud, replica las restricciones en el firewall o grupo de seguridad perimetral.
En un clúster de un solo nodo no necesitas publicar UDP 8472. En clústeres multinodo, Flannel VXLAN lo usa entre nodos, pero la documentación de K3s advierte expresamente que no debe quedar expuesto a Internet.
Paso 3. Descargar, revisar e instalar K3s
Descarga el instalador en un archivo para poder revisarlo antes de ejecutarlo. El canal stable evita seleccionar manualmente una versión en una guía introductoria. En producción, fija una versión concreta después de revisar sus notas de lanzamiento y probar la actualización.
curl -sfL https://get.k3s.io -o install-k3s.shless install-k3s.shsudo env INSTALL_K3S_CHANNEL=stable sh install-k3s.sh server \ --write-kubeconfig-mode=600 \ --secrets-encryptionrm install-k3s.sh
La opción --write-kubeconfig-mode=600 conserva el kubeconfig administrativo legible solo por root. --secrets-encryption cifra en reposo los objetos Secret almacenados por Kubernetes. El instalador crea y habilita el servicio k3s, instala kubectl, crictl y ctr, y genera /etc/rancher/k3s/k3s.yaml.
Seguridad. No cambies el kubeconfig a modo 0644 para evitar usar sudo: ese archivo concede privilegios administrativos completos. Para esta guía ejecutaremos sudo k3s kubectl.
Paso 4. Validar K3s antes de desplegar
Primero comprueba systemd y después consulta Kubernetes. El orden permite distinguir un fallo del servicio de un fallo de los componentes internos.
sudo systemctl is-enabled k3ssudo systemctl is-active k3ssudo k3s kubectl get nodes -o widesudo k3s kubectl get pods -A
El servicio debe responder enabled y active. El nodo debe aparecer Ready. Espera hasta que los Pods de kube-system estén Running o Completed; durante el arranque pueden permanecer unos minutos en Pending o ContainerCreating.
sudo journalctl -u k3s --no-pager -n 100
Consulta el journal si el nodo no llega a Ready. No avances al despliegue mientras el servicio o la red interna sigan degradados.
Paso 5. Crear un namespace y el manifiesto de prueba
El namespace separa los recursos de laboratorio. Créalo de forma idempotente: el mismo comando puede ejecutarse otra vez sin duplicarlo.
sudo k3s kubectl create namespace donweb-lab \ --dry-run=client -o yaml | sudo k3s kubectl apply -f -
Guarda el siguiente contenido como web-demo.yaml. El Deployment ejecuta una réplica de nginx y el Service publica el puerto 80 del contenedor mediante el NodePort 30080.
apiVersion: apps/v1kind: Deploymentmetadata: name: web-demo namespace: donweb-labspec: replicas: 1 selector: matchLabels: app: web-demo template: metadata: labels: app: web-demo spec: containers: - name: nginx image: nginx:1.27-alpine ports: - name: http containerPort: 80 readinessProbe: httpGet: path: / port: http initialDelaySeconds: 3 periodSeconds: 5 resources: requests: cpu: 25m memory: 32Mi limits: cpu: 200m memory: 128Mi—apiVersion: v1kind: Servicemetadata: name: web-demo namespace: donweb-labspec: type: NodePort selector: app: web-demo ports: - name: http port: 80 targetPort: http nodePort: 30080
Alcance. La imagen nginx se fija a una rama menor para hacer la práctica repetible. En producción, usa una versión aprobada o un digest inmutable, escaneo de vulnerabilidades y una política de actualización.
Paso 6. Validar, aplicar y observar
Valida el manifiesto contra la API antes de persistirlo. kubectl diff devuelve código 1 cuando encuentra diferencias; eso no es un fallo del manifiesto, sino la indicación de que apply producirá cambios.
sudo k3s kubectl apply --dry-run=server -f web-demo.yamlsudo k3s kubectl diff -f web-demo.yaml
Si el dry-run termina sin error y el diff contiene solo los recursos esperados, aplica y espera el rollout.
sudo k3s kubectl apply -f web-demo.yamlsudo k3s kubectl rollout status deployment/web-demo -n donweb-lab --timeout=120ssudo k3s kubectl get pods,svc,endpoints -n donweb-lab -o widesudo k3s kubectl get events -n donweb-lab --sort-by=.metadata.creationTimestamp
El Pod debe estar 1/1 Ready. El Service debe mostrar NodePort 30080 y el recurso Endpoints debe contener la IP del Pod y el puerto 80. Un Service sin endpoints no tiene un destino saludable al cual enviar tráfico.
Paso 7. Autorizar y probar el acceso
Autoriza el puerto de demostración solo desde tu IP. Kubernetes puede programar reglas de red antes que UFW; por eso el firewall del proveedor debe ser el control perimetral principal y la exposición debe probarse desde una red externa.
sudo ufw allow from TU_IP_PUBLICA to any port 30080 proto tcp comment 'K3s demo'sudo ufw status numbered# Desde el propio servidor:curl -I http://127.0.0.1:30080# Desde la estación autorizada:curl -I http://IP_DEL_CLOUD_SERVER:30080
La respuesta esperada incluye HTTP/1.1 200 OK. Si funciona en localhost pero no desde el cliente, concentra el diagnóstico en el firewall del proveedor, UFW, la IP de destino y las rutas. Si falla también en localhost, revisa Service, Endpoints, Pod y logs.
Comprobación funcional completa
systemctl is-active k3s devuelve active.
kubectl get nodes muestra el nodo Ready.
Los Pods de kube-system están Running o Completed.
El Deployment web-demo informa Available=1 y el Pod está 1/1 Ready.
El Service tiene el NodePort 30080 y Endpoints contiene una dirección.
curl devuelve HTTP 200 desde el servidor y desde la IP externa autorizada.
Los eventos del namespace no muestran errores repetidos.
Rollback y limpieza de la prueba
Si una actualización futura del Deployment falla, consulta el historial y vuelve a la revisión anterior. La orden undo solo es útil cuando existe una revisión previa.
sudo k3s kubectl rollout history deployment/web-demo -n donweb-labsudo k3s kubectl rollout undo deployment/web-demo -n donweb-labsudo k3s kubectl rollout status deployment/web-demo -n donweb-lab
Para retirar exclusivamente la práctica, elimina el namespace y la regla del NodePort. Busca primero el número exacto de la regla, porque cambia según el servidor.
sudo k3s kubectl delete namespace donweb-labsudo ufw status numberedsudo ufw delete NUMERO_DE_REGLA
Peligro de pérdida de datos. No uses /usr/local/bin/k3s-uninstall.sh como limpieza rutinaria. El desinstalador detiene K3s y elimina el datastore local, datos de Persistent Volumes locales, configuración del nodo y herramientas instaladas. Haz backup y verifica su restauración antes de desinstalar.
Problemas frecuentes
El servicio k3s no inicia
Ejecuta sudo systemctl status k3s --no-pager y sudo journalctl -u k3s -n 200 --no-pager. Comprueba recursos, resolución DNS, acceso HTTPS y si otro proceso ocupa puertos locales necesarios.
El nodo permanece NotReady o los Pods de sistema están Pending
Revisa los eventos, las reglas para 10.42.0.0/16 y 10.43.0.0/16, y la carga del host. No abras UDP 8472 a Internet; en multinodo debe permitirse solo entre nodos.
Aparece ImagePullBackOff
Comprueba DNS y salida HTTPS desde el host, el nombre y tag de la imagen, y los eventos del Pod con sudo k3s kubectl describe pod NOMBRE -n donweb-lab.
El Service no responde
Verifica que el Pod esté Ready, que el selector app=web-demo coincida con sus etiquetas y que Endpoints no esté vacío. Si localhost responde y el cliente remoto no, revisa ambos firewalls y la IP pública.
kubectl devuelve permiso denegado
El kubeconfig administrativo se mantiene en modo 600. Usa sudo k3s kubectl en esta guía. Para equipos reales, crea accesos con certificados o identidades y RBAC; no distribuyas copias del kubeconfig system:admin.
Buenas prácticas para producción
No confundas un nodo único con alta disponibilidad. Planifica varios servers y un datastore soportado cuando la carga no tolere interrupciones.
Fija la versión de K3s y prueba las actualizaciones en un entorno equivalente antes de aplicarlas.
Restringe SSH, la API 6443 y los puertos de aplicaciones por IP de origen. Nunca expongas UDP 8472 a Internet.
Usa RBAC y credenciales individuales; protege y rota los kubeconfig administrativos.
Cifra Secrets en reposo, evita secretos en manifiestos versionados y usa un gestor de secretos cuando el riesgo lo justifique.
Define requests, limits, probes y políticas de seguridad para cada workload.
Supervisa capacidad, disponibilidad, eventos y logs; documenta umbrales y responsables de respuesta.
Prueba backups y restauraciones. Un snapshot sin ensayo de recuperación no demuestra que el servicio pueda volver.
Cloud Servers by Donweb
Acabas de levantar K3s en un solo nodo. Un nodo único no es alta disponibilidad.
Alojamiento ultra rápido, escalable y con alta disponibilidad.
- Performance que te sorprenderá
- Rápida escalabilidad y sin limitaciones
- Arquitectura de alta disponibilidad
- Soporte experto y ejecutivos de cuenta
- Pagos en tu moneda y facturación local
