feat(hami): add HAMi GPU virtualization system package (#2484)

## What this PR does

Documentation: https://github.com/cozystack/website/pull/517

Integrates [HAMi](https://github.com/Project-HAMi/HAMi) v2.8.1 (CNCF
Sandbox) into Cozystack as a system-level package for fractional GPU
sharing in tenant Kubernetes clusters.

The integration covers three layers:

- **System chart** (`packages/system/hami/`): Vendors upstream HAMi Helm
chart with device plugin, scheduler extender, mutating webhook, and
RuntimeClass configuration. The broken DRA subchart was removed — it
renders resources even when disabled and references unpublished images.

- **Kubernetes app addon** (`packages/apps/kubernetes/`): HAMi exposed
as an optional toggle (`hami.enabled`). Automatically disables GPU
Operator's native device plugin when active to avoid conflicts. Enforces
hard dependency on GPU Operator.

- **Platform registration** (`packages/core/platform/`): HAMi declared
as PackageSource with gpu-operator dependency, included in the iaas
bundle.

**Known limitation**: HAMi-core relies on a private glibc symbol
(`_dl_sym`) removed in glibc 2.34, which breaks compute isolation on
modern container images (Ubuntu 22.04+, PyTorch/TensorFlow official
images). Alpine/musl is entirely incompatible. See the package README
for details and upstream issue references.

### Screenshots

N/A — no UI changes.

### Release note

```release-note
feat(hami): add HAMi GPU virtualization as an optional system package for fractional GPU sharing. Enables memory and compute isolation for NVIDIA GPUs across tenant workloads. Integrates with GPU Operator and can be enabled per-cluster via the hami.enabled toggle. Note: compute isolation requires glibc < 2.34 in workload containers.
```

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added HAMi GPU virtualization middleware as an optional cluster addon
to enable fractional GPU sharing.
* HAMi addon includes an enable toggle (default: disabled) and a
customizable Helm values override; when enabled it enforces GPU Operator
presence and adjusts GPU Operator values accordingly.
* New HelmRelease integration for deploying HAMi with dependency
ordering and conditional rendering.

* **Documentation**
* Added HAMi setup guide, compatibility notes, and updated cluster addon
configuration reference.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,7 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-labels: 'bug'
+labels: 'kind/bug'
 assignees: ''
 
 ---

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,10 @@
 <!-- Thank you for making a contribution! Here are some tips for you:
 - Use Conventional Commits for the PR title: `type(scope): description`
   - Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
-  - Scopes for system components: dashboard, platform, cilium, kube-ovn, linstor, fluxcd, cluster-api
-  - Scopes for managed apps: postgres, mariadb, redis, kafka, clickhouse, virtual-machine, kubernetes
-  - Scopes for development and maintenance: api, hack, tests, ci, docs, maintenance
+  - Scopes are not an exhaustive list — pick the most specific scope for the change and extend the list when a genuinely new area appears. Examples:
+    - System components: dashboard, platform, operator, cilium, kube-ovn, linstor, fluxcd, cluster-api
+    - Managed apps: postgres, mariadb, redis, kafka, clickhouse, virtual-machine, kubernetes
+    - Development and maintenance: api, hack, tests, ci, docs, maintenance
   - Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREAKING CHANGE:` footer
 - If it's a work in progress, consider creating this PR as a draft.
 - Don't hesistate to ask for opinion and review in the community chats, even if it's still a draft.

.github/labels.yml

@@ -0,0 +1,371 @@
+# Cozystack repository labels
+#
+# Label conventions follow the Kubernetes scheme:
+# https://github.com/kubernetes/test-infra/blob/master/label_sync/labels.md
+#
+# Synced into the repository by .github/workflows/labels.yaml
+# (EndBug/label-sync@v2). Edit this file via pull request — UI changes
+# will be overwritten on the next sync.
+#
+# Constraints (enforced by the validate job in labels.yaml):
+#   - description ≤ 100 characters (GitHub REST API limit)
+#   - color is a 6-character hex string (no leading #)
+#   - label names are unique
+#   - aliases do not collide with top-level names
+#
+# Categories:
+#   kind/         issue or PR type
+#   priority/     urgency
+#   triage/       review state
+#   lifecycle/    issue or PR lifecycle
+#   area/         subsystem; extensible — add when 3+ open issues exist
+#   do-not-merge/ PR merge blockers
+#   security/     security-finding severity and status (Cozystack-specific)
+#   size:         PR size (auto-applied)
+#
+# `aliases:` lets EndBug/label-sync rename existing labels without losing
+# references on already-tagged issues and PRs.
+#
+# GitHub-default labels not migrated here (`wontfix`, `invalid`) currently
+# carry zero issues/PRs in this repo and will be removed in a follow-up
+# cleanup PR rather than aliased to a different namespace.
+
+# ──────────────────────────────────────────────
+# kind/ — issue or PR type
+# ──────────────────────────────────────────────
+
+- name: kind/bug
+  color: 'd73a4a'
+  description: Categorizes issue or PR as related to a bug
+  aliases: ['bug']
+
+- name: kind/feature
+  color: 'a2eeef'
+  description: Categorizes issue or PR as related to a new feature
+  aliases: ['enhancement']
+
+- name: kind/documentation
+  color: '0075ca'
+  description: Categorizes issue or PR as related to documentation
+  aliases: ['documentation']
+
+- name: kind/support
+  color: 'd876e3'
+  description: Categorizes issue as a support question
+  aliases: ['question']
+
+- name: kind/cleanup
+  color: 'c7def8'
+  description: Categorizes issue or PR as related to cleanup of code, process, or technical debt
+
+- name: kind/regression
+  color: 'e11d21'
+  description: Categorizes issue or PR as related to a regression from a prior release
+
+- name: kind/flake
+  color: 'f7c6c7'
+  description: Categorizes issue or PR as related to a flaky test
+
+- name: kind/failing-test
+  color: 'e11d21'
+  description: Categorizes issue or PR as related to a consistently or frequently failing test
+
+- name: kind/api-change
+  color: 'c7def8'
+  description: Categorizes issue or PR as related to adding, removing, or otherwise changing an API
+
+- name: kind/breaking-change
+  color: 'e11d21'
+  description: Indicates the change introduces a breaking API or behaviour change
+
+# ──────────────────────────────────────────────
+# priority/ — urgency
+# ──────────────────────────────────────────────
+
+- name: priority/critical-urgent
+  color: 'e11d21'
+  description: Highest priority. Must be actively worked on as someone's top priority right now
+
+- name: priority/important-soon
+  color: 'eb6420'
+  description: Must be staffed and worked on either currently, or very soon, ideally in time for the next release
+
+- name: priority/important-longterm
+  color: 'fbca04'
+  description: Important over the long term, but may not be staffed and/or may need multiple releases to complete
+
+- name: priority/backlog
+  color: 'fef2c0'
+  description: General backlog priority. Lower than priority/important-longterm
+
+# ──────────────────────────────────────────────
+# triage/ — review state
+# ──────────────────────────────────────────────
+
+- name: triage/needs-triage
+  color: 'ededed'
+  description: Indicates an issue needs triage by a maintainer
+
+- name: triage/accepted
+  color: '0e8a16'
+  description: Indicates an issue is ready to be actively worked on
+
+- name: triage/needs-information
+  color: 'fbca04'
+  description: Indicates an issue needs more information in order to work on it
+
+- name: triage/not-reproducible
+  color: 'fbca04'
+  description: Indicates an issue can not be reproduced as described
+
+- name: triage/duplicate
+  color: 'cfd3d7'
+  description: Indicates an issue is a duplicate of another issue
+  aliases: ['duplicate']
+
+- name: triage/unresolved
+  color: 'cfd3d7'
+  description: Indicates an issue that can not or will not be resolved
+
+# ──────────────────────────────────────────────
+# lifecycle/ — issue or PR lifecycle
+# ──────────────────────────────────────────────
+
+- name: lifecycle/active
+  color: '1d76db'
+  description: Indicates that an issue or PR is actively being worked on by a contributor
+
+- name: lifecycle/frozen
+  color: 'db5dd6'
+  description: Indicates that an issue or PR should not be auto-closed due to staleness
+  aliases: ['frozen']
+
+- name: lifecycle/stale
+  color: 'dadada'
+  description: Denotes an issue or PR has remained open with no activity and has become stale
+  aliases: ['stale']
+
+- name: lifecycle/rotten
+  color: '795548'
+  description: Denotes an issue or PR that has aged beyond stale and will be auto-closed
+
+# ──────────────────────────────────────────────
+# area/ — subsystem (extensible)
+# Add a new area/* when there are 3+ open issues on the topic.
+# ──────────────────────────────────────────────
+
+- name: area/api
+  color: 'bfd4f2'
+  description: Issues or PRs related to the cozystack-api aggregated API server
+
+- name: area/ai
+  color: 'bfd4f2'
+  description: Issues or PRs related to AI agent guides, AGENTS.md, docs/agents/
+
+- name: area/build
+  color: 'bfd4f2'
+  description: Issues or PRs related to image build infrastructure, multi-arch support
+
+- name: area/ci
+  color: 'bfd4f2'
+  description: Issues or PRs related to CI workflows, GitHub Actions, automation
+
+- name: area/dashboard
+  color: 'bfd4f2'
+  description: Issues or PRs related to the dashboard / UI
+
+- name: area/extra
+  color: 'bfd4f2'
+  description: Issues or PRs related to tenant-specific modules (packages/extra/)
+
+- name: area/database
+  color: 'bfd4f2'
+  description: Issues or PRs related to managed databases (postgres, mariadb, redis, etcd, kafka, clickhouse)
+
+- name: area/kubernetes
+  color: 'bfd4f2'
+  description: Issues or PRs related to the tenant Kubernetes app
+
+- name: area/monitoring
+  color: 'bfd4f2'
+  description: Issues or PRs related to the monitoring stack (vlogs, vmstack, grafana, workloadmonitor)
+
+- name: area/networking
+  color: 'bfd4f2'
+  description: Issues or PRs related to networking (ingress, gateway, vpn, metallb, cilium, kube-ovn)
+
+- name: area/platform
+  color: 'bfd4f2'
+  description: Issues or PRs related to platform infrastructure (bundle, flux, talos, installer)
+
+- name: area/release
+  color: 'bfd4f2'
+  description: Issues or PRs related to release tooling (changelog, backport, release pipeline)
+
+- name: area/storage
+  color: 'bfd4f2'
+  description: Issues or PRs related to storage (linstor, seaweedfs, bucket, velero, harbor)
+
+- name: area/testing
+  color: 'bfd4f2'
+  description: Issues or PRs related to testing (e2e, bats, unit tests)
+
+- name: area/virtualization
+  color: 'bfd4f2'
+  description: Issues or PRs related to virtualization (kubevirt, cdi, vmi, vm-import)
+
+- name: area/uncategorized
+  color: 'fbca04'
+  description: PR auto-labeler could not map title scope to a known area/*; please review
+
+# ──────────────────────────────────────────────
+# do-not-merge/ — PR merge blockers (Prow convention)
+# ──────────────────────────────────────────────
+
+- name: do-not-merge/work-in-progress
+  color: 'e11d21'
+  description: Indicates that a PR should not merge because it is a work in progress
+  # Both legacy spellings collapse here. EndBug processes aliases sequentially;
+  # the second rename hits a name collision and logs a warning — the legacy
+  # label survives and gets cleaned up in the follow-up dedup PR.
+  aliases: ['do-not-merge', 'do not merge']
+
+- name: do-not-merge/hold
+  color: 'e11d21'
+  description: Indicates that a PR should not merge because someone has issued /hold
+
+# ──────────────────────────────────────────────
+# Cozystack-specific (preserved)
+# ──────────────────────────────────────────────
+
+- name: epic
+  color: 'a335ee'
+  description: A large development increment that brings definite value to Cozystack users
+
+- name: community
+  color: '97458a'
+  description: Community contributions are welcome in this issue
+
+- name: help wanted
+  color: '008672'
+  description: Extra attention is needed
+
+- name: good first issue
+  color: '7057ff'
+  description: Good for newcomers
+
+- name: quality-of-life
+  color: 'aaaaaa'
+  description: QoL improvements
+
+- name: upstream-issue
+  color: 'aaaaaa'
+  description: Requires resolving an issue in an upstream project
+
+- name: backport
+  color: 'fbca04'
+  description: Should change be backported on previous release
+
+- name: backport-previous
+  color: 'fbd876'
+  description: Backport target — previous release line
+
+- name: release
+  color: 'aaaaaa'
+  description: Releasing a new Cozystack version
+
+- name: automated
+  color: 'ededed'
+  description: Created by automation
+
+- name: debug
+  color: '704479'
+  description: Debugging in progress
+
+- name: sponsored
+  color: '00ff00'
+  description: Sponsored work
+
+- name: lgtm
+  color: '238636'
+  description: This PR has been approved by a maintainer
+
+- name: ok-to-test
+  color: '00ff00'
+  description: Indicates a non-member PR is safe to run CI on
+
+# ──────────────────────────────────────────────
+# size: — PR size (auto-applied by sizing bot)
+# ──────────────────────────────────────────────
+
+- name: 'size:XS'
+  color: '00ff00'
+  description: This PR changes 0-9 lines, ignoring generated files
+
+- name: 'size:S'
+  color: '77b800'
+  description: This PR changes 10-29 lines, ignoring generated files
+
+- name: 'size:M'
+  color: 'ebb800'
+  description: This PR changes 30-99 lines, ignoring generated files
+
+- name: 'size:L'
+  color: 'eb9500'
+  description: This PR changes 100-499 lines, ignoring generated files
+
+- name: 'size:XL'
+  color: 'ff823f'
+  description: This PR changes 500-999 lines, ignoring generated files
+
+- name: 'size:XXL'
+  color: 'ffb8b8'
+  description: This PR changes 1000+ lines, ignoring generated files
+
+# ──────────────────────────────────────────────
+# security/ — security-finding severity and status
+# ──────────────────────────────────────────────
+
+- name: security
+  color: 'aaaaaa'
+  description: Security-related issues and features
+
+- name: security/critical
+  color: 'd73a4a'
+  description: Critical security vulnerability
+
+- name: security/high
+  color: 'e99695'
+  description: High severity security finding
+
+- name: security/medium
+  color: 'f9c513'
+  description: Medium severity security finding
+
+- name: security/low
+  color: '0e8a16'
+  description: Low severity security finding
+
+- name: security/triage-needed
+  color: 'fbca04'
+  description: Needs security triage
+
+- name: security/confirmed
+  color: '1d76db'
+  description: Confirmed vulnerability
+
+- name: security/false-positive
+  color: 'c5def5'
+  description: Triaged as false positive
+
+- name: security/accepted-risk
+  color: 'bfd4f2'
+  description: Risk accepted with justification
+
+- name: security/in-progress
+  color: '0075ca'
+  description: Fix in progress
+
+- name: security/fixed
+  color: '0e8a16'
+  description: Fix released

.github/workflows/codegen-drift.yml

@@ -0,0 +1,61 @@
+name: Codegen Drift Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'api/**'
+      - 'pkg/apis/**'
+      - 'pkg/generated/**'
+      - 'internal/crdinstall/manifests/**'
+      - 'packages/system/cozystack-controller/definitions/**'
+      - 'packages/system/application-definition-crd/definition/**'
+      - 'packages/system/backup-controller/definitions/**'
+      - 'packages/system/backupstrategy-controller/definitions/**'
+      - 'hack/update-codegen.sh'
+      - 'hack/boilerplate.go.txt'
+      - 'Makefile'
+      - 'go.mod'
+      - 'go.sum'
+      - '.github/workflows/codegen-drift.yml'
+
+concurrency:
+  group: codegen-drift-${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  codegen-drift:
+    name: Verify generated code is up to date
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Pre-fetch k8s.io/code-generator module
+        # hack/update-codegen.sh sources kube_codegen.sh from the Go module cache.
+        # The module is not declared in go.mod, so fetch it explicitly at the
+        # version pinned in the script.
+        run: |
+          version=$(grep -oP 'code-generator@\Kv[0-9.]+' hack/update-codegen.sh)
+          tmpdir=$(mktemp -d)
+          cd "$tmpdir"
+          go mod init codegen-fetch
+          go get "k8s.io/code-generator@${version}"
+
+      - name: Run make generate
+        run: make generate
+
+      - name: Fail on drift
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error::'make generate' produced changes. Run 'make generate' locally and commit the result."
+            git status --short
+            git diff --color=always
+            exit 1
+          fi

.github/workflows/labels.yaml

@@ -0,0 +1,84 @@
+name: Labels
+
+on:
+  pull_request:
+    paths:
+      - .github/labels.yml
+      - .github/workflows/labels.yaml
+  push:
+    branches: [main]
+    paths:
+      - .github/labels.yml
+      - .github/workflows/labels.yaml
+  workflow_dispatch:
+  schedule:
+    - cron: '17 4 * * 1'  # Mondays at 04:17 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: labels-sync
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate labels.yml schema
+        run: |
+          python3 - <<'PY'
+          import re, sys, yaml
+
+          path = '.github/labels.yml'
+          data = yaml.safe_load(open(path))
+          errors = []
+
+          # 1. description ≤ 100 chars (GitHub REST API limit)
+          for label in data:
+              desc = label.get('description', '') or ''
+              if len(desc) > 100:
+                  errors.append(f"{label['name']}: description {len(desc)} chars (max 100)")
+
+          # 2. color is 6-char hex without leading #
+          for label in data:
+              color = label.get('color', '') or ''
+              if not re.match(r'^[0-9A-Fa-f]{6}$', color):
+                  errors.append(f"{label['name']}: bad color {color!r} (must be 6-char hex without #)")
+
+          # 3. unique top-level names
+          names = [label['name'] for label in data]
+          dups = sorted({n for n in names if names.count(n) > 1})
+          for n in dups:
+              errors.append(f"duplicate name: {n}")
+
+          # 4. aliases do not collide with any top-level name
+          name_set = set(names)
+          for label in data:
+              for alias in (label.get('aliases') or []):
+                  if alias in name_set:
+                      errors.append(f"alias {alias!r} (under {label['name']!r}) collides with a top-level name")
+
+          if errors:
+              for err in errors:
+                  print(f"::error::{err}")
+              sys.exit(1)
+
+          print(f"labels.yml schema OK ({len(data)} labels)")
+          PY
+
+  sync:
+    needs: validate
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: EndBug/label-sync@v2
+        with:
+          config-file: .github/labels.yml
+          delete-other-labels: false

.github/workflows/pr-labeler.yaml

@@ -0,0 +1,206 @@
+name: PR Auto-Label
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Apply labels from PR title
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // Conventional Commits types accepted by Cozystack (per docs/agents/contributing.md):
+            //   feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+            // Mapping below maps a subset to kind/* — types not listed do not produce a kind/*.
+            const typeToKind = {
+              feat:     'kind/feature',
+              fix:      'kind/bug',
+              docs:     'kind/documentation',
+              chore:    'kind/cleanup',
+              refactor: 'kind/cleanup',
+              // style, perf, test, build, ci, revert — no kind mapping
+            };
+
+            // scope -> area/* mapping. Keys are the scopes observed in cozystack issues
+            // and PRs. Add new entries when a scope recurs (3+ times).
+            const scopeToArea = {
+              // area/api
+              'api':                 'area/api',
+              'cozystack-api':       'area/api',
+
+              // area/ai
+              'agents':              'area/ai',
+              'ai':                  'area/ai',
+
+              // area/build
+              'build':               'area/build',
+
+              // area/ci
+              'ci':                  'area/ci',
+
+              // area/dashboard
+              'dashboard':           'area/dashboard',
+
+              // area/database
+              'postgres':            'area/database',
+              'postgres-operator':   'area/database',
+              'mariadb':             'area/database',
+              'mariadb-operator':    'area/database',
+              'redis':               'area/database',
+              'etcd':                'area/database',
+              'kafka':               'area/database',
+              'clickhouse':          'area/database',
+
+              // area/extra
+              'extra':               'area/extra',
+
+              // area/kubernetes
+              'kubernetes':          'area/kubernetes',
+              'apps/kubernetes':     'area/kubernetes',
+
+              // area/monitoring
+              'monitoring':          'area/monitoring',
+              'vlogs':               'area/monitoring',
+              'vmstack':             'area/monitoring',
+              'grafana':             'area/monitoring',
+              'workloadmonitor':     'area/monitoring',
+
+              // area/networking
+              'ingress':             'area/networking',
+              'ingress-nginx':       'area/networking',
+              'gateway':             'area/networking',
+              'vpn':                 'area/networking',
+              'metallb':             'area/networking',
+              'cilium':              'area/networking',
+              'kube-ovn':            'area/networking',
+              'tcp-balancer':        'area/networking',
+              'securitygroups':      'area/networking',
+              'cozy-proxy':          'area/networking',
+
+              // area/platform
+              'platform':            'area/platform',
+              'bundle':              'area/platform',
+              'flux':                'area/platform',
+              'fluxcd':              'area/platform',
+              'cluster-api':         'area/platform',
+              'talos':               'area/platform',
+              'installer':           'area/platform',
+              'cozyctl':             'area/platform',
+              'cozystack-engine':    'area/platform',
+              'cozy-lib':            'area/platform',
+
+              // area/release
+              'backport':            'area/release',
+              'release':             'area/release',
+
+              // area/storage
+              'seaweedfs':           'area/storage',
+              'seaweedfs-cosi-driver': 'area/storage',
+              'bucket':              'area/storage',
+              'linstor':             'area/storage',
+              'velero':              'area/storage',
+              'harbor':              'area/storage',
+              'backups':             'area/storage',
+
+              // area/testing
+              'tests':               'area/testing',
+              'e2e':                 'area/testing',
+
+              // area/virtualization
+              'kubevirt':            'area/virtualization',
+              'cdi':                 'area/virtualization',
+              'vmi':                 'area/virtualization',
+              'vm-import':           'area/virtualization',
+              'virtual-machine':     'area/virtualization',
+              'hami':                'area/virtualization',
+              'gpu-operator':        'area/virtualization',
+            };
+
+            const pr = context.payload.pull_request;
+            const title = pr.title || '';
+            const body  = pr.body  || '';
+            const existing = new Set((pr.labels || []).map(l => l.name));
+            const toAdd = new Set();
+
+            // 1. Strip "[Backport release-1.x]" prefix if present.
+            const backportMatch = title.match(/^\[Backport ([^\]]+)\]\s+(.+)$/);
+            const cleanTitle = backportMatch ? backportMatch[2] : title;
+            if (backportMatch) {
+              toAdd.add('area/release');
+              toAdd.add('backport');
+            }
+
+            // 2. Try Conventional Commits form: type(scope)?(!)?: description
+            const conv = cleanTitle.match(/^([a-z]+)(?:\(([^)]+)\))?(!)?:\s*.+$/);
+            // 3. Fall back to bracket form: [scope] description
+            const bracket = !conv && cleanTitle.match(/^\[([^\]]+)\]\s+.+$/);
+
+            let type = null, scopeStr = null, breaking = false;
+            if (conv) {
+              type = conv[1];
+              scopeStr = conv[2] || null;
+              breaking = !!conv[3];
+            } else if (bracket) {
+              scopeStr = bracket[1];
+            }
+
+            // 4. Detect BREAKING CHANGE: or BREAKING-CHANGE: footer in body.
+            // Conventional Commits 1.0 spec item 16 treats them as synonymous.
+            if (/^BREAKING[ -]CHANGE:/m.test(body)) {
+              breaking = true;
+            }
+
+            // 5. Apply kind/* from type.
+            if (type) {
+              if (typeToKind[type]) {
+                toAdd.add(typeToKind[type]);
+              } else {
+                core.warning(`type "${type}" has no kind/* mapping — typo or new type? See .github/workflows/pr-labeler.yaml typeToKind`);
+              }
+            }
+
+            // 6. Apply area/* from scope. Composite scopes split on comma.
+            const scopes = (scopeStr || '')
+              .split(/,\s*/)
+              .map(s => s.trim())
+              .filter(Boolean);
+            for (const s of scopes) {
+              if (scopeToArea[s]) {
+                toAdd.add(scopeToArea[s]);
+              } else {
+                core.warning(`scope "${s}" has no area/* mapping — consider extending scopeToArea in .github/workflows/pr-labeler.yaml if it recurs`);
+              }
+            }
+
+            // 7. kind/breaking-change.
+            if (breaking) {
+              toAdd.add('kind/breaking-change');
+            }
+
+            // 8. Fallback: no area/* applied -> area/uncategorized.
+            const hasArea = [...toAdd].some(l => l.startsWith('area/'));
+            if (!hasArea) {
+              toAdd.add('area/uncategorized');
+            }
+
+            // 9. Additive only — never remove existing labels.
+            const newLabels = [...toAdd].filter(l => !existing.has(l));
+            if (newLabels.length === 0) {
+              core.info('No new labels to apply');
+              return;
+            }
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr.number,
+              labels: newLabels,
+            });
+            core.info(`Applied labels: ${newLabels.join(', ')}`);

.github/workflows/tags.yaml

@@ -223,7 +223,7 @@ jobs:
                 repo:  context.repo.repo,
                 head,
                 base,
-                title: `Release v${version}`,
+                title: `chore(release): cut v${version}`,
                 body:  `This PR prepares the release \`v${version}\`.`,
                 draft: false
               });
