Connect a collector

Add a remotecfg block to the collector's config.alloy. Shepherd resolves the collector by its cluster and role attributes — role is one of metrics, logs, singleton, or receiver.

remotecfg {
  url = "http://shepherd:8080"
  basic_auth {
    username = "<token-uuid>"
    password = "<token-secret>"
  }
  attributes = {
    cluster = "<cluster-name>",
    role    = "metrics",
  }
  poll_frequency = "60s"
}

On first poll, an unclaimed cluster gets served an empty config so it keeps running whatever it already has locally — nothing is disrupted until an app admin claims the cluster for an organisation (Roles) and someone with edit rights in that organisation enables pipelines that match it. (A collector authenticating with OIDC under a binding is claimed into its bound organisation on its first poll.)

Collector status

Each collector shows the status its Alloy last reported for the config it was served:

• APPLIED — Alloy loaded the config it was served.
• FAILED — Alloy rejected it, and the collector page shows Alloy’s own error. The collector keeps running its previous config. A config can pass Shepherd’s validation and still fail here, for reasons only the host knows (a file path that does not exist there, Kubernetes discovery outside Kubernetes). When the error’s line falls inside a pipeline, the collector page, its Reconciliation tab and the pipeline’s own page say rejected in pipeline X (line N of its text, line M of the merged config); when the error belongs to an earlier served config, the page says that instead.
• APPLYING — Shepherd is serving a new config and Alloy has not reported on it yet. It lasts until the collector’s next poll, then turns APPLIED or FAILED. An APPLIED is always about the config being served now, never an earlier one; a FAILED collector served a new config stays FAILED until Alloy reports again.
• UNKNOWN — nothing reported yet, for example a collector that has not polled since it was created.

With agent.inactive_after set, an instance that has not polled for that long shows as inactive, whatever it last reported, and a collector shows inactive once all its instances are. Its last reported status is kept, not reset: when it comes back it shows that status again (a FAILED collector stays FAILED) until Alloy reports something new. On Kubernetes each Alloy restart registers a new instance, so the replaced pod’s row turns inactive while the new one carries the status.

A collector’s page has tabs for its Served Config (the exact merged config it receives), Reconciliation (whether what its role declares, what it is served and what its beacon reports agree), Info (its instances), and Attributes & Labels, where an org admin sets labels that pipelines can match on (Matchers); org admins also get Access, its group assignments.

The served config starts with // Generated by Shepherd, then lists each pipeline it includes with its revision, (rev N), and names any pipeline left out for its role and why. Any change to that text — including a revision bump with unchanged pipeline text — makes the collector reload once on its next poll.

With Grafana's k8s-monitoring chart

If your clusters run Grafana's k8s-monitoring Helm chart, Shepherd writes the values for you. On Collectors, an organisation admin chooses Connect a cluster, names the cluster and picks its collectors (metrics, logs, singleton, receiver). Shepherd returns:

• shepherd-layer.yaml — each collector's remoteConfig, pointed at this Shepherd's server.base_url, with the cluster name and role as attributes and the organisation's tenant if it has one;
• shepherd-credentials.yaml — loads the agent token into each collector from a Kubernetes Secret (it names the Secret; it never contains the token);
• the kubectl create secret and helm upgrade --install commands that use them.

Apply both files next to your own values — they set nothing else, so sizing, features and destinations stay yours. The values are checked against the k8s-monitoring version they name, and Shepherd's test suite installs that exact chart with them and watches a collector register and load a pipeline.

Two things still need an app admin: an agent token (Admin → Agent Tokens) for the Secret, and, once the collectors have registered, claiming the cluster for your organisation (Admin → Clusters). The dialog says which of those the cluster still needs. A cluster name another organisation already owns is refused.