STAC-24730: k8s-resource-collector docs

docs/latest/modules/en/nav.adoc

@@ -138,6 +138,7 @@
 ifdef::ss-ff-stackpacks2_enabled[]
 *** xref:setup/otel/agent.adoc[OpenTelemetry pipeline]
 *** xref:setup/otel/telemetry-gateway.adoc[Telemetry gateway]
+*** xref:setup/otel/k8s-resource-collector.adoc[K8s resource collector]
 endif::ss-ff-stackpacks2_enabled[]
 *** xref:k8s-suse-rancher-prime-agent-air-gapped.adoc[Air-gapped installation using Helm charts]
 *** xref:setup/k8s-network-configuration-saas.adoc[Network configuration for SaaS]

docs/latest/modules/en/pages/setup/otel/agent.adoc

@@ -7,12 +7,13 @@ ifdef::ss-ff-stackpacks2_enabled[]
 
 == Overview
 
-The SUSE Observability Agent ships with an OpenTelemetry Collector that supplements the existing agent components. It is the recommended path for ingesting telemetry from any workload that already speaks OTLP or exposes a Prometheus / OpenMetrics endpoint, and lets you consolidate metrics and traces into the SUSE Observability pipeline without running a separate collector. OTLP logs are accepted by the gateway pipeline for future compatibility, but platform log ingestion is not supported yet.
+The SUSE Observability Agent ships with OpenTelemetry Collector based components that supplement the existing agent components. They cover push-based application telemetry, Prometheus/OpenMetrics scraping, and Kubernetes Custom Resource topology collection without requiring a separately managed collector.
 
-The OTel pipeline covers two tracks, each implemented by its own sub-component and independently toggleable:
+The OTel support in the agent is split into independently toggleable components:
 
-* *Telemetry gateway* (`otel.telemetryGateway`) — receives *metrics and traces* pushed over OTLP from application-embedded OpenTelemetry SDKs and forwards them to SUSE Observability. The gateway also has a logs pipeline, but OTLP log ingestion is not supported by the platform yet; keep SDK log export disabled. Point your SDKs at the `suse-observability-agent-otel-telemetry-gateway` service in the agent's namespace on port `4317` (gRPC) or `4318` (HTTP).
+* *Telemetry gateway* (`otel.telemetryGateway`) — receives *metrics and traces* pushed over OTLP from application-embedded OpenTelemetry SDKs and forwards them to SUSE Observability. Point your SDKs at the `suse-observability-agent-otel-telemetry-gateway` service in the agent's namespace on port `4317` (gRPC) or `4318` (HTTP).
 * *Prometheus / OpenMetrics scraping* (`otel.prometheusScraping`) — discovers `ServiceMonitor` and `PodMonitor` Custom Resources, scrapes the targets they describe, and ships the resulting *metrics* over OTLP. This track is metrics-only; use it for workloads that expose a Prometheus / OpenMetrics endpoint but are not instrumented with an OTel SDK. See xref:/use/metrics/k8s-otel-prometheus-scraping.adoc[Scraping OpenMetrics with ServiceMonitor and PodMonitor] for the full how-to.
+* *K8s resource collector* (`otel.k8sResourceCollector`) — watches Custom Resource Definitions (CRDs), selected Custom Resource instances, and optional additional Kubernetes resources, then forwards topology logs to SUSE Observability. See xref:/setup/otel/k8s-resource-collector.adoc[K8s resource collector] for the full configuration guide.
 
 == Default state
 
@@ -56,22 +57,26 @@ otel:
     enabled: false    # stop accepting OTLP push from SDKs
   prometheusScraping:
     enabled: false    # stop scraping ServiceMonitor / PodMonitor targets
+  k8sResourceCollector:
+    enabled: false    # stop collecting CRD/CR topology
 ----
 
 == Resource impact
 
-When enabled, the OTel pipeline can add up to three workloads, depending on which sub-pipelines are turned on:
+When enabled, the OTel support can add up to four workloads, depending on which components are turned on:
 
