What Shepherd is

Shepherd is a self-hosted, Kubernetes-first fleet manager for Grafana Alloy. It runs in your cluster, holds your collectors’ configuration centrally, and serves each one exactly the config it should be running over Alloy’s own remotecfg protocol. Collectors poll it; it never connects to them, so it needs no access into the clusters it manages and no inbound path to a collector.

How it fits together

Alloy (spoke)  ──remotecfg──▶  Shepherd  ──serves──▶  merged Alloy config
                                  │
                 ┌────────────────┼────────────────────┐
                 ▼                ▼                    ▼
           PostgreSQL         Merge engine         Git (GitOps)
        (sessions, store)  (matcher + declare)      (repo_links)

• Collectors authenticate with an agent token over HTTP Basic auth, or with an access token from your identity provider, and poll for their configuration on an interval you choose.
• The merge engine takes every enabled pipeline whose matchers select a given collector and merges them into the single config that collector is served. Pipelines come from a wizard, the visual builder, raw Alloy or git (see Authoring pipelines), and any of them can be read as a graph, Alloy modules drawn as groups — chart-generated config from grafana/k8s-monitoring included.
• PostgreSQL holds everything: pipelines, orgs, sessions, credentials. Shepherd itself is stateless, so the chart runs two replicas by default and you can scale it like any other Deployment. The database is the only thing to back up.
• Git is optional. A repo can be the source of pipelines instead of the UI — see GitOps.

What a collector actually gets

One merged config, assembled from the pipelines that match it. A collector in an unclaimed cluster is served an empty config, and a claimed one that matches nothing a config with no pipelines (only the beacon), rather than an error, so an unclaimed or unmatched collector keeps running whatever it already had locally — nothing is disrupted until somebody claims its cluster and enables pipelines that select it.

Every pipeline passes a three-stage validation gate before it can be served, so a config that would not start is refused at authoring time rather than discovered by a collector at 3am.

The beacon

Every claimed collector is also served a small baseline pipeline that reports which components it is running and whether they are healthy. It reports component names and health only — never config text, never raw samples. It is on by default; set server.beacon_disabled: true to turn it off.

What it is not

• Not a telemetry backend. Shepherd stores none of your metrics, logs or traces. It configures the collectors that ship them, and the data goes wherever your destinations point. The beacon reports only component names and health, and the optional receiver tier is an Alloy that forwards each tenant’s data straight to your backends.
• Not a replacement for Alloy. What Shepherd serves is ordinary Alloy config. Anything Alloy can run, it can serve; anything Alloy cannot, it refuses at the gate.
• Not an agent installer. You deploy Alloy however you already do; Shepherd takes over from the point it starts polling.

Organisations

Everything is scoped to an organisation: collectors are claimed into one, pipelines belong to one, and roles are granted per organisation. An application administrator creates orgs and sets each one’s tenant identity; everyone else works inside one. See Roles and access.