De Cero a Kubernetes Parte 5: Dos Frontends + Stack Completo

Serie: De Cero a Kubernetes — Parte 1 · Parte 2 · Parte 3 · Parte 4 · Parte 5

Llegaste a la última parte. Ya tienes un cluster Kubernetes real, TLS automático, GitOps con ArgoCD, PostgreSQL y un backend FastAPI corriendo con 2 réplicas. Solo falta lo que tus usuarios realmente ven: los frontends.

Vamos a desplegar dos aplicaciones independientes que consumen la misma API. Una es un dashboard administrativo (React + Vite). La otra es una app pública (Vue 3). Ambas empaquetadas con Docker, servidas con nginx para producción, y expuestas con ingress + TLS. Al final, haremos una prueba de integración completa.

Arquitectura final del stack completo

┌────────────────────────────────────────────────────────────┐
│                      INTERNET                               │
│                         │                                   │
│    ┌────────────────────┼────────────────────┐              │
│    │                    │                    │              │
│    ▼                    ▼                    ▼              │
│ ┌──────────┐    ┌──────────────┐    ┌──────────────┐       │
│ │ admin.   │    │ api.         │    │ app.         │       │
│ │tudominio │    │tudominio.com │    │tudominio.com │       │
│ │.com      │    │              │    │              │       │
│ └────┬─────┘    └──────┬───────┘    └──────┬───────┘       │
│      │                 │                   │               │
│      ▼                 ▼                   ▼               │
│ ┌──────────┐    ┌──────────────┐    ┌──────────────┐       │
│ │ React    │    │ FastAPI      │    │ Vue 3        │       │
│ │ Dashboard│───▶│ Backend      │◀───│ Landing Page │       │
│ │ (Vite)   │    │ (2 réplicas) │    │ (Vite)       │       │
│ └──────────┘    └──────┬───────┘    └──────────────┘       │
│                        │                                   │
│                        ▼                                   │
│               ┌────────────────┐                           │
│               │ PostgreSQL 16  │                           │
│               │ (CloudNativePG)│                           │
│               └────────────────┘                           │
│                                                            │
│ ☸️ Kubernetes (kubeadm + containerd + Calico)               │
│ 🌐 nginx ingress + cert-manager (Let's Encrypt TLS)        │
│ 🔄 ArgoCD — todo sincronizado desde GitHub                 │
└────────────────────────────────────────────────────────────┘

Parte A: Frontend #1 — Dashboard Administrativo (React + Vite)

Creamos el proyecto:

npm create vite@latest frontend-admin -- --template react-ts
cd frontend-admin
npm install

Lógica de la app: Un dashboard sencillo que consume GET /items del backend y los muestra en una tabla con estadísticas. Permite crear y eliminar items.

src/App.tsx (simplificado):

import { useEffect, useState } from 'react'

const API_URL = import.meta.env.VITE_API_URL || 'https://api.tudominio.com:30443'

interface Item {
  id: number
  name: string
  description: string
  created_at: string
}

export default function App() {
  const [items, setItems] = useState<Item[]>([])
  const [name, setName] = useState('')
  const [desc, setDesc] = useState('')
  const [loading, setLoading] = useState(true)
  const [dbStatus, setDbStatus] = useState('')

  useEffect(() => {
    fetch(`${API_URL}/health`)
      .then(r => r.json())
      .then(d => setDbStatus(d.db))
    loadItems()
  }, [])

  const loadItems = () => {
    fetch(`${API_URL}/items`)
      .then(r => r.json())
      .then(setItems)
      .finally(() => setLoading(false))
  }

  const createItem = async () => {
    await fetch(`${API_URL}/items`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name, description: desc })
    })
    setName('')
    setDesc('')
    loadItems()
  }

  const deleteItem = async (id: number) => {
    await fetch(`${API_URL}/items/${id}`, { method: 'DELETE' })
    loadItems()
  }

  return (
    <div className="dashboard">
      <header>
        <h1>📊 Dashboard Admin</h1>
        <span className={`status ${dbStatus === 'connected' ? 'ok' : 'err'}`}>
          DB: {dbStatus}
        </span>
      </header>

      <section className="create-form">
        <input value={name} onChange={e => setName(e.target.value)}
               placeholder="Nombre del item" />
        <input value={desc} onChange={e => setDesc(e.target.value)}
               placeholder="Descripción (opcional)" />
        <button onClick={createItem}>Crear Item</button>
      </section>

      <section className="items-table">
        <h2>Items ({items.length})</h2>
        {loading ? <p>Cargando...</p> : (
          <table>
            <thead><tr><th>ID</th><th>Nombre</th><th>Descripción</th><th>Creado</th><th></th></tr></thead>
            <tbody>
              {items.map(item => (
                <tr key={item.id}>
                  <td>{item.id}</td>
                  <td>{item.name}</td>
                  <td>{item.description}</td>
                  <td>{new Date(item.created_at).toLocaleString()}</td>
                  <td><button onClick={() => deleteItem(item.id)}>🗑️</button></td>
                </tr>
              ))}
            </tbody>
          </table>
        )}
      </section>
    </div>
  )
}

