Si solo vas a ejecutar un blog, una base de datos y unos cuantos contenedores, la guía de configuración de producción de VPS con Docker Compose suele ser más directa. Elige K3s cuando necesites Helm, Ingress, Operators, actualizaciones graduales o quieras aprender la API de Kubernetes.

K3s recomienda oficialmente un mínimo de 1 núcleo de CPU y 512 MB de memoria, aconseja al menos 2 núcleos y 1 GB de memoria, y sugiere usar SSD. Sin embargo, esa cifra solo alcanza para el propio clúster y cargas de trabajo muy ligeras; para una compra real, parte de lo siguiente:

Si no estás seguro de la configuración, consulta primero Cómo elegir la configuración de un VPS. Este artículo usa como ejemplo Ubuntu 24.04 y un VPS KVM con IPv4 pública. Antes de instalar, confirma:

• El registro A del dominio ya apunta al VPS;
• TCP 80 y 443 están abiertos a Internet;
• Un solo nodo no necesita exponer 6443 a Internet; para la administración remota, prioriza una VPN o restringe las IP de origen;
• Con varios nodos, solo permite que los nodos accedan a TCP 6443, UDP 8472 y TCP 10250 por la red privada;
• UDP 8472 es el puerto VXLAN de Flannel y nunca debe abrirse a todo Internet.

Primero actualiza el sistema y comprueba si 80/443 están ocupados:

sudo apt update
sudo apt upgrade -y
sudo ss -lntup | grep -E ':(80|443|6443)\b' || true

Si Nginx, Caddy o contenedores Docker ya ocupan 80/443, el Traefik predeterminado no podrá enlazar los puertos. Primero usa la guía de diagnóstico de puertos ocupados en VPS para identificar el proceso; no mates directamente servicios desconocidos.

Usa el script de instalación oficial:

curl -sfL https://get.k3s.io | sh -

El instalador crea y habilita el servicio k3s, y también instala kubectl, crictl, ctr, un script de parada y un script de desinstalación. Comprueba el estado:

sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

El nodo debería estar en Ready, y los Pods de kube-system como CoreDNS, Traefik, metrics-server y local-path-provisioner deberían ir entrando en Running o Completed.

El kubeconfig de administrador está en /etc/rancher/k3s/k3s.yaml, con permisos predeterminados 600. Lo más seguro es seguir usando:

sudo k3s kubectl get nodes

Si necesitas ejecutar kubectl con tu cuenta personal, puedes copiar el kubeconfig y restringir los permisos:

mkdir -p "$HOME/.kube"
sudo cp /etc/rancher/k3s/k3s.yaml "$HOME/.kube/config"
sudo chown "$(id -u):$(id -g)" "$HOME/.kube/config"
chmod 600 "$HOME/.kube/config"
kubectl get nodes

No envíes el kubeconfig a herramientas de chat ni lo subas a Git; contiene credenciales de administrador del clúster.

Crea whoami.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami:latest
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 20m
              memory: 32Mi
            limits:
              cpu: 200m
              memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
spec:
  selector:
    app: whoami
  ports:
    - port: 80
      targetPort: 80

Aplica y comprueba:

kubectl apply -f whoami.yaml
kubectl rollout status deployment/whoami
kubectl get pods,svc

En producción, no uses a largo plazo una imagen latest flotante; fija una versión o un digest verificados.

K3s despliega Traefik de forma predeterminada, y ServiceLB usa los puertos 80/443 del host. Primero crea un Ingress HTTP:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: whoami
spec:
  ingressClassName: traefik
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: whoami
                port:
                  number: 80

kubectl apply -f ingress.yaml
kubectl get ingress
curl -I http://app.example.com

Traefik se encarga de la entrada HTTPS, pero el certificado lo debes proporcionar tú. Si ya tienes un certificado, puedes crear un Secret TLS:

kubectl create secret tls app-example-tls \
  --cert=fullchain.pem \
  --key=privkey.pem

Luego añádelo a spec del Ingress:

tls:
  - hosts:
      - app.example.com
    secretName: app-example-tls

Si necesitas emisión y renovación automáticas, puedes instalar cert-manager y luego crear un Issuer/ClusterIssuer ACME. No modifiques manualmente /var/lib/rancher/k3s/server/manifests/traefik.yaml; K3s restaura el contenido predeterminado al arrancar. Para personalizar Traefik, usa un HelmChartConfig adicional.

Si estás más familiarizado con un proxy inverso independiente, también puedes desactivar Traefik durante la instalación y consultar la guía de HTTPS automático con Caddy, pero debes indicar explícitamente --disable=traefik en la configuración de la primera instalación para evitar conflictos de puertos.

