Telflo Docs

A Kubernetes fleet manages collectors that run in a Kubernetes cluster as OpenTelemetryCollector resources under the OpenTelemetry Operator. Instead of installing a supervisor on each host, you install one bridge into the cluster. The bridge connects to Telflo, reports the collectors it manages, and applies each collector's assigned configuration. The Operator then rolls the collector pods.

One bridge per cluster. Telflo sends each collector's assigned configuration to the bridge and reads status back. The bridge manages the collectors in the cluster.

Kubernetes fleets manage operator-managed collectors only: collectors that run as OpenTelemetryCollector resources. To run a standalone collector container in a cluster you manage yourself, use a server fleet and its container image instead. See Install collectors.

How a Kubernetes fleet differs from a server fleet

	Server fleet	Kubernetes fleet
Connection	Each collector runs a supervisor that connects to Telflo.	One bridge per cluster connects to Telflo and manages many collectors.
Configuration	The fleet has a default version, rolled out with Set Default Version.	Configurations are assigned per collector. There is no fleet default version.
Install token	Expiry set at creation. Rotation is picked up automatically.	One token, created with the fleet, with no expiry choice. After rotating, redeploy the bridge.
Install	A bundle or container per host.	One bridge install per cluster.

Create a Kubernetes fleet

Go to Fleet Mgmt and select New Fleet.
In the Create a new fleet dialog, select Create new Kubernetes Bridge Fleet.
Enter a Name. The name must be unique within your organization.
Select Create fleet.

You do not select a configuration or a token expiry. Collectors you onboard report the configuration they already run, and collectors you add from Telflo get a configuration when you add them. The fleet's token is created with the fleet, with no expiry.

Deploy the bridge

Open the fleet and select Deploy. The Deploy Telflo bridge dialog asks whether the cluster already has collectors.
Select I have existing collectors to onboard OpenTelemetryCollector resources already running in the cluster, or I have no collectors yet to install only the bridge.
For existing collectors, enter the Namespaces to onboard as a comma-separated list, or select All namespaces. Collectors in the selected namespaces are onboarded when the bundle installs.
Select Include Operator Installer if the OpenTelemetry Operator is not yet installed in the cluster. The installer sets up cert-manager and the Operator, and requires cluster-admin access.
Install with one of the two options:
- Quick Deploy. Generates a single command that downloads the bundle and runs the install. Run it on a machine with cluster-admin kubectl and helm access. The URL in the command is a credential and expires after 24 hours. Active URLs are managed on the fleet's Deployment Tokens tab.
- Download. Downloads a zip with the installers and a README. Follow the README for the exact steps. The bundle contains the fleet's token, so treat it as a secret.

The bridge installs into the telflo-system namespace. Once it connects, onboarded collectors appear on the fleet's Collectors tab, each with the configuration it reported.

How configuration flows

The bridge checks in with Telflo about every 30 seconds. On each check-in it reports the collectors it manages and the configuration each one runs, and receives the configuration assigned to each collector. The bridge applies the changes, and the Operator rolls the affected collector pods.

Status can take a short time to reflect a change: the Operator must roll the collector, and the bridge reports the result on its next check-in.

Add a collector

You can create a collector in the cluster from Telflo.

On the Collectors tab, select Add collector. The button appears once the bridge has connected.
Enter the Namespace and a Collector name.
Select the Configuration and its published Version. The collector image is matched to the configuration's collector version automatically.
Select the Mode: Deployment for a gateway or standalone collector, or DaemonSet for one collector on every node.
Review the assembled OpenTelemetryCollector resource in the preview. The preview is read-only; select Download to keep a copy, for example for a Git repository.
Select Ok. The bridge creates the collector on its next check-in.

The success step shows the collector's in-cluster service address, in the form <name>-collector.<namespace>.svc.cluster.local. Point your applications' telemetry at this address. The ports depend on the receivers in the collector's configuration.

Assign configurations

Configuration is assigned per collector on a Kubernetes fleet.

To change one collector, select its Name on the Collectors tab and assign a published configuration version.
To change several at once, select Migrate Instances and pin the selected collectors to a configuration version.

Changes are picked up on the bridge's next check-in. A collector you onboarded but have not assigned a configuration to is report-only: Telflo shows the configuration it runs but does not manage it, and it is never counted as drift.

Monitor a Kubernetes fleet

The stats strip leads with the Bridge state.

Bridge state	Meaning
Applied	The bridge applied the last configuration it received.
Applying	The bridge received a configuration change and is applying it.
Failed	The last apply failed. The error is shown on the stat.
Connected	The bridge is checking in, and no collectors are reported in the cluster yet.
Unknown	The bridge has stopped checking in. Collector state may be out of date.

Each collector on the Collectors tab shows a status.

Status	Meaning
Online	The bridge confirmed the collector within the last 2 minutes.
Pending pickup	A configuration is assigned, but the bridge has not picked it up yet.
Apply failed	The bridge reported an apply failure whose error names this collector. The bridge reports one result for all the collectors it manages, so the attribution is best-effort.
Degraded	The collector is running but not healthy, such as pods not ready.
Unknown	The bridge has not reported for more than 2 minutes, so Telflo has lost visibility. The collector itself may still be running.
Stale	The bridge is reporting, and this collector is gone from the cluster.

Because the bridge reports on the collectors' behalf, a quiet bridge means lost visibility, not stopped collectors. Unknown points at the bridge; Stale points at the collector. To investigate a quiet bridge, check the bridge pod in the telflo-system namespace.

The table also shows each collector's namespace, mode, assigned and running configuration versions, running collector version, and when it was last seen.

Remove a collector

Removing a collector from the Collectors tab stops Telflo from managing it. The workload itself is not deleted from the cluster, and a collector that is still running is discovered again on the bridge's next check-in. To remove it permanently, delete it from the cluster as well.

Tokens

A Kubernetes fleet has one token, created with the fleet. The bridge authenticates with it, and the deploy bundle embeds the current token when the bundle is generated. The token does not expire; copy it from the Client Tokens tab if you need it directly. If the token is exposed, rotate it and redeploy the bridge: a deployed bridge keeps its installed token, so it needs a redeploy to authenticate with the new one. Quick Deploy URLs are managed separately on the Deployment Tokens tab. See Tokens & security.

Kubernetes fleets

On this page