Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Keep Kubernetes metrics setup read-only and host identities separate

pulse-triage[bot]b3b7c286693f
diff --git a/docs/KUBERNETES.md b/docs/KUBERNETES.md
index 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.
```yaml
apiVersion: 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 Specifics
Talos 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.md
index 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.
```yaml
apiVersion: 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 Specifics
Talos 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.ts
index 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');
});
});