Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Keep Kubernetes metrics setup read-only and host identities separate
pulse-triage[bot]b3b7c286693f
diff --git a/docs/KUBERNETES.md b/docs/KUBERNETES.mdindex 28f3fce498..d768315f00 100644--- a/docs/KUBERNETES.md+++ b/docs/KUBERNETES.md@@ -215,7 +215,13 @@ To monitor Kubernetes resources, run the unified agent as a DaemonSet and enable**Recommended options:**- **Kubernetes-only monitoring**: `PULSE_ENABLE_KUBERNETES=true` and `PULSE_ENABLE_HOST=false` (no host mounts required).-- **Kubernetes + node metrics**: `PULSE_ENABLE_KUBERNETES=true` and `PULSE_ENABLE_HOST=true` (requires host mounts and privileged mode).+- **Node and pod CPU/memory usage**: the Kubernetes module reads the cluster's+ `metrics.k8s.io` API. It does not require host mounts or privileged mode;+ the [read-only RBAC example](#rbac) includes the necessary metrics permissions.+- **Additional host-local telemetry**: a separate, deliberate host-agent+ deployment, with a distinct identity for each node. See+ [host metrics](#add-host-metrics-optional); do not enable it merely to repair+ missing API usage.#### Minimal DaemonSet Example@@ -323,45 +329,40 @@ See [UNIFIED_AGENT.md](UNIFIED_AGENT.md) for all available configuration options#### Add Host Metrics (Optional)-If you want node CPU/memory/disk metrics, add privileged mode plus host mounts:--```yaml- env:- - name: PULSE_ENABLE_HOST- value: "true"- - name: HOST_PROC- value: "/host/proc"- - name: HOST_SYS- value: "/host/sys"- - name: HOST_ETC- value: "/host/etc"- securityContext:- privileged: true- volumeMounts:- - name: host-proc- mountPath: /host/proc- readOnly: true- - name: host-sys- mountPath: /host/sys- readOnly: true- - name: host-root- mountPath: /host/root- readOnly: true- volumes:- - name: host-proc- hostPath:- path: /proc- - name: host-sys- hostPath:- path: /sys- - name: host-root- hostPath:- path: /-```+Keep the cluster example **Kubernetes-only**. Its shared `PULSE_AGENT_ID` is+not an identity for every host: enabling host reporting under that same ID can+combine different nodes' host readings. Do not turn on `PULSE_ENABLE_HOST` or+add privileged mode and host-root mounts to obtain Kubernetes CPU/memory usage.+Use the metrics API and its read permissions instead.++Host-local disks, sensors and other host readings are a different collection+path. If you deliberately need them, plan a separate node-local deployment+through the [Unified Agent configuration](UNIFIED_AGENT.md#configuration),+with only the access those collectors need, persistent agent state and a+distinct, stable identity for each node. A Kubernetes-only `kubernetes:report`+token does not authorise host reporting; that path also needs `agent:report`.+It is not a reason to reuse an administrator token.++For an existing installation, preserve the current IDs, credentials and state;+do not rename, re-enrol or restart agents just to diagnose missing usage. Use+the [identity checks](UNIFIED_AGENT.md#duplicate-agents) before repairing a+confirmed host-identity collision. Read-only host mounts do not remove the+security exposure of a privileged pod, and neither changes Kubernetes API RBAC.#### RBAC-The Kubernetes agent uses the in-cluster API and needs read access to cluster resources (nodes, pods, deployments, etc.). Create a read-only `ClusterRole` and bind it to the `pulse-agent` service account.+The Kubernetes module uses the pod's service account to read the cluster API.+The minimal role below covers node, pod and Deployment inventory, their+CPU/memory usage from `metrics.k8s.io`, and optional recovery records. It is+not a complete role for every Kubernetes tab or resource type Pulse can collect.+Other inventory needs its own explicit read permissions; a running pod or one+populated tab does not establish complete collection.++For a new deployment, create the service account, role and binding in the+intended cluster before applying the agent workload. For an existing one,+reconcile the exact denied API group/resource with its managed role through+normal review, not by replacing a working binding or adding `cluster-admin`.+The service account and binding must use the agent pod's actual namespace.```yamlapiVersion: v1@@ -381,6 +382,9 @@ rules:- apiGroups: ["apps"]resources: ["deployments"]verbs: ["get", "list", "watch"]+ - apiGroups: ["metrics.k8s.io"]+ resources: ["nodes", "pods"]+ verbs: ["get", "list"]# Optional (Recovery): VolumeSnapshots and Velero backups.# These rules are safe to include even if the APIs are not installed; the agent will# feature-detect and ignore 404/403 responses.@@ -405,6 +409,17 @@ roleRef:apiGroup: rbac.authorization.k8s.io```+These permissions do not install a metrics provider. The cluster must already+serve `metrics.k8s.io`; inventory can remain available when usage collection+is unavailable, and missing usage is not measured zero.++This role grants no Secret reads, `nodes/proxy`, writes or workload execution.+The collector's additional kubelet-summary path uses `nodes/proxy`, so network+and ephemeral-storage usage from that path can remain unavailable under this+minimal role even when API CPU/memory works. Do not broaden access or enable+host privileges merely to fill an empty field. Follow the+[failure-specific checks](#4-troubleshooting) using existing observations.+## 3. Talos Linux SpecificsTalos Linux is immutable, so you cannot install the agent via the shell script. Use the DaemonSet approach above.diff --git a/frontend-modern/public/docs/KUBERNETES.md b/frontend-modern/public/docs/KUBERNETES.mdindex 28f3fce498..d768315f00 100644--- a/frontend-modern/public/docs/KUBERNETES.md+++ b/frontend-modern/public/docs/KUBERNETES.md@@ -215,7 +215,13 @@ To monitor Kubernetes resources, run the unified agent as a DaemonSet and enable**Recommended options:**- **Kubernetes-only monitoring**: `PULSE_ENABLE_KUBERNETES=true` and `PULSE_ENABLE_HOST=false` (no host mounts required).-- **Kubernetes + node metrics**: `PULSE_ENABLE_KUBERNETES=true` and `PULSE_ENABLE_HOST=true` (requires host mounts and privileged mode).+- **Node and pod CPU/memory usage**: the Kubernetes module reads the cluster's+ `metrics.k8s.io` API. It does not require host mounts or privileged mode;+ the [read-only RBAC example](#rbac) includes the necessary metrics permissions.+- **Additional host-local telemetry**: a separate, deliberate host-agent+ deployment, with a distinct identity for each node. See+ [host metrics](#add-host-metrics-optional); do not enable it merely to repair+ missing API usage.#### Minimal DaemonSet Example@@ -323,45 +329,40 @@ See [UNIFIED_AGENT.md](UNIFIED_AGENT.md) for all available configuration options#### Add Host Metrics (Optional)-If you want node CPU/memory/disk metrics, add privileged mode plus host mounts:--```yaml- env:- - name: PULSE_ENABLE_HOST- value: "true"- - name: HOST_PROC- value: "/host/proc"- - name: HOST_SYS- value: "/host/sys"- - name: HOST_ETC- value: "/host/etc"- securityContext:- privileged: true- volumeMounts:- - name: host-proc- mountPath: /host/proc- readOnly: true- - name: host-sys- mountPath: /host/sys- readOnly: true- - name: host-root- mountPath: /host/root- readOnly: true- volumes:- - name: host-proc- hostPath:- path: /proc- - name: host-sys- hostPath:- path: /sys- - name: host-root- hostPath:- path: /-```+Keep the cluster example **Kubernetes-only**. Its shared `PULSE_AGENT_ID` is+not an identity for every host: enabling host reporting under that same ID can+combine different nodes' host readings. Do not turn on `PULSE_ENABLE_HOST` or+add privileged mode and host-root mounts to obtain Kubernetes CPU/memory usage.+Use the metrics API and its read permissions instead.++Host-local disks, sensors and other host readings are a different collection+path. If you deliberately need them, plan a separate node-local deployment+through the [Unified Agent configuration](UNIFIED_AGENT.md#configuration),+with only the access those collectors need, persistent agent state and a+distinct, stable identity for each node. A Kubernetes-only `kubernetes:report`+token does not authorise host reporting; that path also needs `agent:report`.+It is not a reason to reuse an administrator token.++For an existing installation, preserve the current IDs, credentials and state;+do not rename, re-enrol or restart agents just to diagnose missing usage. Use+the [identity checks](UNIFIED_AGENT.md#duplicate-agents) before repairing a+confirmed host-identity collision. Read-only host mounts do not remove the+security exposure of a privileged pod, and neither changes Kubernetes API RBAC.#### RBAC-The Kubernetes agent uses the in-cluster API and needs read access to cluster resources (nodes, pods, deployments, etc.). Create a read-only `ClusterRole` and bind it to the `pulse-agent` service account.+The Kubernetes module uses the pod's service account to read the cluster API.+The minimal role below covers node, pod and Deployment inventory, their+CPU/memory usage from `metrics.k8s.io`, and optional recovery records. It is+not a complete role for every Kubernetes tab or resource type Pulse can collect.+Other inventory needs its own explicit read permissions; a running pod or one+populated tab does not establish complete collection.++For a new deployment, create the service account, role and binding in the+intended cluster before applying the agent workload. For an existing one,+reconcile the exact denied API group/resource with its managed role through+normal review, not by replacing a working binding or adding `cluster-admin`.+The service account and binding must use the agent pod's actual namespace.```yamlapiVersion: v1@@ -381,6 +382,9 @@ rules:- apiGroups: ["apps"]resources: ["deployments"]verbs: ["get", "list", "watch"]+ - apiGroups: ["metrics.k8s.io"]+ resources: ["nodes", "pods"]+ verbs: ["get", "list"]# Optional (Recovery): VolumeSnapshots and Velero backups.# These rules are safe to include even if the APIs are not installed; the agent will# feature-detect and ignore 404/403 responses.@@ -405,6 +409,17 @@ roleRef:apiGroup: rbac.authorization.k8s.io```+These permissions do not install a metrics provider. The cluster must already+serve `metrics.k8s.io`; inventory can remain available when usage collection+is unavailable, and missing usage is not measured zero.++This role grants no Secret reads, `nodes/proxy`, writes or workload execution.+The collector's additional kubelet-summary path uses `nodes/proxy`, so network+and ephemeral-storage usage from that path can remain unavailable under this+minimal role even when API CPU/memory works. Do not broaden access or enable+host privileges merely to fill an empty field. Follow the+[failure-specific checks](#4-troubleshooting) using existing observations.+## 3. Talos Linux SpecificsTalos Linux is immutable, so you cannot install the agent via the shell script. Use the DaemonSet approach above.diff --git a/frontend-modern/src/features/docs/__tests__/kubernetesSetupDocs.test.ts b/frontend-modern/src/features/docs/__tests__/kubernetesSetupDocs.test.tsindex eef8be9e93..a8e851b576 100644--- a/frontend-modern/src/features/docs/__tests__/kubernetesSetupDocs.test.ts+++ b/frontend-modern/src/features/docs/__tests__/kubernetesSetupDocs.test.ts@@ -1,4 +1,5 @@import { readFileSync } from 'node:fs';+import { createRequire } from 'node:module';import path from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, it } from 'vitest';@@ -8,6 +9,22 @@ const frontendRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)),const repoRoot = path.resolve(frontendRoot, '..');const readDoc = (name: string) => readFileSync(path.join(repoRoot, 'docs', `${name}.md`), 'utf8');const guide = readDoc('KUBERNETES');+// js-yaml is already in the committed lint/build graph. Parse the copied YAML,+// rather than accepting a permissions sentence elsewhere in the guide.+const yaml = createRequire(import.meta.url)('js-yaml') as {+ loadAll: (text: string) => unknown[];+};+type Rule = { apiGroups: string[]; resources: string[]; verbs: string[] };+type Role = { kind: string; rules: Rule[] };++function canReadMetrics(role: Role, resource: string) {+ return role.rules.some(+ (rule) =>+ rule.apiGroups.includes('metrics.k8s.io') &&+ rule.resources.includes(resource) &&+ rule.verbs.includes('list'),+ );+}function articleFor(name: string) {const article = document.createElement('article');@@ -78,11 +95,87 @@ describe('Kubernetes credential setup and diagnosis', () => {);});- it('ships the exact canonical guide without changing the optional host profile', () => {+ it('copies the metrics read role and binds it to the actual agent service account', () => {+ const article = articleFor('KUBERNETES');+ const block = [...article.querySelectorAll('pre code')].find((code) =>+ code.textContent?.includes('kind: ClusterRole\n'),+ )!.textContent!;+ const [account, role, binding] = yaml.loadAll(block) as [+ { kind: string; metadata: { name: string; namespace: string } },+ Role & { metadata: { name: string } },+ { subjects: { kind: string; name: string; namespace: string }[]; roleRef: { name: string } },+ ];+ expect(account.kind).toBe('ServiceAccount');+ expect(account.metadata).toEqual({ name: 'pulse-agent', namespace: 'pulse' });+ expect(role.kind).toBe('ClusterRole');+ expect(binding.subjects).toEqual([{ kind: 'ServiceAccount', ...account.metadata }]);+ expect(binding.roleRef.name).toBe(role.metadata.name);+ for (const resource of ['nodes', 'pods']) {+ expect(canReadMetrics(role, resource), resource).toBe(true);+ }+ expect(role.rules.find((rule) => rule.apiGroups.includes('metrics.k8s.io'))).toEqual({+ apiGroups: ['metrics.k8s.io'],+ resources: ['nodes', 'pods'],+ verbs: ['get', 'list'],+ });+ for (const rule of role.rules) {+ expect(rule.verbs.every((verb) => ['get', 'list', 'watch'].includes(verb))).toBe(true);+ expect(+ rule.resources.some((resource) =>+ ['*', 'secrets', 'nodes/proxy', 'pods/exec'].includes(resource),+ ),+ ).toBe(false);+ expect(rule.apiGroups).not.toContain('*');+ }+ // Missing metrics group, wrong resource, and get-only all deny the actual+ // list requests; these controls would catch the predecessor's recipe.+ for (const changed of [+ block.replace('["metrics.k8s.io"]', '["other.example"]'),+ block.replace(+ 'apiGroups: ["metrics.k8s.io"]\n resources: ["nodes", "pods"]',+ 'apiGroups: ["metrics.k8s.io"]\n resources: ["nodes"]',+ ),+ block.replace('verbs: ["get", "list"]', 'verbs: ["get"]'),+ ]) {+ expect(changed).not.toBe(block);+ const changedRole = yaml.loadAll(changed)[1] as Role;+ expect(['nodes', 'pods'].every((resource) => canReadMetrics(changedRole, resource))).toBe(+ false,+ );+ }+ });++ it('keeps API usage, optional host identity and incomplete collection distinct', () => {+ const article = articleFor('KUBERNETES');+ const text = article.textContent!.replace(/\s+/g, ' ');+ for (const boundary of [+ 'It does not require host mounts or privileged mode',+ 'not a complete role for every Kubernetes tab',+ 'These permissions do not install a metrics provider',+ 'missing usage is not measured zero',+ 'grants no Secret reads, nodes/proxy, writes or workload execution',+ 'network and ephemeral-storage usage',+ 'Its shared PULSE_AGENT_ID is not an identity for every host',+ 'distinct, stable identity for each node',+ 'preserve the current IDs, credentials and state',+ 'Read-only host mounts do not remove the security exposure of a privileged pod',+ ])+ expect(text, boundary).toContain(boundary);+ const recipes = [...article.querySelectorAll('pre code')].map((code) => code.textContent!);+ expect(+ recipes.some((recipe) => recipe.includes('privileged: true') || recipe.includes('hostPath:')),+ ).toBe(false);+ for (const anchor of ['rbac', 'add-host-metrics-optional', '4-troubleshooting']) {+ expect(article.querySelector(`a[href="#${anchor}"]`)).not.toBeNull();+ expect(article.querySelector(`[id="${anchor}"]`)).not.toBeNull();+ }+ for (const anchor of ['configuration', 'duplicate-agents']) {+ expect(article.querySelector(`a[href="/docs/UNIFIED_AGENT#${anchor}"]`)).not.toBeNull();+ expect(articleFor('UNIFIED_AGENT').querySelector(`[id="${anchor}"]`)).not.toBeNull();+ }+ });++ it('ships the exact canonical guide with the scoped role and existing private-file recipes', () => {expect(readFileSync(path.join(frontendRoot, 'public/docs/KUBERNETES.md'), 'utf8')).toBe(guide);- const hostProfile = guide.split('#### Add Host Metrics (Optional)')[1].split('#### RBAC')[0];- expect(hostProfile).toContain('privileged: true');- expect(hostProfile).toContain('readOnly: true');- expect(hostProfile).toContain('PULSE_ENABLE_HOST');});});