Kubernetes fleets
Manage the collectors in a Kubernetes cluster through one bridge.
A Kubernetes bridge 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.
There are two Kubernetes fleet types. This page covers the Kubernetes bridge fleet, which manages operator-managed collectors: collectors that run as OpenTelemetryCollector resources. A Kubernetes supervisor fleet instead runs supervisor-managed collectors installed by Helm into node, cluster, and gateway groups, with no bridge and no Operator; it is available in private preview. To run a standalone collector container in a cluster you manage yourself, use a server fleet and its container image. See Install collectors.
How a Kubernetes bridge fleet differs from a server fleet
| Server fleet | Kubernetes bridge fleet | |
|---|---|---|
| Connection | Each collector runs a supervisor that connects to Telflo. | One bridge per cluster connects to Telflo and manages many collectors. |
| Configuration | Each deploy group has an assigned version, managed on the Deploy Groups tab. | 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 at creation. After rotating, redeploy the bridge. |
| Install | A bundle or container per host. | One bridge install per cluster. |
Create a Kubernetes bridge fleet
- Go to Fleet and select New Fleet.
- In the Create a new fleet dialog, select Kubernetes (Operator bridge) under Kubernetes. If the card shows a Private Preview badge and cannot be selected, the bridge fleet is not yet enabled for your account. The New Kubernetes Bridge Fleet dialog opens.
- Enter a Name. The name must be unique within your organization.
- Select Create fleet.
The fleet opens on its detail page with a setup checklist: deploy the bridge, wait for it to report the cluster's collectors, and assign configurations. 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
OpenTelemetryCollectorresources 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 of DNS-1123 names, or select All namespaces (label every collector cluster-wide). Collectors in the selected namespaces are onboarded when the install runs. View Steps is available once you have entered a namespace or selected the checkbox.
- Select Include Operator Installer if the OpenTelemetry Operator is not yet installed in the cluster. The install then includes a step that sets up the Operator from its published Helm chart, with self-generated webhook certificates; cert-manager is not required.
- Select View Steps. The Deploy steps dialog shows numbered, copyable commands to run in order on a machine with cluster-admin
kubectlandhelmaccess: install the Operator if you included it, install the Telflo bridge from its published Helm chart, label the existing collectors to onboard them, and verify that the bridge pod is running.
The bridge install command contains the fleet's token. It is masked on screen, and copying puts the real value on your clipboard, so share it over a secure channel only and keep it out of shared logs. If it leaks, rotate the token from the fleet page.
The bridge installs into the telflo-system namespace. Until it first checks in, the fleet page reads Awaiting first contact from bridge. Once it connects, onboarded collectors appear on the fleet's Collectors tab, each with the configuration it reported, and the setup checklist can be reopened later with Setup guide.
How configuration flows
The bridge checks in with Telflo about every 30 seconds. On each check-in it reports the health of the collectors it manages and receives the configuration assigned to each collector, and it re-reports a collector's running configuration when that configuration changes. 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. Both must be DNS-1123 labels: lowercase letters, digits, and hyphens, up to 63 characters. The Namespace field suggests namespaces already seen in the fleet.
- 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.
- Select Next, and review the assembled
OpenTelemetryCollectorresource in the preview; Back returns to the form. Select Download to keep a copy, for example for a Git repository. To adjust the resource before it deploys, select Edit: the preview becomes editable, and the edited resource is stored verbatim and applied by the bridge as-is. Manual edits are not validated beyond YAML well-formedness, and Download exports the resource exactly as previewed, including any edits. - 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 Pin collectors 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 Health Checks link on the Bridge stat opens the Bridge Health Checks dialog, which lists the bridge's recent health-check snapshots with when each state was first seen and last confirmed, and the collectors it reported.
The table also shows each collector's namespace, mode, assigned and running configuration versions, running collector version, and when it was last seen. Filter the table with the search box, which matches a collector's name, namespace, or configuration name as you type.
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.
Kubernetes supervisor fleets
A Kubernetes supervisor fleet, created with Kubernetes (Helm) in the Create a new fleet dialog and available in private preview, runs supervisor-managed collectors installed by Helm into node, cluster, and gateway deploy groups, with no bridge and no Operator. Each group's Deploy button, disabled with the tooltip Assign a configuration first until the group has a configuration, opens a dialog with the steps to run: download the group's values.yaml, which carries the mounts, then run the helm command the dialog assembles. For a configuration on OpenTelemetry Collector Contrib, the dialog lists the configuration's ${env:NAME} variables under Configuration environment variables (optional), the same way the server fleet's install dialog does. Each included value becomes a --set-string collectorEnv.NAME flag on the helm command and reaches the collector pods through a Kubernetes Secret; a variable left unchecked is marked not set here, and you deliver it to the pods yourself, for example as a collectorEnv entry in values.yaml.
The same steps are available from the CLI: telflo fleet create --label <name> --type kubernetes-supervisor creates the fleet, telflo deploy --fleet <fleet-id> --config <id> --name <group> --role node|cluster|gateway creates a deploy group, and telflo fleet install <fleet-id> --platform kubernetes --deployment <id> prints the values.yaml download and the helm command for that group, with --env NAME=value for the configuration's variables. The values.yaml link expires after 24 hours. For a ClickStack group the CLI does not add the ClickHouse connection flags; its notes tell you to add them to the helm command.
A supervisor fleet's deploy group dialogs also hold a Volume mounts editor, the same one a server fleet's deploy groups use, because every collector in a cluster is a container. The node role always mounts /var/log/pods; add hostPath mounts for other directories a filelog receiver reads or a file_storage extension writes. Paths the assigned configuration references are listed under This config references paths with no matching volume mount, each with an Add mount shortcut, and the heading changes to All referenced paths have a volume mount once every path is covered. Each mount is written into the group's values.yaml with its Type and becomes a pod volume. See Volume mounts.
ClickStack configurations
A Kubernetes supervisor fleet is the Kubernetes deploy path for a configuration on the ClickStack distribution, available in private preview; on a server fleet, only the container image option runs the ClickStack collector image. When a group's assigned configuration targets ClickStack, its Deploy button opens the Deploy dialog marked ClickStack, with three steps:
- Download the values.yaml. The file pins Telflo's ClickStack collector image for the configuration's ClickStack version.
- Provide Connection Details. Enter the ClickHouse endpoint, ClickHouse user, ClickHouse database, and ClickHouse password. The endpoint, user, and database are remembered for the group; the password is not stored.
- Deploy Helm. Copy and run the
helmcommand, which carries the connection details. The collector pod runs ClickHouse's schema migration when it starts, so ClickHouse must be reachable from the cluster.
Kubernetes bridge fleets and server fleet bundle installs run configurations on OpenTelemetry Collector Contrib. See Collector distributions.
Tokens
A Kubernetes bridge fleet has one token, created with the fleet. The bridge authenticates with it, and the bridge install command in the deploy steps embeds the current token when the steps are generated. The token created with the fleet does not expire; copy it from the Fleet Tokens section of the Tokens tab if you need it directly. If the token is exposed, select Rotate token: the dialog asks for New token expires, with Never, 180 days, 1 year, or 2 years and a default of 1 year, and Old token revoked on (grace period end), which defaults to 30 days out. Choose Never to keep the bridge's token non-expiring. Then redeploy the bridge: a deployed bridge keeps its installed token, so it needs a redeploy to authenticate with the new one. Regenerate the deploy steps for the redeploy, and confirm the bridge still authenticates after the grace period ends, since both tokens are valid until then. See Tokens & security.
Last updated on