vCluster Platform¶

Parte de la guía de implementación

Fase 5 — vCluster — pasos ejecutables. Requiere Fase 4 — GitOps (Dex, Gateway).

Complemento de profundización. vCluster Platform ofrece UI (interfaz de usuario) web, SSO (inicio de sesión único) vía Dex de ArgoCD y descarga de kubeconfig del management K3s (connected cluster) y de vclusters, sin depender solo de CLI (interfaz de línea de comandos).

Para qué sirve¶

Capacidad	Descripción
Clústeres virtuales	API Kubernetes aislada dentro del management K3s, sin levantar VMs Incus
UI web	Crear/borrar vclusters, ver estado, conectar desde navegador
SSO	Login OIDC vía Dex → GitHub (team `devops` de la org `symintel`); credenciales en 1Password
Kubeconfig	Download kubeconfig / Connect para el host K3s (connected cluster) y para cada vCluster

Sync manual — Application vcluster-platform (comentada en el ApplicationSet homelab-root: se activa a mano).

Componentes involucrados¶

Recurso	Para qué sirve
`vcluster-platform.yaml`	Application Helm que instala Loft Platform en `vcluster-platform`
`vcluster/values/platform.yaml`	HTTPRoute `vcluster.homelab.local` (`vcluster/route`), OIDC issuer → ArgoCD Dex
`argocd/config/dex.config`	Connector GitHub + OAuth client `vcluster-platform`
`argocd/secrets/1password.md`	Ítems 1Password → `argocd-secret`
`argocd-route`	Publica ArgoCD/Dex en `argocd.homelab.local` (ver GitOps)

Flujo de autenticación¶

sequenceDiagram
  participant U as Usuario
  participant VP as vcluster_homelab_local
  participant Dex as argocd_api_dex
  U->>VP: Login SSO
  VP->>Dex: OIDC authorize
  Dex->>U: GitHub OAuth
  Dex->>VP: token
  VP->>U: UI + kubeconfig

URL	Rol
`https://argocd.homelab.local`	ArgoCD UI; Dex issuer en `/api/dex`
`https://vcluster.homelab.local`	vCluster Platform UI

Implementación (resumen)¶

Sigue la Fase 4 — GitOps hasta completar OAuth Dex y el Gateway. Luego:

1. Secretos OAuth (paso 4.7 de la guía GitOps)¶

Ansible genera y aplica los secretos locales; en 1Password solo necesitas crear manualmente GITHUB_CLIENT_ID y GITHUB_CLIENT_SECRET:

cd ansible
ansible-playbook -i inventory.ini playbook-dex-oauth-secrets.yml
# Tras desplegar Platform (paso 2):
ansible-playbook -i inventory.ini playbook-dex-oauth-secrets.yml \
  --tags vcluster -e dex_oauth.apply_vcluster=true

2. Desplegar Platform¶

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

ArgoCD UI → vcluster-platform → Sync.

3. Validar SSO GitHub¶

Tras sync de argocd, login en ArgoCD o Platform debe ofrecer GitHub. Si falla, revisa el Redirect URIs de la OAuth App y el team symintel/devops en dex.config.

Con SSO estable, pon auth.password.disabled: true en platform.yaml.

4. /etc/hosts¶

<IP-del-Gateway>  argocd.homelab.local vcluster.homelab.local
192.168.20.6      incus.homelab.local

<IP-del-Gateway> es la IP que MetalLB le da al Gateway homelab; incus apunta siempre a invincible. Obtén la IP del Gateway:

kubectl get gateway homelab -n gateway -o jsonpath='{.status.addresses[0].value}'; echo

Uso diario¶

Abre https://vcluster.homelab.local
Login with SSO (GitHub) o admin local hasta deshabilitar password
New Virtual Cluster → nombre → Create
En el vcluster: Connect / Download kubeconfig
export KUBECONFIG=~/Downloads/kubeconfig.yaml y kubectl get nodes

Kubeconfig del management K3s (connected cluster)¶

El clúster host donde corre Platform aparece en Clusters como connected cluster. Mismo flujo SSO → Connect / Download kubeconfig. Sin Cluster Access explícito, el usuario autenticado no ve el clúster (denegar por defecto). Asigna permisos al usuario/equipo loft-* en la UI de Platform.

Alternativa sin web: fase-4-gitops.md 4.1.

CLI alternativa:

vcluster connect <nombre> -n <namespace>

vCluster vs CAPN¶

	vCluster Platform	CAPN
Auth	Dex ArgoCD + UI kubeconfig	Secret Incus sellado
Runtime	Pods en management K3s	Instancias Incus
RAM	Moderada (1 vcluster)	Alta por nodo kubeadm
Sync ArgoCD	manual	manual

vCluster vs CAPN

vCluster Platform

Pods en K3s; kubeconfig web; SSO Dex

Overhead por vcluster; permisos Platform

CAPN

Clusters kubeadm reales en Incus

Mucha RAM por nodo; secret Incus sellado

Kubeconfig web (Platform)

Sin scp; audit centralizado

Requiere Cluster Access explícito

scp / CLI

Funciona antes de Fase 5

Archivo local; sin SSO en el flujo

Dependencias¶

Deben estar Healthy antes de sync Platform:

openebs, homelab-storage (PVCs)
metallb, metallb-config, cert-manager-config y el controlador de Gateway (kong) (URLs HTTPS)
argocd-route, argocd (Dex + staticClient)