@@ -411,7 +411,7 @@ jobs:
                 repo:  context.repo.repo,
                 head:  changelogBranch,
                 base:  baseBranch,
-                title: `docs: add changelog for v${version}`,
+                title: `docs(release): add changelog for v${version}`,
                 body:  `This PR adds the changelog for release \`v${version}\`.\n\n✅ Changelog has been automatically generated in \`docs/changelogs/v${version}.md\`.`,
                 draft: false
               });
@@ -421,7 +421,7 @@ jobs:
                 owner: context.repo.owner,
                 repo:  context.repo.repo,
                 issue_number: pr.data.number,
-                labels: ['documentation', 'automated']
+                labels: ['kind/documentation', 'automated']
               });
               
               console.log(`Created PR #${pr.data.number} for changelog`);

.pre-commit-config.yaml

@@ -1,6 +1,17 @@
 repos:
 - repo: local
   hooks:
+    - id: run-make-generate-root
+      name: Run 'make generate' at repo root
+      entry: |
+        flock -x .git/pre-commit.lock sh -c '
+          echo "Running make generate at repo root"
+          make generate || exit $?
+          git diff --color=always | cat
+        '
+      language: system
+      files: ^(api/|pkg/apis/|pkg/generated/|internal/crdinstall/manifests/|packages/system/cozystack-controller/definitions/|packages/system/application-definition-crd/definition/|packages/system/backup-controller/definitions/|packages/system/backupstrategy-controller/definitions/|hack/update-codegen\.sh$|hack/boilerplate\.go\.txt$|Makefile$)
+      pass_filenames: false
     - id: run-make-generate
       name: Run 'make generate' in all app directories
       entry: |

AGENTS.md

@@ -27,6 +27,12 @@ working with the **Cozystack** project.
   - Read: [`contributing.md`](./docs/agents/contributing.md)
   - Action: Read the file to understand git workflow, commit format, PR process
 
+- **Issue and PR labeling, triage** (e.g., "label this issue", "what label should I use", "triage this", "categorize")
+  - Read: [`.github/labels.yml`](./.github/labels.yml)
+  - Action: Use labels defined there. Conventions follow the Kubernetes scheme — `kind/*` (type), `area/*` (subsystem), `priority/*` (urgency), `triage/*` (review state), `lifecycle/*` (auto-close), `do-not-merge/*` (PR blockers), `security/*` (severity)
+  - For `area/*`: accuracy outweighs reuse. If no existing `area/*` truly fits the change, propose a new one via PR (extend `.github/labels.yml` and the scope mapping in `.github/workflows/pr-labeler.yaml`) — do not shoehorn the change into a wrong area. `area/uncategorized` is the auto-labeler fallback; treat it as a signal to pick a fit, create a new area, or correct the PR title
+  - PR titles: a Conventional Commits header (`type(scope): description`, types from [`contributing.md`](./docs/agents/contributing.md)) auto-applies `kind/*` and `area/*` via `.github/workflows/pr-labeler.yaml`. Append `!` (or add a `BREAKING CHANGE:` footer) to apply `kind/breaking-change`
+
 **Important rules:**
 - ✅ **ONLY read the file if the task matches the documented process scope** - do not read files for tasks that don't match their purpose
 - ✅ **ALWAYS read the file FIRST** before starting the task (when applicable)

Makefile

@@ -22,6 +22,7 @@ build: build-deps
 	make -C packages/system/lineage-controller-webhook image
 	make -C packages/system/cilium image
 	make -C packages/system/linstor image
+	make -C packages/system/linstor-gui image
 	make -C packages/system/kubeovn-webhook image
 	make -C packages/system/kubeovn-plunger image
 	make -C packages/system/dashboard image
@@ -82,11 +83,19 @@ test:
 	make -C packages/core/testing apply
 	make -C packages/core/testing test
 
-unit-tests: helm-unit-tests bats-unit-tests
+unit-tests: helm-unit-tests bats-unit-tests go-unit-tests
 
 helm-unit-tests:
 	hack/helm-unit-tests.sh
 
+# Scoped go test over the cozystack-api surface that this repo owns. Kept
+# narrow intentionally - running `go test ./...` pulls in generated code
+# round-trip suites whose behavior depends on tool versions outside this
+# repo's control (kubebuilder, openapi-gen, etc.) and is better exercised
+# from their generator workflows.
+go-unit-tests:
+	go test ./pkg/registry/... ./pkg/config/... ./pkg/cmd/server/...
+
 # Discover every hack/*.bats file that is NOT an e2e test and run it
 # through cozytest.sh. Drop a new *.bats file in hack/ and it is picked
 # up automatically on the next `make unit-tests` run.

api/apps/v1alpha1/kubernetes/types.go

