Kubernetes monitoring with osuite-k8s

The osuite-k8s Helm chart is the supported way to monitor a Kubernetes cluster with Osuite. It installs OpenTelemetry collectors that scrape node, pod, and object metrics, watch cluster events, and optionally collect host metrics and container logs, then forward everything to your Osuite ingest endpoint over OTLP.

The chart is published from the public osuite-io/integrations repository. If you would rather assemble the collector configuration yourself, see Manual collector setup.

What the chart installs

The chart deploys two OpenTelemetry collectors, managed by the bundled OpenTelemetry Operator, plus kube-state-metrics.

• Cluster-wide collector (otel-clusterwide, a single-replica Deployment) — always installed. It collects:
  • Node, pod, and container metrics from every kubelet and cAdvisor endpoint.
  • Object-state metrics scraped from kube-state-metrics (deployments, replicasets, statefulsets, daemonsets, jobs, cronjobs, pods, nodes, namespaces).
  • Cluster events and object snapshots through the k8sobjects receiver — see Kubernetes events.
• Node collector (otel-daemon, a DaemonSet) — installed only when you enable host metrics or container logs. It collects:
  • Host CPU, memory, disk, filesystem, network, and load metrics (otel_daemon.enableHostMetrics).
  • Container stdout and stderr logs with per-namespace filtering (otel_daemon.containerlogs) — see Container logs.
• kube-state-metrics — installed as a subchart (kube-state-metrics.enabled, on by default) and scraped by the cluster-wide collector.

Prerequisites

• A Kubernetes cluster and kubectl configured against it, with permission to create cluster-scoped RBAC.
• Helm 3.
• An Osuite ingest token and your region’s ingest endpoint.

The chart bundles the OpenTelemetry Operator and kube-state-metrics as subcharts. If the Operator is already installed in your cluster, disable the bundled one with opentelemetry.enabled: false.

Install

1. Add the chart repository.

   helm repo add osuite https://osuite-io.github.io/integrations
   helm repo update

2. Create a values.yaml. At minimum, set your ingest credentials and a cluster name.

   common:
     osuite_ingest_key: "<your-ingest-token>"
     osuite_ingest_endpoint: "ingest.<region>.osuite.io:443"
   
   cluster: "prod-us-east"
   environment: "production"
   
   otel_daemon:
     enableHostMetrics: true
     containerlogs:
       enabled: true

   cluster and environment are attached as resource attributes to the telemetry the chart sends, so you can scope dashboards and queries to this cluster. Host metrics and container logs are opt-in; leave them at their defaults to install only the cluster-wide collector.

3. Install the chart into its own namespace.

   helm install osuite-k8s osuite/osuite-k8s \
     --namespace osuite \
     --create-namespace \
     --values values.yaml

Note

The chart bundles kube-state-metrics and the OpenTelemetry Operator as subchart dependencies, so a repository install pulls them in automatically. You do not need to run helm dependency build.

Validate

Confirm the operator has reconciled the collectors and their pods are running.

kubectl get opentelemetrycollectors -n osuite
kubectl get pods -n osuite

You should see the otel-clusterwide Deployment pod, one otel-daemon pod per node (if you enabled host metrics or container logs), and the kube-state-metrics pod.

Verify in Osuite

What you should see

Within a few minutes, cluster and node metrics appear on the Kubernetes dashboards, filterable by the cluster label you set. Cluster events show up as a log stream, and — if enabled — container logs appear under the workloads that produced them.

Data collected

Signal	Receiver	What it covers
Metrics	prometheus/kubelet (kubelet + cAdvisor)	Node, pod, and container CPU, memory, network, and filesystem usage
Metrics	prometheus/ksm (kube-state-metrics)	Object state: deployments, replicasets, statefulsets, daemonsets, jobs, cronjobs, pods, nodes, namespaces
Metrics	hostmetrics (DaemonSet, optional)	Host CPU, memory, disk, filesystem, network, and load
Logs	k8sobjects	Cluster events plus periodic object snapshots
Logs	filelog (DaemonSet, optional)	Container stdout and stderr, enriched with workload identity

Next steps

• Kubernetes events — how cluster events are collected and enriched.
• Container logs — namespace, pod, and severity filtering.
• Manual collector setup — the raw-collector alternative for teams not using Helm.
• Dashboards and Alerts — visualize and alert on the metrics the chart collects.

Troubleshooting

Collectors never appear after helm install? The most common causes are Operator-related:

• Operator webhook not ready — if the otel-clusterwide or otel-daemon resources exist but no pods are created, the Operator is usually not running. Check the Operator pods in the release namespace, and if you disabled the bundled Operator, confirm your own installation is healthy.
• Missing kube-state-metrics scrape — if object-state metrics are absent but kubelet metrics arrive, confirm the kube-state-metrics pod is running and kube-state-metrics.enabled was not set to false.
• Nodes with taints — the collectors tolerate all taints by default so the DaemonSet lands on every node; if you overrode tolerations, some nodes may be skipped.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.