Tokens & security
Manage the tokens that authenticate a fleet's collectors and installs.
A fleet's collectors authenticate to Telflo with two credentials.
| Credential | Purpose |
|---|---|
| Install token | Delivered with the fleet's install commands: the Quick Deploy command and the container run command carry it, and for a downloaded bundle you set it on the host as the OPAMP_TOKEN environment variable. A collector authenticates with it when it first connects, and falls back to it if its fleet token becomes invalid. It does not expire and is not affected by token rotation. |
| Fleet token | A rotating bearer token issued at fleet creation with the expiry you choose. A connected collector receives it and uses it at runtime. Rotate and revoke it from the fleet's Tokens tab. |
The fleet's Tokens tab has two sections.
| Section | Contents |
|---|---|
| Fleet Tokens | The fleet's rotating tokens, with their creation and expiry dates, status, and recent activity. During a rotation, the outgoing token shows as the predecessor until the grace period ends. Rotate or revoke here. |
| Install Links | The time-limited Quick Deploy links generated when you install collectors: who generated each one, a masked value, its status and download history, and actions to copy the install command, extend the expiry (from 1 day up to never), or revoke the link. Revoking a link stops further downloads; collectors already installed are unaffected. |
Revealing a fleet's container run command discloses the install token, so each reveal is recorded in the token audit log, the same as viewing a token. For the Docker and Linux platforms, composing an install command with telflo fleet install or POST /fleets/{id}/install embeds the token in the output and is recorded the same way; the Kubernetes platform's output carries a time-limited values.yaml download URL instead, with the token inside the downloaded file, and it is that download that is recorded.
Expiry
You set the fleet token's expiry when you create the fleet: Never, 180 days, 1 year, or 2 years. A server fleet created through the Telflo API takes the same choice as expires_in, and telflo fleet create as --expires-in, with never as the default; a Kubernetes supervisor fleet's token is issued without expiry whatever the API is given. Either way the response reports the install token's ID and never a token value. The Fleet Tokens section shows the active token and its expiry.
Rotate a token
Rotating mints a new fleet token and schedules the current one for graceful retirement. Select Rotate token in the Fleet Tokens section, then choose the new token's expiry (Never, 180 days, 1 year, or 2 years) and the date the grace period ends; it defaults to 30 days from the rotation and must be on or before the new token's expiry. During the grace period, both tokens authenticate.
Telflo's supervisor-managed collectors switch to the new token automatically at a check-in shortly after the rotation, with no change on the hosts. A collector that restarts authenticates with its install token and receives the current fleet token on its next check-in. No reinstall is needed.
On a Kubernetes bridge fleet, the bridge does not pick up a rotated token automatically. After rotating, redeploy the bridge so it authenticates with the new token. See Kubernetes fleets.
Rotate the token when it is approaching expiry, or on a regular schedule.
Revoke a token
Revoking invalidates a fleet token, and collectors using it are rejected at check-in within about 30 seconds; the server caches token state briefly, so a just-revoked token can authenticate for up to 30 seconds more. A collector that reconnects with its install token, for example after a supervisor restart, stays enrolled and visible in the fleet, but Telflo stops delivering configuration to it: its last applied configuration keeps running unchanged, telemetry included. A newly installed collector receives no configuration beyond its bundled starter config. Configuration delivery resumes when you rotate to issue a new fleet token. Revoking the only valid fleet token stops configuration delivery for the whole fleet this way; it does not stop the collectors or their telemetry.
If an install artifact leaks, revoke its Quick Deploy link from the Install Links section, and re-create the fleet if the install token itself is exposed. The install token cannot be rotated or revoked from the Tokens tab and has no expiry. A fleet whose install token is no longer valid reports Default token is revoked. Re-create the fleet to issue a new one. when you reveal the container run command, or No default token for this deployment. The deployment must be re-created. when you generate a Quick Deploy or Download command; either way, the fleet must be re-created.
Quick Deploy links can be revoked individually from the Install Links section.
Kubernetes fleet tokens
A Kubernetes bridge fleet has one fleet token, created with the fleet and embedded in the bridge install command shown in the fleet's deploy steps. There is no expiry choice at creation, and the raw token can be copied from the Tokens tab. Rotation is available, with the new token's expiry and the grace period chosen in the Rotate token dialog, and a deployed bridge keeps its installed token, so redeploy the bridge after rotating. Re-create the fleet only when no valid token remains. See Kubernetes fleets.
A Kubernetes supervisor fleet, available in private preview, also has no expiry choice at creation, and the token created with the fleet does not expire; a later rotation asks for the new token's expiry, so choose Never to keep it non-expiring. Its Tokens tab has the same Fleet Tokens and Install Links sections, without a copy button for the raw token. The install token is embedded in each deploy group's downloaded values.yaml and reaches the collector pods through a Kubernetes Secret as OPAMP_TOKEN; the pods then pick up a rotated fleet token automatically, like server-fleet collectors, so no redeploy is needed after a rotation. The 24-hour values.yaml download links appear under Install Links.
Recommendations
- Keep install commands, tokens, Quick Deploy links, and any configuration environment variable values you included in them out of source control and shared documents. They are credentials. On installed hosts, the token is stored in the bundle's
opamp.envfile, readable by root only; treat that file as a secret. The output oftelflo fleet installcarries the token for Docker and Linux, and a time-limited download URL for Kubernetes, so do not commit it. - Keep a deploy group's volume mounts read-only unless the collector must write to the path, and avoid mounting sensitive host paths such as
/etcor the Docker socket; the editor warns about both. - Set a bounded expiry rather than Never for long-lived fleets, and rotate on a schedule.
- For credentials inside your configurations, such as backend API keys, reference environment variables with
${env:NAME}so the values come from the host environment and are not embedded in the YAML you publish. If you enter a variable's value under Configuration environment variables (optional) in the install or deploy dialog, the value is written into the run command, the bundle's start script, or the helm command, so treat that artifact as a secret; leave the variable unchecked to set it on the host or in the cluster instead. See Install collectors and Vault.
Last updated on