Saltar a contenido

Fase 5 — vCluster Platform (opcional)

Objetivo

UI (interfaz de usuario) web para clústeres virtuales y el management K3s (distribución ligera de Kubernetes) (connected cluster), con SSO (inicio de sesión único) vía Dex/GitHub y descarga de kubeconfig desde el navegador.

Qué aprendes

Un vCluster expone una API (Application Programming Interface) Kubernetes aislada sin levantar VMs (máquinas virtuales) Incus; vCluster Platform añade UI, SSO y kubeconfig desde el navegador.

Stack de esta fase

flowchart TB
  User[Usuario] --> VP[vcluster_homelab_local]
  VP --> Dex[Dex_ArgoCD]
  Dex --> GH[GitHub]
  VP --> VC[vCluster_API]
  VC --> Mgmt[Pods_en_K3s_management]
  • vCluster Platform — UI + control plane virtual; Fase 5.
  • Dex — IdP OIDC (OpenID Connect); configurado en Fase 4.
  • Gateway API — Expone Platform en LAN (red local) con un HTTPRoute sobre el Gateway homelab.

Profundización: vCluster Platform

Antes de empezar

  • Fase 4 — GitOps completada (Gateway, Dex, OAuth 1Password).
  • /etc/hosts con vcluster.homelab.local.

Ejecutar

kubectl apply -f gitops/argocd/apps/vcluster-platform.yaml

Argo CD UI → Application vcluster-platform → Sync.

Secretos OAuth (si no en 4.7): argocd/secrets/1password.md.

Tras sync de vcluster-platform, aplica VCLUSTER_CLIENT_SECRET en Helm:

cd ansible
ansible-playbook -i inventory.ini playbook-dex-oauth-secrets.yml \
  --tags vcluster -e dex_oauth.apply_vcluster=true

Opciones

Decisión Default HomeLab
Sync ArgoCD Manual (comentada en homelab-root)
Login admin auth.password.disabled: false hasta validar SSO GitHub
Permisos usuarios SSO Denegar por defecto — sin Cluster Access / proyecto asignado no ven clústeres ni kubeconfig
Análisis de trade-offs
Sync manual
Evita borrado accidental de Platform
Paso extra en Argo CD
Admin password habilitado
Acceso de rescate sin GitHub
Superficie de ataque si no se deshabilita tras SSO
Solo SSO GitHub
Un solo IdP; alineado con Dex
Sin login si Dex/GitHub caen
Kubeconfig web (Platform)
Sin scp; permisos centralizados
Requiere asignar Cluster Access explícitamente
CLI (vcluster connect)
Automatizable en scripts
Sin SSO integrado en el flujo

Permisos: denegar por defecto

vCluster Platform no concede acceso a clústeres conectados ni vclusters solo por iniciar sesión. Un usuario SSO nuevo no ve recursos hasta que un admin le asigne:

  • Cluster Access — kubeconfig del management K3s (connected cluster)
  • Proyecto + rol — crear/gestionar vclusters dentro de un proyecto
  • Management Role — operaciones de plataforma (solo admins)

Pasos típicos para el primer operador (como admin de Platform):

  1. Clusters → Cluster Access → Create → usuario/equipo + ClusterRole
  2. Para vclusters: asignar al usuario a un Project con rol adecuado
  3. Los equipos de GitHub llegan como grupos loft-* (OIDC)

Verificar

kubectl get pods -n vcluster-platform
curl -kI https://vcluster.homelab.local
  1. Abre https://vcluster.homelab.local
  2. Login with SSO (GitHub)
  3. New Virtual Cluster → Download kubeconfig

Kubeconfig del management K3s

vCluster Platform registra automáticamente el clúster host (el K3s donde corre Platform) como connected cluster. Desde la misma UI obtienes el kubeconfig del management cluster, no solo el de vclusters.

  1. Login SSO en https://vcluster.homelab.local
  2. Clusters → selecciona el clúster host (p. ej. el nombre del contexto K3s)
  3. Connect / Download kubeconfig
  4. export KUBECONFIG=~/Downloads/kubeconfig.yaml && kubectl get nodes

Si no ves el clúster o no puedes descargar kubeconfig, asigna Cluster Access al usuario o equipo en Platform. Sin esa asignación, el login SSO funciona pero no hay clústeres ni kubeconfig visibles (denegar por defecto). Los grupos OIDC de GitHub llegan con prefijo loft- (ver platform.yaml).

Accesos web del HomeLab

Recurso URL Qué obtienes
Management K3s https://vcluster.homelab.local Kubeconfig del host K3s (connected cluster)
vClusters https://vcluster.homelab.local Kubeconfig de cada clúster virtual
Incus cluster https://incus.homelab.local:8443 UI de administración Incus (OIDC tras Fase 4)

Alternativa CLI (interfaz de línea de comandos) para el management K3s: fase-4-gitops.md 4.1 (scp / Ansible).

Si falla

Síntoma Revisar
SSO loop Secretos Dex + playbook-dex-oauth-secrets.yml --tags vcluster
PVC pending OpenEBS/Longhorn Healthy

Siguiente

Opcional: → Fase 6 — CAPN · Resumen del HomeLab