Arquitectura en Kubernetes (K8s Multi-Node Cluster)

La implementación de Mañuti en Kubernetes (v1.31+) representa la cúspide de la alta disponibilidad, auto-curación y escalabilidad empresarial.

Esta guía documenta la construcción desde cero de un clúster nativo de 5 nodos con kubeadm y containerd, equipado con balanceador de carga de capa 2 (MetalLB), enrutamiento por dominios (NGINX Ingress Controller), certificados SSL automáticos (cert-manager), aprovisionamiento dinámico de discos por red (NFS Subdir External Provisioner) y el despliegue completo del ecosistema Mañuti dentro del namespace aislado manuti-v12.

1. Inventario del Clúster y Equivalencias de Arquitectura

Topología de Nodos (Ubuntu LTS)

2. Fase 1: Preparación de los 5 Nodos e Instalación de containerd y kubeadm

Ejecuta los siguientes bloques en todos los nodos del clúster (182 al 186):

2.1. Resolución de Nombres (/etc/hosts) y Desactivación de Swap

sudo tee -a /etc/hosts <<EOF
192.168.1.182 k8s-control
192.168.1.183 k8s-worker1
192.168.1.184 k8s-worker2
192.168.1.185 k8s-worker3
192.168.1.186 k8s-worker4
EOF

# Desactivar Swap permanentemente (Requisito estricto del Kubelet)
sudo swapoff -a && sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

2.2. Módulos de Kernel y Parámetros de Red (sysctl)

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

2.3. Instalar y Configurar containerd con SystemdCgroup = true

sudo apt-get update && sudo apt-get install -y ca-certificates curl gpg conntrack nfs-common
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update && sudo apt-get install -y containerd.io
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml
sudo systemctl restart containerd && sudo systemctl enable containerd

2.4. Instalar Binarios de Kubernetes (v1.31)

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

3. Fase 2: Inicialización del Control Plane, Red CNI, MetalLB e Ingress

Ejecuta estos pasos exclusivamente en k8s-control (192.168.1.182):

3.1. Inicializar Clúster y Configurar kubeconfig

sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=192.168.1.182

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# Instalar Red de Pods (Flannel CNI)
kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

(Ejecuta el comando sudo kubeadm join ... resultante en cada uno de los 4 nodos Workers y verifica con kubectl get nodes que todos estén en estado Ready).

3.2. Instalar MetalLB (Balanceador de Carga Bare-Metal)

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.5/config/manifests/metallb-native.yaml

# Definir el Pool de IPs Flotantes (metallb-config.yaml)
cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: first-pool
  namespace: metallb-system
spec:
  addresses:
  - 192.168.1.190-192.168.1.210
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: homelab-adv
  namespace: metallb-system
spec:
  ipAddressPools:
  - first-pool
EOF

3.3. Instalar NGINX Ingress Controller y cert-manager

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.11.1/deploy/static/provider/cloud/deploy.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml

4. Fase 3: Aprovisionador Dinámico de Almacenamiento NFS (StorageClass)

En el servidor NFS dedicado (192.168.1.97), exporta /srv/k8s/dev-storage 192.168.1.0/24(rw,sync,no_subtree_check,no_root_squash). Luego, en k8s-control, instala el NFS Subdir External Provisioner para que cree carpetas automáticamente cada vez que un Pod solicite un PersistentVolumeClaim (PVC):

kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/nfs-subdir-external-provisioner/master/deploy/rbac.yaml

cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nfs-client-provisioner
  namespace: default
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: nfs-client-provisioner
  template:
    metadata:
      labels:
        app: nfs-client-provisioner
    spec:
      serviceAccountName: nfs-client-provisioner
      containers:
        - name: nfs-client-provisioner
          image: registry.k8s.io/sig-storage/nfs-subdir-external-provisioner:v4.0.2
          volumeMounts:
            - name: nfs-client-root
              mountPath: /persistentvolumes
          env:
            - name: PROVISIONER_NAME
              value: k8s-sigs.io/nfs-subdir-external-provisioner
            - name: NFS_SERVER
              value: 192.168.1.97
            - name: NFS_PATH
              value: /srv/k8s/dev-storage
      volumes:
        - name: nfs-client-root
          nfs:
            server: 192.168.1.97
            path: /srv/k8s/dev-storage
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-desarrollo
provisioner: k8s-sigs.io/nfs-subdir-external-provisioner
parameters:
  archiveOnDelete: "false"
EOF

5. Fase 4: Despliegue Integral de Mañuti en el Namespace manuti-v12

5.1. Crear Namespace, Fijar Contexto y Secreto de Registro (ghcr.io)

kubectl create namespace manuti-v12
kubectl config set-context --current --namespace=manuti-v12

kubectl create secret docker-registry ghcr-secret \
  --docker-server=ghcr.io \
  --docker-username=manuelemiliano \
  --docker-password=TU_PAT_GITHUB \
  [email protected]

5.2. Reclamar los 5 Volúmenes Persistentes (manuti-storage.yaml)