@@ -36,6 +36,9 @@ type ConfigSpec struct {
 	// Kubernetes control-plane configuration.
 	// +kubebuilder:default:={}
 	ControlPlane ControlPlane `json:"controlPlane"`
+	// Optional image overrides for air-gapped or rate-limited registries.
+	// +kubebuilder:default:={}
+	Images Images `json:"images"`
 }
 
 type APIServer struct {
@@ -66,6 +69,9 @@ type Addons struct {
 	// NVIDIA GPU Operator.
 	// +kubebuilder:default:={}
 	GpuOperator GPUOperatorAddon `json:"gpuOperator"`
+	// HAMi GPU virtualization middleware.
+	// +kubebuilder:default:={}
+	Hami HAMiAddon `json:"hami"`
 	// Ingress-NGINX controller.
 	// +kubebuilder:default:={}
 	IngressNginx IngressNginxAddon `json:"ingressNginx"`
@@ -157,6 +163,21 @@ type GatewayAPIAddon struct {
 	Enabled bool `json:"enabled"`
 }
 
+type HAMiAddon struct {
+	// Enable HAMi (requires GPU Operator).
+	// +kubebuilder:default:=false
+	Enabled bool `json:"enabled"`
+	// Custom Helm values overrides.
+	// +kubebuilder:default:={}
+	ValuesOverride k8sRuntime.RawExtension `json:"valuesOverride"`
+}
+
+type Images struct {
+	// Image used by the wait-for-kubeconfig init container. Empty falls back to images/busybox.tag.
+	// +kubebuilder:default:=""
+	WaitForKubeconfig string `json:"waitForKubeconfig,omitempty"`
+}
+
 type IngressNginxAddon struct {
 	// Enable the controller (requires nodes labeled `ingress-nginx`).
 	// +kubebuilder:default:=false

api/apps/v1alpha1/kubernetes/zz_generated.deepcopy.go

@@ -49,6 +49,7 @@ func (in *Addons) DeepCopyInto(out *Addons) {
 	in.Fluxcd.DeepCopyInto(&out.Fluxcd)
 	out.GatewayAPI = in.GatewayAPI
 	in.GpuOperator.DeepCopyInto(&out.GpuOperator)
+	in.Hami.DeepCopyInto(&out.Hami)
 	in.IngressNginx.DeepCopyInto(&out.IngressNginx)
 	in.MonitoringAgents.DeepCopyInto(&out.MonitoringAgents)
 	in.Velero.DeepCopyInto(&out.Velero)
@@ -135,6 +136,7 @@ func (in *ConfigSpec) DeepCopyInto(out *ConfigSpec) {
 	}
 	in.Addons.DeepCopyInto(&out.Addons)
 	in.ControlPlane.DeepCopyInto(&out.ControlPlane)
+	out.Images = in.Images
 }
 
 // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ConfigSpec.
@@ -260,6 +262,37 @@ func (in *GatewayAPIAddon) DeepCopy() *GatewayAPIAddon {
 	return out
 }
 
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *HAMiAddon) DeepCopyInto(out *HAMiAddon) {
+	*out = *in
+	in.ValuesOverride.DeepCopyInto(&out.ValuesOverride)
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HAMiAddon.
+func (in *HAMiAddon) DeepCopy() *HAMiAddon {
+	if in == nil {
+		return nil
+	}
+	out := new(HAMiAddon)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *Images) DeepCopyInto(out *Images) {
+	*out = *in
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Images.
+func (in *Images) DeepCopy() *Images {
+	if in == nil {
+		return nil
+	}
+	out := new(Images)
+	in.DeepCopyInto(out)
+	return out
+}
+
 // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
 func (in *IngressNginxAddon) DeepCopyInto(out *IngressNginxAddon) {
 	*out = *in

api/apps/v1alpha1/postgresql/types.go

@@ -92,6 +92,9 @@ type Bootstrap struct {
 	// Timestamp (RFC3339) for point-in-time recovery; empty means latest.
 	// +kubebuilder:default:=""
 	RecoveryTime string `json:"recoveryTime,omitempty"`
+	// Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name.
+	// +kubebuilder:default:=""
+	ServerName string `json:"serverName,omitempty"`
 }
 
 type Database struct {

api/apps/v1alpha1/vminstance/types.go

@@ -26,6 +26,9 @@ type ConfigSpec struct {
 	// Ports to forward from outside the cluster.
 	// +kubebuilder:default:={22}
 	ExternalPorts []int `json:"externalPorts,omitempty"`
+	// Whether to accept ICMP traffic to the VM in PortList mode (preserves ping and PMTU discovery). No effect in WholeIP mode. Default true so ping behaves as users expect even when port filtering is in effect.
+	// +kubebuilder:default:=true
+	ExternalAllowICMP bool `json:"externalAllowICMP"`
 	// Requested running state of the VirtualMachineInstance
 	// +kubebuilder:default:="Always"
 	RunStrategy RunStrategy `json:"runStrategy"`

api/backups/v1alpha1/zz_generated.deepcopy.go

@@ -620,6 +620,11 @@ func (in *RestoreJobSpec) DeepCopyInto(out *RestoreJobSpec) {
 		*out = new(v1.TypedLocalObjectReference)
 		(*in).DeepCopyInto(*out)
 	}
+	if in.Options != nil {
+		in, out := &in.Options, &out.Options
+		*out = new(runtime.RawExtension)
+		(*in).DeepCopyInto(*out)
+	}
 }
 
 // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RestoreJobSpec.

api/v1alpha1/packagesource_types.go

@@ -132,6 +132,16 @@ type ComponentInstall struct {
 	// DependsOn is a list of component names that must be installed before this component
 	// +optional
 	DependsOn []string `json:"dependsOn,omitempty"`
+
+	// UpgradeCRDs controls how CRDs from the chart's crds/ directory are
+	// handled on HelmRelease upgrades. Maps to HelmRelease.Spec.Upgrade.CRDs.
+	// Empty string (default) preserves the helm-controller default (Skip).
+	// Use "CreateReplace" for operators that evolve their CRD set between
+	// versions. Warning: CreateReplace overwrites CRDs and may cause data
+	// loss if upstream drops fields from a CRD with live objects.
+	// +optional
+	// +kubebuilder:validation:Enum=Skip;Create;CreateReplace
+	UpgradeCRDs string `json:"upgradeCRDs,omitempty"`
 }
 
 // Component defines a single Helm release component within a package source

dashboards/gpu/gpu-efficiency.json

@@ -0,0 +1,819 @@
+{
+  "uid": "gpu-efficiency",
+  "title": "GPU Efficiency Score",
+  "description": "Tensor saturation, util/watt and throttling — reveals inefficient GPU workloads",
+  "tags": [
+    "gpu",
+    "efficiency",
+    "finops"
+  ],
+  "timezone": "browser",
+  "editable": true,
+  "graphTooltip": 1,
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "fiscalYearStartMonth": 0,
+  "schemaVersion": 42,
+  "panels": [
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Overall efficiency metrics",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "panels": []
+    },
+    {
+      "type": "stat",
+      "id": 2,
+      "targets": [
+        {
+          "expr": "avg(gpu:tensor_saturation:avg5m) * 100",
+          "refId": "A"
+        }
+      ],
+      "title": "Avg Tensor Saturation",
+      "description": "Mean tensor core saturation across all GPUs. \u003c10% means GPUs are used inefficiently (workloads could move to CPU or optimize their code). Cluster-wide — DCGM metrics cannot be attributed to workload namespaces.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 5,
+        "w": 8,
+        "x": 0,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "area",
+        "colorMode": "background",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "red"
+              },
+              {
+                "value": 10,
+                "color": "orange"
+              },
+              {
+                "value": 30,
+                "color": "yellow"
+              },
+              {
+                "value": 60,
+                "color": "green"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 3,
+      "targets": [
+        {
+          "expr": "avg(gpu:util_per_watt:avg5m)",
+          "refId": "A"
+        }
+      ],
+      "title": "Avg Utilization per Watt",
+      "description": "NVML utilization % per watt across all GPUs. Higher value = more efficient workload. Cluster-wide — DCGM metrics cannot be attributed to workload namespaces.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 5,
+        "w": 8,
+        "x": 8,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "area",
+        "colorMode": "background",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "none",
+          "decimals": 3,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "red"
+              },
+              {
+                "value": 0.5,
+                "color": "yellow"
+              },
+              {
+                "value": 1,
+                "color": "green"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 4,
+      "targets": [
+        {
+          "expr": "avg(gpu:power_throttle_fraction:rate5m)",
+          "refId": "A"
+        }
+      ],
+      "title": "Avg Power Throttling",
+      "description": "Fraction of time GPUs hit the TDP cap and lose performance. \u003e5% means tenants underutilize billed FLOPS. Cluster-wide — rule aggregates by (Hostname, gpu, UUID) and drops namespace label.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 5,
+        "w": 8,
+        "x": 16,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "area",
+        "colorMode": "background",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "decimals": 2,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 0.05,
+                "color": "yellow"
+              },
+              {
+                "value": 0.2,
+                "color": "red"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "NVML vs Tensor (mismatch detector)",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 6
+      },
+      "id": 10,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "id": 11,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_GPU_UTIL",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "NVML GPU Utilization",
+      "description": "Classic utilization metric. Shows activity of any engine (SM, copy, encoder). Cluster-wide — DCGM namespace is the exporter's own namespace, not the workload namespace.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 7
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 12,
+      "targets": [
+        {
+          "expr": "DCGM_FI_PROF_PIPE_TENSOR_ACTIVE * 100",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Tensor Pipe Active",
+      "description": "Real tensor core load (HMMA). For AI/LLM inference it should be ≥20%, otherwise the workload is unoptimized. Cluster-wide — DCGM namespace is the exporter's own namespace, not the workload namespace.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 7
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Per-GPU ranking",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 15
+      },
+      "id": 20,
+      "panels": []
+    },
+    {
+      "type": "table",
+      "id": 21,
+      "targets": [
+        {
+          "expr": "topk(20, gpu:tensor_saturation:avg5m * 100)",
+          "instant": true,
+          "range": false,
+          "format": "table",
+          "refId": "A"
+        }
+      ],
+      "title": "Tensor Saturation per GPU (5m avg)",
+      "description": "Which GPUs are exercising tensor cores and which are not. Sorted descending. Grouped by Hostname/gpu/UUID — DCGM metrics cannot be attributed to workload namespaces.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "repeatDirection": "h",
+      "transformations": [
+        {
+          "id": "organize",
+          "options": {
+            "excludeByName": {
+              "DCGM_FI_DRIVER_VERSION": true,
+              "Time": true,
+              "__name__": true,
+              "cluster": true,
+              "container": true,
+              "device": true,
+              "endpoint": true,
+              "gpu_driver_version": true,
+              "instance": true,
+              "job": true,
+              "modelName": true,
+              "namespace": true,
+              "pci_bus_id": true,
+              "pod": true,
+              "prometheus": true,
+              "service": true,
+              "tenant": true,
+              "tier": true,
+              "uid": true,
+              "unit": true
+            },
+            "indexByName": {
+              "Hostname": 0,
+              "UUID": 2,
+              "Value": 3,
+              "gpu": 1
+            },
+            "renameByName": {
+              "Hostname": "Node",
+              "UUID": "UUID",
+              "Value": "Saturation",
+              "gpu": "GPU"
+            }
+          }
+        }
+      ],
+      "options": {
+        "frameIndex": 0,
+        "showHeader": true,
+        "showTypeIcons": false,
+        "sortBy": [
+          {
+            "displayName": "Saturation",
+            "desc": true
+          }
+        ],
+        "footer": {
+          "show": false,
+          "reducer": []
+        },
+        "cellHeight": "sm"
+      },
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Saturation"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "percent"
+              },
+              {
+                "id": "min",
+                "value": 0
+              },
+              {
+                "id": "max",
+                "value": 100
+              },
+              {
+                "id": "custom.cellOptions",
+                "value": {
+                  "mode": "gradient",
+                  "type": "gauge"
+                }
+              },
+              {
+                "id": "thresholds",
+                "value": {
+                  "mode": "absolute",
+                  "steps": [
+                    {
+                      "color": "red"
+                    },
+                    {
+                      "color": "orange",
+                      "value": 10
+                    },
+                    {
+                      "color": "yellow",
+                      "value": 30
+                    },
+                    {
+                      "color": "green",
+                      "value": 60
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "table",
+      "id": 22,
+      "targets": [
+        {
+          "expr": "topk(20, gpu:util_per_watt:avg5m)",
+          "instant": true,
+          "range": false,
+          "format": "table",
+          "refId": "A"
+        }
+      ],
+      "title": "Utilization / Watt per GPU (5m avg)",
+      "description": "How efficiently each GPU spends watts. Low value = poor optimization. Grouped by Hostname/gpu/UUID — DCGM metrics cannot be attributed to workload namespaces.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 16
+      },
+      "repeatDirection": "h",
+      "transformations": [
+        {
+          "id": "organize",
+          "options": {
+            "excludeByName": {
+              "DCGM_FI_DRIVER_VERSION": true,
+              "Time": true,
+              "__name__": true,
+              "cluster": true,
+              "container": true,
+              "device": true,
+              "endpoint": true,
+              "gpu_driver_version": true,
+              "instance": true,
+              "job": true,
+              "modelName": true,
+              "namespace": true,
+              "pci_bus_id": true,
+              "pod": true,
+              "prometheus": true,
+              "service": true,
+              "tenant": true,
+              "tier": true,
+              "uid": true,
+              "unit": true
+            },
+            "indexByName": {
+              "Hostname": 0,
+              "UUID": 2,
+              "Value": 3,
+              "gpu": 1
+            },
+            "renameByName": {
+              "Hostname": "Node",
+              "UUID": "UUID",
+              "Value": "Util/Watt",
+              "gpu": "GPU"
+            }
+          }
+        }
+      ],
+      "options": {
+        "frameIndex": 0,
+        "showHeader": true,
+        "showTypeIcons": false,
+        "sortBy": [
+          {
+            "displayName": "Util/Watt",
+            "desc": true
+          }
+        ],
+        "footer": {
+          "show": false,
+          "reducer": []
+        },
+        "cellHeight": "sm"
+      },
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Util/Watt"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "none"
+              },
+              {
+                "id": "decimals",
+                "value": 3
+              },
+              {
+                "id": "min",
+                "value": 0
+              },
+              {
+                "id": "max",
+                "value": 1.5
+              },
+              {
+                "id": "custom.cellOptions",
+                "value": {
+                  "mode": "gradient",
+                  "type": "gauge"
+                }
+              },
+              {
+                "id": "thresholds",
+                "value": {
+                  "mode": "absolute",
+                  "steps": [
+                    {
+                      "color": "red"
+                    },
+                    {
+                      "color": "yellow",
+                      "value": 0.5
+                    },
+                    {
+                      "color": "green",
+                      "value": 1
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Throttling",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 24
+      },
+      "id": 30,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "id": 31,
+      "targets": [
+        {
+          "expr": "gpu:power_throttle_fraction:rate5m",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Power throttle fraction per GPU",
+      "description": "Fraction of time the GPU was power-throttled. 1.0 = always throttled. Cluster-wide — rule aggregates by (Hostname, gpu, UUID) and drops namespace label.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 25
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 0.05,
+                "color": "yellow"
+              },
+              {
+                "value": 0.2,
+                "color": "red"
+              }
+            ]
+          },
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 25,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 32,
+      "targets": [
+        {
+          "expr": "gpu:thermal_throttle_fraction:rate5m",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Thermal throttle fraction per GPU",
+      "description": "Fraction of time the GPU was thermal-throttled. Cluster-wide — rule aggregates by (Hostname, gpu, UUID) and drops namespace label.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 25
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 0.05,
+                "color": "yellow"
+              },
+              {
+                "value": 0.2,
+                "color": "red"
+              }
+            ]
+          },
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 25,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "templating": {
+    "list": [
+      {
+        "type": "datasource",
+        "name": "ds_prometheus",
+        "label": "Prometheus",
+        "skipUrlSync": false,
+        "query": "prometheus",
+        "current": {
+          "selected": false,
+          "text": "default",
+          "value": "default"
+        },
+        "multi": false,
+        "allowCustomValue": true,
+        "includeAll": false,
+        "regex": "",
+        "auto": false,
+        "auto_min": "10s",
+        "auto_count": 30
+      }
+    ]
+  },
+  "annotations": {}
+}

dashboards/gpu/gpu-performance.json

@@ -0,0 +1,957 @@
+{
+  "uid": "gpu-performance",
+  "title": "GPU Performance",
+  "tags": [
+    "gpu",
+    "dcgm"
+  ],
+  "timezone": "browser",
+  "editable": true,
+  "graphTooltip": 1,
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "fiscalYearStartMonth": 0,
+  "schemaVersion": 42,
+  "panels": [
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Overview",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "panels": []
+    },
+    {
+      "type": "stat",
+      "id": 2,
+      "targets": [
+        {
+          "expr": "cluster:gpu_count:total",
+          "refId": "A"
+        }
+      ],
+      "title": "Total GPUs",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 0,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "none",
+        "colorMode": "value",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "blue"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 3,
+      "targets": [
+        {
+          "expr": "cluster:gpu_count:allocated",
+          "refId": "A"
+        }
+      ],
+      "title": "Allocated",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 6,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "none",
+        "colorMode": "value",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 1,
+                "color": "yellow"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 4,
+      "targets": [
+        {
+          "expr": "cluster:gpu_util:avg",
+          "refId": "A"
+        }
+      ],
+      "title": "Average utilization",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 12,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "area",
+        "colorMode": "value",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "blue"
+              },
+              {
+                "value": 30,
+                "color": "green"
+              },
+              {
+                "value": 80,
+                "color": "orange"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 5,
+      "targets": [
+        {
+          "expr": "cluster:gpu_power_watts:sum",
+          "refId": "A"
+        }
+      ],
+      "title": "Power draw",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 18,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "area",
+        "colorMode": "value",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "watt",
+          "decimals": 0,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Utilization",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 5
+      },
+      "id": 10,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "id": 11,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_GPU_UTIL{Hostname=~\"$Hostname\"}",
+          "legendFormat": "{{Hostname}}/{{gpu}} {{pod}}",
+          "refId": "A"
+        }
+      ],
+      "title": "GPU Utilization (NVML)",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 6
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never",
+            "spanNulls": false
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 12,
+      "targets": [
+        {
+          "expr": "DCGM_FI_PROF_PIPE_TENSOR_ACTIVE{Hostname=~\"$Hostname\"} * 100",
+          "legendFormat": "{{Hostname}}/{{gpu}} {{pod}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Tensor Pipe Active (realistic load for LLM/AI)",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 6
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never",
+            "spanNulls": false
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 13,
+      "targets": [
+        {
+          "expr": "DCGM_FI_PROF_GR_ENGINE_ACTIVE{Hostname=~\"$Hostname\"} * 100",
+          "legendFormat": "{{Hostname}}/{{gpu}} {{pod}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Graphics Engine Active",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 14
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never",
+            "spanNulls": false
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 14,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_MEM_COPY_UTIL{Hostname=~\"$Hostname\"}",
+          "legendFormat": "{{Hostname}}/{{gpu}} {{pod}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Memory Copy Utilization",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 14
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never",
+            "spanNulls": false
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Memory",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 22
+      },
+      "id": 20,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "id": 21,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_FB_USED{Hostname=~\"$Hostname\"} * 1048576",
+          "legendFormat": "{{Hostname}}/{{gpu}} {{pod}}",
+          "refId": "A"
+        }
+      ],
+      "title": "VRAM Used",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 23
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes",
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 25,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 22,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_FB_FREE{Hostname=~\"$Hostname\"} * 1048576",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "VRAM Free",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 23
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "min"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes",
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Power \u0026 Temperature",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 31
+      },
+      "id": 30,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "id": 31,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_POWER_USAGE{Hostname=~\"$Hostname\"}",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Power Usage per GPU",
+      "description": "Hardware-level metric — shown cluster-wide regardless of namespace filter.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 32
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "watt",
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 32,
+      "targets": [
+        {
+          "expr": "DCGM_FI_DEV_GPU_TEMP{Hostname=~\"$Hostname\"}",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "GPU Temperature",
+      "description": "Hardware-level metric — shown cluster-wide regardless of namespace filter.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 32
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "celsius",
+          "min": 20,
+          "max": 100,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 75,
+                "color": "yellow"
+              },
+              {
+                "value": 85,
+                "color": "red"
+              }
+            ]
+          },
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Health",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 40
+      },
+      "id": 40,
+      "panels": []
+    },
+    {
+      "type": "stat",
+      "id": 41,
+      "targets": [
+        {
+          "expr": "max by (Hostname, gpu) (DCGM_FI_DEV_XID_ERRORS{Hostname=~\"$Hostname\"})",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "XID errors (latest)",
+      "description": "Hardware-level metric — shown cluster-wide regardless of namespace filter.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 5,
+        "w": 8,
+        "x": 0,
+        "y": 41
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "none",
+        "colorMode": "background",
+        "justifyMode": "auto",
+        "textMode": "value_and_name",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 1,
+                "color": "red"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 42,
+      "targets": [
+        {
+          "expr": "rate(DCGM_FI_DEV_POWER_VIOLATION{Hostname=~\"$Hostname\"}[5m])",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Power Violation (µs/s throttled due to power)",
+      "description": "Hardware-level metric — shown cluster-wide regardless of namespace filter.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 5,
+        "w": 8,
+        "x": 8,
+        "y": 41
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": []
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "µs",
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 43,
+      "targets": [
+        {
+          "expr": "rate(DCGM_FI_DEV_THERMAL_VIOLATION{Hostname=~\"$Hostname\"}[5m])",
+          "legendFormat": "{{Hostname}}/{{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Thermal Violation (µs/s throttled due to thermals)",
+      "description": "Hardware-level metric — shown cluster-wide regardless of namespace filter.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 5,
+        "w": 8,
+        "x": 16,
+        "y": 41
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": []
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "µs",
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "linear",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": []
+      }
+    }
+  ],
+  "templating": {
+    "list": [
+      {
+        "type": "datasource",
+        "name": "ds_prometheus",
+        "label": "Prometheus",
+        "skipUrlSync": false,
+        "query": "prometheus",
+        "current": {
+          "selected": false,
+          "text": "default",
+          "value": "default"
+        },
+        "multi": false,
+        "allowCustomValue": true,
+        "includeAll": false,
+        "regex": "",
+        "auto": false,
+        "auto_min": "10s",
+        "auto_count": 30
+      },
+      {
+        "type": "query",
+        "name": "Hostname",
+        "label": "Host",
+        "skipUrlSync": false,
+        "query": "label_values(DCGM_FI_DEV_GPU_UTIL, Hostname)",
+        "datasource": {
+          "type": "prometheus",
+          "uid": "$ds_prometheus"
+        },
+        "current": {
+          "selected": true,
+          "text": "All",
+          "value": "$__all"
+        },
+        "multi": true,
+        "allowCustomValue": true,
+        "refresh": 2,
+        "sort": 1,
+        "includeAll": true,
+        "auto": false,
+        "auto_min": "10s",
+        "auto_count": 30
+      }
+    ]
+  },
+  "annotations": {}
+}

dashboards/gpu/gpu-quotas.json

@@ -0,0 +1,637 @@
+{
+  "uid": "gpu-quotas",
+  "title": "GPU Quotas \u0026 Allocation",
+  "tags": [
+    "gpu",
+    "quotas"
+  ],
+  "timezone": "browser",
+  "editable": true,
+  "graphTooltip": 1,
+  "time": {
+    "from": "now-6h",
+    "to": "now"
+  },
+  "fiscalYearStartMonth": 0,
+  "schemaVersion": 42,
+  "panels": [
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Allocation overview",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "panels": []
+    },
+    {
+      "type": "stat",
+      "id": 2,
+      "targets": [
+        {
+          "expr": "sum(kube_node_status_allocatable{resource=\"nvidia_com_gpu\"})",
+          "refId": "A"
+        }
+      ],
+      "title": "GPU allocatable",
+      "description": "Total GPU capacity the cluster can schedule to pods.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 0,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "none",
+        "colorMode": "value",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "blue"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 3,
+      "targets": [
+        {
+          "expr": "cluster:gpu_count:allocated",
+          "refId": "A"
+        }
+      ],
+      "title": "GPU requested",
+      "description": "Sum of GPU requests across all pods cluster-wide, including system namespaces.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 6,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "none",
+        "colorMode": "value",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 1,
+                "color": "yellow"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "gauge",
+      "id": 4,
+      "targets": [
+        {
+          "expr": "cluster:gpu_count:allocated / sum(kube_node_status_allocatable{resource=\"nvidia_com_gpu\"}) * 100",
+          "refId": "A"
+        }
+      ],
+      "title": "Allocation ratio",
+      "description": "Percentage of allocatable GPUs currently requested by pods.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 12,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "showThresholdLabels": false,
+        "showThresholdMarkers": true,
+        "sizing": "auto",
+        "minVizWidth": 75,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "minVizHeight": 75,
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "blue"
+              },
+              {
+                "value": 40,
+                "color": "green"
+              },
+              {
+                "value": 80,
+                "color": "yellow"
+              },
+              {
+                "value": 95,
+                "color": "red"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "stat",
+      "id": 5,
+      "targets": [
+        {
+          "expr": "count((sum by (namespace, pod) (kube_pod_container_resource_requests{resource=\"nvidia_com_gpu\"}) \u003e 0) * on(namespace, pod) group_left() (kube_pod_status_phase{phase=\"Pending\"} == 1)) or vector(0)",
+          "refId": "A"
+        }
+      ],
+      "title": "Pending pods (GPU)",
+      "description": "Pods requesting GPUs that are stuck in Pending state — indicates capacity shortage.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 4,
+        "w": 6,
+        "x": 18,
+        "y": 1
+      },
+      "repeatDirection": "h",
+      "options": {
+        "graphMode": "none",
+        "colorMode": "background",
+        "justifyMode": "auto",
+        "textMode": "value",
+        "wideLayout": true,
+        "showPercentChange": false,
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "percentChangeColorMode": "standard",
+        "orientation": ""
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              },
+              {
+                "value": 1,
+                "color": "red"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Per namespace",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 5
+      },
+      "id": 10,
+      "panels": []
+    },
+    {
+      "type": "bargauge",
+      "id": 11,
+      "targets": [
+        {
+          "expr": "sum by (namespace) (namespace:gpu_count:allocated{namespace=~\"$namespace\"})",
+          "legendFormat": "{{namespace}}",
+          "refId": "A"
+        }
+      ],
+      "title": "GPU requested per namespace",
+      "description": "GPU allocation breakdown by namespace — spot top consumers at a glance.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 6
+      },
+      "repeatDirection": "h",
+      "options": {
+        "displayMode": "gradient",
+        "valueMode": "color",
+        "namePlacement": "auto",
+        "showUnfilled": true,
+        "sizing": "auto",
+        "minVizWidth": 8,
+        "minVizHeight": 16,
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": []
+        },
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "maxVizHeight": 300,
+        "orientation": "horizontal"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "min": 0,
+          "max": 8,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "value": null,
+                "color": "green"
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "id": 12,
+      "targets": [
+        {
+          "expr": "sum(kube_node_status_allocatable{resource=\"nvidia_com_gpu\"})",
+          "legendFormat": "Allocatable (total)",
+          "refId": "A"
+        },
+        {
+          "expr": "sum(namespace:gpu_count:allocated{namespace=~\"$namespace\"})",
+          "legendFormat": "Requested",
+          "refId": "B"
+        }
+      ],
+      "title": "GPU allocated over time",
+      "description": "Requested vs allocatable GPUs over time — shows allocation pressure trends.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 6
+      },
+      "repeatDirection": "h",
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom",
+          "showLegend": false,
+          "calcs": []
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": ""
+        }
+      },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "drawStyle": "line",
+            "lineInterpolation": "stepAfter",
+            "fillOpacity": 10,
+            "showPoints": "never"
+          }
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Allocatable (total)"
+            },
+            "properties": [
+              {
+                "id": "color",
+                "value": {
+                  "fixedColor": "blue",
+                  "mode": "fixed"
+                }
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "row",
+      "collapsed": false,
+      "title": "Pods with GPU",
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 14
+      },
+      "id": 20,
+      "panels": []
+    },
+    {
+      "type": "table",
+      "id": 21,
+      "targets": [
+        {
+          "expr": "kube_pod_container_resource_requests{resource=\"nvidia_com_gpu\", namespace=~\"$namespace\"} * on(namespace, pod) group_left(phase) (kube_pod_status_phase{phase=~\"Running|Pending\"} == 1)",
+          "instant": true,
+          "range": false,
+          "format": "table",
+          "refId": "requested"
+        },
+        {
+          "expr": "kube_pod_container_resource_limits{resource=\"nvidia_com_gpu\", namespace=~\"$namespace\"} * on(namespace, pod) group_left() (kube_pod_status_phase{phase=~\"Running|Pending\"} == 1)",
+          "instant": true,
+          "range": false,
+          "format": "table",
+          "refId": "limits"
+        }
+      ],
+      "title": "Pods requesting GPU",
+      "description": "Per-pod GPU requests and limits with scheduling status — Running or Pending.",
+      "transparent": false,
+      "datasource": {
+        "type": "prometheus",
+        "uid": "$ds_prometheus"
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 24,
+        "x": 0,
+        "y": 15
+      },
+      "repeatDirection": "h",
+      "transformations": [
+        {
+          "id": "joinByField",
+          "options": {
+            "byField": "pod",
+            "mode": "outer"
+          }
+        },
+        {
+          "id": "organize",
+          "options": {
+            "excludeByName": {
+              "Time": true,
+              "Time 1": true,
+              "Time 2": true,
+              "__name__": true,
+              "__name__ 1": true,
+              "__name__ 2": true,
+              "cluster": true,
+              "cluster 1": true,
+              "cluster 2": true,
+              "container 2": true,
+              "endpoint": true,
+              "endpoint 1": true,
+              "endpoint 2": true,
+              "instance": true,
+              "instance 1": true,
+              "instance 2": true,
+              "job": true,
+              "job 1": true,
+              "job 2": true,
+              "namespace 2": true,
+              "node 2": true,
+              "prometheus": true,
+              "prometheus 1": true,
+              "prometheus 2": true,
+              "resource": true,
+              "resource 1": true,
+              "resource 2": true,
+              "service": true,
+              "service 1": true,
+              "service 2": true,
+              "tenant": true,
+              "tenant 1": true,
+              "tenant 2": true,
+              "tier": true,
+              "tier 1": true,
+              "tier 2": true,
+              "uid": true,
+              "uid 1": true,
+              "uid 2": true,
+              "unit": true,
+              "unit 1": true,
+              "unit 2": true
+            },
+            "indexByName": {
+              "Value #limits": 5,
+              "Value #requested": 4,
+              "container 1": 2,
+              "namespace 1": 0,
+              "node 1": 3,
+              "phase": 6,
+              "pod": 1
+            },
+            "renameByName": {
+              "Value #limits": "Limit",
+              "Value #requested": "Req",
+              "container 1": "Container",
+              "namespace 1": "Namespace",
+              "node 1": "Node",
+              "phase": "Status"
+            }
+          }
+        }
+      ],
+      "options": {
+        "frameIndex": 0,
+        "showHeader": true,
+        "showTypeIcons": false,
+        "footer": {
+          "show": false,
+          "reducer": []
+        },
+        "cellHeight": "sm"
+      },
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Status"
+            },
+            "properties": [
+              {
+                "id": "custom.cellOptions",
+                "value": {
+                  "mode": "basic",
+                  "type": "color-background"
+                }
+              },
+              {
+                "id": "mappings",
+                "value": [
+                  {
+                    "options": {
+                      "Failed": {
+                        "color": "red",
+                        "index": 2
+                      },
+                      "Pending": {
+                        "color": "orange",
+                        "index": 1
+                      },
+                      "Running": {
+                        "color": "green",
+                        "index": 0
+                      }
+                    },
+                    "type": "value"
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ],
+  "templating": {
+    "list": [
+      {
+        "type": "datasource",
+        "name": "ds_prometheus",
+        "label": "Prometheus",
+        "skipUrlSync": false,
+        "query": "prometheus",
+        "current": {
+          "selected": false,
+          "text": "default",
+          "value": "default"
+        },
+        "multi": false,
+        "allowCustomValue": true,
+        "includeAll": false,
+        "regex": "",
+        "auto": false,
+        "auto_min": "10s",
+        "auto_count": 30
+      },
+      {
+        "type": "query",
+        "name": "namespace",
+        "label": "Namespace",
+        "skipUrlSync": false,
+        "query": "label_values(kube_pod_container_resource_requests{resource=\"nvidia_com_gpu\"}, namespace)",
+        "datasource": {
+          "type": "prometheus",
+          "uid": "$ds_prometheus"
+        },
+        "current": {
+          "selected": true,
+          "text": "All",
+          "value": "$__all"
+        },
+        "multi": true,
+        "allowCustomValue": true,
+        "refresh": 2,
+        "sort": 1,
+        "includeAll": true,
+        "auto": false,
+        "auto_min": "10s",
+        "auto_count": 30
+      }
+    ]
+  },
+  "annotations": {}
+}

docs/agents/contributing.md

@@ -43,10 +43,11 @@ git commit --signoff -m "type(scope): brief description"
 
 **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
 
-**Scopes** (e.g., not exhaustive — use any scope that names the component you are touching):
-- System: `dashboard`, `platform`, `cilium`, `kube-ovn`, `linstor`, `fluxcd`, `cluster-api`
-- Apps: `postgres`, `mariadb`, `redis`, `kafka`, `clickhouse`, `virtual-machine`, `kubernetes`
-- Other: `api`, `hack`, `tests`, `ci`, `docs`, `agents`, `maintenance`
+**Scopes** (examples — not an exhaustive list; pick the most specific scope that describes the change, and introduce a new one if a genuinely new area needs its own):
+
+- System, e.g.: `dashboard`, `platform`, `operator`, `cilium`, `kube-ovn`, `linstor`, `fluxcd`, `cluster-api`
+- Apps, e.g.: `postgres`, `mariadb`, `redis`, `kafka`, `clickhouse`, `virtual-machine`, `kubernetes`
+- Other, e.g.: `api`, `hack`, `tests`, `ci`, `docs`, `agents`, `maintenance`
 
 Breaking changes: append `!` after type/scope (`feat(api)!: ...`) or add a `BREAKING CHANGE:` footer.
 
@@ -57,6 +58,49 @@ git commit --signoff -m "fix(postgres): update operator to version 1.2.3"
 git commit --signoff -m "docs(contributing): add installation guide"
 ```
 
+## PR Title Auto-Labeling
+
+`.github/workflows/pr-labeler.yaml` parses the PR title on `opened`, `edited`, `reopened`, and `synchronize` events and applies labels additively (never removes). The title is expected to follow Conventional Commits — same format as commit messages above.
+
+**Type → `kind/*`:**
+
+| type      | label              |
+| --------- | ------------------ |
+| feat      | kind/feature       |
+| fix       | kind/bug           |
+| docs      | kind/documentation |
+| chore     | kind/cleanup       |
+| refactor  | kind/cleanup       |
+| style, perf, test, build, ci, revert | (no kind label) |
+
+**Scope → `area/*`** (full mapping in `.github/workflows/pr-labeler.yaml`):
+
+| scope (examples) | label |
+| --- | --- |
+| agents, ai | area/ai |
+| api, cozystack-api | area/api |
+| build | area/build |
+| ci | area/ci |
+| dashboard | area/dashboard |
+| postgres, mariadb, redis, etcd, kafka, clickhouse, postgres-operator, mariadb-operator | area/database |
+| extra | area/extra |
+| kubernetes | area/kubernetes |
+| monitoring, vlogs, vmstack, grafana, workloadmonitor | area/monitoring |
+| ingress, gateway, vpn, metallb, cilium, kube-ovn, cozy-proxy, ... | area/networking |
+| platform, bundle, flux, fluxcd, cluster-api, talos, installer, cozyctl, cozystack-engine, cozy-lib | area/platform |
+| backport, release | area/release |
+| seaweedfs, bucket, linstor, velero, harbor, backups | area/storage |
+| tests, e2e | area/testing |
+| kubevirt, cdi, vmi, vm-import, virtual-machine, hami, gpu-operator | area/virtualization |
+
+**Special handling:**
+
+- `[Backport release-1.x]` prefix is stripped before parsing; `area/release` and `backport` labels are added.
+- Composite scope (`feat(platform, system, apps): ...`) — each comma-separated part is mapped independently.
+- `!` after type or `BREAKING CHANGE:` footer in the body → `kind/breaking-change`.
+- Unmapped scope or non-conventional title → `area/uncategorized` (signals the PR needs manual area selection).
+- Bracket-style fallback (`[scope] description`) maps `scope` → `area/*` but cannot infer `kind/*`.
+
 ### AI Agent Attribution
 
 When an AI agent authors or materially assists with a commit, add an `Assisted-By:` trailer naming the model:

docs/agents/overview.md

@@ -83,6 +83,14 @@ packages/<category>/<package-name>/
 - Reference PR numbers when available
 - Keep commits atomic and focused
 
+### PackageSource CRD upgrade policy
+
+Each component in a `PackageSource` may set `install.upgradeCRDs` to control how CRDs from the chart's `crds/` directory are handled on `HelmRelease` upgrades. Allowed values: `Skip` (default — helm-controller does not touch CRDs on upgrade), `Create` (create new CRDs only), `CreateReplace` (create new and overwrite existing).
+
+Set `upgradeCRDs: CreateReplace` for operators whose upstream regularly adds new CRDs between versions (etcd-operator, cnpg, kubevirt, kamaji). Without it, new CRDs from a chart bump do not land on existing clusters — only fresh installs get them.
+
+Do **not** set `CreateReplace` blindly: it overwrites every CRD in `crds/` and can cause silent data loss if upstream drops a field from a CRD that has live objects. Only enable it for operators whose schema evolution is additive-only. When in doubt, leave it unset and apply new CRDs manually.
+
 ### Documentation
 
 Documentation is organized as follows:

docs/changelogs/v1.3.1.md

@@ -0,0 +1,37 @@
+<!--
+https://github.com/cozystack/cozystack/releases/tag/v1.3.1
+-->
+
+# v1.3.1 (2026-04-28)
+
+Patch release covering a TenantNamespace IDOR fix in the API, a destructive `post-upgrade` hook removed from the etcd chart, kamaji controller stability, a `linstor-csi` bump that fixes live migration on Protocol-A/B DRBD resources, the missing `linstor-gui` build wiring, and a velero RBAC fix that unblocked installs on bundles without Velero.
+
+## Security
+
+* **fix(api): prevent IDOR in TenantNamespace Get and Watch handlers**: Two IDOR (Insecure Direct Object Reference) vulnerabilities allowed authenticated users to read TenantNamespace metadata they had no RoleBinding for. The `Get` and `Watch` handlers now go through a new `hasAccessToNamespace()` helper that lists RoleBindings scoped only to the target namespace (orders of magnitude faster than the previous all-cluster scan), returns `NotFound` instead of leaking existence on unauthorized access, and applies the same check on the `Watch` filter path. Includes regression tests for the unauthorized paths. ([**@IvanHunters**](https://github.com/IvanHunters) in #2471, backport #2524)
+
+## Features
+
+* **feat(linstor): bump linstor-csi to v1.10.6 with Protocol-C dual-attach fix**: Live migration of KubeVirt VMs on Protocol-A/B (async) DRBD volumes no longer fails with `Protocol C required`. `linstor-csi` v1.10.6 now installs a `Protocol=C` override on the resource-definition during dual-attach and reverts it on detach, so `replicated-async` StorageClasses and other Protocol-A/B resource groups support live migration without manual `drbdadm adjust` intervention. ([**@kvaps**](https://github.com/kvaps) in #2496, backport #2505)
+
+## Fixes
+
+* **fix(backups): move velero-configmap Role to velero chart**: The `backupstrategy-controller` (a default package) declared a Role/RoleBinding scoped to the `cozy-velero` namespace for managing `ResourceModifier` ConfigMaps. On bundles where Velero was not enabled, that namespace did not exist and the HelmRelease failed with `namespaces "cozy-velero" not found`, blocking installation. The Role/RoleBinding now lives in the velero chart, so it is created only when velero is actually deployed. ([**@myasnikovdaniil**](https://github.com/myasnikovdaniil) in #2459, backport #2467)
+
+* **fix(etcd): remove destructive post-upgrade cert-regeneration hook**: The etcd chart ran a `post-upgrade` Helm hook on every upgrade that deleted etcd TLS Secrets (`etcd-ca-tls`, `etcd-peer-ca-tls`, `etcd-client-tls`, `etcd-peer-tls`, `etcd-server-tls`) and then deleted etcd pods, forcing cert-manager to re-issue the entire etcd CA chain. On clusters with Kamaji-managed tenant control planes this put every tenant `kube-apiserver` into CrashLoopBackOff until each DataStore was manually re-reconciled. The hook was a one-shot `2.6.0 → 2.6.1` migration that became a permanent footgun once chart versioning moved to `0.0.0+<git-hash>` (always `< 2.6.1` per semver) and after the underlying `rotationPolicy: Always` issue was fixed in `47d81f70`. The hook is now removed entirely. ([**@myasnikovdaniil**](https://github.com/myasnikovdaniil) in #2462, backport #2511)
+
+* **fix(kamaji): increase memory limits and add startup probe**: The kamaji controller frequently entered CrashLoopBackOff due to OOMKills (exit 137) within ~20–25 seconds of startup, with the readiness probe failing while the controller was still finishing initialization. Memory limit raised from 500Mi to 512Mi, request from 100Mi to 256Mi, and a 60-second startup probe (12 attempts × 5s periods) is added so the controller has room to boot before liveness/readiness probes engage. ([**@IvanHunters**](https://github.com/IvanHunters) in #2421, backport #2491)
+
+## Build
+
+* **build(linstor): include linstor-gui in root image build target**: The `linstor-gui` package (added in #2382) was never wired into the root `Makefile`'s `build:` target, so CI never built or published the image. `ghcr.io/cozystack/cozystack/linstor-gui` returned `NAME_UNKNOWN` and `values.yaml` stayed pinned to `tag: 2.3.0` without a digest. The missing build line is added so the next CI run publishes the image and the per-package `Makefile` digest-pins `values.yaml` automatically. ([**@myasnikovdaniil**](https://github.com/myasnikovdaniil) in #2498, backport #2518)
+
+## Contributors
+
+Thanks to everyone who contributed to this patch release:
+
+* [**@IvanHunters**](https://github.com/IvanHunters)
+* [**@kvaps**](https://github.com/kvaps)
+* [**@myasnikovdaniil**](https://github.com/myasnikovdaniil)
+
+**Full Changelog**: https://github.com/cozystack/cozystack/compare/v1.3.0...v1.3.1

hack/admin-kubeconfig-invariant.bats

@@ -0,0 +1,145 @@
+#!/usr/bin/env bats
+# -----------------------------------------------------------------------------
+# Chart-wide invariant for packages/apps/kubernetes:
+#
+# Every Deployment in this chart that mounts <release>-admin-kubeconfig as a
+# Secret volume MUST:
+#   - declare that volume optional: true (so kubelet does not FailedMount
+#     while Kamaji is still provisioning the Secret), AND
+#   - include the wait-for-kubeconfig init container (so the pod becomes
+#     Ready only after Kamaji publishes the Secret).
+#
+# The per-template unittests in packages/apps/kubernetes/tests/ lock in
+# today's three Deployments (cluster-autoscaler, kccm, csi controller) by
+# name. This invariant is stricter: any future Deployment added to this
+# chart that mounts the same Secret but forgets the guard will fail here.
+#
+# Requires: helm, yq (mikefarah v4+), jq. All three are available on the
+# project's CI runners and on the maintainer workstation.
+# -----------------------------------------------------------------------------
+
+@test "every Deployment mounting admin-kubeconfig has optional:true and wait-for-kubeconfig init" {
+  values_file="packages/apps/kubernetes/tests/values-ci.yaml"
+  [ -f "$values_file" ]
+
+  tmp=$(mktemp -d)
+  trap 'rm -rf "$tmp"' EXIT
+
+  helm template invariant packages/apps/kubernetes \
+    --namespace tenant-root \
+    --values "$values_file" \
+    2>/dev/null > "$tmp/rendered.yaml"
+
+  # yq streams one JSON object per input document. jq -s slurps the stream
+  # into an array so we can treat all Deployments as a single collection.
+  yq --output-format=json eval-all '.' "$tmp/rendered.yaml" \
+    | jq -s --raw-output '
+        map(select(.kind == "Deployment")) |
+        map({
+          name: .metadata.name,
+          volumes: (.spec.template.spec.volumes // []),
+          initNames: ((.spec.template.spec.initContainers // []) | map(.name)),
+        }) |
+        map(
+          .name as $n |
+          .initNames as $ins |
+          (.volumes[] | select(.secret.secretName | test("-admin-kubeconfig$")?))
+          | {
+              name: $n,
+              optional: (.secret.optional == true),
+              hasInit: ($ins | index("wait-for-kubeconfig") != null),
+            }
+        )
+      ' > "$tmp/summary.json"
+
+  # At least one Deployment must match; if a refactor removes every
+  # admin-kubeconfig volume from this chart, the test must be updated
+  # deliberately rather than silently passing.
+  matched=$(jq 'length' "$tmp/summary.json")
+  [ "$matched" -ge 1 ]
+
+  offenders=$(jq --raw-output '.[] | select(.optional != true or .hasInit != true) | .name' "$tmp/summary.json")
+
+  if [ -n "$offenders" ]; then
+    echo "Deployments mounting *-admin-kubeconfig without optional:true + wait-for-kubeconfig init:" >&2
+    echo "$offenders" >&2
+    echo "Full summary:" >&2
+    cat "$tmp/summary.json" >&2
+    exit 1
+  fi
+
+  echo "Invariant holds for $matched Deployment(s)"
+}
+
+@test "chart emits zero admin-kubeconfig Deployments when tenant has no etcd DataStore" {
+  # Without a DataStore (parent Tenant has not populated _namespace.etcd yet)
+  # the control-plane-side Deployments must NOT render at all. If they did,
+  # the wait-for-kubeconfig init would CrashLoopBackOff indefinitely - there
+  # would be no KamajiControlPlane to provision the Secret - consuming the
+  # HelmRelease wait budget and triggering exactly the remediation cycle the
+  # rest of this chart tries to avoid. This test renders the whole chart
+  # with etcd empty and asserts no Deployment references the admin-kubeconfig
+  # Secret.
+  tmp=$(mktemp -d)
+  trap 'rm -rf "$tmp"' EXIT
+
+  helm template invariant packages/apps/kubernetes \
+    --namespace tenant-root \
+    --values packages/apps/kubernetes/tests/values-ci-no-etcd.yaml \
+    2>/dev/null > "$tmp/rendered.yaml"
+
+  matched=$(
+    yq --output-format=json eval-all '.' "$tmp/rendered.yaml" \
+      | jq -s '
+          map(select(.kind == "Deployment")) |
+          map(select(
+            (.spec.template.spec.volumes // [])
+              | any(.secret.secretName | test("-admin-kubeconfig$")?)
+          )) |
+          length
+        '
+  )
+
+  if [ "$matched" -ne 0 ]; then
+    echo "Expected zero Deployments mounting *-admin-kubeconfig when etcd is empty, got $matched:" >&2
+    yq --output-format=json eval-all '.' "$tmp/rendered.yaml" \
+      | jq -s 'map(select(.kind == "Deployment") | .metadata.name)' >&2
+    exit 1
+  fi
+
+  echo "No admin-kubeconfig Deployments rendered for empty etcd (as expected)"
+}
+
+@test "chart emits zero admin-kubeconfig HelmReleases when tenant has no etcd DataStore" {
+  # Same principle as the Deployment variant above, extended to every child
+  # HelmRelease (cilium, coredns, csi, cert-manager, ...). They reference
+  # *-admin-kubeconfig via kubeConfig.secretRef and would otherwise sit in
+  # NotReady forever on an etcd-less tenant, polluting the HelmRelease list
+  # the operator sees and contradicting the "awaiting-etcd beacon only"
+  # contract of the soft-skip path.
+  tmp=$(mktemp -d)
+  trap 'rm -rf "$tmp"' EXIT
+
+  helm template invariant packages/apps/kubernetes \
+    --namespace tenant-root \
+    --values packages/apps/kubernetes/tests/values-ci-no-etcd.yaml \
+    2>/dev/null > "$tmp/rendered.yaml"
+
+  matched=$(
+    yq --output-format=json eval-all '.' "$tmp/rendered.yaml" \
+      | jq -s '
+          map(select(.kind == "HelmRelease")) |
+          map(select(.spec.kubeConfig.secretRef.name | test("-admin-kubeconfig$")?)) |
+          length
+        '
+  )
+
+  if [ "$matched" -ne 0 ]; then
+    echo "Expected zero HelmReleases referencing *-admin-kubeconfig when etcd is empty, got $matched:" >&2
+    yq --output-format=json eval-all '.' "$tmp/rendered.yaml" \
+      | jq -s 'map(select(.kind == "HelmRelease") | .metadata.name)' >&2
+    exit 1
+  fi
+
+  echo "No admin-kubeconfig HelmReleases rendered for empty etcd (as expected)"
+}

hack/check-gpu-recording-rules.bats

@@ -0,0 +1,206 @@
+#!/usr/bin/env bats
+# -----------------------------------------------------------------------------
+# Cross-validation between GPU recording rules, the dashboards that consume
+# them, and the DCGM Exporter metric set the cluster actually scrapes. Catches:
+#
+#   1. dangling references — a dashboard query mentions a recording rule name
+#      that doesn't exist in gpu-recording.rules.yaml. This is the bug the
+#      pre-merge review caught: gpu-efficiency.json shipped panels keyed on
+#      pod:tensor_saturation:avg5m without the rule being defined, so the
+#      panel showed "No data" everywhere.
+#
+#   2. typos in rule names — same bug class, manifested as a single-character
+#      difference between rule and reference.
+#
+#   3. undeclared DCGM metrics — a dashboard query or recording rule mentions
+#      a DCGM_FI_* metric that is neither in the upstream default CSV nor in
+#      the project's custom CSV (dcgm-custom-metrics.yaml), meaning DCGM
+#      Exporter would never emit it and the panel silently shows "No data".
+#      Example regression: gpu-fleet.json shipped a TDP panel referencing
+#      DCGM_FI_DEV_POWER_MGMT_LIMIT before the custom CSV declared it.
+#
+# Scope: only dashboards listed in packages/system/monitoring/dashboards-infra.list
+# under the "gpu/" prefix (i.e. shipped to production), not every JSON file in
+# dashboards/gpu/. Untracked drafts stay out of scope on purpose — adding one
+# to dashboards-infra.list is what brings it under the test.
+#
+# Reverse direction (rule defined but never consumed) is intentionally NOT
+# enforced: some rules exist for ad-hoc PromQL or upcoming dashboards. Treat
+# unused rules as an editorial concern, not a regression.
+#
+# Title syntax constraints from cozytest.sh's awk parser:
+#   - Titles delimited by ASCII double quotes; embedded quotes truncate.
+#   - Only [A-Za-z0-9] from the title survives into the function name; titles
+#     differing only in punctuation collapse to the same function.
+#
+# Run with: hack/cozytest.sh hack/check-gpu-recording-rules.bats
+# -----------------------------------------------------------------------------
+
+REPO_ROOT="$(cd "$(dirname "${BATS_TEST_FILENAME:-$0}")/.." && pwd)"
+RULES_FILE="$REPO_ROOT/packages/system/monitoring-agents/alerts/gpu-recording.rules.yaml"
+DASHBOARDS_LIST="$REPO_ROOT/packages/system/monitoring/dashboards-infra.list"
+DASHBOARDS_DIR="$REPO_ROOT/dashboards"
+DCGM_DEFAULT_CSV="$REPO_ROOT/hack/dcgm-default-counters.csv"
+DCGM_CUSTOM_CSV="$REPO_ROOT/packages/system/gpu-operator/examples/dcgm-custom-metrics.yaml"
+
+# Extract the set of "- record: NAME" entries from the rules YAML.
+# Outputs one rule name per line, sorted and deduplicated.
+extract_rules() {
+  awk '/^[[:space:]]*-[[:space:]]*record:[[:space:]]/ {
+    sub(/^[[:space:]]*-[[:space:]]*record:[[:space:]]*/, "")
+    sub(/[[:space:]]*$/, "")
+    print
+  }' "$RULES_FILE" | sort -u
+}
+
+# Extract the set of recording-rule references from a dashboard JSON.
+# A recording-rule reference is matched by the pattern
+#   <segment>:<segment>(:<segment>)+
+# where each <segment> is [a-z0-9_]. Raw DCGM metrics (DCGM_FI_*),
+# kube-state-metrics (kube_*) and similar uppercase / single-word metric
+# names do not match because the leading segment must be lowercase and the
+# whole expression must contain at least two ':' characters.
+extract_refs() {
+  json_file=$1
+  # Prometheus convention allows 2-segment rule names (level:metric); this
+  # regex is tuned to the 3+ segment convention used in this repo
+  # (level:metric:op — e.g. cluster:gpu_count:total). Update if future
+  # rules use 2 segments, otherwise they will be silently skipped.
+  grep -hoE '[a-z][a-z0-9_]*:[a-z0-9_]+:[a-z0-9_]+' "$json_file" | sort -u
+}
+
+# Resolve "gpu/foo" -> "$DASHBOARDS_DIR/gpu/foo.json"
+list_tracked_gpu_dashboards() {
+  awk '/^gpu\// { print $0 ".json" }' "$DASHBOARDS_LIST"
+}
+
+# Extract the set of DCGM_FI_* metric names declared in a CSV file. Handles
+# both the upstream-style default CSV (unindented) and the ConfigMap-style
+# custom CSV (YAML-indented). A declaration line starts — after any leading
+# whitespace — with "DCGM_FI_<NAME>," ; comment lines begin with "#" and are
+# skipped. Uses POSIX awk's match()+RSTART/RLENGTH so no GNU extensions
+# are required.
+extract_csv_metrics() {
+  file=$1
+  awk '
+    {
+      line = $0
+      sub(/^[[:space:]]+/, "", line)
+      if (line ~ /^#/) next
+      if (match(line, /^DCGM_FI_[A-Z0-9_]+/)) {
+        print substr(line, RSTART, RLENGTH)
+      }
+    }
+  ' "$file" | sort -u
+}
+
+# Extract the set of DCGM_FI_* metric references from a text file (dashboard
+# JSON or rules YAML). A DCGM metric name has at least two underscore-delimited
+# segments after the "DCGM_FI_" prefix (e.g. DCGM_FI_DEV_GPU_UTIL, DCGM_FI_PROF_
+# PIPE_TENSOR_ACTIVE, DCGM_FI_DRIVER_VERSION). Requiring two segments keeps
+# the matcher from latching onto glob stubs like "DCGM_FI_DEV_*_VIOLATION" that
+# appear in comments.
+extract_dcgm_refs() {
+  file=$1
+  grep -hoE 'DCGM_FI_[A-Z0-9]+(_[A-Z0-9]+)+' "$file" | sort -u
+}
+
+@test "every recording rule reference in tracked GPU dashboards has a matching record" {
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+
+  extract_rules > "$TMP/rules.txt"
+  [ -s "$TMP/rules.txt" ] || { echo "no recording rules extracted from $RULES_FILE" >&2; exit 1; }
+
+  list_tracked_gpu_dashboards > "$TMP/dashboards.txt"
+  [ -s "$TMP/dashboards.txt" ] || { echo "no gpu/* dashboards listed in $DASHBOARDS_LIST" >&2; exit 1; }
+
+  failed=0
+  while IFS= read -r dashboard_rel; do
+    dashboard="$DASHBOARDS_DIR/$dashboard_rel"
+    if [ ! -f "$dashboard" ]; then
+      echo "ERROR: dashboard listed but file missing: $dashboard" >&2
+      failed=1
+      continue
+    fi
+
+    extract_refs "$dashboard" > "$TMP/refs.txt"
+    # comm -23: lines unique to refs.txt (referenced but not defined)
+    # Both inputs must be sorted; extract_* helpers already sort.
+    comm -23 "$TMP/refs.txt" "$TMP/rules.txt" > "$TMP/missing.txt"
+    if [ -s "$TMP/missing.txt" ]; then
+      echo "ERROR: $dashboard_rel references undefined recording rules:" >&2
+      sed 's/^/  - /' "$TMP/missing.txt" >&2
+      failed=1
+    fi
+  done < "$TMP/dashboards.txt"
+
+  [ "$failed" -eq 0 ]
+}
+
+@test "every DCGM metric referenced in tracked dashboards and rules is declared" {
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+
+  [ -f "$DCGM_DEFAULT_CSV" ] || { echo "missing $DCGM_DEFAULT_CSV" >&2; exit 1; }
+  [ -f "$DCGM_CUSTOM_CSV" ]  || { echo "missing $DCGM_CUSTOM_CSV"  >&2; exit 1; }
+
+  {
+    extract_csv_metrics "$DCGM_DEFAULT_CSV"
+    extract_csv_metrics "$DCGM_CUSTOM_CSV"
+  } | sort -u > "$TMP/declared.txt"
+  [ -s "$TMP/declared.txt" ] || { echo "no DCGM metrics extracted from CSVs" >&2; exit 1; }
+
+  list_tracked_gpu_dashboards > "$TMP/dashboards.txt"
+  [ -s "$TMP/dashboards.txt" ] || { echo "no gpu/* dashboards listed in $DASHBOARDS_LIST" >&2; exit 1; }
+
+  failed=0
+
+  # Dashboard coverage — every dashboard's DCGM references must resolve.
+  while IFS= read -r dashboard_rel; do
+    dashboard="$DASHBOARDS_DIR/$dashboard_rel"
+    [ -f "$dashboard" ] || continue  # handled by the existence test
+    extract_dcgm_refs "$dashboard" > "$TMP/refs.txt"
+    [ -s "$TMP/refs.txt" ] || continue  # dashboard relies entirely on recording rules
+    comm -23 "$TMP/refs.txt" "$TMP/declared.txt" > "$TMP/missing.txt"
+    if [ -s "$TMP/missing.txt" ]; then
+      echo "ERROR: $dashboard_rel references DCGM metrics not declared in any CSV:" >&2
+      sed 's/^/  - /' "$TMP/missing.txt" >&2
+      failed=1
+    fi
+  done < "$TMP/dashboards.txt"
+
+  # Rules coverage — recording rules consume DCGM directly, so their set
+  # must be declared too, otherwise derived series on every dashboard
+  # collapse to empty.
+  extract_dcgm_refs "$RULES_FILE" > "$TMP/rule-refs.txt"
+  if [ -s "$TMP/rule-refs.txt" ]; then
+    comm -23 "$TMP/rule-refs.txt" "$TMP/declared.txt" > "$TMP/rule-missing.txt"
+    if [ -s "$TMP/rule-missing.txt" ]; then
+      echo "ERROR: gpu-recording.rules.yaml references DCGM metrics not declared in any CSV:" >&2
+      sed 's/^/  - /' "$TMP/rule-missing.txt" >&2
+      failed=1
+    fi
+  fi
+
+  [ "$failed" -eq 0 ]
+}
+
+@test "every tracked GPU dashboard listed in dashboards-infra.list exists on disk" {
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+
+  list_tracked_gpu_dashboards > "$TMP/dashboards.txt"
+  [ -s "$TMP/dashboards.txt" ] || { echo "no gpu/* dashboards listed in $DASHBOARDS_LIST" >&2; exit 1; }
+
+  failed=0
+  while IFS= read -r dashboard_rel; do
+    dashboard="$DASHBOARDS_DIR/$dashboard_rel"
+    if [ ! -f "$dashboard" ]; then
+      echo "ERROR: $dashboard_rel listed in dashboards-infra.list but $dashboard does not exist" >&2
+      failed=1
+    fi
+  done < "$TMP/dashboards.txt"
+
+  [ "$failed" -eq 0 ]
+}

hack/dcgm-default-counters.csv

@@ -0,0 +1,104 @@
+# Snapshot of the upstream DCGM Exporter default-counters.csv used as a
+# fixture by hack/check-gpu-recording-rules.bats. The test verifies that
+# every DCGM_FI_* metric referenced by a tracked GPU dashboard is either
+# declared here (upstream defaults) or in
+# packages/system/gpu-operator/examples/dcgm-custom-metrics.yaml
+# (the project's custom CSV).
+#
+# Source: https://github.com/NVIDIA/dcgm-exporter/blob/4.1.1-4.0.4/etc/default-counters.csv
+# Pinned to the DCGM Exporter image tag shipped by the gpu-operator
+# chart under packages/system/gpu-operator/charts/gpu-operator/values.yaml
+# (dcgmExporter.version = 4.1.1-4.0.4-ubuntu22.04). When that image is
+# bumped, refresh this file from the matching tag in the NVIDIA/dcgm-exporter
+# repo and re-run `./hack/cozytest.sh hack/check-gpu-recording-rules.bats`.
+
+# Format
+# If line starts with a '#' it is considered a comment
+# DCGM FIELD, Prometheus metric type, help message
+
+# Clocks
+DCGM_FI_DEV_SM_CLOCK,  gauge, SM clock frequency (in MHz).
+DCGM_FI_DEV_MEM_CLOCK, gauge, Memory clock frequency (in MHz).
+
+# Temperature
+DCGM_FI_DEV_MEMORY_TEMP, gauge, Memory temperature (in C).
+DCGM_FI_DEV_GPU_TEMP,    gauge, GPU temperature (in C).
+
+# Power
+DCGM_FI_DEV_POWER_USAGE,              gauge, Power draw (in W).
+DCGM_FI_DEV_TOTAL_ENERGY_CONSUMPTION, counter, Total energy consumption since boot (in mJ).
+
+# PCIE
+# DCGM_FI_PROF_PCIE_TX_BYTES,  counter, Total number of bytes transmitted through PCIe TX via NVML.
+# DCGM_FI_PROF_PCIE_RX_BYTES,  counter, Total number of bytes received through PCIe RX via NVML.
+DCGM_FI_DEV_PCIE_REPLAY_COUNTER, counter, Total number of PCIe retries.
+
+# Utilization (the sample period varies depending on the product)
+DCGM_FI_DEV_GPU_UTIL,      gauge, GPU utilization (in %).
+DCGM_FI_DEV_MEM_COPY_UTIL, gauge, Memory utilization (in %).
+DCGM_FI_DEV_ENC_UTIL,      gauge, Encoder utilization (in %).
+DCGM_FI_DEV_DEC_UTIL ,     gauge, Decoder utilization (in %).
+
+# Errors and violations
+DCGM_FI_DEV_XID_ERRORS,              gauge,   Value of the last XID error encountered.
+# DCGM_FI_DEV_POWER_VIOLATION,       counter, Throttling duration due to power constraints (in us).
+# DCGM_FI_DEV_THERMAL_VIOLATION,     counter, Throttling duration due to thermal constraints (in us).
+# DCGM_FI_DEV_SYNC_BOOST_VIOLATION,  counter, Throttling duration due to sync-boost constraints (in us).
+# DCGM_FI_DEV_BOARD_LIMIT_VIOLATION, counter, Throttling duration due to board limit constraints (in us).
+# DCGM_FI_DEV_LOW_UTIL_VIOLATION,    counter, Throttling duration due to low utilization (in us).
+# DCGM_FI_DEV_RELIABILITY_VIOLATION, counter, Throttling duration due to reliability constraints (in us).
+
+# Memory usage
+DCGM_FI_DEV_FB_FREE, gauge, Framebuffer memory free (in MiB).
+DCGM_FI_DEV_FB_USED, gauge, Framebuffer memory used (in MiB).
+
+# ECC
+# DCGM_FI_DEV_ECC_SBE_VOL_TOTAL, counter, Total number of single-bit volatile ECC errors.
+# DCGM_FI_DEV_ECC_DBE_VOL_TOTAL, counter, Total number of double-bit volatile ECC errors.
+# DCGM_FI_DEV_ECC_SBE_AGG_TOTAL, counter, Total number of single-bit persistent ECC errors.
+# DCGM_FI_DEV_ECC_DBE_AGG_TOTAL, counter, Total number of double-bit persistent ECC errors.
+
+# Retired pages
+# DCGM_FI_DEV_RETIRED_SBE,     counter, Total number of retired pages due to single-bit errors.
+# DCGM_FI_DEV_RETIRED_DBE,     counter, Total number of retired pages due to double-bit errors.
+# DCGM_FI_DEV_RETIRED_PENDING, counter, Total number of pages pending retirement.
+
+# NVLink
+# DCGM_FI_DEV_NVLINK_CRC_FLIT_ERROR_COUNT_TOTAL, counter, Total number of NVLink flow-control CRC errors.
+# DCGM_FI_DEV_NVLINK_CRC_DATA_ERROR_COUNT_TOTAL, counter, Total number of NVLink data CRC errors.
+# DCGM_FI_DEV_NVLINK_REPLAY_ERROR_COUNT_TOTAL,   counter, Total number of NVLink retries.
+# DCGM_FI_DEV_NVLINK_RECOVERY_ERROR_COUNT_TOTAL, counter, Total number of NVLink recovery errors.
+DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL,            counter, Total number of NVLink bandwidth counters for all lanes.
+# DCGM_FI_DEV_NVLINK_BANDWIDTH_L0,               counter, The number of bytes of active NVLink rx or tx data including both header and payload.
+
+# VGPU License status
+DCGM_FI_DEV_VGPU_LICENSE_STATUS, gauge, vGPU License status
+
+# Remapped rows
+DCGM_FI_DEV_UNCORRECTABLE_REMAPPED_ROWS, counter, Number of remapped rows for uncorrectable errors
+DCGM_FI_DEV_CORRECTABLE_REMAPPED_ROWS,   counter, Number of remapped rows for correctable errors
+DCGM_FI_DEV_ROW_REMAP_FAILURE,           gauge,   Whether remapping of rows has failed
+
+# Static configuration information. These appear as labels on the other metrics
+DCGM_FI_DRIVER_VERSION,        label, Driver Version
+# DCGM_FI_NVML_VERSION,          label, NVML Version
+# DCGM_FI_DEV_BRAND,             label, Device Brand
+# DCGM_FI_DEV_SERIAL,            label, Device Serial Number
+# DCGM_FI_DEV_OEM_INFOROM_VER,   label, OEM inforom version
+# DCGM_FI_DEV_ECC_INFOROM_VER,   label, ECC inforom version
+# DCGM_FI_DEV_POWER_INFOROM_VER, label, Power management object inforom version
+# DCGM_FI_DEV_INFOROM_IMAGE_VER, label, Inforom image version
+# DCGM_FI_DEV_VBIOS_VERSION,     label, VBIOS version of the device
+
+# Datacenter Profiling (DCP) metrics
+# NOTE: supported on Nvidia datacenter Volta GPUs and newer
+DCGM_FI_PROF_GR_ENGINE_ACTIVE,   gauge, Ratio of time the graphics engine is active.
+# DCGM_FI_PROF_SM_ACTIVE,          gauge, The ratio of cycles an SM has at least 1 warp assigned.
+# DCGM_FI_PROF_SM_OCCUPANCY,       gauge, The ratio of number of warps resident on an SM.
+DCGM_FI_PROF_PIPE_TENSOR_ACTIVE, gauge, Ratio of cycles the tensor (HMMA) pipe is active.
+DCGM_FI_PROF_DRAM_ACTIVE,        gauge, Ratio of cycles the device memory interface is active sending or receiving data.
+# DCGM_FI_PROF_PIPE_FP64_ACTIVE,   gauge, Ratio of cycles the fp64 pipes are active.
+# DCGM_FI_PROF_PIPE_FP32_ACTIVE,   gauge, Ratio of cycles the fp32 pipes are active.
+# DCGM_FI_PROF_PIPE_FP16_ACTIVE,   gauge, Ratio of cycles the fp16 pipes are active.
+DCGM_FI_PROF_PCIE_TX_BYTES,      gauge, The rate of data transmitted over the PCIe bus - including both protocol headers and data payloads - in bytes per second.
+DCGM_FI_PROF_PCIE_RX_BYTES,      gauge, The rate of data received over the PCIe bus - including both protocol headers and data payloads - in bytes per second.

hack/e2e-apps/remediation-guard.sh

@@ -0,0 +1,39 @@
+# Helpers for asserting that a Flux HelmRelease did not fall into an
+# install/upgrade remediation cycle during an e2e run.
+#
+# Background: Flux helm-controller's ClearFailures() zeroes
+# .status.installFailures / .status.upgradeFailures on every successful
+# reconciliation (see the upstream ClearFailures method on
+# HelmReleaseStatus). That makes those counters useless for a guard that
+# runs after the HelmRelease has reached Ready - the values are always 0.
+#
+# What survives a successful reconciliation is .status.history, a bounded
+# list of release Snapshots. Each Snapshot carries a status field that
+# tracks the Helm release state: deployed, superseded, failed, uninstalled,
+# and so on. A remediation cycle leaves the footprint behind: a snapshot
+# with status "uninstalled" (from install/upgrade remediation) or "failed"
+# (Helm release failure that remediation then uninstalled). Those stay in
+# history even after a subsequent successful reinstall.
+#
+# helmrelease_has_remediation_cycle takes a newline-delimited list of
+# snapshot statuses (whatever the caller extracted via kubectl -o jsonpath
+# or equivalent) and returns 0 (detected) when any entry is "failed" or
+# "uninstalled", 1 otherwise. Empty input is treated as "no history yet,
+# no cycle observed".
+
+helmrelease_has_remediation_cycle() {
+    statuses="$1"
+    if [ -z "${statuses}" ]; then
+        return 1
+    fi
+    # printf + grep over the pipe, rather than a heredoc plus while read.
+    # printf %s treats the status string as a literal payload, so any stray
+    # $ in a future caller's input does not trigger shell expansion. grep
+    # returns 0 iff at least one line matches the allowlist, which is
+    # exactly the contract the caller wants, so we can return its exit
+    # status directly.
+    if printf '%s\n' "${statuses}" | grep --extended-regexp --quiet '^(failed|uninstalled)$'; then
+        return 0
+    fi
+    return 1
+}

hack/e2e-apps/run-kubernetes.sh

@@ -1,3 +1,5 @@
+. hack/e2e-apps/remediation-guard.sh
+
 run_kubernetes_test() {
     local version_expr="$1"
     local test_name="$2"
@@ -320,6 +322,35 @@ EOF
     done
     kubectl wait hr kubernetes-${test_name}-ingress-nginx -n tenant-test --timeout=5m --for=condition=ready
 
+  # Guard: parent HelmRelease must not have entered an install/upgrade remediation cycle.
+  # A non-zero installFailures/upgradeFailures indicates the helm-wait budget expired while
+  # admin-kubeconfig was still being provisioned, which would trigger uninstall remediation
+  # and churn the Cluster CR.
+  # Flux helm-controller v2 retains per-revision release Snapshots in
+  # .status.history; each Snapshot's .status reflects the Helm release
+  # state (deployed/superseded/failed/uninstalled). A remediation cycle
+  # leaves a "failed" or "uninstalled" entry behind that survives a later
+  # successful reinstall, unlike the installFailures/upgradeFailures
+  # counters (which ClearFailures zeroes on every successful reconcile).
+  # The shape is pinned by hack/remediation-guard.bats; the upstream
+  # types are github.com/fluxcd/helm-controller/api v2 Snapshot.
+  history_statuses=$(kubectl get hr -n tenant-test "kubernetes-${test_name}" \
+    -ojsonpath='{range .status.history[*]}{.status}{"\n"}{end}')
+  # Always emit the raw value so a silent future-Flux field rename shows
+  # up as "empty history on a Ready HR" in CI logs rather than vanishing.
+  echo "Parent HelmRelease history statuses:"
+  printf '%s\n' "${history_statuses:-<empty>}"
+  if [ -z "${history_statuses}" ]; then
+    echo "Unexpected empty .status.history on a Ready HelmRelease - Flux API shape may have changed." >&2
+    kubectl -n tenant-test describe hr "kubernetes-${test_name}" >&2
+    exit 1
+  fi
+  if helmrelease_has_remediation_cycle "${history_statuses}"; then
+    echo "Parent HelmRelease entered remediation cycle." >&2
+    kubectl -n tenant-test describe hr "kubernetes-${test_name}" >&2
+    exit 1
+  fi
+
   # Clean up
   pkill -f "port-forward.*${port}:" 2>/dev/null || true
   rm -f "tenantkubeconfig-${test_name}"

hack/remediation-guard.bats

@@ -0,0 +1,127 @@
+#!/usr/bin/env bats
+# -----------------------------------------------------------------------------
+# Unit tests for hack/e2e-apps/remediation-guard.sh
+#
+# helmrelease_has_remediation_cycle takes a newline-delimited list of
+# HelmRelease history snapshot status values (deployed/superseded/failed/
+# uninstalled/...) and returns 0 when any entry is "failed" or "uninstalled"
+# (meaning flux helm-controller performed install/upgrade remediation).
+#
+# This is used by the e2e script after the HelmRelease reaches Ready. The
+# failure/upgrade counters (.status.installFailures / .status.upgradeFailures)
+# are useless there because flux's ClearFailures zeroes them on successful
+# reconciliation; .status.history retains the snapshot trail.
+#
+# cozytest.sh's awk parser recognizes only @test blocks and a bare `}` on
+# its own line; there is no bats `run` or `$status`. Assertions are
+# expressed as direct shell tests that exit non-zero on failure.
+#
+# Run with: hack/cozytest.sh hack/remediation-guard.bats
+# -----------------------------------------------------------------------------
+
+@test "empty history returns not-detected" {
+    . hack/e2e-apps/remediation-guard.sh
+    if helmrelease_has_remediation_cycle ""; then
+        echo "expected not-detected for empty history" >&2
+        exit 1
+    fi
+}
+
+@test "single deployed snapshot returns not-detected" {
+    . hack/e2e-apps/remediation-guard.sh
+    if helmrelease_has_remediation_cycle "deployed"; then
+        echo "expected not-detected for deployed-only history" >&2
+        exit 1
+    fi
+}
+
+@test "deployed then superseded returns not-detected" {
+    . hack/e2e-apps/remediation-guard.sh
+    statuses=$(printf 'deployed\nsuperseded\n')
+    if helmrelease_has_remediation_cycle "${statuses}"; then
+        echo "expected not-detected for deployed+superseded history" >&2
+        exit 1
+    fi
+}
+
+@test "single failed snapshot returns detected" {
+    . hack/e2e-apps/remediation-guard.sh
+    if ! helmrelease_has_remediation_cycle "failed"; then
+        echo "expected detected when history contains failed snapshot" >&2
+        exit 1
+    fi
+}
+
+@test "single uninstalled snapshot returns detected" {
+    # The exact signature of the install-remediation race: the first install
+    # exceeded flux's wait budget, remediation uninstalled, the next retry
+    # eventually succeeded. History still carries the uninstalled snapshot.
+    . hack/e2e-apps/remediation-guard.sh
+    if ! helmrelease_has_remediation_cycle "uninstalled"; then
+        echo "expected detected when history contains uninstalled snapshot" >&2
+        exit 1
+    fi
+}
+
+@test "uninstalled then deployed still returns detected" {
+    . hack/e2e-apps/remediation-guard.sh
+    statuses=$(printf 'uninstalled\ndeployed\n')
+    if ! helmrelease_has_remediation_cycle "${statuses}"; then
+        echo "expected detected despite later successful deploy" >&2
+        exit 1
+    fi
+}
+
+@test "deployed then failed still returns detected" {
+    . hack/e2e-apps/remediation-guard.sh
+    statuses=$(printf 'deployed\nfailed\n')
+    if ! helmrelease_has_remediation_cycle "${statuses}"; then
+        echo "expected detected when any entry is failed" >&2
+        exit 1
+    fi
+}
+
+@test "status.history extraction pins HR v2 status.history shape" {
+    # Pins the Flux HelmRelease v2 .status.history[].status shape that
+    # run-kubernetes.sh relies on. If a future flux release renames the
+    # field, the jsonpath returns nothing, the guard reports no cycle,
+    # and real remediation loops slip past the e2e assertion. This test
+    # uses yq to read the exact path used in the e2e script; the upstream
+    # Snapshot type lives at
+    # github.com/fluxcd/helm-controller/api/v2.Snapshot (via go.mod).
+    tmp=$(mktemp -d)
+    trap 'rm -rf "$tmp"' EXIT
+
+    cat > "$tmp/hr.yaml" <<'YAML'
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: kubernetes-test
+  namespace: tenant-test
+status:
+  history:
+    - name: kubernetes-test
+      namespace: tenant-test
+      version: 1
+      status: uninstalled
+    - name: kubernetes-test
+      namespace: tenant-test
+      version: 2
+      status: deployed
+YAML
+
+    # Default yq output is yaml scalar format, which for string values emits
+    # bare unquoted tokens - matching what kubectl -o jsonpath produces in
+    # e2e. Do not switch to JSON output here; that would quote the values
+    # and break the loop in helmrelease_has_remediation_cycle.
+    statuses=$(yq '.status.history[].status' "$tmp/hr.yaml")
+
+    [ -n "$statuses" ]
+    echo "$statuses" | grep --quiet '^uninstalled$'
+
+    . hack/e2e-apps/remediation-guard.sh
+    if ! helmrelease_has_remediation_cycle "$statuses"; then
+        echo "expected detected for pinned HR snippet with uninstalled + deployed history" >&2
+        exit 1
+    fi
+}

internal/crdinstall/manifests/cozystack.io_packagesources.yaml

@@ -118,6 +118,19 @@ spec:
                                   ReleaseName is the name of the HelmRelease resource that will be created
                                   If not specified, defaults to the component Name field
                                 type: string
+                              upgradeCRDs:
+                                description: |-
+                                  UpgradeCRDs controls how CRDs from the chart's crds/ directory are
+                                  handled on HelmRelease upgrades. Maps to HelmRelease.Spec.Upgrade.CRDs.
+                                  Empty string (default) preserves the helm-controller default (Skip).
+                                  Use "CreateReplace" for operators that evolve their CRD set between
+                                  versions. Warning: CreateReplace overwrites CRDs and may cause data
+                                  loss if upstream drops fields from a CRD with live objects.
+                                enum:
+                                - Skip
+                                - Create
+                                - CreateReplace
+                                type: string
                             type: object
                           libraries:
                             description: |-

internal/operator/package_reconciler.go

@@ -45,6 +45,16 @@ const (
 	SecretCozystackValues = "cozystack-values"
 )
 
+// parseCRDPolicy maps ComponentInstall.UpgradeCRDs to a helmv2.CRDsPolicy.
+// Empty / nil preserves the helm-controller default (Skip on upgrade);
+// the CRD enum marker restricts the string to Skip/Create/CreateReplace.
+func parseCRDPolicy(install *cozyv1alpha1.ComponentInstall) helmv2.CRDsPolicy {
+	if install == nil || install.UpgradeCRDs == "" {
+		return ""
+	}
+	return helmv2.CRDsPolicy(install.UpgradeCRDs)
+}
+
 // PackageReconciler reconciles Package resources
 type PackageReconciler struct {
 	client.Client
@@ -221,6 +231,7 @@ func (r *PackageReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ct
 					Remediation: &helmv2.UpgradeRemediation{
 						Retries: -1,
 					},
+					CRDs: parseCRDPolicy(component.Install),
 				},
 			},
 		}

internal/operator/package_reconciler_test.go

@@ -0,0 +1,138 @@
+/*
+Copyright 2025 The Cozystack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package operator
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	cozyv1alpha1 "github.com/cozystack/cozystack/api/v1alpha1"
+	helmv2 "github.com/fluxcd/helm-controller/api/v2"
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	"sigs.k8s.io/yaml"
+)
+
+func TestParseCRDPolicy(t *testing.T) {
+	tests := []struct {
+		name    string
+		install *cozyv1alpha1.ComponentInstall
+		want    helmv2.CRDsPolicy
+	}{
+		{
+			name:    "nil install leaves flux default",
+			install: nil,
+			want:    "",
+		},
+		{
+			name:    "empty upgradeCRDs leaves flux default",
+			install: &cozyv1alpha1.ComponentInstall{},
+			want:    "",
+		},
+		{
+			name:    "Skip is passed through",
+			install: &cozyv1alpha1.ComponentInstall{UpgradeCRDs: "Skip"},
+			want:    helmv2.Skip,
+		},
+		{
+			name:    "Create is passed through",
+			install: &cozyv1alpha1.ComponentInstall{UpgradeCRDs: "Create"},
+			want:    helmv2.Create,
+		},
+		{
+			name:    "CreateReplace is passed through",
+			install: &cozyv1alpha1.ComponentInstall{UpgradeCRDs: "CreateReplace"},
+			want:    helmv2.CreateReplace,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := parseCRDPolicy(tc.install)
+			if got != tc.want {
+				t.Errorf("parseCRDPolicy() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestPackageSourceCRDHasUpgradeCRDsEnum guards the generated CRD schema: the
+// invalid-value case from the spec is enforced at the API server via a
+// kubebuilder enum marker, not in the reconciler. If someone drops the marker
+// and forgets to regenerate, this test catches it.
+func TestPackageSourceCRDHasUpgradeCRDsEnum(t *testing.T) {
+	path := filepath.Join("..", "crdinstall", "manifests", "cozystack.io_packagesources.yaml")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+
+	var crd apiextensionsv1.CustomResourceDefinition
+	if err := yaml.Unmarshal(data, &crd); err != nil {
+		t.Fatalf("unmarshal CRD: %v", err)
+	}
+
+	var field *apiextensionsv1.JSONSchemaProps
+	for i := range crd.Spec.Versions {
+		v := &crd.Spec.Versions[i]
+		if v.Schema == nil || v.Schema.OpenAPIV3Schema == nil {
+			continue
+		}
+		spec, ok := v.Schema.OpenAPIV3Schema.Properties["spec"]
+		if !ok {
+			continue
+		}
+		variants, ok := spec.Properties["variants"]
+		if !ok || variants.Items == nil || variants.Items.Schema == nil {
+			continue
+		}
+		components, ok := variants.Items.Schema.Properties["components"]
+		if !ok || components.Items == nil || components.Items.Schema == nil {
+			continue
+		}
+		install, ok := components.Items.Schema.Properties["install"]
+		if !ok {
+			continue
+		}
+		f, ok := install.Properties["upgradeCRDs"]
+		if !ok {
+			continue
+		}
+		field = &f
+		break
+	}
+
+	if field == nil {
+		t.Fatal("upgradeCRDs field not found in PackageSource CRD schema")
+	}
+
+	got := map[string]bool{}
+	for _, e := range field.Enum {
+		var s string
+		if err := json.Unmarshal(e.Raw, &s); err != nil {
+			t.Fatalf("unmarshal enum value %q: %v", e.Raw, err)
+		}
+		got[s] = true
+	}
+
+	for _, want := range []string{"Skip", "Create", "CreateReplace"} {
+		if !got[want] {
+			t.Errorf("enum value %q missing from upgradeCRDs; got %v", want, got)
+		}
+	}
+}

packages/apps/kubernetes/Makefile

@@ -4,6 +4,9 @@ KUBERNETES_PKG_TAG = $(shell awk '$$1 == "version:" {print $$2}' Chart.yaml)
 include ../../../hack/common-envs.mk
 include ../../../hack/package.mk
 
+test:
+	helm unittest .
+
 generate:
 	cozyvalues-gen -m 'kubernetes' -v values.yaml -s values.schema.json -r README.md -g ../../../api/apps/v1alpha1/kubernetes/types.go
 	../../../hack/update-crd.sh
@@ -67,3 +70,4 @@ image-cluster-autoscaler:
 	echo "$(REGISTRY)/cluster-autoscaler:$(call settag,$(KUBERNETES_PKG_TAG))@$$(yq e '."containerimage.digest"' images/cluster-autoscaler.json -o json -r)" \
 		> images/cluster-autoscaler.tag
 	rm -f images/cluster-autoscaler.json
+

packages/apps/kubernetes/README.md

@@ -128,6 +128,9 @@ See the reference for components utilized in this service:
 | `addons.gpuOperator`                          | NVIDIA GPU Operator.                                                        | `object`   | `{}`      |
 | `addons.gpuOperator.enabled`                  | Enable GPU Operator.                                                        | `bool`     | `false`   |
 | `addons.gpuOperator.valuesOverride`           | Custom Helm values overrides.                                               | `object`   | `{}`      |
+| `addons.hami`                                 | HAMi GPU virtualization middleware.                                         | `object`   | `{}`      |
+| `addons.hami.enabled`                         | Enable HAMi (requires GPU Operator).                                        | `bool`     | `false`   |
+| `addons.hami.valuesOverride`                  | Custom Helm values overrides.                                               | `object`   | `{}`      |
 | `addons.fluxcd`                               | FluxCD GitOps operator.                                                     | `object`   | `{}`      |
 | `addons.fluxcd.enabled`                       | Enable FluxCD.                                                              | `bool`     | `false`   |
 | `addons.fluxcd.valuesOverride`                | Custom Helm values overrides.                                               | `object`   | `{}`      |
@@ -145,31 +148,33 @@ See the reference for components utilized in this service:
 
 ### Kubernetes Control Plane Configuration
 
-| Name                                                | Description                                      | Type       | Value   |
-| --------------------------------------------------- | ------------------------------------------------ | ---------- | ------- |
-| `controlPlane`                                      | Kubernetes control-plane configuration.          | `object`   | `{}`    |
-| `controlPlane.replicas`                             | Number of control-plane replicas.                | `int`      | `2`     |
-| `controlPlane.apiServer`                            | API Server configuration.                        | `object`   | `{}`    |
-| `controlPlane.apiServer.resources`                  | CPU and memory resources for API Server.         | `object`   | `{}`    |
-| `controlPlane.apiServer.resources.cpu`              | CPU available.                                   | `quantity` | `""`    |
-| `controlPlane.apiServer.resources.memory`           | Memory (RAM) available.                          | `quantity` | `""`    |
-| `controlPlane.apiServer.resourcesPreset`            | Preset if `resources` omitted.                   | `string`   | `large` |
-| `controlPlane.controllerManager`                    | Controller Manager configuration.                | `object`   | `{}`    |
-| `controlPlane.controllerManager.resources`          | CPU and memory resources for Controller Manager. | `object`   | `{}`    |
-| `controlPlane.controllerManager.resources.cpu`      | CPU available.                                   | `quantity` | `""`    |
-| `controlPlane.controllerManager.resources.memory`   | Memory (RAM) available.                          | `quantity` | `""`    |
-| `controlPlane.controllerManager.resourcesPreset`    | Preset if `resources` omitted.                   | `string`   | `micro` |
-| `controlPlane.scheduler`                            | Scheduler configuration.                         | `object`   | `{}`    |
-| `controlPlane.scheduler.resources`                  | CPU and memory resources for Scheduler.          | `object`   | `{}`    |
-| `controlPlane.scheduler.resources.cpu`              | CPU available.                                   | `quantity` | `""`    |
-| `controlPlane.scheduler.resources.memory`           | Memory (RAM) available.                          | `quantity` | `""`    |
-| `controlPlane.scheduler.resourcesPreset`            | Preset if `resources` omitted.                   | `string`   | `micro` |
-| `controlPlane.konnectivity`                         | Konnectivity configuration.                      | `object`   | `{}`    |
-| `controlPlane.konnectivity.server`                  | Konnectivity Server configuration.               | `object`   | `{}`    |
-| `controlPlane.konnectivity.server.resources`        | CPU and memory resources for Konnectivity.       | `object`   | `{}`    |
-| `controlPlane.konnectivity.server.resources.cpu`    | CPU available.                                   | `quantity` | `""`    |
-| `controlPlane.konnectivity.server.resources.memory` | Memory (RAM) available.                          | `quantity` | `""`    |
-| `controlPlane.konnectivity.server.resourcesPreset`  | Preset if `resources` omitted.                   | `string`   | `micro` |
+| Name                                                | Description                                                                                   | Type       | Value   |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | ------- |
+| `controlPlane`                                      | Kubernetes control-plane configuration.                                                       | `object`   | `{}`    |
+| `controlPlane.replicas`                             | Number of control-plane replicas.                                                             | `int`      | `2`     |
+| `controlPlane.apiServer`                            | API Server configuration.                                                                     | `object`   | `{}`    |
+| `controlPlane.apiServer.resources`                  | CPU and memory resources for API Server.                                                      | `object`   | `{}`    |
+| `controlPlane.apiServer.resources.cpu`              | CPU available.                                                                                | `quantity` | `""`    |
+| `controlPlane.apiServer.resources.memory`           | Memory (RAM) available.                                                                       | `quantity` | `""`    |
+| `controlPlane.apiServer.resourcesPreset`            | Preset if `resources` omitted.                                                                | `string`   | `large` |
+| `controlPlane.controllerManager`                    | Controller Manager configuration.                                                             | `object`   | `{}`    |
+| `controlPlane.controllerManager.resources`          | CPU and memory resources for Controller Manager.                                              | `object`   | `{}`    |
+| `controlPlane.controllerManager.resources.cpu`      | CPU available.                                                                                | `quantity` | `""`    |
+| `controlPlane.controllerManager.resources.memory`   | Memory (RAM) available.                                                                       | `quantity` | `""`    |
+| `controlPlane.controllerManager.resourcesPreset`    | Preset if `resources` omitted.                                                                | `string`   | `micro` |
+| `controlPlane.scheduler`                            | Scheduler configuration.                                                                      | `object`   | `{}`    |
+| `controlPlane.scheduler.resources`                  | CPU and memory resources for Scheduler.                                                       | `object`   | `{}`    |
+| `controlPlane.scheduler.resources.cpu`              | CPU available.                                                                                | `quantity` | `""`    |
+| `controlPlane.scheduler.resources.memory`           | Memory (RAM) available.                                                                       | `quantity` | `""`    |
+| `controlPlane.scheduler.resourcesPreset`            | Preset if `resources` omitted.                                                                | `string`   | `micro` |
+| `controlPlane.konnectivity`                         | Konnectivity configuration.                                                                   | `object`   | `{}`    |
+| `controlPlane.konnectivity.server`                  | Konnectivity Server configuration.                                                            | `object`   | `{}`    |
+| `controlPlane.konnectivity.server.resources`        | CPU and memory resources for Konnectivity.                                                    | `object`   | `{}`    |
+| `controlPlane.konnectivity.server.resources.cpu`    | CPU available.                                                                                | `quantity` | `""`    |
+| `controlPlane.konnectivity.server.resources.memory` | Memory (RAM) available.                                                                       | `quantity` | `""`    |
+| `controlPlane.konnectivity.server.resourcesPreset`  | Preset if `resources` omitted.                                                                | `string`   | `micro` |
+| `images`                                            | Optional image overrides for air-gapped or rate-limited registries.                           | `object`   | `{}`    |
+| `images.waitForKubeconfig`                          | Image used by the wait-for-kubeconfig init container. Empty falls back to images/busybox.tag. | `string`   | `""`    |
 
 
 ## Parameter examples and reference

packages/apps/kubernetes/images/busybox.tag

@@ -0,0 +1 @@
+docker.io/library/busybox:1.37.0@sha256:1487d0af5f52b4ba31c7e465126ee2123fe3f2305d638e7827681e7cf6c83d5e

packages/apps/kubernetes/templates/_helpers.tpl

@@ -49,3 +49,52 @@ Selector labels
 app.kubernetes.io/name: {{ include "kubernetes.name" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end }}
+
+{{/*
+wait-for-kubeconfig init container shared by the control-plane-side
+Deployments (cluster-autoscaler, kccm, kcsi-controller) that mount the
+*-admin-kubeconfig Secret provisioned asynchronously by Kamaji. The
+Secret volume is declared optional so kubelet does not FailedMount while
+Kamaji is still bootstrapping; this container polls the mounted path and
+exits only when super-admin.svc appears, which happens after kubelet's
+optional-Secret refresh cycle.
+
+The 10m deadline stays strictly below the 15m HelmRelease
+Install.Timeout set by cozystack-api for the Kubernetes kind (via the
+release.cozystack.io/helm-install-timeout annotation) so the
+CrashLoopBackOff surfaces before flux remediation fires and uninstalls
+the Cluster CR.
+
+The default image lives in images/busybox.tag and points directly at
+docker.io by digest (not mirrored to ghcr.io like the other .tag files
+here): the payload is a one-shot sh loop and the digest pin makes the
+pull immutable. Operators in air-gapped or rate-limited environments
+can override it via .Values.images.waitForKubeconfig (any registry
+reference kubelet can pull). When the value is empty the chart falls
+back to the bundled digest pin, preserving the prior default.
+
+Call site owns the surrounding volumes block; the kubeconfig volume
+must exist on the pod and mount at /etc/kubernetes/kubeconfig.
+*/}}
+{{- define "kubernetes.waitForAdminKubeconfig" -}}
+- name: wait-for-kubeconfig
+  image: "{{ default (.Files.Get "images/busybox.tag" | trim) .Values.images.waitForKubeconfig }}"
+  command:
+  - sh
+  - -c
+  - |
+    set -eu
+    deadline=$(( $(date +%s) + 600 ))
+    until [ -s /etc/kubernetes/kubeconfig/super-admin.svc ]; do
+      if [ "$(date +%s)" -ge "$deadline" ]; then
+        echo "admin kubeconfig was not provisioned within 10m; exiting so the pod goes CrashLoopBackOff and surfaces in dashboards" >&2
+        exit 1
+      fi
+      echo "waiting for admin kubeconfig (provisioned by Kamaji, visible after kubelet Secret refresh)..."
+      sleep 5
+    done
+  volumeMounts:
+  - name: kubeconfig
+    mountPath: /etc/kubernetes/kubeconfig
+    readOnly: true
+{{- end }}

packages/apps/kubernetes/templates/cluster-autoscaler/deployment.yaml

@@ -1,3 +1,14 @@
+{{- /*
+  Gate the control-plane-side workloads on the parent tenant having an etcd
+  DataStore. Without it no KamajiControlPlane is ever created, Kamaji never
+  provisions -admin-kubeconfig, and rendering these Deployments would cause
+  the wait-for-kubeconfig init to CrashLoopBackOff indefinitely, consuming
+  the parent HelmRelease install timeout and triggering the very uninstall
+  remediation cycle this chart is supposed to avoid. Rendering them only
+  when $etcd is set keeps the HelmRelease Ready while flux retries on its
+  interval and picks up the DataStore as soon as the Tenant chart finishes.
+*/}}
+{{- if .Values._namespace.etcd }}
 ---
 apiVersion: apps/v1
 kind: Deployment
@@ -23,6 +34,8 @@ spec:
         - key: node-role.kubernetes.io/control-plane
           operator: Exists
           effect: "NoSchedule"
+      initContainers:
+      {{- include "kubernetes.waitForAdminKubeconfig" $ | nindent 6 }}
       containers:
       - image: "{{ $.Files.Get "images/cluster-autoscaler.tag" | trim }}"
         name: cluster-autoscaler
@@ -56,6 +69,7 @@ spec:
         name: cloud-config
       - secret:
           secretName: {{ .Release.Name }}-admin-kubeconfig
+          optional: true
         name: kubeconfig
       serviceAccountName: {{ .Release.Name }}-cluster-autoscaler
       terminationGracePeriodSeconds: 10
@@ -105,3 +119,4 @@ rules:
     - list
     - update
     - watch
+{{- end }}

packages/apps/kubernetes/templates/cluster.yaml

@@ -1,4 +1,15 @@
 {{- $etcd := .Values._namespace.etcd }}
+{{- /*
+  When $etcd is empty, the parent Tenant application has not populated
+  _namespace.etcd in cozystack-values yet - either the operator forgot to
+  set etcd: true on an ancestor Tenant, or the Tenant HelmRelease is still
+  reconciling. Either way, rendering a KamajiControlPlane with an empty
+  dataStoreName would be rejected by Kamaji's admission webhook and the
+  HelmRelease would fail to install, triggering remediation. Instead, emit
+  a single ConfigMap as a user-visible status beacon and skip the rest so
+  flux marks the HelmRelease Ready and retries its 5m reconcile loop until
+  the Tenant chart catches up.
+*/}}
 {{- $ingress := .Values._namespace.ingress }}
 {{- $host := .Values._namespace.host }}
 {{- $kubevirtmachinetemplateNames := list }}
@@ -84,6 +95,26 @@ spec:
           - name: default
             pod: {}
 {{- end }}
+{{- if not $etcd }}
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ .Release.Name }}-awaiting-etcd
+  namespace: {{ .Release.Namespace }}
+  labels:
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+    app.kubernetes.io/name: kubernetes
+    app.kubernetes.io/instance: {{ .Release.Name }}
+data:
+  status: "awaiting-etcd"
+  message: |
+    No DataStore is available for this tenant Kubernetes cluster. The parent
+    Tenant application has not populated _namespace.etcd. Set spec.etcd: true
+    on an ancestor Tenant (usually tenant-root) and wait for its HelmRelease
+    to reconcile - this HelmRelease will pick up the DataStore on its next
+    5m reconcile loop and provision the cluster.
+{{- else }}
 ---
 apiVersion: cluster.x-k8s.io/v1beta1
 kind: Cluster
@@ -404,3 +435,4 @@ metadata:
 spec:
   {{- .spec | toYaml | nindent 2 }}
 {{- end }}
+{{- end }}

packages/apps/kubernetes/templates/csi/deploy.yaml

@@ -1,3 +1,4 @@
+{{- if .Values._namespace.etcd }}
 kind: Deployment
 apiVersion: apps/v1
 metadata:
@@ -24,6 +25,8 @@ spec:
         - key: node-role.kubernetes.io/control-plane
           operator: Exists
           effect: "NoSchedule"
+      initContainers:
+      {{- include "kubernetes.waitForAdminKubeconfig" $ | nindent 6 }}
       containers:
         - name: csi-driver
           imagePullPolicy: Always
@@ -234,4 +237,6 @@ spec:
           emptyDir: {}
         - secret:
             secretName: {{ .Release.Name }}-admin-kubeconfig
+            optional: true
           name: kubeconfig
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/cert-manager-crds.yaml

@@ -1,4 +1,4 @@
-{{- if .Values.addons.certManager.enabled }}
+{{- if and .Values.addons.certManager.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/cert-manager.yaml

@@ -8,7 +8,7 @@ cert-manager:
 {{- end }}
 {{- end }}
 
-{{- if .Values.addons.certManager.enabled }}
+{{- if and .Values.addons.certManager.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/cilium.yaml

@@ -14,6 +14,7 @@ cilium:
   {{- end }}
 {{- end }}
 
+{{- if .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -55,3 +56,4 @@ spec:
   - name: {{ .Release.Name }}-gateway-api-crds
     namespace: {{ .Release.Namespace }}
   {{- end }}
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/coredns.yaml

@@ -4,6 +4,7 @@ coredns:
     clusterIP: "10.95.0.10"
 {{- end }}
 
+{{- if .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -42,3 +43,4 @@ spec:
   {{- end }}
   - name: {{ .Release.Name }}-cilium
     namespace: {{ .Release.Namespace }}
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/csi.yaml

@@ -1,3 +1,4 @@
+{{- if .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -39,3 +40,4 @@ spec:
   - name: {{ .Release.Name }}
     namespace: {{ .Release.Namespace }}
   {{- end }}
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/fluxcd.yaml

@@ -1,4 +1,4 @@
-{{- if .Values.addons.fluxcd.enabled }}
+{{- if and .Values.addons.fluxcd.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/gateway-api-crds.yaml

@@ -1,4 +1,4 @@
-{{- if $.Values.addons.gatewayAPI.enabled }}
+{{- if and $.Values.addons.gatewayAPI.enabled $.Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/gpu-operator.yaml

@@ -1,4 +1,12 @@
-{{- if .Values.addons.gpuOperator.enabled }}
+{{- define "cozystack.defaultGpuOperatorValues" -}}
+{{- if .Values.addons.hami.enabled }}
+gpu-operator:
+  devicePlugin:
+    enabled: false
+{{- end }}
+{{- end }}
+
+{{- if and .Values.addons.gpuOperator.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -29,9 +37,12 @@ spec:
     force: true
     remediation:
       retries: -1
-  {{- with .Values.addons.gpuOperator.valuesOverride }}
+  {{- $defaults := fromYaml (include "cozystack.defaultGpuOperatorValues" .) }}
+  {{- $overrides := deepCopy (default (dict) .Values.addons.gpuOperator.valuesOverride) }}
+  {{- $merged := mergeOverwrite (default (dict) $defaults) $overrides }}
+  {{- if $merged }}
   values:
-    {{- toYaml . | nindent 4 }}
+    {{- toYaml $merged | nindent 4 }}
   {{- end }}
 
   dependsOn:

packages/apps/kubernetes/templates/helmreleases/hami.yaml

@@ -0,0 +1,49 @@
+{{- if and .Values.addons.hami.enabled .Values._namespace.etcd }}
+{{- if not .Values.addons.gpuOperator.enabled }}
+{{- fail "addons.hami requires addons.gpuOperator to be enabled" }}
+{{- end }}
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: {{ .Release.Name }}-hami
+  labels:
+    cozystack.io/repository: system
+    cozystack.io/target-cluster-name: {{ .Release.Name }}
+    sharding.fluxcd.io/key: tenants
+spec:
+  releaseName: hami
+  chartRef:
+    kind: ExternalArtifact
+    name: cozystack-kubernetes-application-kubevirt-kubernetes-hami
+    namespace: cozy-system
+  kubeConfig:
+    secretRef:
+      name: {{ .Release.Name }}-admin-kubeconfig
+      key: super-admin.svc
+  targetNamespace: cozy-hami
+  storageNamespace: cozy-hami
+  interval: 5m
+  timeout: 10m
+  install:
+    createNamespace: true
+    remediation:
+      retries: -1
+  upgrade:
+    force: true
+    remediation:
+      retries: -1
+  {{- with .Values.addons.hami.valuesOverride }}
+  values:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+
+  dependsOn:
+  {{- if lookup "helm.toolkit.fluxcd.io/v2" "HelmRelease" .Release.Namespace .Release.Name }}
+  - name: {{ .Release.Name }}
+    namespace: {{ .Release.Namespace }}
+  {{- end }}
+  - name: {{ .Release.Name }}-cilium
+    namespace: {{ .Release.Namespace }}
+  - name: {{ .Release.Name }}-gpu-operator
+    namespace: {{ .Release.Namespace }}
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/ingress-nginx.yaml

@@ -20,7 +20,7 @@ ingress-nginx:
     node-role.kubernetes.io/ingress-nginx: ""
 {{- end }}
 
-{{- if .Values.addons.ingressNginx.enabled }}
+{{- if and .Values.addons.ingressNginx.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/metrics-server.yaml

@@ -1,3 +1,4 @@
+{{- if .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -36,3 +37,4 @@ spec:
     namespace: {{ .Release.Namespace }}
   - name: {{ .Release.Name }}-prometheus-operator-crds
     namespace: {{ .Release.Namespace }}
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/monitoring-agents.yaml

@@ -1,6 +1,6 @@
 {{- $targetTenant := .Values._namespace.monitoring }}
 {{- $clusterDomain := (index .Values._cluster "cluster-domain") | default "cozy.local" }}
-{{- if .Values.addons.monitoringAgents.enabled }}
+{{- if and .Values.addons.monitoringAgents.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/prometheus-operator-crds.yaml

@@ -1,3 +1,4 @@
+{{- if .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -31,3 +32,4 @@ spec:
   - name: {{ .Release.Name }}
     namespace: {{ .Release.Namespace }}
   {{- end }}
+{{- end }}

packages/apps/kubernetes/templates/helmreleases/velero.yaml

@@ -1,4 +1,4 @@
-{{- if .Values.addons.velero.enabled }}
+{{- if and .Values.addons.velero.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/vertical-pod-autoscaler-crds.yaml

@@ -1,4 +1,4 @@
-{{- if .Values.addons.monitoringAgents.enabled }}
+{{- if and .Values.addons.monitoringAgents.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/vertical-pod-autoscaler.yaml

@@ -24,7 +24,7 @@ vertical-pod-autoscaler:
         memory: 1600Mi
 {{- end }}
 
-{{- if .Values.addons.monitoringAgents.enabled }}
+{{- if and .Values.addons.monitoringAgents.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/victoria-metrics-operator.yaml

@@ -1,4 +1,4 @@
-{{- if .Values.addons.monitoringAgents.enabled }}
+{{- if and .Values.addons.monitoringAgents.enabled .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:

packages/apps/kubernetes/templates/helmreleases/volumesnapshot-crd.yaml

@@ -1,3 +1,4 @@
+{{- if .Values._namespace.etcd }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -33,3 +34,4 @@ spec:
   - name: {{ .Release.Name }}
     namespace: {{ .Release.Namespace }}
   {{- end }}
+{{- end }}

packages/apps/kubernetes/templates/kccm/manager.yaml

@@ -1,3 +1,4 @@
+{{- if .Values._namespace.etcd }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -22,6 +23,8 @@ spec:
         - key: node-role.kubernetes.io/control-plane
           operator: Exists
           effect: "NoSchedule"
+      initContainers:
+      {{- include "kubernetes.waitForAdminKubeconfig" $ | nindent 6 }}
       containers:
       - name: kubevirt-cloud-controller-manager
         args:
@@ -55,5 +58,7 @@ spec:
         name: cloud-config
       - secret:
           secretName: {{ .Release.Name }}-admin-kubeconfig
+          optional: true
         name: kubeconfig
       serviceAccountName: {{ .Release.Name }}-kccm
+{{- end }}

packages/apps/kubernetes/tests/admin_kubeconfig_wait_test.yaml

@@ -0,0 +1,155 @@
+suite: admin-kubeconfig wait guards
+
+release:
+  name: test
+  namespace: tenant-root
+
+values:
+  - values-ci.yaml
+
+tests:
+  - it: cluster-autoscaler mounts admin-kubeconfig as optional
+    template: templates/cluster-autoscaler/deployment.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - equal:
+          path: spec.template.spec.volumes[?(@.name=="kubeconfig")].secret.secretName
+          value: test-admin-kubeconfig
+      - equal:
+          path: spec.template.spec.volumes[?(@.name=="kubeconfig")].secret.optional
+          value: true
+
+  - it: cluster-autoscaler waits for admin-kubeconfig via initContainer
+    template: templates/cluster-autoscaler/deployment.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - equal:
+          path: spec.template.spec.initContainers[0].name
+          value: wait-for-kubeconfig
+      - contains:
+          path: spec.template.spec.initContainers[0].volumeMounts
+          content:
+            name: kubeconfig
+            mountPath: /etc/kubernetes/kubeconfig
+            readOnly: true
+
+  - it: kccm mounts admin-kubeconfig as optional
+    template: templates/kccm/manager.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - equal:
+          path: spec.template.spec.volumes[?(@.name=="kubeconfig")].secret.secretName
+          value: test-admin-kubeconfig
+      - equal:
+          path: spec.template.spec.volumes[?(@.name=="kubeconfig")].secret.optional
+          value: true
+
+  - it: kccm waits for admin-kubeconfig via initContainer
+    template: templates/kccm/manager.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - equal:
+          path: spec.template.spec.initContainers[0].name
+          value: wait-for-kubeconfig
+      - contains:
+          path: spec.template.spec.initContainers[0].volumeMounts
+          content:
+            name: kubeconfig
+            mountPath: /etc/kubernetes/kubeconfig
+            readOnly: true
+
+  - it: csi controller mounts admin-kubeconfig as optional
+    template: templates/csi/deploy.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - equal:
+          path: spec.template.spec.volumes[?(@.name=="kubeconfig")].secret.secretName
+          value: test-admin-kubeconfig
+      - equal:
+          path: spec.template.spec.volumes[?(@.name=="kubeconfig")].secret.optional
+          value: true
+
+  - it: csi controller waits for admin-kubeconfig via initContainer
+    template: templates/csi/deploy.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - equal:
+          path: spec.template.spec.initContainers[0].name
+          value: wait-for-kubeconfig
+      - contains:
+          path: spec.template.spec.initContainers[0].volumeMounts
+          content:
+            name: kubeconfig
+            mountPath: /etc/kubernetes/kubeconfig
+            readOnly: true
+
+  - it: wait-for-kubeconfig defaults to bundled busybox digest pin
+    template: templates/cluster-autoscaler/deployment.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    asserts:
+      - matchRegex:
+          path: spec.template.spec.initContainers[0].image
+          pattern: '^docker\.io/library/busybox:[^@]+@sha256:[0-9a-f]{64}$'
+
+  - it: wait-for-kubeconfig honours images.waitForKubeconfig override
+    template: templates/cluster-autoscaler/deployment.yaml
+    documentSelector:
+      path: kind
+      value: Deployment
+    set:
+      images:
+        waitForKubeconfig: "registry.example.test/library/busybox:1.37.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    asserts:
+      - equal:
+          path: spec.template.spec.initContainers[0].image
+          value: "registry.example.test/library/busybox:1.37.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+
+  - it: cluster.yaml renders and wires dataStoreName when tenant has etcd
+    template: templates/cluster.yaml
+    documentSelector:
+      path: kind
+      value: KamajiControlPlane
+    asserts:
+      - equal:
+          path: spec.dataStoreName
+          value: tenant-root
+
+  - it: cluster.yaml skips Cluster resources when tenant has no etcd DataStore
+    # Must NOT fail rendering - the parent Tenant chart populates
+    # _namespace.etcd asynchronously, so rendering failures here would cause
+    # flux install remediation on every cold bootstrap. Instead, emit only a
+    # ConfigMap status beacon so the HelmRelease reports Ready while flux
+    # retries on its interval until the DataStore appears.
+    template: templates/cluster.yaml
+    set:
+      _namespace:
+        etcd: ""
+        monitoring: ""
+        ingress: ""
+        seaweedfs: ""
+        host: ""
+    asserts:
+      - hasDocuments:
+          count: 1
+      - isKind:
+          of: ConfigMap
+      - equal:
+          path: metadata.name
+          value: test-awaiting-etcd
+      - equal:
+          path: data.status
+          value: awaiting-etcd

packages/apps/kubernetes/tests/gpu_operator_hami_test.yaml

@@ -0,0 +1,99 @@
+suite: GPU Operator HelmRelease HAMi integration tests
+templates:
+  - templates/helmreleases/gpu-operator.yaml
+values:
+  - values-ci.yaml
+tests:
+  - it: should disable devicePlugin when hami is enabled
+    set:
+      addons:
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+        hami:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: spec.values.gpu-operator.devicePlugin.enabled
+          value: false
+
+  - it: should not have values when hami is disabled and no overrides
+    set:
+      addons:
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+        hami:
+          enabled: false
+          valuesOverride: {}
+    asserts:
+      - notExists:
+          path: spec.values
+
+  - it: should apply hami defaults when valuesOverride key is omitted
+    set:
+      addons:
+        gpuOperator:
+          enabled: true
+        hami:
+          enabled: true
+    asserts:
+      - equal:
+          path: spec.values.gpu-operator.devicePlugin.enabled
+          value: false
+
+  - it: should allow user overrides to merge with hami defaults
+    set:
+      addons:
+        gpuOperator:
+          enabled: true
+          valuesOverride:
+            gpu-operator:
+              driver:
+                enabled: false
+        hami:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: spec.values.gpu-operator.devicePlugin.enabled
+          value: false
+      - equal:
+          path: spec.values.gpu-operator.driver.enabled
+          value: false
+
+  - it: should let user explicitly override devicePlugin.enabled to true with hami enabled
+    set:
+      addons:
+        gpuOperator:
+          enabled: true
+          valuesOverride:
+            gpu-operator:
+              devicePlugin:
+                enabled: true
+              driver:
+                enabled: false
+        hami:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: spec.values.gpu-operator.devicePlugin.enabled
+          value: true
+      - equal:
+          path: spec.values.gpu-operator.driver.enabled
+          value: false
+
+  - it: should not render when gpuOperator is disabled
+    set:
+      addons:
+        gpuOperator:
+          enabled: false
+          valuesOverride: {}
+        hami:
+          enabled: false
+          valuesOverride: {}
+    asserts:
+      - hasDocuments:
+          count: 0

packages/apps/kubernetes/tests/hami_test.yaml

@@ -0,0 +1,153 @@
+suite: HAMi HelmRelease tests
+templates:
+  - templates/helmreleases/hami.yaml
+values:
+  - values-ci.yaml
+tests:
+  - it: should not render when hami is disabled
+    set:
+      addons:
+        hami:
+          enabled: false
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: should render HelmRelease when hami is enabled
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - hasDocuments:
+          count: 1
+      - isKind:
+          of: HelmRelease
+
+  - it: should fail when gpuOperator is not enabled
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: false
+          valuesOverride: {}
+    asserts:
+      - failedTemplate:
+          errorMessage: "addons.hami requires addons.gpuOperator to be enabled"
+
+  - it: should have correct metadata labels
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: metadata.labels["cozystack.io/repository"]
+          value: system
+      - equal:
+          path: metadata.labels["sharding.fluxcd.io/key"]
+          value: tenants
+
+  - it: should use ExternalArtifact chartRef
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: spec.chartRef.kind
+          value: ExternalArtifact
+      - equal:
+          path: spec.chartRef.namespace
+          value: cozy-system
+
+  - it: should target cozy-hami namespace
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: spec.targetNamespace
+          value: cozy-hami
+      - equal:
+          path: spec.storageNamespace
+          value: cozy-hami
+
+  - it: should depend on gpu-operator and cilium
+    release:
+      name: test
+      namespace: test-ns
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - contains:
+          path: spec.dependsOn
+          content:
+            name: test-cilium
+            namespace: test-ns
+      - contains:
+          path: spec.dependsOn
+          content:
+            name: test-gpu-operator
+            namespace: test-ns
+
+  - it: should not render spec.values when valuesOverride is empty
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride: {}
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - hasDocuments:
+          count: 1
+      - notExists:
+          path: spec.values
+
+  - it: should pass through valuesOverride
+    set:
+      addons:
+        hami:
+          enabled: true
+          valuesOverride:
+            hami:
+              devicePlugin:
+                deviceSplitCount: 5
+        gpuOperator:
+          enabled: true
+          valuesOverride: {}
+    asserts:
+      - equal:
+          path: spec.values.hami.devicePlugin.deviceSplitCount
+          value: 5

packages/apps/kubernetes/tests/values-ci-no-etcd.yaml

@@ -0,0 +1,9 @@
+_namespace:
+  etcd: ""
+  monitoring: ""
+  ingress: ""
+  seaweedfs: ""
+  host: ""
+_cluster:
+  cluster-domain: cozy.local
+nodeGroups: null

packages/apps/kubernetes/tests/values-ci.yaml

@@ -0,0 +1,9 @@
+_namespace:
+  etcd: tenant-root
+  monitoring: ""
+  ingress: ""
+  seaweedfs: ""
+  host: ""
+_cluster:
+  cluster-domain: cozy.local
+nodeGroups: null

packages/apps/kubernetes/values.schema.json

@@ -149,6 +149,7 @@
         "fluxcd",
         "gatewayAPI",
         "gpuOperator",
+        "hami",
         "ingressNginx",
         "monitoringAgents",
         "velero",
@@ -268,6 +269,28 @@
             }
           }
         },
+        "hami": {
+          "description": "HAMi GPU virtualization middleware.",
+          "type": "object",
+          "default": {},
+          "required": [
+            "enabled",
+            "valuesOverride"
+          ],
+          "properties": {
+            "enabled": {
+              "description": "Enable HAMi (requires GPU Operator).",
+              "type": "boolean",
+              "default": false
+            },
+            "valuesOverride": {
+              "description": "Custom Helm values overrides.",
+              "type": "object",
+              "default": {},
+              "x-kubernetes-preserve-unknown-fields": true
+            }
+          }
+        },
         "ingressNginx": {
           "description": "Ingress-NGINX controller.",
           "type": "object",
@@ -630,6 +653,18 @@
           }
         }
       }
+    },
+    "images": {
+      "description": "Optional image overrides for air-gapped or rate-limited registries.",
+      "type": "object",
+      "default": {},
+      "properties": {
+        "waitForKubeconfig": {
+          "description": "Image used by the wait-for-kubeconfig init container. Empty falls back to images/busybox.tag.",
+          "type": "string",
+          "default": ""
+        }
+      }
     }
   }
 }

packages/apps/kubernetes/values.yaml

@@ -94,6 +94,10 @@ host: ""
 ## @field {bool} enabled - Enable FluxCD.
 ## @field {object} valuesOverride - Custom Helm values overrides.
 
+## @typedef {struct} HAMiAddon - HAMi GPU virtualization middleware.
+## @field {bool} enabled - Enable HAMi (requires GPU Operator).
+## @field {object} valuesOverride - Custom Helm values overrides.
+
 ## @typedef {struct} MonitoringAgentsAddon - Monitoring agents (Fluent Bit, VMAgents).
 ## @field {bool} enabled - Enable monitoring agents.
 ## @field {object} valuesOverride - Custom Helm values overrides.
@@ -114,6 +118,7 @@ host: ""
 ## @field {GatewayAPIAddon} gatewayAPI - Gateway API addon.
 ## @field {IngressNginxAddon} ingressNginx - Ingress-NGINX controller.
 ## @field {GPUOperatorAddon} gpuOperator - NVIDIA GPU Operator.
+## @field {HAMiAddon} hami - HAMi GPU virtualization middleware.
 ## @field {FluxCDAddon} fluxcd - FluxCD GitOps operator.
 ## @field {MonitoringAgentsAddon} monitoringAgents - Monitoring agents.
 ## @field {VerticalPodAutoscalerAddon} verticalPodAutoscaler - Vertical Pod Autoscaler.
@@ -137,6 +142,9 @@ addons:
   gpuOperator:
     enabled: false
     valuesOverride: {}
+  hami:
+    enabled: false
+    valuesOverride: {}
   fluxcd:
     enabled: false
     valuesOverride: {}
@@ -197,3 +205,10 @@ controlPlane:
     server:
       resources: {}
       resourcesPreset: "micro"
+
+## @typedef {struct} Images - Optional image overrides for chart-internal helpers.
+## @field {string} [waitForKubeconfig] - Image used by the wait-for-kubeconfig init container. Empty falls back to images/busybox.tag.
+
+## @param {Images} images - Optional image overrides for air-gapped or rate-limited registries.
+images:
+  waitForKubeconfig: ""

packages/apps/postgres/README.md

@@ -133,12 +133,13 @@ See:
 
 ### Bootstrap (recovery) parameters
 
-| Name                     | Description                                                         | Type     | Value   |
-| ------------------------ | ------------------------------------------------------------------- | -------- | ------- |
-| `bootstrap`              | Bootstrap configuration.                                            | `object` | `{}`    |
-| `bootstrap.enabled`      | Whether to restore from a backup.                                   | `bool`   | `false` |
-| `bootstrap.recoveryTime` | Timestamp (RFC3339) for point-in-time recovery; empty means latest. | `string` | `""`    |
-| `bootstrap.oldName`      | Previous cluster name before deletion.                              | `string` | `""`    |
+| Name                     | Description                                                                                                                                                                                                                  | Type     | Value   |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `bootstrap`              | Bootstrap configuration.                                                                                                                                                                                                     | `object` | `{}`    |
+| `bootstrap.enabled`      | Whether to restore from a backup.                                                                                                                                                                                            | `bool`   | `false` |
+| `bootstrap.recoveryTime` | Timestamp (RFC3339) for point-in-time recovery; empty means latest.                                                                                                                                                          | `string` | `""`    |
+| `bootstrap.oldName`      | Previous cluster name before deletion.                                                                                                                                                                                       | `string` | `""`    |
+| `bootstrap.serverName`   | Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name. | `string` | `""`    |
 
 
 ## Parameter examples and reference

packages/apps/postgres/templates/db.yaml

@@ -32,6 +32,9 @@ spec:
     - name: {{ .Values.bootstrap.oldName }}
       barmanObjectStore:
         destinationPath: {{ .Values.backup.destinationPath }}
+        {{- if .Values.bootstrap.serverName }}
+        serverName: {{ .Values.bootstrap.serverName }}
+        {{- end }}
         endpointURL: {{ .Values.backup.endpointURL }}
         s3Credentials:
           accessKeyId:

packages/apps/postgres/values.schema.json

@@ -254,6 +254,11 @@
           "description": "Timestamp (RFC3339) for point-in-time recovery; empty means latest.",
           "type": "string",
           "default": ""
+        },
+        "serverName": {
+          "description": "Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name.",
+          "type": "string",
+          "default": ""
         }
       }
     }

packages/apps/postgres/values.yaml

@@ -154,6 +154,7 @@ backup:
 ## @field {bool} enabled - Whether to restore from a backup.
 ## @field {string} [recoveryTime] - Timestamp (RFC3339) for point-in-time recovery; empty means latest.
 ## @field {string} oldName - Previous cluster name before deletion.
+## @field {string} [serverName] - Barman server name (S3 path prefix) used by the original cluster when writing backups. Set this only when the original cluster had an explicit barmanObjectStore.serverName that differed from its Kubernetes resource name.
 
 ## @param {Bootstrap} bootstrap - Bootstrap configuration.
 bootstrap:
@@ -161,3 +162,4 @@ bootstrap:
   # example: 2020-11-26 15:22:00.00000+00
   recoveryTime: ""
   oldName: ""
+  serverName: ""

packages/apps/tenant/Makefile

@@ -3,3 +3,6 @@ include ../../../hack/package.mk
 generate:
 	cozyvalues-gen -m 'tenant' -v values.yaml -s values.schema.json -r README.md -g ../../../api/apps/v1alpha1/tenant/types.go
 	../../../hack/update-crd.sh
+
+test:
+	helm unittest .

packages/apps/tenant/templates/cilium-lb-pool.yaml

@@ -0,0 +1,28 @@
+{{- $exposeMode := (index .Values._cluster "expose-mode") | default "externalIPs" }}
+{{- $exposeIngress := (index .Values._cluster "expose-ingress") | default "tenant-root" }}
+{{- $exposeIPs := (index .Values._cluster "expose-external-ips") | default "" | nospace }}
+{{- $ipsList := list }}
+{{- range splitList "," $exposeIPs }}
+  {{- $ip := . | trim }}
+  {{- if $ip }}
+    {{- $ipsList = append $ipsList $ip }}
+  {{- end }}
+{{- end }}
+{{- $isPublishingIngressLB := and
+      (eq $exposeMode "loadBalancer")
+      (eq $exposeIngress .Release.Namespace)
+      .Values.ingress }}
+{{- if and $isPublishingIngressLB $ipsList }}
+apiVersion: cilium.io/v2
+kind: CiliumLoadBalancerIPPool
+metadata:
+  name: {{ trimPrefix "tenant-" .Release.Namespace }}-exposure
+spec:
+  blocks:
+  {{- range $ipsList }}
+  - cidr: {{ . }}{{ if not (contains "/" .) }}/{{ if contains ":" . }}128{{ else }}32{{ end }}{{ end }}
+  {{- end }}
+  serviceSelector:
+    matchLabels:
+      "io.kubernetes.service.namespace": {{ .Release.Namespace | quote }}
+{{- end }}

packages/apps/tenant/tests/exposure_test.yaml

@@ -0,0 +1,141 @@
+suite: tenant CiliumLoadBalancerIPPool rendering for publishing.exposure=loadBalancer
+templates:
+  - templates/cilium-lb-pool.yaml
+
+release:
+  name: tenant-root
+  namespace: tenant-root
+
+tests:
+  - it: default exposure (externalIPs) renders no pool
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,192.0.2.11"
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: loadBalancer mode in publishing tenant with ingress=true renders v2 pool with namespace-only selector
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,192.0.2.11"
+        expose-mode: loadBalancer
+    asserts:
+      - hasDocuments:
+          count: 1
+      - equal:
+          path: apiVersion
+          value: cilium.io/v2
+      - equal:
+          path: kind
+          value: CiliumLoadBalancerIPPool
+      - equal:
+          path: metadata.name
+          value: root-exposure
+      - equal:
+          path: spec.blocks
+          value:
+            - cidr: 192.0.2.10/32
+            - cidr: 192.0.2.11/32
+      - equal:
+          path: spec.serviceSelector.matchLabels["io.kubernetes.service.namespace"]
+          value: tenant-root
+      - notExists:
+          path: spec.serviceSelector.matchLabels["app.kubernetes.io/name"]
+
+  - it: loadBalancer mode with IPv6 emits /128 CIDR
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "2001:db8::1"
+        expose-mode: loadBalancer
+    asserts:
+      - equal:
+          path: spec.blocks
+          value:
+            - cidr: 2001:db8::1/128
+
+  - it: loadBalancer mode with mixed IPv4 and IPv6 emits correct CIDR per family
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,2001:db8::1"
+        expose-mode: loadBalancer
+    asserts:
+      - equal:
+          path: spec.blocks
+          value:
+            - cidr: 192.0.2.10/32
+            - cidr: 2001:db8::1/128
+
+  - it: loadBalancer mode accepts pre-CIDR input without double-suffixing
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10/32,2001:db8::1/128"
+        expose-mode: loadBalancer
+    asserts:
+      - equal:
+          path: spec.blocks
+          value:
+            - cidr: 192.0.2.10/32
+            - cidr: 2001:db8::1/128
+
+  - it: loadBalancer mode filters out empty entries from externalIPs (trailing, leading, repeated commas)
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,,192.0.2.11,"
+        expose-mode: loadBalancer
+    asserts:
+      - hasDocuments:
+          count: 1
+      - equal:
+          path: spec.blocks
+          value:
+            - cidr: 192.0.2.10/32
+            - cidr: 192.0.2.11/32
+
+  - it: loadBalancer mode with ingress=false in publishing tenant renders no pool
+    set:
+      ingress: false
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+        expose-mode: loadBalancer
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: loadBalancer mode in a non-publishing tenant renders no pool
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+        expose-mode: loadBalancer
+    release:
+      name: tenant-u1
+      namespace: tenant-u1
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: loadBalancer mode in publishing tenant with empty externalIPs renders no pool
+    set:
+      ingress: true
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: ""
+        expose-mode: loadBalancer
+    asserts:
+      - hasDocuments:
+          count: 0

packages/apps/vm-instance/README.md

@@ -36,31 +36,32 @@ virtctl ssh <user>@<vm>
 
 ### Common parameters
 
-| Name                | Description                                                                                                                       | Type       | Value       |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- |
-| `external`          | Enable external access from outside the cluster.                                                                                  | `bool`     | `false`     |
-| `externalMethod`    | Method to pass through traffic to the VM.                                                                                         | `string`   | `PortList`  |
-| `externalPorts`     | Ports to forward from outside the cluster.                                                                                        | `[]int`    | `[22]`      |
-| `runStrategy`       | Requested running state of the VirtualMachineInstance                                                                             | `string`   | `Always`    |
-| `instanceType`      | Virtual Machine instance type.                                                                                                    | `string`   | `u1.medium` |
-| `instanceProfile`   | Virtual Machine preferences profile.                                                                                              | `string`   | `ubuntu`    |
-| `disks`             | List of disks to attach.                                                                                                          | `[]object` | `[]`        |
-| `disks[i].name`     | Disk name.                                                                                                                        | `string`   | `""`        |
-| `disks[i].bus`      | Disk bus type (e.g. "sata").                                                                                                      | `string`   | `""`        |
-| `networks`          | Networks to attach the VM to.                                                                                                     | `[]object` | `[]`        |
-| `networks[i].name`  | Network attachment name.                                                                                                          | `string`   | `""`        |
-| `subnets`           | Deprecated: use networks instead.                                                                                                 | `[]object` | `[]`        |
-| `subnets[i].name`   | Network attachment name.                                                                                                          | `string`   | `""`        |
-| `gpus`              | List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM).                                                               | `[]object` | `[]`        |
-| `gpus[i].name`      | The name of the GPU resource to attach.                                                                                           | `string`   | `""`        |
-| `cpuModel`          | Model specifies the CPU model inside the VMI. List of available models https://github.com/libvirt/libvirt/tree/master/src/cpu_map | `string`   | `""`        |
-| `resources`         | Resource configuration for the virtual machine.                                                                                   | `object`   | `{}`        |
-| `resources.cpu`     | Number of CPU cores allocated.                                                                                                    | `quantity` | `""`        |
-| `resources.memory`  | Amount of memory allocated.                                                                                                       | `quantity` | `""`        |
-| `resources.sockets` | Number of CPU sockets (vCPU topology).                                                                                            | `quantity` | `""`        |
-| `sshKeys`           | List of SSH public keys for authentication.                                                                                       | `[]string` | `[]`        |
-| `cloudInit`         | Cloud-init user data.                                                                                                             | `string`   | `""`        |
-| `cloudInitSeed`     | Seed string to generate SMBIOS UUID for the VM.                                                                                   | `string`   | `""`        |
+| Name                | Description                                                                                                                                                                                                   | Type       | Value       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- |
+| `external`          | Enable external access from outside the cluster.                                                                                                                                                              | `bool`     | `false`     |
+| `externalMethod`    | Method to pass through traffic to the VM.                                                                                                                                                                     | `string`   | `PortList`  |
+| `externalPorts`     | Ports to forward from outside the cluster.                                                                                                                                                                    | `[]int`    | `[22]`      |
+| `externalAllowICMP` | Whether to accept ICMP traffic to the VM in PortList mode (preserves ping and PMTU discovery). No effect in WholeIP mode. Default true so ping behaves as users expect even when port filtering is in effect. | `bool`     | `true`      |
+| `runStrategy`       | Requested running state of the VirtualMachineInstance                                                                                                                                                         | `string`   | `Always`    |
+| `instanceType`      | Virtual Machine instance type.                                                                                                                                                                                | `string`   | `u1.medium` |
+| `instanceProfile`   | Virtual Machine preferences profile.                                                                                                                                                                          | `string`   | `ubuntu`    |
+| `disks`             | List of disks to attach.                                                                                                                                                                                      | `[]object` | `[]`        |
+| `disks[i].name`     | Disk name.                                                                                                                                                                                                    | `string`   | `""`        |
+| `disks[i].bus`      | Disk bus type (e.g. "sata").                                                                                                                                                                                  | `string`   | `""`        |
+| `networks`          | Networks to attach the VM to.                                                                                                                                                                                 | `[]object` | `[]`        |
+| `networks[i].name`  | Network attachment name.                                                                                                                                                                                      | `string`   | `""`        |
+| `subnets`           | Deprecated: use networks instead.                                                                                                                                                                             | `[]object` | `[]`        |
+| `subnets[i].name`   | Network attachment name.                                                                                                                                                                                      | `string`   | `""`        |
+| `gpus`              | List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM).                                                                                                                                           | `[]object` | `[]`        |
+| `gpus[i].name`      | The name of the GPU resource to attach.                                                                                                                                                                       | `string`   | `""`        |
+| `cpuModel`          | Model specifies the CPU model inside the VMI. List of available models https://github.com/libvirt/libvirt/tree/master/src/cpu_map                                                                             | `string`   | `""`        |
+| `resources`         | Resource configuration for the virtual machine.                                                                                                                                                               | `object`   | `{}`        |
+| `resources.cpu`     | Number of CPU cores allocated.                                                                                                                                                                                | `quantity` | `""`        |
+| `resources.memory`  | Amount of memory allocated.                                                                                                                                                                                   | `quantity` | `""`        |
+| `resources.sockets` | Number of CPU sockets (vCPU topology).                                                                                                                                                                        | `quantity` | `""`        |
+| `sshKeys`           | List of SSH public keys for authentication.                                                                                                                                                                   | `[]string` | `[]`        |
+| `cloudInit`         | Cloud-init user data.                                                                                                                                                                                         | `string`   | `""`        |
+| `cloudInitSeed`     | Seed string to generate SMBIOS UUID for the VM.                                                                                                                                                               | `string`   | `""`        |
 
 
 ## U Series

packages/apps/vm-instance/templates/service.yaml

@@ -9,7 +9,10 @@ metadata:
 {{- if .Values.external }}
     service.kubernetes.io/service-proxy-name: "cozy-proxy"
   annotations:
-    networking.cozystack.io/wholeIP: "true"
+    networking.cozystack.io/wholeIP: {{ ternary "true" "false" (eq .Values.externalMethod "WholeIP") | quote }}
+    {{- if eq .Values.externalMethod "PortList" }}
+    networking.cozystack.io/allowICMP: {{ ternary "true" "false" (ne .Values.externalAllowICMP false) | quote }}
+    {{- end }}
 {{- end }}
 spec:
   type: {{ ternary "LoadBalancer" "ClusterIP" .Values.external }}

packages/apps/vm-instance/values.schema.json

@@ -26,6 +26,11 @@
         "type": "integer"
       }
     },
+    "externalAllowICMP": {
+      "description": "Whether to accept ICMP traffic to the VM in PortList mode (preserves ping and PMTU discovery). No effect in WholeIP mode. Default true so ping behaves as users expect even when port filtering is in effect.",
+      "type": "boolean",
+      "default": true
+    },
     "runStrategy": {
       "description": "Requested running state of the VirtualMachineInstance",
       "type": "string",

packages/apps/vm-instance/values.yaml

@@ -31,6 +31,9 @@ externalMethod: PortList
 externalPorts:
 - 22
 
+## @param {bool} externalAllowICMP - Whether to accept ICMP traffic to the VM in PortList mode (preserves ping and PMTU discovery). No effect in WholeIP mode. Default true so ping behaves as users expect even when port filtering is in effect.
+externalAllowICMP: true
+
 ## @enum {string} RunStrategy - Requested running state of the VirtualMachineInstance
 ## @value Always - VMI should always be running
 ## @value Halted - VMI should never be running

packages/core/platform/sources/hami.yaml

@@ -0,0 +1,24 @@
+---
+apiVersion: cozystack.io/v1alpha1
+kind: PackageSource
+metadata:
+  name: cozystack.hami
+spec:
+  sourceRef:
+    kind: OCIRepository
+    name: cozystack-packages
+    namespace: cozy-system
+    path: /
+  variants:
+  - name: default
+    dependsOn:
+    - cozystack.gpu-operator
+    components:
+    - name: hami
+      path: system/hami
+      valuesFiles:
+      - values.yaml
+      install:
+        privileged: true
+        namespace: cozy-hami
+        releaseName: hami

packages/core/platform/sources/kubernetes-application.yaml

@@ -52,6 +52,8 @@ spec:
           path: system/cilium
         - name: kubernetes-gpu-operator
           path: system/gpu-operator
+        - name: kubernetes-hami
+          path: system/hami
         - name: kubernetes-vertical-pod-autoscaler
           path: system/vertical-pod-autoscaler
         - name: kubernetes-prometheus-operator-crds

packages/core/platform/templates/apps.yaml

@@ -30,6 +30,7 @@ stringData:
       expose-services: {{ .Values.publishing.exposedServices | join "," | quote }}
       expose-ingress: {{ .Values.publishing.ingressName | quote }}
       expose-external-ips: {{ .Values.publishing.externalIPs | join "," | quote }}
+      expose-mode: {{ .Values.publishing.exposure | default "externalIPs" | quote }}
       cluster-domain: {{ .Values.networking.clusterDomain | quote }}
       api-server-endpoint: {{ .Values.publishing.apiServerEndpoint | quote }}
       {{- with .Values.branding }}

packages/core/platform/templates/bundles/iaas.yaml

@@ -10,6 +10,7 @@
 {{include "cozystack.platform.package.default" (list "cozystack.kubevirt-cdi" $) }}
 {{include "cozystack.platform.package.optional.default" (list "cozystack.vm-default-images" $) }}
 {{include "cozystack.platform.package.optional.default" (list "cozystack.gpu-operator" $) }}
+{{include "cozystack.platform.package.optional.default" (list "cozystack.hami" $) }}
 {{include "cozystack.platform.package.default" (list "cozystack.kamaji" $) }}
 {{include "cozystack.platform.package.default" (list "cozystack.capi-operator" $) }}
 {{include "cozystack.platform.package.default" (list "cozystack.capi-provider-bootstrap-kubeadm" $) }}

packages/core/platform/templates/bundles/system.yaml

@@ -105,9 +105,6 @@
 {{- /* cozystack-api DaemonSet */ -}}
 {{- $apiValues := dict "cozystackAPI" (dict "nodeSelector" $genericNodeSelector) -}}
 {{- $_ := set $cozystackEngineComponents "cozystack-api" (dict "values" $apiValues) -}}
-{{- /* lineage-controller-webhook DaemonSet */ -}}
-{{- $lineageValues := dict "lineageControllerWebhook" (dict "nodeSelector" $genericNodeSelector) -}}
-{{- $_ := set $cozystackEngineComponents "lineage-controller-webhook" (dict "values" $lineageValues) -}}
 {{- end -}}
 {{- if .Values.authentication.oidc.enabled }}
 {{include "cozystack.platform.package" (list "cozystack.cozystack-engine" "oidc" $ $cozystackEngineComponents) }}

packages/core/platform/values.yaml

@@ -45,6 +45,41 @@ publishing:
     - cdi-uploadproxy
   apiServerEndpoint: "" # example: "https://api.example.org"
   externalIPs: []
+  # Exposure mode for the ingress-nginx Service. When "externalIPs" (current
+  # default) is selected, the Service is created as ClusterIP with
+  # Service.spec.externalIPs set from publishing.externalIPs. When
+  # "loadBalancer" is selected, the Service is type: LoadBalancer and a
+  # CiliumLoadBalancerIPPool makes those same addresses allocatable via LB IPAM.
+  #
+  # Service.spec.externalIPs is deprecated upstream in Kubernetes v1.36
+  # (KEP-5707). The AllowServiceExternalIPs feature gate is expected to default
+  # to false around v1.40 and the implementation removed around v1.43 — switch
+  # to "loadBalancer" before upgrading past v1.40.
+  #
+  # Caveats for the "loadBalancer" mode:
+  #   - publishing.externalIPs must contain at least one non-empty address,
+  #     otherwise the chart render fails with an explicit error (a LoadBalancer
+  #     Service without a pool would sit in <pending> forever).
+  #   - The ingress-nginx Service is created with externalTrafficPolicy: Local
+  #     to preserve the client source IP. Traffic arriving on a node that does
+  #     not host an ingress-nginx pod is dropped, so the external IP must be
+  #     routed to a node that runs the ingress pod (floating IP / keepalived /
+  #     upstream router / podAntiAffinity).
+  #   - Cilium does NOT announce the IP on its own unless L2 announcements or
+  #     BGP are enabled in the Cilium values (disabled by default in Cozystack).
+  #     This mode assumes the operator already routes the externalIPs to a
+  #     cluster node; enabling announcements is out of scope for this setting.
+  #   - Switching this value on a running cluster causes the ingress-nginx
+  #     Service to be recreated (the HelmRelease has upgrade.force: true and
+  #     the Service kind changes between ClusterIP and LoadBalancer). Expect a
+  #     brief interruption of ingress traffic during the flip.
+  #
+  # Scope: this setting only controls the ingress-nginx Service. Other
+  # cozystack components that currently write Service.spec.externalIPs directly
+  # (e.g. the vpn app at packages/apps/vpn/templates/service.yaml) are NOT
+  # migrated by flipping this value and must be addressed separately before
+  # the AllowServiceExternalIPs feature gate flips to off in ~v1.40.
+  exposure: externalIPs # "externalIPs" or "loadBalancer"
   certificates:
     solver: http01 # "http01" or "dns01"
     issuerName: letsencrypt-prod

packages/extra/etcd/Makefile

@@ -5,3 +5,6 @@ include ../../../hack/package.mk
 generate:
 	cozyvalues-gen -v values.yaml -s values.schema.json -r README.md
 	../../../hack/update-crd.sh
+
+test:
+	helm unittest .

packages/extra/etcd/templates/hook/job.yaml

@@ -1,39 +0,0 @@
-{{- $shouldUpdateCerts := true }}
-{{- $configMap := lookup "v1" "ConfigMap" .Release.Namespace "etcd-deployed-version" }}
-{{- if $configMap }}
-  {{- $deployedVersion := index $configMap "data" "version" }}
-  {{- if $deployedVersion | semverCompare ">= 2.6.1" }}
-    {{- $shouldUpdateCerts = false }}
-  {{- end }}
-{{- end }}
-
-{{- if $shouldUpdateCerts }}
----
-apiVersion: batch/v1
-kind: Job
-metadata:
-  name: etcd-hook
-  annotations:
-    helm.sh/hook: post-upgrade
-    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
-spec:
-  template:
-    metadata:
-      labels:
-        policy.cozystack.io/allow-to-apiserver: "true"
-    spec:
-      serviceAccountName: etcd-hook
-      containers:
-        - name: kubectl
-          image: docker.io/alpine/k8s:1.33.4
-          command:
-          - sh
-          args:
-            - -exc
-            - |-
-              kubectl --namespace={{ .Release.Namespace }} delete secrets etcd-ca-tls etcd-peer-ca-tls 
-              sleep 10
-              kubectl --namespace={{ .Release.Namespace }} delete secrets etcd-client-tls etcd-peer-tls etcd-server-tls
-              kubectl --namespace={{ .Release.Namespace }} delete pods --selector=app.kubernetes.io/instance=etcd,app.kubernetes.io/managed-by=etcd-operator,app.kubernetes.io/name=etcd,cozystack.io/service=etcd
-      restartPolicy: Never
-{{- end }}

packages/extra/etcd/templates/hook/role.yaml

@@ -1,26 +0,0 @@
-apiVersion: rbac.authorization.k8s.io/v1
-kind: Role
-metadata:
-  annotations:
-    helm.sh/hook: post-upgrade
-    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
-  name: etcd-hook
-rules:
-- apiGroups:
-  - ""
-  resources:
-  - secrets
-  - pods
-  verbs:
-  - get
-  - list
-  - watch
-  - delete
-- apiGroups:
-  - ""
-  resources:
-  - configmaps
-  verbs:
-  - get
-  - list
-  - watch

packages/extra/etcd/templates/hook/rolebinding.yaml

@@ -1,15 +0,0 @@
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  name: etcd-hook
-  annotations:
-    helm.sh/hook: post-upgrade
-    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
-roleRef:
-  apiGroup: rbac.authorization.k8s.io
-  kind: Role
-  name: etcd-hook
-subjects:
-  - kind: ServiceAccount
-    name: etcd-hook
-    namespace: {{ .Release.Namespace | quote }}

packages/extra/etcd/templates/hook/serviceaccount.yaml

@@ -1,7 +0,0 @@
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: etcd-hook
-  annotations:
-    helm.sh/hook: post-upgrade
-    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded

packages/extra/etcd/templates/version.yaml

@@ -1,6 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: etcd-deployed-version
-data:
-  version: {{ .Chart.Version }}

packages/extra/etcd/tests/no-post-upgrade-hook_test.yaml

@@ -0,0 +1,34 @@
+suite: etcd chart does not ship a destructive post-upgrade cert-regeneration hook
+
+release:
+  name: etcd
+  namespace: tenant-root
+
+templates:
+  - templates/check-release-name.yaml
+  - templates/dashboard-resourcemap.yaml
+  - templates/datastore.yaml
+  - templates/etcd-defrag.yaml
+  - templates/hook/job.yaml
+  - templates/podscrape.yaml
+  - templates/prometheus-rules.yaml
+  - templates/version.yaml
+
+tests:
+  - it: renders no Job named etcd-hook
+    documentSelector:
+      path: metadata.name
+      value: etcd-hook
+      skipEmptyTemplates: true
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: renders no ConfigMap named etcd-deployed-version
+    documentSelector:
+      path: metadata.name
+      value: etcd-deployed-version
+      skipEmptyTemplates: true
+    asserts:
+      - hasDocuments:
+          count: 0

packages/extra/ingress/Makefile

@@ -10,3 +10,6 @@ get-cloudflare-ips:
 generate:
 	cozyvalues-gen -v values.yaml -s values.schema.json -r README.md
 	../../../hack/update-crd.sh
+
+test:
+	helm unittest .

packages/extra/ingress/README.md

@@ -14,3 +14,17 @@
 | `resources.memory` | Memory (RAM) available to each replica.                                                                                                 | `quantity` | `""`    |
 | `resourcesPreset`  | Default sizing preset used when `resources` is omitted.                                                                                 | `string`   | `micro` |
 
+
+## Exposure mode
+
+The ingress Service type is driven by the cluster-wide `publishing.exposure` value in the platform chart, not by any key in this package. Two modes exist:
+
+- `externalIPs` (default) has three rendered shapes:
+  - Release namespace matches `publishing.ingressName` AND `publishing.externalIPs` is non-empty → Service is `ClusterIP` with `Service.spec.externalIPs` set from that list and `externalTrafficPolicy: Cluster`.
+  - Release namespace matches `publishing.ingressName` but `publishing.externalIPs` is empty → Service falls back to `type: LoadBalancer` with `externalTrafficPolicy: Local`.
+  - Release namespace does not match `publishing.ingressName` (non-root tenants) → Service is `type: LoadBalancer` with `externalTrafficPolicy: Local`.
+  `Service.spec.externalIPs` is deprecated upstream in Kubernetes v1.36 (KEP-5707); plan migration before v1.40.
+- `loadBalancer` — Service is `type: LoadBalancer` with `externalTrafficPolicy: Local`, and a `CiliumLoadBalancerIPPool` makes the addresses in `publishing.externalIPs` allocatable via Cilium LB IPAM. Requires `publishing.externalIPs` to contain at least one non-empty address (render fails otherwise) and assumes the addresses are already routed to a cluster node (floating IP / upstream router). See the inline comment on `publishing.exposure` in the platform chart for full caveats, including the note that switching the value on a running cluster causes the ingress Service to be recreated.
+
+This setting only migrates ingress-nginx away from `Service.spec.externalIPs`. Other cozystack components that use the same deprecated field (e.g. the `vpn` app) must be migrated separately before Kubernetes v1.40 flips the `AllowServiceExternalIPs` feature gate off.
+

packages/extra/ingress/templates/nginx-ingress.yaml

@@ -1,5 +1,19 @@
 {{- $exposeIngress := (index .Values._cluster "expose-ingress") | default "tenant-root" }}
 {{- $exposeExternalIPs := (index .Values._cluster "expose-external-ips") | default "" | nospace }}
+{{- $exposeMode := (index .Values._cluster "expose-mode") | default "externalIPs" }}
+{{- $exposeIPsList := list }}
+{{- range splitList "," $exposeExternalIPs }}
+  {{- $ip := . | trim }}
+  {{- if $ip }}
+    {{- $exposeIPsList = append $exposeIPsList $ip }}
+  {{- end }}
+{{- end }}
+{{- if not (has $exposeMode (list "externalIPs" "loadBalancer")) }}
+{{- fail (printf "unknown publishing.exposure mode %q: must be \"externalIPs\" or \"loadBalancer\"" $exposeMode) }}
+{{- end }}
+{{- if and (eq $exposeMode "loadBalancer") (eq $exposeIngress .Release.Namespace) (not $exposeIPsList) }}
+{{- fail "publishing.exposure=loadBalancer requires publishing.externalIPs to contain at least one non-empty address: the CiliumLoadBalancerIPPool has nothing to advertise and the Service would stay in <pending>." }}
+{{- end }}
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
@@ -41,9 +55,12 @@ spec:
           enabled: false
         {{- end }}
         service:
-          {{- if and (eq $exposeIngress .Release.Namespace) $exposeExternalIPs }}
+          {{- if and (eq $exposeIngress .Release.Namespace) (eq $exposeMode "loadBalancer") }}
+          type: LoadBalancer
+          externalTrafficPolicy: Local
+          {{- else if and (eq $exposeIngress .Release.Namespace) $exposeIPsList }}
           externalIPs:
-            {{- toYaml (splitList "," $exposeExternalIPs) | nindent 12 }}
+            {{- toYaml $exposeIPsList | nindent 12 }}
           type: ClusterIP
           externalTrafficPolicy: Cluster
           {{- else }}

packages/extra/ingress/tests/exposure_test.yaml

@@ -0,0 +1,165 @@
+suite: ingress exposure modes
+templates:
+  - templates/nginx-ingress.yaml
+
+release:
+  name: ingress
+  namespace: tenant-root
+
+tests:
+  - it: default exposure (externalIPs) renders ClusterIP Service with spec.externalIPs
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,192.0.2.11"
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.type
+          value: ClusterIP
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.externalTrafficPolicy
+          value: Cluster
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.externalIPs
+          value:
+            - 192.0.2.10
+            - 192.0.2.11
+      - template: templates/nginx-ingress.yaml
+        notExists:
+          path: spec.values.ingress-nginx.controller.service.labels
+
+  - it: legacy config without expose-mode falls back to externalIPs behavior
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.type
+          value: ClusterIP
+
+  - it: externalIPs mode in a namespace other than publishing.ingressName renders LoadBalancer fallback without externalIPs
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+    release:
+      namespace: tenant-other
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.type
+          value: LoadBalancer
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.externalTrafficPolicy
+          value: Local
+      - template: templates/nginx-ingress.yaml
+        notExists:
+          path: spec.values.ingress-nginx.controller.service.externalIPs
+
+  - it: loadBalancer mode renders LoadBalancer Service without externalIPs on the Service
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,192.0.2.11"
+        expose-mode: loadBalancer
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.type
+          value: LoadBalancer
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.externalTrafficPolicy
+          value: Local
+      - template: templates/nginx-ingress.yaml
+        notExists:
+          path: spec.values.ingress-nginx.controller.service.labels
+      - template: templates/nginx-ingress.yaml
+        notExists:
+          path: spec.values.ingress-nginx.controller.service.externalIPs
+
+  - it: loadBalancer mode without externalIPs fails chart render with explicit message
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: ""
+        expose-mode: loadBalancer
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        failedTemplate:
+          errorMessage: "publishing.exposure=loadBalancer requires publishing.externalIPs to contain at least one non-empty address: the CiliumLoadBalancerIPPool has nothing to advertise and the Service would stay in <pending>."
+
+  - it: unknown exposure mode is rejected with a clear error (case-sensitive enum)
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+        expose-mode: LoadBalancer
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        failedTemplate:
+          errorMessage: "unknown publishing.exposure mode \"LoadBalancer\": must be \"externalIPs\" or \"loadBalancer\""
+
+  - it: another typo in exposure mode also fails
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+        expose-mode: loadbalancer
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        failedTemplate:
+          errorMessage: "unknown publishing.exposure mode \"loadbalancer\": must be \"externalIPs\" or \"loadBalancer\""
+
+  - it: loadBalancer mode in a namespace other than publishing.ingressName falls back to LoadBalancer Service without pool
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10"
+        expose-mode: loadBalancer
+    release:
+      namespace: tenant-other
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.type
+          value: LoadBalancer
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.externalTrafficPolicy
+          value: Local
+      - template: templates/nginx-ingress.yaml
+        notExists:
+          path: spec.values.ingress-nginx.controller.service.labels
+      - template: templates/nginx-ingress.yaml
+        notExists:
+          path: spec.values.ingress-nginx.controller.service.externalIPs
+
+  - it: loadBalancer mode with only-empty externalIPs fails chart render (comma-only input)
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: ",,"
+        expose-mode: loadBalancer
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        failedTemplate:
+          errorMessage: "publishing.exposure=loadBalancer requires publishing.externalIPs to contain at least one non-empty address: the CiliumLoadBalancerIPPool has nothing to advertise and the Service would stay in <pending>."
+
+  - it: externalIPs mode also filters out empty entries (trailing comma)
+    set:
+      _cluster:
+        expose-ingress: tenant-root
+        expose-external-ips: "192.0.2.10,"
+    asserts:
+      - template: templates/nginx-ingress.yaml
+        equal:
+          path: spec.values.ingress-nginx.controller.service.externalIPs
+          value:
+            - 192.0.2.10

packages/system/cozy-proxy/charts/cozy-proxy/Chart.yaml

@@ -2,5 +2,5 @@ apiVersion: v2
 name: cozy-proxy
 description: A simple kube-proxy addon for 1:1 NAT services in Kubernetes using an NFT backend
 type: application
-version: 0.2.0
-appVersion: 0.2.0
+version: 0.3.0
+appVersion: 0.3.0

packages/system/cozy-proxy/charts/cozy-proxy/values.yaml

@@ -1,6 +1,6 @@
 image:
   repository: ghcr.io/cozystack/cozystack/cozy-proxy
-  tag: v0.2.0
+  tag: v0.3.0
   pullPolicy: IfNotPresent
 
 daemonset:

packages/system/gpu-operator/examples/README.md

@@ -0,0 +1,121 @@
+# GPU operator — native pod workload on Talos (reference)
+
+The files in this directory are **not** templates. They are reference
+artifacts that document one working configuration for running GPU
+workloads directly in pods on a Talos-based Cozystack cluster, together
+with the DCGM metrics needed by the `gpu/gpu-performance` Grafana
+dashboard.
+
+The out-of-the-box `values-talos.yaml` for this package targets the
+sandbox (VFIO passthrough to KubeVirt VMs) scenario. The files here
+illustrate an alternative — running CUDA workloads in regular pods with
+the NVIDIA device plugin — and the workarounds it currently requires on
+Talos.
+
+## Files
+
+- [`values-native-talos.yaml`](./values-native-talos.yaml) — Cozystack
+  `Package` values that disable sandbox workloads, enable the device
+  plugin, point `hostPaths.driverInstallDir` at the staging location
+  used by the compat DaemonSet, and wire DCGM to the custom metrics
+  ConfigMap.
+- [`dcgm-custom-metrics.yaml`](./dcgm-custom-metrics.yaml) — `ConfigMap`
+  with a DCGM metrics CSV that adds profiling, ECC, throttling and
+  energy counters on top of the upstream defaults. The CSV is a
+  superset needed for full coverage of the `gpu/gpu-performance`
+  dashboard. Which parts are actually required depends on which
+  dashboards you ship — see the table below.
+- [`nvidia-driver-compat.yaml`](./nvidia-driver-compat.yaml) — DaemonSet
+  that stages `libnvidia-ml.so.1` and `nvidia-smi` from the Talos glibc
+  tree into a path where the NVIDIA GPU Operator validator expects
+  them. See the "Why the compat DaemonSet exists" section below.
+
+## Why these are reference, not templates
+
+Shipping these as first-class templates would silently impose
+assumptions that do not hold for every user:
+
+- Whether the NVIDIA Talos system extension is installed on the nodes.
+- Whether GPUs are exposed directly to pods or passed through to VMs.
+- The exact path the installed driver ends up at (depends on the
+  extension version and Talos release).
+
+The sandbox-oriented `values-talos.yaml` remains the default. Operators
+who want native pod GPU workloads can start from this directory and
+adapt as needed.
+
+## Why the compat DaemonSet exists
+
+The NVIDIA GPU Operator validator checks for `libnvidia-ml.so.1` and
+`bin/nvidia-smi` in the path given by `hostPaths.driverInstallDir`.
+Talos installs them under `/usr/local/glibc/usr/lib/` and
+`/usr/local/bin/`, which the validator does not look at. Until upstream
+addresses [NVIDIA/gpu-operator#1687][1], the DaemonSet copies those
+files into a directory the validator does inspect and creates the
+`.driver-ctr-ready` flag file so the validator proceeds.
+
+[1]: https://github.com/NVIDIA/gpu-operator/issues/1687
+
+The compat DaemonSet runs privileged and bind-mounts host paths, so
+the target namespace must allow privileged pods. On clusters that
+enforce the Kubernetes Pod Security Standards at `baseline` or
+`restricted`, label the namespace with
+`pod-security.kubernetes.io/enforce: privileged` (and the matching
+`audit`/`warn` labels if the admission webhook is configured to
+surface violations) before applying the manifest.
+
+## Dashboards and what DCGM metrics they need
+
+Five GPU dashboards live under `gpu/*` in
+`packages/system/monitoring/dashboards-infra.list`. All of them share
+`packages/system/monitoring-agents/alerts/gpu-recording.rules.yaml` as
+their source of aggregated series. The recording rules are safe to
+ship on any cluster — they evaluate to empty series when DCGM is not
+scraped, or when optional counters are missing.
+
+What each dashboard needs on top of the upstream DCGM Exporter
+[`default-counters.csv`][default-csv]:
+
+| Dashboard         | Scope                              | Needs beyond defaults                                                   |
+| ----------------- | ---------------------------------- | ----------------------------------------------------------------------- |
+| `gpu-performance` | Per-node, per-GPU deep dive        | `DCGM_FI_DEV_POWER_VIOLATION`, `DCGM_FI_DEV_THERMAL_VIOLATION`          |
+| `gpu-efficiency`  | Per-workload util vs tensor active | `DCGM_FI_DEV_POWER_VIOLATION`, `DCGM_FI_DEV_THERMAL_VIOLATION` (via `gpu:*_throttle_fraction:rate5m` recording rules) |
+| `gpu-fleet`       | Cluster-wide admin inventory       | `DCGM_FI_DEV_POWER_MGMT_LIMIT` (for the TDP vs draw panel)              |
+| `gpu-quotas`      | Kube-quota vs live usage           | `kube_pod_container_resource_requests`, `kube_pod_status_phase`, `kube_node_status_allocatable` (via `namespace:gpu_count:allocated` / `cluster:gpu_count:*` recording rules) |
+| `gpu-tenants`     | Per-namespace tenant view          | nothing (works on default counters)                                     |
+
+`DCGM_FI_PROF_PIPE_TENSOR_ACTIVE` and `DCGM_FI_PROF_GR_ENGINE_ACTIVE`
+are already in the upstream default set for the pinned DCGM Exporter
+version, so the tensor-saturation and engine-active panels work without
+any CSV override. The three counters listed in the table — throttling
+violations and the power management limit — are the only extras the
+tracked dashboards need. The recording rules in
+`gpu-recording.rules.yaml` consume utilization, FB used, power,
+temperature and the tensor-active profiling counter from the default
+set, plus `DCGM_FI_DEV_POWER_VIOLATION` and
+`DCGM_FI_DEV_THERMAL_VIOLATION` — used by the
+`gpu.recording.efficiency.1m` group to derive the
+`gpu:power_throttle_fraction:rate5m` and
+`gpu:thermal_throttle_fraction:rate5m` series consumed by the
+throttling panels on the efficiency and fleet dashboards.
+
+The `gpu.recording.throttle.validation.5m` group additionally ships the
+`GPUThrottleFractionOverOne` alert (severity `warning`) as a regression
+detector: it fires when either throttle-fraction series exceeds 1.0,
+which would indicate that DCGM changed the scale/divisor of the
+underlying violation counters and the recording rules need to be
+re-derived.
+
+## Verification status
+
+The minimum-CSV claims above are verified by
+`hack/check-gpu-recording-rules.bats`, which cross-checks every
+`DCGM_FI_*` reference in the tracked GPU dashboards and recording rules
+against the union of the upstream default set (snapshotted at
+`hack/dcgm-default-counters.csv` for the pinned DCGM Exporter version)
+and the custom CSV in `dcgm-custom-metrics.yaml`. When the DCGM
+Exporter image in `packages/system/gpu-operator/charts/gpu-operator/values.yaml`
+is bumped, refresh the snapshot from the matching tag of the
+[`NVIDIA/dcgm-exporter`][default-csv] repository and rerun the test.
+
+[default-csv]: https://github.com/NVIDIA/dcgm-exporter/blob/main/etc/default-counters.csv

packages/system/gpu-operator/examples/dcgm-custom-metrics.yaml

@@ -0,0 +1,88 @@
+# Custom DCGM Exporter metrics CSV. Referenced from
+# examples/values-native-talos.yaml via dcgmExporter.config.name.
+#
+# Extends the upstream default set with profiling counters, ECC, page
+# retirement, row remap, energy and throttling violations — everything
+# the gpu/gpu-performance dashboard and the GPU recording rules in
+# monitoring-agents expect.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: dcgm-custom-metrics
+  namespace: cozy-gpu-operator
+data:
+  dcgm-metrics.csv: |
+    # Format
+    # If line starts with a '#' it is considered a comment
+    # DCGM FIELD, Prometheus metric type, help message
+
+    # Identity
+    DCGM_FI_DRIVER_VERSION, label, Driver version.
+
+    # Clocks
+    DCGM_FI_DEV_SM_CLOCK,  gauge, SM clock frequency (in MHz).
+    DCGM_FI_DEV_MEM_CLOCK, gauge, Memory clock frequency (in MHz).
+
+    # Temperature
+    DCGM_FI_DEV_MEMORY_TEMP, gauge, Memory temperature (in C).
+    DCGM_FI_DEV_GPU_TEMP,    gauge, GPU temperature (in C).
+
+    # Power
+    DCGM_FI_DEV_POWER_USAGE,              gauge, Power draw (in W).
+    DCGM_FI_DEV_POWER_MGMT_LIMIT,         gauge, Current power management limit (in W).
+    DCGM_FI_DEV_TOTAL_ENERGY_CONSUMPTION, counter, Total energy consumption since boot (in mJ).
+
+    # PCIE
+    DCGM_FI_DEV_PCIE_REPLAY_COUNTER, counter, Total number of PCIe retries.
+
+    # Utilization (the sample period varies depending on the product)
+    DCGM_FI_DEV_GPU_UTIL,      gauge, GPU utilization (in %).
+    DCGM_FI_DEV_MEM_COPY_UTIL, gauge, Memory utilization (in %).
+    DCGM_FI_DEV_ENC_UTIL,      gauge, Encoder utilization (in %).
+    DCGM_FI_DEV_DEC_UTIL,      gauge, Decoder utilization (in %).
+
+    # Errors and violations
+    DCGM_FI_DEV_XID_ERRORS, gauge, Value of the last XID error encountered.
+
+    # Memory usage
+    DCGM_FI_DEV_FB_FREE,     gauge, Framebuffer memory free (in MiB).
+    DCGM_FI_DEV_FB_USED,     gauge, Framebuffer memory used (in MiB).
+    DCGM_FI_DEV_FB_RESERVED, gauge, Framebuffer memory reserved (in MiB).
+
+    # ECC (supported on datacenter-class GPUs such as A10)
+    DCGM_FI_DEV_ECC_SBE_VOL_TOTAL, counter, Total number of single-bit volatile ECC errors.
+    DCGM_FI_DEV_ECC_DBE_VOL_TOTAL, counter, Total number of double-bit volatile ECC errors.
+    DCGM_FI_DEV_ECC_SBE_AGG_TOTAL, counter, Total number of single-bit persistent ECC errors.
+    DCGM_FI_DEV_ECC_DBE_AGG_TOTAL, counter, Total number of double-bit persistent ECC errors.
+
+    # Retired pages
+    DCGM_FI_DEV_RETIRED_SBE,     counter, Total number of retired pages due to single-bit errors.
+    DCGM_FI_DEV_RETIRED_DBE,     counter, Total number of retired pages due to double-bit errors.
+    DCGM_FI_DEV_RETIRED_PENDING, counter, Total number of pages pending retirement.
+
+    # Row remapping (not applicable to GDDR6 but left for datacenter GPUs)
+    DCGM_FI_DEV_UNCORRECTABLE_REMAPPED_ROWS, counter, Number of remapped rows for uncorrectable errors.
+    DCGM_FI_DEV_CORRECTABLE_REMAPPED_ROWS,   counter, Number of remapped rows for correctable errors.
+    DCGM_FI_DEV_ROW_REMAP_FAILURE,           gauge,   Whether remapping of rows has failed.
+
+    # Throttle / violation counters (crucial for SLA and tenant monitoring)
+    DCGM_FI_DEV_POWER_VIOLATION,       counter, Throttling duration due to power constraints (us per docs; ns on DCGM 3.x).
+    DCGM_FI_DEV_THERMAL_VIOLATION,     counter, Throttling duration due to thermal constraints (us per docs; ns on DCGM 3.x).
+    DCGM_FI_DEV_SYNC_BOOST_VIOLATION,  counter, Throttling duration due to sync-boost constraints (us per docs; ns on DCGM 3.x).
+    DCGM_FI_DEV_BOARD_LIMIT_VIOLATION, counter, Throttling duration due to board limit constraints (us per docs; ns on DCGM 3.x).
+    DCGM_FI_DEV_LOW_UTIL_VIOLATION,    counter, Throttling duration due to low utilization (us per docs; ns on DCGM 3.x).
+    DCGM_FI_DEV_RELIABILITY_VIOLATION, counter, Throttling duration due to reliability constraints (us per docs; ns on DCGM 3.x).
+
+    # NVLink — DCGM silently drops this metric on GPUs without NVLink, so
+    # enabling it unconditionally is safe and keeps this file reusable
+    # across GPU families.
+    DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL, counter, Total number of NVLink bandwidth counters for all lanes.
+
+    # DCP (profiling) metrics — supported from Ampere onwards.
+    DCGM_FI_PROF_GR_ENGINE_ACTIVE,   gauge, Ratio of time the graphics engine is active.
+    DCGM_FI_PROF_SM_ACTIVE,          gauge, The ratio of cycles an SM has at least 1 warp assigned.
+    DCGM_FI_PROF_SM_OCCUPANCY,       gauge, The ratio of number of warps resident on an SM.
+    DCGM_FI_PROF_PIPE_TENSOR_ACTIVE, gauge, Ratio of cycles the tensor (HMMA) pipe is active.
+    DCGM_FI_PROF_DRAM_ACTIVE,        gauge, Ratio of cycles the device memory interface is active sending or receiving data.
+    DCGM_FI_PROF_PCIE_TX_BYTES,      counter, The number of bytes of active PCIe tx (transmit) data including both header and payload.
+    DCGM_FI_PROF_PCIE_RX_BYTES,      counter, The number of bytes of active PCIe rx (read) data including both header and payload.

packages/system/gpu-operator/examples/nvidia-driver-compat.yaml

@@ -0,0 +1,109 @@
+# Workaround for https://github.com/NVIDIA/gpu-operator/issues/1687
+#
+# On Talos, the NVIDIA system extension installs driver files under
+# /usr/local/glibc/usr/lib/ and /usr/local/bin/. The GPU Operator
+# validator only looks for libnvidia-ml.so.1 and bin/nvidia-smi under
+# the path configured as hostPaths.driverInstallDir. This DaemonSet
+# stages the required files into /var/nvidia-driver on each node and
+# creates the .driver-ctr-ready flag so the validator proceeds.
+#
+# Paired with examples/values-native-talos.yaml, which sets
+# hostPaths.driverInstallDir to /var/nvidia-driver.
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: nvidia-driver-compat
+  namespace: cozy-gpu-operator
+  labels:
+    app: nvidia-driver-compat
+spec:
+  selector:
+    matchLabels:
+      app: nvidia-driver-compat
+  template:
+    metadata:
+      labels:
+        app: nvidia-driver-compat
+    # DaemonSet rather than a one-shot Job: staging is idempotent per-node,
+    # must re-run after every Talos reboot (hostPath contents are wiped on
+    # reboot when the system extension re-installs), and the pause container
+    # keeps the pod visible for operator observability (kubectl get pods).
+    spec:
+      priorityClassName: system-node-critical
+      # Restrict to GPU nodes only. Without this the DaemonSet schedules onto
+      # every node (including control-plane and CPU-only workers) and burns
+      # resources on hosts where the compat tree is meaningless.
+      # The label is published by Node Feature Discovery / GPU Operator's NFD
+      # subchart; if NFD is disabled, replace this with whatever label your
+      # cluster uses to mark GPU hosts.
+      nodeSelector:
+        nvidia.com/gpu.present: "true"
+      # Tolerate-all is intentionally broad: the nodeSelector above already
+      # confines scheduling to GPU nodes, so the "Exists" toleration only
+      # matters when those nodes carry extra taints (dedicated=gpu:NoSchedule,
+      # nvidia.com/gpu:NoSchedule from the GPU Operator's default policy,
+      # etc.). This mirrors the stance of the upstream nvidia-driver-daemonset
+      # and nvidia-device-plugin DaemonSets — blanket tolerations plus a
+      # narrow nodeSelector.
+      tolerations:
+        - operator: Exists
+      initContainers:
+        - name: create-driver-tree
+          image: busybox:1.37
+          command:
+            - sh
+            - -c
+            - |
+              set -e
+              GLIBC_LIB="/host/usr/local/glibc/usr/lib"
+              SRC_BIN="/host/usr/local/bin"
+              DST="/host/var/nvidia-driver"
+
+              mkdir -p "$DST/bin"
+
+              [ -f "$GLIBC_LIB/libnvidia-ml.so.1" ] || {
+                echo "missing $GLIBC_LIB/libnvidia-ml.so.1" >&2
+                exit 1
+              }
+              [ -f "$SRC_BIN/nvidia-smi" ] || {
+                echo "missing $SRC_BIN/nvidia-smi" >&2
+                exit 1
+              }
+
+              cp -f "$GLIBC_LIB/libnvidia-ml.so.1" "$DST/libnvidia-ml.so.1"
+              echo "Copied libnvidia-ml.so.1"
+
+              cp -f "$SRC_BIN/nvidia-smi" "$DST/bin/nvidia-smi"
+              chmod +x "$DST/bin/nvidia-smi"
+              echo "Copied nvidia-smi"
+
+              mkdir -p /host/run/nvidia/validations
+              touch /host/run/nvidia/validations/.driver-ctr-ready
+              echo "Created driver-ctr-ready flag"
+              echo "Done"
+          securityContext:
+            privileged: true
+          resources:
+            requests:
+              cpu: 10m
+              memory: 16Mi
+            limits:
+              cpu: 100m
+              memory: 64Mi
+          volumeMounts:
+            - name: host-root
+              mountPath: /host
+      containers:
+        - name: pause
+          image: registry.k8s.io/pause:3.10
+          resources:
+            requests:
+              cpu: 10m
+              memory: 8Mi
+            limits:
+              cpu: 50m
+              memory: 16Mi
+      volumes:
+        - name: host-root
+          hostPath:
+            path: /

packages/system/gpu-operator/examples/values-native-talos.yaml

@@ -0,0 +1,52 @@
+# Cozystack Package values for running GPU workloads natively in pods
+# on Talos. This is the counterpart to values-talos.yaml, which targets
+# the sandbox (VFIO passthrough) scenario.
+#
+# Prerequisites:
+#   - NVIDIA Talos system extension installed on GPU nodes.
+#   - examples/nvidia-driver-compat.yaml deployed to stage driver files
+#     where the gpu-operator validator looks for them.
+#   - examples/dcgm-custom-metrics.yaml applied so DCGM Exporter exports
+#     the full set of metrics used by the dashboard and recording rules.
+apiVersion: cozystack.io/v1alpha1
+kind: Package
+metadata:
+  name: cozystack.gpu-operator
+spec:
+  variant: default
+  components:
+    gpu-operator:
+      values:
+        gpu-operator:
+          # The compat DaemonSet stages libnvidia-ml.so.1 and nvidia-smi
+          # under /var/nvidia-driver. Point the validator at that path.
+          hostPaths:
+            driverInstallDir: "/var/nvidia-driver"
+          # Disable the sandbox path — workloads run in pods, not VMs.
+          sandboxWorkloads:
+            enabled: false
+          vfioManager:
+            enabled: false
+          # The Talos extension provides the driver and runtime hooks,
+          # so the operator's own toolkit and driver components must be
+          # switched off to avoid conflicting installations.
+          toolkit:
+            enabled: false
+          devicePlugin:
+            enabled: true
+          # Export full set of DCGM metrics using the ConfigMap in
+          # examples/dcgm-custom-metrics.yaml.
+          dcgmExporter:
+            serviceMonitor:
+              enabled: true
+              # Matches the 1m evaluation cadence of GPU recording rules with
+              # 4x oversampling headroom. DCGM_FI_PROF_* counters have
+              # documented overhead concerns below 1s; 15s is safe.
+              interval: "15s"
+              honorLabels: true
+              relabelings:
+                - sourceLabels: [__meta_kubernetes_pod_node_name]
+                  targetLabel: node
+                  action: replace
+            config:
+              name: dcgm-custom-metrics