vCluster Platform¶

Part of the implementation guide

Phase 5 — vCluster — executable steps. Requires Phase 4 — GitOps (Dex, Gateway).

Deep dive supplement. vCluster Platform offers UI (web interface), SSO (single sign-on) via Argo CD Dex, and kubeconfig download for the management K3s (connected cluster) and vClusters, without relying solely on CLI.

What it does¶

Capability	Description
Virtual clusters	Isolated Kubernetes API within the management K3s, without lifting Incus VMs
Web UI	Create/delete vClusters, view status, connect from browser
SSO	Login OIDC via Dex → GitHub (team `devops` of org `maceosoft`); credentials in 1Password
Kubeconfig	Download kubeconfig / Connect for the host K3s (connected cluster) and for each vCluster

Sync manual — Application vcluster-platform (commented in the ApplicationSet homelab-root: manually activated).

Components involved¶

Resource	Purpose
`vcluster-platform.yaml`	Helm Application that installs Loft Platform in `vcluster-platform`
`vcluster/values/platform.yaml`	HTTPRoute `vcluster.homelab.local` (`vcluster/route`), OIDC issuer → Argo CD Dex
`argocd/config/dex.config`	GitHub connector + OAuth client `vcluster-platform`
`argocd/secrets/1password.md`	1Password items → `argocd-secret`
`argocd-route`	Publishes Argo CD/Dex in `argocd.homelab.local` (see GitOps)

Authentication flow¶

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	Role
`https://argocd.homelab.local`	Argo CD UI; Dex issuer in `/api/dex`
`https://vcluster.homelab.local`	vCluster Platform UI

Implementation (summary)¶

Follow the Phase 4 — GitOps until OAuth Dex and the Gateway are complete. Then:

1. OAuth Secrets (step 4.7 of the GitOps guide)¶

Ansible generates and applies the local secrets; manually create GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in 1Password:

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. Deploy Platform¶

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

🖱️ From the UI⌨️ From the console

Argo CD UI → vcluster-platform → Sync.

With the Argo CD CLI:

argocd login argocd.homelab.local --grpc-web
argocd app sync vcluster-platform

3. Validate GitHub SSO¶

After syncing argocd, login to Argo CD or Platform should offer GitHub. If it fails, check the Redirect URIs of the OAuth App and the team maceosoft/devops in dex.config.

With SSO established, put auth.password.disabled: true in platform.yaml.

4. DNS¶

vcluster.homelab.local and argocd.homelab.local are resolved by the LAN DNS (BIND in deborah) to the fixed IP of the Gateway, 192.168.23.200 (Phase 4 — 4.8). Use 192.168.20.5 as DNS; if not possible, the backup is /etc/hosts:

192.168.23.200  argocd.homelab.local vcluster.homelab.local
192.168.20.6    incus.homelab.local

Daily use¶

Open https://vcluster.homelab.local
Login with SSO (GitHub) or local admin until password is disabled
New Virtual Cluster → name → Create
In the vcluster: Connect / Download kubeconfig
export KUBECONFIG=~/Downloads/kubeconfig.yaml and kubectl get nodes

Kubeconfig of the management K3s (connected cluster)¶

The host cluster where Platform runs appears in Clusters as connected cluster. Same SSO flow → Connect / Download kubeconfig. Without Cluster Access explicitly granted, the authenticated user does not see the cluster (default deny). Grant permissions to the user/team loft-* in the Platform UI.

Alternative without web: fase-4-gitops.md 4.1.

CLI alternative:

vcluster connect <nombre> -n <namespace>

vCluster vs CAPN¶

	vCluster Platform	CAPN
Auth	Dex Argo CD + UI kubeconfig	Secret Incus sealed
Runtime	Pods in management K3s	Incus instances
RAM	Moderate (1 vcluster)	High per kubeadm node
Argo CD Sync	manual	manual

vCluster vs CAPN

vCluster Platform

Pods in K3s; web kubeconfig; SSO Dex

Overhead per vcluster; Platform permissions

CAPN

Real kubeadm clusters in Incus

High RAM per node; secret Incus sealed

Web kubeconfig (Platform)

No scp; centralized audit

Requires explicit Cluster Access

scp / CLI

Works before Phase 5

Local file; no SSO in the flow

Dependencies¶

Must be Healthy before syncing Platform:

openebs, homelab-storage (PVCs)
metallb, metallb-config, cert-manager-config and the Gateway controller (kong) (HTTPS URLs)
argocd-route, argocd (Dex + staticClient)