Nota cómo assets-data-pvc utiliza ReadWriteMany (RWX) para que las 3 réplicas de PHP-FPM y el Gateway Nginx compartan la misma carpeta public/:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mariadb-data-pvc
  namespace: manuti-v12
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: nfs-desarrollo
  resources: { requests: { storage: 5Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: assets-data-pvc
  namespace: manuti-v12
spec:
  accessModes: ["ReadWriteMany"]
  storageClassName: nfs-desarrollo
  resources: { requests: { storage: 2Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: redis-data-pvc
  namespace: manuti-v12
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: nfs-desarrollo
  resources: { requests: { storage: 2Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mongo-data-pvc
  namespace: manuti-v12
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: nfs-desarrollo
  resources: { requests: { storage: 2Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minio-data-pvc
  namespace: manuti-v12
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: nfs-desarrollo
  resources: { requests: { storage: 2Gi } }

5.3. Jobs Autónomos de Inicialización (Migraciones, MinIO Buckets y Copia de Assets)

En Kubernetes no entramos manualmente a los contenedores a correr comandos iniciales; delegamos estas tareas a objetos Job que se ejecutan una sola vez hasta completarse:

# 1. JOB DE MIGRACIONES LARAVEL
apiVersion: batch/v1
kind: Job
metadata:
  name: manuti-migrate
  namespace: manuti-v12
spec:
  template:
    spec:
      imagePullSecrets: [{ name: ghcr-secret }]
      containers:
      - name: migrate
        image: ghcr.io/activemediacdmx/manuti:v12.00.03
        command: ["php", "artisan", "migrate", "--seed", "--force"]
        envFrom: [{ configMapRef: { name: manuti-config } }]
      restartPolicy: OnFailure
---
# 2. JOB DE AUTO-APROVISIONAMIENTO DE BUCKETS Y PERMISOS EN MINIO
apiVersion: batch/v1
kind: Job
metadata:
  name: minio-setup
  namespace: manuti-v12
spec:
  template:
    spec:
      restartPolicy: OnFailure
      containers:
      - name: minio-mc
        image: minio/mc
        command: ["/bin/sh", "-c"]
        args:
          - |
            until mc alias set local http://minio:9000 minioadmin tCT8H83o7U7Gm2; do sleep 2; done
            mc mb local/framedev-bucket || true
            echo -n '' | mc pipe local/framedev-bucket/avatars/.empty
            echo -n '' | mc pipe local/framedev-bucket/architecture/.empty
            mc anonymous set download local/framedev-bucket/avatars
            mc anonymous set download local/framedev-bucket/architecture
---
# 3. JOB DE POBLADO DE ASSETS PÚBLICOS AL VOLUMEN COMPARTIDO NFS
apiVersion: batch/v1
kind: Job
metadata:
  name: copy-manuti-assets
  namespace: manuti-v12
spec:
  template:
    spec:
      imagePullSecrets: [{ name: ghcr-secret }]
      containers:
      - name: copier
        image: ghcr.io/activemediacdmx/manuti:v12.00.03
        command: ["sh", "-c", "cp -rp /var/www/html/public/. /mnt/nfs-storage/ && echo 'Copia finalizada'"]
        resources:
          requests: { memory: "256Mi", cpu: "200m" }
          limits: { memory: "512Mi", cpu: "500m" }
        volumeMounts:
        - name: assets-data
          mountPath: /mnt/nfs-storage
      restartPolicy: OnFailure
      volumes:
      - name: assets-data
        persistentVolumeClaim: { claimName: assets-data-pvc }

5.4. Despliegue de Capa de Aplicación (Web 3 Réplicas, Worker Horizon, Reverb y Nginx Gateway)

Todos los Deployments de aplicación incluyen contratos estrictos de recursos (requests: 256Mi/200m, limits: 512Mi/500m) para evitar que un pico de memoria provoque un OOMKill que afecte al nodo:

# DEPLOYMENT PHP-FPM (3 RÉPLICAS) + SERVICE INTERNO
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: manuti-v12
spec:
  replicas: 3
  selector: { matchLabels: { app: web } }
  template:
    metadata: { labels: { app: web } }
    spec:
      imagePullSecrets: [{ name: ghcr-secret }]
      containers:
      - name: php-fpm
        image: ghcr.io/activemediacdmx/manuti:v12.00.03
        command: ["php-fpm"]
        resources:
          requests: { memory: "256Mi", cpu: "200m" }
          limits: { memory: "512Mi", cpu: "500m" }
        volumeMounts:
        - name: assets-data
          mountPath: /var/www/html/public
        envFrom: [{ configMapRef: { name: manuti-config } }]
      volumes:
      - name: assets-data
        persistentVolumeClaim: { claimName: assets-data-pvc }
---
apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: manuti-v12
spec:
  ports: [{ port: 9000, targetPort: 9000 }]
  selector: { app: web }

6. Protocolo de Mantenimiento: Apagado y Encendido Seguro del Clúster

Para apagar o reiniciar físicamente los servidores sin corromper la base de datos etcd ni los volúmenes NFS:

6.1. Secuencia de Apagado (Workers Primero → Control Plane al Final)

# 1. En k8s-control: Desalojar los Pods de cada Worker
kubectl drain k8s-worker1 --ignore-daemonsets --delete-emptydir-data

# 2. En cada Worker (por SSH): Detener servicios y apagar
sudo systemctl stop kubelet && sudo systemctl stop containerd && sudo shutdown -h now

# 3. Al final, apagar k8s-control

6.2. Secuencia de Encendido (Control Plane Primero → Workers Después)

# 1. Encender k8s-control y esperar a que responda 'kubectl get nodes'
# 2. Encender los 4 Workers
# 3. En k8s-control: Rehabilitar la programación de Pods en los Workers (Uncordon)
kubectl uncordon k8s-worker1 k8s-worker2 k8s-worker3 k8s-worker4