.env.production:

VITE_API_URL=https://api.tudominio.com

Parte B: Frontend #2 — Landing Pública (Vue 3)

npm create vite@latest frontend-app -- --template vue-ts
cd frontend-app
npm install

src/App.vue (simplificado):

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const API_URL = import.meta.env.VITE_API_URL || 'https://api.tudominio.com:30443'

const items = ref<any[]>([])
const loading = ref(true)
const form = ref({ name: '', description: '' })

const loadItems = async () => {
  const r = await fetch(`${API_URL}/items`)
  items.value = await r.json()
  loading.value = false
}

const createItem = async () => {
  await fetch(`${API_URL}/items`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(form.value)
  })
  form.value = { name: '', description: '' }
  loadItems()
}

onMounted(loadItems)
</script>

<template>
  <main class="landing">
    <h1>🚀 Guayoyo Items</h1>
    <p class="subtitle">Crea y comparte items al instante</p>

    <form @submit.prevent="createItem" class="create">
      <input v-model="form.name" placeholder="¿Qué quieres crear?" required />
      <textarea v-model="form.description" placeholder="Describe tu item..." rows="2" />
      <button type="submit">Crear</button>
    </form>

    <div class="grid">
      <div v-for="item in items" :key="item.id" class="card">
        <h3>{{ item.name }}</h3>
        <p>{{ item.description }}</p>
        <small>{{ new Date(item.created_at).toLocaleDateString() }}</small>
      </div>
    </div>
    <p v-if="loading">Cargando...</p>
  </main>
</template>

Parte C: Docker + nginx para producción

Ambos frontends usan exactamente el mismo patrón Docker multi-stage:

frontend-admin/Dockerfile (idéntico para ambos, solo cambia el nombre de la app):

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

frontend-admin/nginx.conf:

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    # SPA routing — todas las rutas van a index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache estática
    location ~* .(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Health check para Kubernetes
    location /health {
        return 200 "OK";
        add_header Content-Type text/plain;
    }
}

Build y push para ambos:

# Admin
docker build -t ghcr.io/tu-org/frontend-admin:v1.0.0 ./frontend-admin
docker push ghcr.io/tu-org/frontend-admin:v1.0.0

# App pública
docker build -t ghcr.io/tu-org/frontend-app:v1.0.0 ./frontend-app
docker push ghcr.io/tu-org/frontend-app:v1.0.0

Parte D: Manifiestos Kubernetes para ambos frontends

Ambos usan la misma estructura. Solo cambian la imagen, el host del ingress y la variable de API.

gitops/apps/frontend-app1/deployment.yaml (Dashboard Admin):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-admin
  namespace: production
spec:
  replicas: 2
  selector:
    matchLabels:
      app: frontend-admin
  template:
    metadata:
      labels:
        app: frontend-admin
    spec:
      containers:
        - name: nginx
          image: ghcr.io/tu-org/frontend-admin:v1.0.0
          ports:
            - containerPort: 80
          resources:
            requests:
              memory: "64Mi"
              cpu: "50m"
            limits:
              memory: "128Mi"
              cpu: "200m"
          livenessProbe:
            httpGet:
              path: /health
              port: 80
            initialDelaySeconds: 5
            periodSeconds: 15
          readinessProbe:
            httpGet:
              path: /health
              port: 80
            initialDelaySeconds: 3
            periodSeconds: 10

Service e Ingress para ambos:

# Service (idéntico, cambia name y selector)
apiVersion: v1
kind: Service
metadata:
  name: frontend-admin  # o frontend-app
  namespace: production
spec:
  selector:
    app: frontend-admin
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP

---
# Ingress (cambia host)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: frontend-admin
  namespace: production
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-production
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - admin.tudominio.com  # o app.tudominio.com
      secretName: admin-tls
  rules:
    - host: admin.tudominio.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend-admin
                port:
                  number: 80

Variables de entorno en build time:

Como estamos sirviendo estáticos con nginx, la URL de la API se inyecta en el build de Vite (VITE_API_URL). Esto significa que API_URL queda hardcodeada en el bundle de JavaScript. Es intencional: no necesitas runtime injection para valores que no cambian entre entornos.

Si quisieras runtime injection sin rebuild, usarías un ConfigMap montado en nginx que exponga un /config.js con window.__CONFIG__. Pero para este tutorial, el build-time injection es suficiente.

Parte E: ArgoCD sincroniza todo

