Fleet Management Operator

A Kubernetes operator for managing Grafana Cloud Fleet Management Pipelines as native Kubernetes resources.

Disclaimer: This is not an official Grafana Labs product and is not officially supported by Grafana Labs. This is a community project provided as-is. For official Grafana Cloud Fleet Management support, please contact Grafana Support.

Overview

This operator enables declarative management of Fleet Management configuration pipelines using Kubernetes. Define your Alloy or OpenTelemetry Collector configurations as Kubernetes resources, and the operator automatically syncs them to Grafana Cloud Fleet Management.

Features

• Declarative Pipeline Management: Define pipelines as Kubernetes resources
• Dual Config Support: Both Grafana Alloy and OpenTelemetry Collector configurations
• Source Tracking: Track pipeline origins (Git, Terraform, Grafana)
• GitOps Friendly: Manage pipelines through version control
• Status Tracking: Pipeline status reflects Fleet Management state with conditions
• High Availability: Leader election support for multiple replicas

Custom Resources

This operator manages the following CRD types:

CRD	Purpose
Pipeline	Deploy Alloy or OpenTelemetry Collector config fragments to matching collectors
PipelineDiscovery	Import Fleet Management pipelines as Kubernetes Pipeline CRs
Collector	Manage remote attributes for a specific collector by ID
CollectorDiscovery	Auto-discover Fleet Management collectors and create Collector CRs
RemoteAttributePolicy	Assign default attributes to collectors matching a selector
ExternalAttributeSync	Sync collector attributes from an external HTTP or SQL source
TenantPolicy	Enforce RBAC tenancy by requiring specific matchers on CRs

See Sample CRs for runnable examples of every type.

Installation

Prerequisites

• Grafana Cloud Fleet Management credentials (base URL, username, password/token)
• cert-manager, or a manually managed webhook serving certificate and CA bundle

Get credentials from your Grafana Cloud Fleet Management interface:

• Navigate to Connections > Collector > Fleet Management
• Switch to the API tab
• Find the base URL and generate an API token

Install with Helm

# Ensure the default webhook issuer exists, or override webhook.certManager.issuerRef
kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-issuer
spec:
  selfSigned: {}
EOF

# Install the operator
helm install fleet-management-operator \
  oci://ghcr.io/rknightion/charts/fleet-management-operator \
  --namespace fleet-management-system \
  --create-namespace \
  --set fleetManagement.baseUrl='https://fleet-management-<CLUSTER>.grafana.net/pipeline.v1.PipelineService/' \
  --set fleetManagement.username='<STACK_ID>' \
  --set fleetManagement.password='<API_TOKEN>'

Supplying credentials from an existing Secret

Prefer this over inline --set values for anything beyond a quick test; point fleetManagement.existingSecret at it.

kubectl create namespace fleet-management-system
kubectl create secret generic fleet-management-operator-credentials \
  -n fleet-management-system \
  --from-literal=base-url='https://fleet-management-<CLUSTER>.grafana.net/pipeline.v1.PipelineService/' \
  --from-literal=username='<STACK_ID>' \
  --from-literal=password='<API_TOKEN>'

Usage

Create a Pipeline

Create a Pipeline resource to define your Alloy or OpenTelemetry Collector configuration. See Sample CRs for full working examples of both Alloy and OpenTelemetry Collector pipelines.

Apply a pipeline:

kubectl apply -n <namespace> -f pipeline.yaml

Check Pipeline Status

# List all pipelines
kubectl get pipelines -n <namespace>

# Get detailed status
kubectl describe pipeline prometheus-metrics -n <namespace>

# Watch for changes
kubectl get pipelines -n <namespace> -w

The status shows the Fleet Management pipeline ID and sync state:

status:
  id: "12345"
  observedGeneration: 1
  conditions:
  - type: Ready
    status: "True"
    reason: Synced
  - type: Synced
    status: "True"
    reason: UpsertSucceeded

Update a Pipeline

Edit the Pipeline resource and apply changes:

kubectl edit pipeline prometheus-metrics

The operator automatically syncs changes to Fleet Management.

Delete a Pipeline

kubectl delete pipeline prometheus-metrics -n <namespace>

The operator removes the pipeline from Fleet Management before deleting the Kubernetes resource.

Configuration

Matchers

Pipelines are assigned to collectors using matchers with Prometheus Alertmanager syntax:

• key=value - Equals
• key!=value - Not equals
• key=~regex - Regex match
• key!~regex - Regex not match

Example:

matchers:
  - collector.os=linux
  - environment!=development
  - region=~us-.*

Config Types

• Alloy: For Grafana Alloy collectors (default)
• OpenTelemetryCollector: For OpenTelemetry Collector instances

The configType must match your collector type.

Source Tracking

Track pipeline origins with the source field:

spec:
  source:
    type: Git  # or Terraform, Grafana, Unspecified
    namespace: github.com/myorg/configs

Grafana-sourced pipelines are observed as read-only. For discovered pipelines, fleetmanagement.grafana.com/import-mode=read-only means the operator mirrors Fleet status without creating or updating the remote pipeline.

Troubleshooting

Pipeline not syncing

Check controller logs:

kubectl logs -n fleet-management-system -l app.kubernetes.io/name=fleet-management-operator

Check pipeline status:

kubectl describe pipeline <pipeline-name>

Look for error messages in status.conditions.

Common Issues

Authentication error:

• Verify credentials in the secret are correct
• Check that the API token has Pipeline Management permissions

Validation error:

• Check status.conditions for specific validation errors
• Verify configType matches the configuration syntax (Alloy vs OTEL)

Rate limit exceeded:

• Controller automatically retries with exponential backoff
• Fleet Management has a 3 req/s limit on management endpoints

Pipeline stuck in Terminating:

• Check controller logs for finalizer removal errors
• Verify network connectivity to Fleet Management API

Uninstall

With Helm:

helm uninstall fleet-management-operator -n fleet-management-system
kubectl delete namespace fleet-management-system

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

Copyright 2026.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Resources

• Fleet Management Documentation
• Helm Chart Documentation — generated from values.yaml via just chart-docs
• CRD API Reference — generated from godoc on api/v1alpha1/*_types.go
• Manager Flags — every CLI flag, default, and chart coverage
• Metrics Reference — Prometheus metric names, labels, and bucket boundaries
• Event Reference — per-controller event reasons and their triggers
• Status Conditions — condition types and reasons emitted by each CRD
• Security Model & Hardening — trust boundaries, privileged-CR delegation, cross-namespace authority, and the hardening checklist
• Sample CRs — runnable examples for every CRD
• Upgrade Guide — CRD, webhook, and rollback guidance for production releases
• Contributor Guide — architecture notes, gotchas, and patterns

The generated reference pages above are updated by just docs; CI fails the build if they drift from source.