K3s incluye Local Path Provisioner, así que puedes crear PVC directamente:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi

kubectl apply -f pvc.yaml
kubectl get pvc,pv

local-path usa el disco local del nodo donde se ejecuta el Pod. Tras recrear el Pod, los datos suelen seguir ahí, pero si el nodo se daña de forma permanente, los datos no aparecerán automáticamente en otro nodo. Por lo tanto:

• Un solo nodo sirve para aplicaciones ligeras, pero es obligatorio hacer copias de seguridad en otra máquina;
• En bases de datos de varios nodos, no trates local-path como almacenamiento compartido o replicado;
• Cuando necesites persistencia entre nodos, evalúa Longhorn, CSI de disco en la nube o una base de datos gestionada externamente;
• Antes de escalar, confirma el modo de acceso, la topología y el proceso de recuperación del PVC.

Por defecto, un único nodo Server usa SQLite. Los requisitos oficiales son hacer copia de seguridad de:

• /var/lib/rancher/k3s/server/db/;
• /var/lib/rancher/k3s/server/token;
• Copias seguras de los manifiestos de aplicaciones, los values de Helm y los Secrets;
• Datos de negocio como local-path, bases de datos y archivos subidos por usuarios.

Para obtener una copia consistente, puedes detener K3s durante una ventana de mantenimiento y luego copiar la base de datos y el token:

sudo systemctl stop k3s
sudo tar -C /var/lib/rancher/k3s/server \
  -czf /root/k3s-control-plane-$(date +%F).tar.gz db token
sudo systemctl start k3s
sudo k3s kubectl get nodes

Una copia de seguridad del plano de control no equivale a una copia de los datos de negocio; el contenido de los PVC debe copiarse por separado a otra máquina o a un almacenamiento de objetos. Para una estrategia completa, consulta la guía de simulacros de copia de seguridad y recuperación en VPS.

Solo cuando uses etcd embebido debes seguir el proceso k3s etcd-snapshot; con el SQLite predeterminado de un solo nodo, no copies los comandos de snapshot de etcd. Sea cual sea el datastore, la recuperación requiere el token original del servidor; de lo contrario, los datos cifrados pueden quedar inutilizables.

En el Server, lee el token de unión:

sudo cat /var/lib/rancher/k3s/server/node-token

Ejecuta en el nuevo VPS:

curl -sfL https://get.k3s.io | \
  K3S_URL=https://SERVER_PRIVATE_IP:6443 \
  K3S_TOKEN='替换为真实Token' sh -

Cada máquina debe usar un hostname único. Después, comprueba en el Server:

sudo k3s kubectl get nodes -o wide

Añadir un Agent solo aumenta la capacidad de cómputo; no hace que el plano de control sea de alta disponibilidad. La HA real requiere varios nodos Server con etcd embebido o una base de datos externa, y también rediseñar el punto de entrada de carga y la persistencia.

Haz una copia de seguridad antes de actualizar y registra los parámetros de instalación originales. Oficialmente se admite actualizar volviendo a ejecutar el script de instalación con la misma configuración; si olvidas las variables de entorno o los parámetros originales, puedes perder la configuración. Los negocios estables también deben seguir la política de desfase de versiones de Kubernetes y no saltarse versiones menores intermedias.

Comandos habituales de diagnóstico:

kubectl get nodes
kubectl get pods -A -o wide
kubectl describe pod POD_NAME
kubectl logs POD_NAME --previous
sudo journalctl -u k3s -n 200 --no-pager
kubectl top nodes
kubectl top pods -A

• Pending: revisa solicitudes de CPU/memoria, PVC, taints y eventos de programación;
• CrashLoopBackOff: revisa los logs actuales, los logs de --previous, las variables de entorno y las comprobaciones de estado;
• Fallo de acceso al Ingress: revisa DNS, 80/443, grupos de seguridad, Pods de Traefik y el backend del Ingress;
• Nodo NotReady: revisa los logs de k3s/k3s-agent, la conectividad a 6443, la sincronización horaria y el firewall de Flannel;
• Métricas vacías: confirma que metrics-server está sano y permite TCP 10250 entre nodos.

Para la operación a largo plazo, puedes combinar con la solución de monitorización Prometheus + Grafana para observar nodos, Pods, discos y fechas de caducidad de certificados.

El comando de desinstalación de un nodo Server es:

sudo /usr/local/bin/k3s-uninstall.sh

Detiene K3s y elimina el datastore local del clúster, los datos de los PV de Local Storage, la configuración del nodo y los scripts relacionados. Antes de ejecutarlo, debes confirmar que tanto el plano de control como los datos de negocio se han verificado como recuperables en otra máquina; no es un comando normal de "detener el servicio".