Al hacer git push con los archivos de ambos frontends, ArgoCD detecta los nuevos directorios en gitops/apps/ automáticamente (gracias a directory.recurse: true en app-of-apps). La UI muestra:

🌳 app-of-apps
  ├── 🟢 database        (Healthy · Synced)
  ├── 🟢 backend         (Healthy · Synced)  2 pods
  ├── 🟢 frontend-app1   (Healthy · Synced)  2 pods
  └── 🟢 frontend-app2   (Healthy · Synced)  2 pods

Cuatro aplicaciones, dos réplicas cada una (excepto DB), TLS en todos los ingress. Todo desde un git push.

Parte F: Prueba de integración completa

1. Verificar que todo está verde

argocd app list
# NAME           HEALTH   STATUS
# database       Healthy  Synced
# backend        Healthy  Synced
# frontend-app1  Healthy  Synced
# frontend-app2  Healthy  Synced

2. Crear un item desde la app pública (Vue)

Abrimos https://app.tudominio.com, llenamos el formulario con “Café guayoyo” y creamos. El backend responde 201 Created.

3. Verlo en el dashboard admin (React)

Abrimos https://admin.tudominio.com. La tabla muestra:

ID	Nombre	Descripción	Creado
1	Café guayoyo	El mejor café de Caracas	2026-05-20, 10:15:00 AM

El dashboard también muestra DB: connected en verde.

4. Crear otro item desde el dashboard

Botón “Crear Item” → “Tequeños con guasacaca” → Enter.

5. Verificar que la app pública lo ve

Recargamos https://app.tudominio.com. Ahora hay 2 cards:

🚀 Guayoyo Items
Crea y comparte items al instante

┌──────────────────────┐  ┌──────────────────────────┐
│ Tequeños con         │  │ Café guayoyo             │
│ guasacaca            │  │                          │
│ El mejor acompañante │  │ El mejor café de Caracas │
│ 5/20/2026            │  │ 5/20/2026                │
└──────────────────────┘  └──────────────────────────┘

6. Borrar un item desde el dashboard

🗑️ en “Café guayoyo” → desaparece de ambas apps.

Rollback en acción

Imagina que la versión v1.1.0 del backend tiene un bug. Así se revierte:

# 1. Revertir el cambio en git
cd gitops
git revert HEAD --no-edit
git push

# 2. ArgoCD detecta el cambio y revierte el deployment
argocd app diff backend
# (muestra que la imagen volverá a v1.0.0)

# 3. Verificar
curl https://api.tudominio.com/health
# {"status":"ok","db":"connected"}

Tiempo total de rollback: lo que tardes en hacer git revert && git push. Menos de 30 segundos.

Si el rollback de urgencia no puede esperar el reconciliation loop (3 min), fuerzas el sync manual:

argocd app sync backend

Lo que construiste en estas 5 partes

Parte	Entregable
Parte 1	3 VMs Hetzner, kubeadm, containerd, Calico — cluster real
Parte 2	Namespaces, nginx ingress, cert-manager (TLS automático), storage, RBAC
Parte 3	ArgoCD, GitOps, app-of-apps, sync automático con selfHeal + prune
Parte 4	PostgreSQL con CloudNativePG, backend FastAPI con health checks y migraciones
Parte 5	Dos frontends (React + Vue, cada uno en su ingress con TLS), comunicación backend ↔ ambos

Stack tecnológico completo: Hetzner Cloud → Terraform → kubeadm → containerd → Calico → nginx ingress → cert-manager → ArgoCD → CloudNativePG → FastAPI → React → Vue → Docker → GitHub

Próximos pasos (por tu cuenta)

Lo que construiste es la base. Sobre esto puedes agregar:

CI con GitHub Actions: Build de Docker automático en cada push, push a registry, actualizar tag en repo GitOps
Monitoreo: Prometheus + Grafana (el operator kube-prometheus-stack se instala en 5 minutos)
Logs centralizados: Loki + Grafana (o Elastic Cloud on Kubernetes)
HA: Segunda instancia de PostgreSQL con replicación, múltiples control-planes
Service Mesh: Linkerd para mTLS automático entre servicios
Image Updater: ArgoCD Image Updater para auto-actualizar imágenes cuando hay nuevo tag
Secrets de verdad: Migrar de Secret en texto plano a SealedSecrets o ExternalSecrets + Vault

En Guayoyo Tech armamos arquitecturas completas como esta para empresas que necesitan infraestructura seria. Desde el Terraform que levanta las VMs hasta el último botón del dashboard React. Kubernetes, GitOps, CI/CD, monitoreo — todo integrado, documentado y con transferencia de conocimiento incluida. Habla con el equipo gratis 15 minutos y te mostramos cómo llevamos tu infraestructura al siguiente nivel.