-* A *telemetry gateway* OpenTelemetry Collector (when `otel.telemetryGateway.enabled=true`) that terminates the OTLP push receiver and forwards metrics and traces to SUSE Observability. The gateway logs pipeline is present for future compatibility, but platform log ingestion is not supported yet.
+* A *telemetry gateway* OpenTelemetry Collector (when `otel.telemetryGateway.enabled=true`) that terminates the OTLP push receiver and forwards metrics and traces to SUSE Observability.
 * A *scraper* OpenTelemetry Collector (when `otel.prometheusScraping.enabled=true`) that scrapes the targets selected by the Target Allocator.
 * A *Target Allocator* (when `otel.prometheusScraping.enabled=true`) that watches `ServiceMonitor` / `PodMonitor` resources and distributes scrape targets across the scraper collectors.
+* A *k8s resource collector* OpenTelemetry Collector (when `otel.k8sResourceCollector.enabled=true`) that discovers CRDs and selected Custom Resources.
 
-All three have conservative CPU and memory requests / limits that can be tuned in the agent Helm values under `otel.telemetryGateway`, `otel.prometheusScraping.collector`, and `otel.prometheusScraping.targetAllocator`. Refer to the agent Helm chart `values.yaml` for the full set of knobs.
+All workloads have conservative CPU and memory requests / limits that can be tuned in the agent Helm values under `otel.telemetryGateway`, `otel.prometheusScraping.collector`, `otel.prometheusScraping.targetAllocator`, and `otel.k8sResourceCollector`. Refer to the agent Helm chart `values.yaml` for the full set of knobs.
 
 == See also
 
 * xref:/k8s-quick-start-guide.adoc[Agent quick start guide]
 * xref:/setup/otel/telemetry-gateway.adoc[Telemetry gateway (OTLP push)]
+* xref:/setup/otel/k8s-resource-collector.adoc[K8s resource collector]
 * xref:/use/metrics/k8s-otel-prometheus-scraping.adoc[Scraping OpenMetrics with ServiceMonitor and PodMonitor]
 * xref:/setup/otel/concepts.adoc[OpenTelemetry concepts]
 * xref:/setup/otel/troubleshooting.adoc[OpenTelemetry troubleshooting]

docs/latest/modules/en/pages/setup/otel/k8s-resource-collector.adoc

