Phase 5 — vCluster Platform (optional)

Objective

Web UI for virtual clusters and K3s management (connected cluster), with SSO (single sign-on) via Dex/GitHub and kubeconfig download from the browser.

What You Learn

A vCluster exposes a Kubernetes API isolated without lifting Incus VMs; vCluster Platform adds UI, SSO, and kubeconfig download from the browser.

Learn this phase

In simple terms: a vCluster is a department within a department: a virtual Kubernetes cluster, isolated, that lives inside another. Each team gets "its own cluster" without paying the cost of setting up a new one.

Key concepts

• Virtual cluster: an isolated Kubernetes API running as pods on the host cluster.
• Multi-tenancy: sharing the same infrastructure among teams without them seeing each other.
• Kubeconfig: the file that gives access to a cluster; the platform allows downloading it from the browser.
• SSO and OIDC (OpenID Connect): logging in with GitHub through Dex, without another password.

Practical challenge (read-only): read the login flow from Phase 4 and explain in your own words, in four steps, what happens when someone logs in with GitHub.

What advantage does a vCluster have over a full virtual machine?

It starts in seconds and uses fewer resources, because it shares the host's kernel and infrastructure.

What role does Dex play in login?

It acts as an intermediary: it receives the GitHub login and translates it to the applications (Argo CD, Platform, Incus).

Questions? Use the Learn with AI button next to each title, or the page Learn.

Stack for this phase

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 + virtual control plane; Phase 5.
• Dex — OIDC IdP (identity provider); configured in Phase 4.
• Gateway API — Exposes Platform on LAN (local network) with a HTTPRoute over the Gateway homelab.

Further reading: vCluster Platform

This decision in other environments

🏠 At home🏢 In a company☁️ In the cloud

vCluster Platform runs inside the same K3s management cluster: you create virtual clusters to test things without spinning up new VMs or using up the limited RAM. It is optional and its Sync is manual.

• Benefits: each team or customer gets its own cluster (its API, its CRDs, its admin permissions) without the company maintaining a real cluster for each one; ephemeral environments for each PR are created in seconds and deleted when closed, and access is centralized in the corporate SSO.
• Isolation: vClusters share nodes and kernel with the host cluster. For customers that do not trust each other, quotas, NetworkPolicies, and dedicated nodes are added, or separate clusters are maintained.
• Commercial support: vCluster is open source and vCluster Platform has an Enterprise plan with support, SLA, and security and compliance features.
• Permissions: instead of manually assigning cluster access, corporate IdP groups are mapped to projects and roles, and reviewed in access audits.
• When it makes sense like in a HomeLab: internal platforms with many small teams, test environments for PRs, and training labs, where a real cluster per team would be too costly.

Cloud	Equivalent service
GCP	GKE with fleet teams
AWS	Amazon EKS (tenant isolation)
Azure	AKS (cluster isolation)
Oracle Cloud (OCI)	OCI Kubernetes Engine (OKE)

In the cloud, the simple option is a cluster per team: strong isolation and SLA, but you pay for each control plane and multiply what needs to be updated. vCluster runs the same on any of them and reduces the number of real clusters, at the cost of weaker isolation and another piece to operate.

Before You Start

• Phase 4 — GitOps completed (Gateway, Dex, and OAuth secrets in 1Password).
• vcluster.homelab.local resolves (DNS from section 4.8 or, if not, /etc/hosts).

Run

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

🖱️ From the UI⌨️ From the console

Argo CD UI → Application vcluster-platform → Sync.

With the Argo CD CLI:

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

OAuth secrets (if not in 4.7): argocd/secrets/1password.md.

After sync of vcluster-platform, apply VCLUSTER_CLIENT_SECRET in Helm:

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

Options

Decision	Default HomeLab
Sync Argo CD	Manual (commented in homelab-root)
Admin login	auth.password.disabled: false until validating SSO GitHub
SSO user permissions	Deny by default — without Cluster Access / project assignment, no clusters or kubeconfig are visible

Trade-off analysis

Manual sync

Avoids accidental deletion of Platform

Extra step in Argo CD

Admin password enabled

Rescue access without GitHub

Attack surface if not disabled after SSO

GitHub SSO only

Single IdP; aligned with Dex

No login if Dex/GitHub are down

Web kubeconfig (Platform)

No scp; centralized permissions

Requires explicit Cluster Access assignment

CLI (vcluster connect)

Automatable in scripts

No SSO integrated in the flow

Permissions: deny by default

vCluster Platform does not grant access to connected clusters or vClusters just by logging in. A new SSO user does not see resources until an admin assigns:

• Cluster Access — management K3s kubeconfig (connected cluster)
• Project + role — create/manage vClusters within a project
• Management Role — platform operations (only for admins)

Typical steps for the first operator (as Platform admin):

1. Clusters → Cluster Access → Create → user/team + ClusterRole
2. For vClusters: assign the user to a Project with the appropriate role
3. GitHub teams arrive as groups loft-* (OIDC)

Verify

kubectl get pods -n vcluster-platform
curl -kI https://vcluster.homelab.local

1. Open https://vcluster.homelab.local
2. Login with SSO (GitHub)
3. New Virtual Cluster → Download kubeconfig

Management K3s kubeconfig

vCluster Platform automatically registers the host cluster (the K3s where Platform runs) as a connected cluster. From the same UI, you get the management cluster's kubeconfig, not just the vClusters'.

1. SSO login in https://vcluster.homelab.local
2. Clusters → select the host cluster (e.g., the K3s context name)
3. Connect / Download kubeconfig
4. export KUBECONFIG=~/Downloads/kubeconfig.yaml && kubectl get nodes

If you do not see the cluster or cannot download the kubeconfig, assign Cluster Access to the user or team in Platform. Without this assignment, SSO login works but no clusters or kubeconfig are visible (deny by default). GitHub OIDC groups arrive with prefix loft- (see platform.yaml).

HomeLab web access

Resource	URL	What you get
Management K3s	https://vcluster.homelab.local	Kubeconfig of the host K3s (connected cluster)
vClusters	https://vcluster.homelab.local	Kubeconfig of each virtual cluster
Incus cluster	https://incus.homelab.local:8443	Incus admin UI (OIDC after Phase 4)

Alternative CLI (command-line interface) for management K3s: fase-4-gitops.md 4.1 (ssh … sudo cat or Ansible).

If it fails

Symptom	Check
SSO loops back to login	Dex secrets + playbook-dex-oauth-secrets.yml --tags vcluster
PVC pending	OpenEBS/Longhorn Healthy

Next

Optional: → Phase 6 — CAPN (Cluster API Provider for Incus) · HomeLab Summary