Arquitectura en Minikube (Laboratorio K8s Single-Node + Observabilidad)

Minikube permite ejecutar un clúster completo de Kubernetes dentro de un único servidor o máquina virtual de desarrollo (minikube.manu.ti), utilizando Docker como driver de virtualización y manteniendo 100% de compatibilidad con los manifiestos YAML de producción de Mañuti.

Esta guía incluye la configuración de almacenamiento persistente mediante Helm + CSI Driver for NFS, exposición de subdominios con Ingress Addon, túneles maestros para clientes de base de datos (Navicat) y monitoreo en tiempo real con Prometheus, Grafana y Loki.

1. Fase 1: Preparación del Host, Usuario Dedicado y Servidor NFS Local

Ejecuta estos pasos en tu servidor Ubuntu LTS (192.168.1.104):

1.1. Paquetes Base, Usuario manuti y Hostname

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl apt-transport-https ca-certificates software-properties-common

# Crear usuario dedicado de administración
sudo useradd -m -s /bin/bash manuti
echo "manuti:kls2qr824" | sudo chpasswd
sudo usermod -aG sudo manuti

# Configurar identidad de red
sudo hostnamectl set-hostname minikube.manu.ti

1.2. Configurar Servidor NFS Local (/srv/nfs/manuti-data)

Para que los PersistentVolumeClaims (PVCs) de MariaDB, MongoDB, Redis, MinIO y Assets funcionen igual que en producción:

sudo apt install -y nfs-kernel-server
sudo mkdir -p /srv/nfs/manuti-data
sudo chown -R nobody:nogroup /srv/nfs/manuti-data
sudo chmod -R 777 /srv/nfs/manuti-data

# Exportar con bandera 'insecure' (Requerida para puertos >1024 desde contenedores Minikube)
echo "/srv/nfs/manuti-data *(rw,sync,no_subtree_check,no_root_squash,insecure)" | sudo tee /etc/exports
sudo exportfs -fv
sudo systemctl restart nfs-kernel-server

2. Fase 2: Instalación de Docker Engine, kubectl, helm y minikube

2.1. Instalar Docker Engine y Asignar Permisos al Usuario manuti

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker manuti

2.2. Instalar kubectl, minikube y helm

# 1. Instalar kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

# 2. Instalar Minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# 3. Instalar Helm 3 (Gestor de paquetes de Kubernetes)
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | sudo bash

3. Fase 3: Arranque del Clúster, Addons y CSI Driver para NFS

Cambia a la sesión del usuario manuti (su - manuti o newgrp docker) y levanta el clúster:

# 1. Iniciar Minikube asignando recursos dedicados
minikube start --driver=docker --cpus=4 --memory=8192 --disk-size=80g

# 2. Habilitar Addons esenciales
minikube addons enable ingress
minikube addons enable ingress-dns
minikube addons enable metrics-server

# 3. Verificar estado del nodo
kubectl get nodes

3.1. Instalar el Controlador Oficial CSI para NFS vía Helm

helm repo add csi-driver-nfs https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts
helm repo update

helm install csi-driver-nfs csi-driver-nfs/csi-driver-nfs \
    --namespace kube-system \
    --version v4.9.0

3.2. Registrar la StorageClass (nfs-desarrollo)

cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-desarrollo
provisioner: nfs.csi.k8s.io
parameters:
  server: 192.168.1.104
  share: /srv/nfs/manuti-data
reclaimPolicy: Delete
volumeBindingMode: Immediate
mountOptions:
  - nfsvers=4.1
EOF

4. Fase 4: Despliegue Secuencial del Ecosistema Mañuti (manuti-v12)

4.1. Crear Namespace 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]

4.2. Regla de Ingress Multi-Dominio (manuti-ingress.yaml)

Enruta el tráfico hacia la aplicación web, la consola administrativa de MinIO y el CDN de objetos:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: manuti-v12-ingress
  namespace: manuti-v12
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
  rules:
  - host: web.minikube.manu.ti
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-externo
            port: { number: 80 }
  - host: minio.minikube.manu.ti
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: minio-externo
            port: { number: 9001 }
  - host: cdn.minio.minikube.manu.ti
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: minio-externo
            port: { number: 9000 }

4.3. Ejecución Ordenada de Manifiestos

# Fase 1 y 2: Configuración, PVCs y Motores de Datos
kubectl apply -f manuti-config.yaml
kubectl apply -f manuti-storage.yaml
kubectl apply -f manuti-dbs.yaml
kubectl apply -f manuti-acceso-externo.yaml

# Fase 3 y 4: Jobs de Inicialización y Servicios Backend (Reverb & Horizon)
kubectl apply -f manuti-migrate-job.yaml
kubectl apply -f manuti-minio-setup.yaml
kubectl apply -f manuti-reverb-service.yaml
kubectl apply -f manuti-reverb.yaml
kubectl apply -f manuti-worker.yaml

# Fase 5: Capa Web PHP-FPM, Copia de Assets, Gateway Nginx e Ingress
kubectl apply -f manuti-nginx-config.yaml
kubectl apply -f manuti-web-internal-svc.yaml
kubectl apply -f manuti-web.yaml
kubectl apply -f manuti-copy-assets-job.yaml
kubectl apply -f manuti-nginx-gateway.yaml
kubectl apply -f manuti-web-external-svc.yaml
kubectl apply -f manuti-ingress.yaml

5. Fase 5: Túneles de Acceso Externo (Web, Dashboard y Navicat)

Debido a que Minikube corre dentro de una red interna de Docker (192.168.49.2), exponemos el tráfico hacia la red LAN (192.168.1.104) mediante los siguientes puentes:

5.1. Túnel HTTP para el Ingress Controller (Acceso Web desde la LAN)

# Ejecutar en segundo plano en el servidor Ubuntu:
sudo nohup kubectl --kubeconfig=/home/manuti/.kube/config port-forward --address 0.0.0.0 -n ingress-nginx service/ingress-nginx-controller 80:80 > ingress.log 2>&1 &

(Permite acceder desde cualquier PC en la red a http://web.minikube.manu.ti y http://minio.minikube.manu.ti).

5.2. Túnel para el Dashboard Oficial de Minikube

nohup minikube dashboard --url > dashboard.log 2>&1 &
nohup kubectl proxy --address='0.0.0.0' --port=8001 --accept-hosts='^.*$' > proxy.log 2>&1 &

• URL de acceso: http://192.168.1.104:8001/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/

5.3. Túnel Maestro SSH para Bases de Datos (Desde Windows / Navicat)

Ejecuta este comando en el PowerShell de tu PC Windows para conectar clientes gráficos directamente a los NodePort internos de Minikube (192.168.49.2):

ssh -L 30306:192.168.49.2:30306 -L 30017:192.168.49.2:30017 -L 30379:192.168.49.2:30379 [email protected]

6. Fase 6: Observabilidad con Prometheus y Grafana (monitoring)

6.1. Instalación Ligera con Helm

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm install monitor prometheus-community/kube-prometheus-stack \
  --namespace monitoring --create-namespace \
  --set grafana.enabled=true \
  --set prometheus.enabled=true \
  --set alertmanager.enabled=false

6.2. Exponer Grafana vía Ingress (grafana-ingress.yaml)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana-ingress
  namespace: monitoring
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: monitor.minikube.manu.ti
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: monitor-grafana
            port: { number: 80 }

6.3. Obtener la Contraseña de admin de Grafana

kubectl get secret -n monitoring monitor-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo