fleet-management-operator¶
Manage Grafana Cloud Fleet Management as Kubernetes custom resources. Fleet Management distributes Alloy or OpenTelemetry Collector configuration fragments — "pipelines" — to fleets of collectors, matching them by Prometheus Alertmanager-style label selectors (collector.os=linux, env!=development). Fleet Management's own console and Terraform provider are the usual way to author pipelines; this operator lets you do it with kubectl
apply instead, so pipeline definitions live in Git next to the rest of your cluster configuration and go through the same review and GitOps flow.
This is a community project, not an official Grafana Labs product. See the disclaimer in the GitHub README.
What it manages¶
Seven CRDs in the fleetmanagement.grafana.com/v1alpha1 API group, each mapping to a Fleet Management concept:
| CRD | What it does |
|---|---|
Pipeline | Pushes an Alloy or OpenTelemetry Collector config fragment to Fleet Management, scoped to matching collectors. |
PipelineDiscovery | Imports existing Fleet Management pipelines as read-only (or adoptable) Pipeline CRs. |
Collector | Manages remote attributes for one specific, already-registered collector by ID. |
CollectorDiscovery | Mirrors Fleet Management's registered collectors into Collector CRs automatically. |
RemoteAttributePolicy | Assigns default remote attributes to every collector matching a selector. |
ExternalAttributeSync | Pulls collector attributes from an external HTTP or SQL source (a CMDB, for example) on a schedule. |
TenantPolicy | Cluster-scoped RBAC guardrail: requires specific matchers on CRs authored by a given Kubernetes subject. |
Every CRD except TenantPolicy is namespaced. Pipeline is the only controller enabled by default — everything else is opt-in per the flags reference.
Why a Kubernetes operator for this¶
Fleet Management's API has no concept of Kubernetes RBAC: anyone holding the Cloud access token has full read/write over every pipeline and collector in the stack. Routing all changes through this operator's CRDs turns Kubernetes admission into the enforcement point instead — standard RBAC decides who can create a Pipeline in which namespace, and the opt-in TenantPolicy CRD adds a further "which collectors can this subject target" layer on top. The trade-off is that the operator itself becomes a single, powerful credential holder; read Security Model and Hardening before delegating CR creation to non-admins.
How it works, briefly¶
The controller manager runs one reconciler per enabled CRD. Each reconciler is driven by Kubernetes watch events (no polling of the API server), calls the Fleet Management HTTP API through a shared rate-limited client (default 3 requests/second, matching Fleet Management's own server-side limit), and writes the result back as status.conditions and Kubernetes events. A validating admission webhook enforces spec-shape rules — matcher syntax, config type/contents agreement, reserved attribute-key prefixes — before anything reaches the Fleet API. See Architecture for the full reconcile-loop and webhook picture.
Current status¶
All CRDs ship at v1alpha1, the only served and stored version — see API Versioning and Graduation Policy for the graduation criteria and known v1 blockers. The project has tagged releases (images at ghcr.io/rknightion/fleet-management-operator, Helm chart at oci://ghcr.io/rknightion/charts/fleet-management-operator) but the API and defaults can still change within v1alpha1 per that document's compatibility rules.
Start here¶
- Getting Started — install the chart, get credentials, apply your first
Pipeline. - Sample CRs — a runnable example of every CRD.
- Manager Flags — every CLI flag, its default, and the matching Helm value.
- Security Model and Hardening — read this before delegating CR creation to non-admins or enabling the discovery controllers in a multi-tenant cluster.
- Troubleshooting and Runbooks — diagnosing sync failures, webhook rejections, and alert conditions.
The source, issue tracker, and CONTRIBUTING guide live on GitHub.