| name | console-dashboard |
| description | KubeStellar Console operations: deploy/upgrade via ArgoCD, auth and exposure policy, marketplace cards, guided missions, and the GitOps vs imperative action split. Use when working on the Console deployment or wiring dashboard surfaces.
|
KubeStellar Console — lab Skill
When to Use
- Deploying, upgrading, or recovering the Console
- Wiring new dashboard surfaces (marketplace cards, missions)
- Questions about auth, exposure, or which actions are GitOps vs imperative
When NOT to Use
- Public read-only status site →
astro-dashboard-pages/SKILL.md (the
Astro Pages site stays the reporting layer; Console is the control layer)
- BindingPolicy/WEC mechanics →
kubestellar/SKILL.md
- Grafana or another general-purpose admin/dashboard framework → do not add
one; Prometheus is a backend service, not a parallel UI
Architecture boundary
KubeStellar Console is the sole private cluster-admin and single-pane UI.
Astro remains public and read-only, and Prometheus remains backend-only. Target
the local ghost k3s topology (wds1, its1, and ghost as the WEC); do not
turn cloud or external multi-cluster possibilities into lab requirements.
Core Process
- Confirm the pinned Console chart version in
argocd/kubestellar-console-app.yaml.
- Verify dashboard IDs and Helm values against that exact upstream tag.
- Configure supported built-ins through
enabledDashboards; expose additional
cluster data through precise read-only Kubernetes API permissions.
- For node hardware and utilization surfaces, verify the dependency chain:
metrics-server API → Console
metrics.k8s.io RBAC, plus Node Feature
Discovery workers → feature.node.kubernetes.io/* labels on every node.
- Keep demo data and dynamic cards disabled, and make all desired-state
changes through Git for ArgoCD reconciliation.
- Run
just lint, client-side Kubernetes YAML/RBAC checks, and
git diff --check.
Deployment
ArgoCD Application argocd/kubestellar-console-app.yaml, continuously
reconciled through the GitOps-managed KubeStellar parent Application. Do not
apply it manually. The kubestellar-console chart comes from
https://kubestellar.github.io/console, pinned version. Namespace
kubestellar-console.
Lab-specific values (do not regress these):
persistence.accessModes: [ReadWriteOnce] + deployment.strategy.type: Recreate — local-path has no RWX; Recreate avoids the chart-documented
RWO RollingUpdate mount deadlock.backup.enabled: false — the chart's backup PVC hardcodes ReadWriteMany
which local-path cannot provision. DB protection belongs to the
storage/backup ADR (Velero, user-data-only).service.type: ClusterIP, ingress.enabled: false.clusterName: ghost and consoleProject: kubestellar.enabledDashboards: "dashboard,clusters,cluster-admin,deploy,compute,workloads,deployments,pods,services,nodes,events,gitops,helm,operators,security,storage,network" — restricts the sidebar to supported built-ins useful for local cluster administration. Do not enable demo or local-agent-only surfaces such as arcade or quantum.selfUpgrade.enabled: false and rbac.resourceQuotasReadOnly: true — keep
declarative upgrades and quota changes in Git instead of creating Console
mutations that ArgoCD immediately reverts.- Do not configure
kubeconfig.content for the single-cluster install. Chart
0.3.34 sets KUBECONFIG when it is present, which makes /health report
in_cluster: false and routes cards to local-agent/demo fallbacks instead of
the pod ServiceAccount-backed API.
Exposure and auth policy (locked, ADR-0003)
Dev-mode = anonymous cluster-admin. It NEVER ships exposed. Current access:
kubectl -n kubestellar-console port-forward svc/kubestellar-console 8080:8080
Before any ingress/Gateway exposure: create a GitHub OAuth app, store
client id/secret in a Secret referenced via github.existingSecret, keep
auth.allowedGitHubLogins / adminGitHubLogins tight. No exceptions.
Control model (dual-mode)
- GitOps actions: anything declarative — app installs, BindingPolicy
changes, manifest edits — go through PRs to this repo; ArgoCD syncs;
KubeStellar downsyncs. The Console links/renders state.
- Imperative actions: runtime operations — VM start/stop (KubeVirt
spec.running patch), workflow resubmit, pod logs/exec, rollout
actions — the Console performs directly via its ServiceAccount.
- Rule of thumb: if it should survive a cluster rebuild, it goes through
git; if it's an operation on live state, imperative is fine.
Surfaces
- Multi-cluster resource views cover CRDs generically: ArgoCD Applications,
Argo Workflows, KubeVirt VMs all appear as resources with status.
- The Console ServiceAccount's chart RBAC reads core resources only. Lab
surfaces come from
manifests/kubestellar-console-crd-read.yaml
(ClusterRole kubestellar-console-lab-surfaces, GitOps-managed): CRD
discovery + read on Argo/ArgoCD/KubeVirt/KubeStellar/OCM groups, plus the
imperative verbs listed below. If a surface shows "no resources", check
that ClusterRole before debugging the Console.
- Marketplace cards (kubestellar/console-marketplace) fill dedicated views
(GitOps, networking, security). Prefer a marketplace card over custom UI.
- Console 0.3.34 does not provision external dashboard/card JSON from files or
ConfigMaps. The supported contract is the built-in dashboard allowlist plus
live Kubernetes API resources. Keep
DISABLE_DYNAMIC_CARDS=true; do not add
declarative card JSON until the pinned Console release supports a real
Git-backed provisioning path.
Per-surface action wiring
| Surface | View in Console | Imperative (Console SA verb) | GitOps (PR to this repo) | Deep-dive fallback |
|---|
| ArgoCD apps | Applications CRD status | none — read-only by design | edit argocd/, manifests/, argo/workflow-templates/ | ArgoCD UI: kubectl -n argocd port-forward svc/argocd-server 8081:443 |
| Argo Workflows | Workflow/CronWorkflow CRDs | create workflows (resubmit/submit-from) | edit templates in argo/workflow-templates/ | Argo UI: kubectl -n argo port-forward svc/argo-server 2746:2746; argo logs |
| KubeVirt VMs | VirtualMachine CRDs | patch virtualmachines (spec.running start/stop/restart) | VM definitions in manifests/ | virtctl console / virtctl vnc |
| KubeStellar | ManagedClusters (its1 surfaces on host) | none | BindingPolicies in git, downsynced via wds1 | kubestellar/SKILL.md |
| Catalog apps | index at docs/data/catalog/*.json | install workflow (imperative mode) | install workflow (gitops mode, default capture) | registry-catalog skill (when it lands) |
| Host OS updates (bootc) | none — stays on the Astro Pages site (decision: lab update data already feeds Astro; no Console card duplication) | none | image/branch changes via factory repos | Astro dashboard, bluefin.io/* lanes |
| BuildStream builds | Workflow CRD status (dakota pipeline runs) | create workflows (rerun via submit-from) | pipeline templates in Git | BuildBarn/artifact-cache details remain available on Astro |
BindingPolicy note: the control.kubestellar.io CRDs live in wds1, not
the hosting cluster — kubectl auth can-i get bindingpolicies on ghost
correctly answers no. The Console reaches wds1 as a registered cluster.
- Missions (
kc-mission-v1): step sequences with yaml (one-click
apply) and command blocks; custom missions are shareable via built-in
PR flow. The "add your second PC" onboarding flow is committed as
missions/add-your-second-pc.json.
The Console v0.3.34 does not read custom missions from a ConfigMap/CRD yet;
import it via Missions > Local Files > Import. See
node-lifecycle/SKILL.md for the agent-executable version.
Failure modes
| Symptom | Cause / fix |
|---|
| Pod Pending, backups PVC Pending | backup re-enabled: its PVC is RWX-hardcoded; keep backup.enabled: false |
| New pod stuck ContainerCreating on upgrade | strategy reverted to RollingUpdate with RWO PVC; keep Recreate |
| Console shows sample data instead of ghost | remove chart kubeconfig values and verify /health reports in_cluster: true; clear the browser's stale kc-demo-mode/auth state once after rollout |
Browser reloads /login while APIs return token signature is invalid | the chart-generated JWT changed while the browser retained stale auth. Clear local-storage keys token, auth_token, kc_token, kc-auth-token, kc-has-session, and kc-demo-mode, plus the kc_auth and kc_ux_ctx cookies for the Console origin. The v0.3.34 logout request cannot recover because stale auth fails before its CSRF-protected cookie cleanup runs. |
CPU and memory monitors show zero although kubectl top nodes works | metrics-server is healthy, but the Console ServiceAccount cannot list nodes and pods in metrics.k8s.io; retain that scoped read permission in kubestellar-console-lab-surfaces |
| Hardware inventory has no PCI, storage, CPU, or kernel features | the cluster lacks Node Feature Discovery labels; keep the pinned node-feature-discovery ArgoCD Application healthy and require ready workers plus feature.node.kubernetes.io/* labels in acceptance |
| ArgoCD reports a duplicate-env ComparisonError | NO_LOCAL_AGENT was added to extraEnv; remove it because chart 0.3.34 emits it |
PVC migration hook is ImagePullBackOff on bitnami/kubectl:latest | retain the narrowly scoped kubestellar-console-pvc-migration-image admission policy; chart 0.3.34 hardcodes the image and offers no values override |
kubestellar-console-pvc-migration-image stays OutOfSync after a successful sync |
Common Rationalizations
| Rationalization | Reality |
|---|
| "A card JSON ConfigMap is declarative, so Console will discover it." | Console 0.3.34 has no such provisioning contract; use a supported built-in or Kubernetes API surface. |
| "The project preset is close enough." | It includes demo surfaces; set an explicit cluster-admin allowlist. |
| "Read access can use another wildcard." | Add only the API groups and resource plurals the surface actually queries. |
Red Flags
- External dashboard or card JSON claimed as automatically provisioned
arcade, quantum, or other demo/local-agent-only dashboards enabled- Invented Prometheus metrics without a live exporter
- Grafana or another general-purpose cluster-admin/dashboard framework
- Dev-mode Console exposed beyond a local port-forward
Verification
Sources
- KubeStellar Console v0.3.34 chart values:
deploy/helm/kubestellar-console/values.yaml
- KubeStellar Console v0.3.34 built-in project dashboards:
pkg/api/projects.go and web/src/config/routes.ts
- Context7
/kubestellar/kubestellar documents the WDS → ITS → WEC model but
has no Console library entry; verify Console behavior against the pinned
upstream tag instead.
- Context7
/kubernetes-sigs/node-feature-discovery documents the CPU, kernel,
memory, network, PCI, storage, system, and USB feature sources used by NFD.
Upgrade
Bump targetRevision in argocd/kubestellar-console-app.yaml via PR. Order:
KubeFlex/postgres → core-chart → Console. After upgrade verify pod
Running, / returns 200, auth still enforced.