@@ -0,0 +1,141 @@
+ifdef::ss-ff-stackpacks2_enabled[]
+= K8s resource collector
+:page-languages: [en, de, es, fr, ja, pt, zh]
+:revdate: 2026-07-09
+:page-revdate: {revdate}
+:description: SUSE Observability
+
+== Overview
+
+The *k8s resource collector* is an OpenTelemetry Collector component in the SUSE Observability Agent. It watches Kubernetes Custom Resource Definitions (CRDs), selected Custom Resource (CR) instances, and optional additional Kubernetes resources, then forwards topology logs to SUSE Observability.
+
+CRDs are always collected. CR instances are filtered by API group so you can control ingest volume and avoid forwarding large or sensitive resource payloads.
+
+== Enable
+
+The collector is enabled by default when StackPacks 2.0 support is enabled:
+
+[,yaml]
+----
+global:
+  features:
+    experimentalStackpacks: true
+----
+
+If you enable OTel without StackPacks 2.0, keep the collector enabled explicitly:
+
+[,yaml]
+----
+otel:
+  enabled: true
+  k8sResourceCollector:
+    enabled: true
+----
+
+== Include and exclude Custom Resource API groups
+
+Configure CR collection with `otel.k8sResourceCollector.crDiscovery.apiGroups`:
+
+[,yaml]
+----
+otel:
+  k8sResourceCollector:
+    crDiscovery:
+      discoveryMode: api_groups
+      apiGroups:
+        include:
+          "policies.kubewarden.io": true
+          "kubevirt.io": true
+        exclude:
+          "internal.example.com": true
+----
+
+By default, the chart does not collect every CR API group. Instead, the enabled integration presets add common SUSE-related API groups, such as Kubewarden, SUSE Runtime Enforcer, and SUSE Virtualization. Add more API groups explicitly when you want their CR instances collected.
+
+To disable an integration-provided API group in an override file, set it to `false`:
+
+[,yaml]
+----
+otel:
+  k8sResourceCollector:
+    crDiscovery:
+      apiGroups:
+        include:
+          "kubevirt.io": false
+----
+
+Set `discoveryMode: all` to collect CR instances for every CRD API group. In this mode, `apiGroups` filters are ignored.
+
+[NOTE]
+====
+The Kubernetes Custom Resources StackPack shows all collected CRDs. It marks whether CR instances for that CRD API group are collected. If CR instances are not collected, add the API group to `crDiscovery.apiGroups.include` and upgrade the agent.
+====
+
+== Restricted RBAC
+
+By default the collector uses wildcard read permissions for custom resources. For restricted RBAC, set `rbac.useWildcard: false`. The chart uses the truthy `crDiscovery.apiGroups.include` entries to render API-group RBAC rules:
+
+[,yaml]
+----
+otel:
+  k8sResourceCollector:
+    crDiscovery:
+      discoveryMode: api_groups
+      apiGroups:
+        include:
+          "policies.kubewarden.io": true
+          "kubevirt.io": true
+    rbac:
+      useWildcard: false
+----
+
+Kubernetes RBAC only supports exact API groups or `"*"`. Wildcard filter patterns such as `"*.example.com"` require `rbac.useWildcard: true`.
+
+== Payload budgets
+
+The collector uses total payload budgets to limit how much CR and object data is forwarded per collection cycle. CRDs themselves are always forwarded and do not count against these budgets. CRs and configured Kubernetes objects are considered smallest-first, then by stable identity. Objects that do not fit are dropped for that cycle.
+
+[,yaml]
+----
+otel:
+  k8sResourceCollector:
+    dataLimits:
+      maxCrTotalDataSizeBytes: 10485760       # 10 MiB
+      maxObjectTotalDataSizeBytes: 10485760   # 10 MiB
+----
+
+Increasing these values can increase ingest volume and may forward larger or sensitive payloads. Dropped records are counted by `receiver_k8sresource_payloads_dropped_total`; payload sizes are recorded in `receiver_k8sresource_payload_size_bytes`, labelled by `source` (`cr` or `object`), API group, kind, and outcome.
+
+== Additional Kubernetes resources
+
+Use `objects` to watch non-CRD resources alongside CRDs and CRs:
+
+[,yaml]
+----
+otel:
+  k8sResourceCollector:
+    objects:
+      pods:
+        group: ""
+        namespaces: ["kube-system"]
+      deployments:
+        group: apps
+        labelSelector: "app=foo"
+----
+
+Entries that overlap a CRD covered by `crDiscovery.apiGroups` are rejected at collector startup. With `rbac.useWildcard: false`, the chart derives resource-scoped RBAC for each `objects` entry automatically.
+
+== Operational monitoring
+
+The collector exposes OpenTelemetry Collector self-metrics on `:8888` and forwards those self-metrics to SUSE Observability. The Kubernetes Custom Resources StackPack includes monitors for:
+
+* No CRD/CR records emitted.
+* Oversized CR payloads dropped.
+* Informer reconcile failures.
+
+== See also
+
+* xref:/setup/otel/agent.adoc[OpenTelemetry pipeline overview]
+* xref:/setup/otel/telemetry-gateway.adoc[Telemetry gateway]
+* xref:/use/metrics/k8s-otel-prometheus-scraping.adoc[Scraping OpenMetrics with ServiceMonitor and PodMonitor]
+endif::ss-ff-stackpacks2_enabled[]

docs/latest/modules/en/pages/setup/otel/telemetry-gateway.adoc

@@ -7,7 +7,7 @@ ifdef::ss-ff-stackpacks2_enabled[]
 
 == Overview
 
-The *telemetry gateway* is an OpenTelemetry Collector component in the SUSE Observability Agent that accepts metrics and traces pushed over OTLP from application-embedded OpenTelemetry SDKs. It enriches the data with Kubernetes metadata and forwards it to the SUSE Observability platform. The gateway includes a logs pipeline for future compatibility, but OTLP log ingestion is not supported by the platform yet.
+The *telemetry gateway* is an OpenTelemetry Collector component in the SUSE Observability Agent that accepts metrics and traces pushed over OTLP from application-embedded OpenTelemetry SDKs. It enriches the data with Kubernetes metadata and forwards it to the SUSE Observability platform.
 
 Use the telemetry gateway when your workloads are instrumented with an OTel SDK (Java, Go, Python, Node.js, etc.) and export telemetry using OTLP. It is the recommended integration path for natively instrumented services.