Bootstrap an owner token

Set the OWNER_TOKEN environment variable or pass the --owner-token command flag and Telegraf Controller provisions that value as an API token at startup, owned by the owner account. This mirrors how OWNER_PASSWORD bootstraps the owner account, and exists so immutable-infrastructure and infrastructure-as-code workflows can hand Telegraf Controller a known administrative credential instead of creating one through the UI.

An all-access credential with no expiration

A bootstrap token has full administrative access and never expires. There is no way to express a narrower scope during bootstrap. Treat it as the root credential for the automation that provisions your Telegraf Controller instances, not as a general-purpose token.

Provision a bootstrap token

Set the token value using the environment variable or the command flag. If both are set, the command flag takes precedence.

OWNER_TOKEN=
TOKEN_VALUE
 ./telegraf_controller

Or use the command flag:

./telegraf_controller --owner-token=
TOKEN_VALUE

Replace TOKEN_VALUE with a value that meets the token requirements. To generate one, see Generate a token value.

The provisioned token has the following properties:

  • Description: bootstrap-token. If the description is taken, a numeric suffix is added, for example, bootstrap-token-1.
  • Owner: the owner account.
  • Permissions: full access to all resources.
  • Expiration: none. The token never expires.
  • Source: bootstrap, shown as Env/flag-provided in the UI.

If no owner account exists yet, provisioning is skipped with a warning and retried on the next startup. Malformed values are also logged as a warning and ignored. Neither case affects startup.

Lifecycle across restarts

Telegraf Controller re-evaluates the configured value on every startup:

SituationBehavior
Same value on restartNo-op. The token already exists.
Changed valueThe new token is provisioned first, and then the previous bootstrap token is revoked. Exactly one active bootstrap token remains.
Variable or flag removedNo-op. The last provisioned token stays active, so an accidental drop of the variable never revokes a live credential. Remove the token deliberately through the API or UI.
Value already belongs to a non-bootstrap tokenTelegraf Controller logs a warning and leaves that token untouched. It never escalates an existing token’s privileges, and it revokes nothing.
Bootstrap token revoked by hand, variable still setThe token stays revoked. Manual revocation is deliberate, and a restart does not undo it. Change the value or remove the variable.
Bootstrap token deleted by hand, variable still setThe token is provisioned again on the next startup. To keep it disabled, revoke it instead or remove the variable.
Malformed valueLogged as a warning and ignored. Startup is unaffected.

High availability

In a high-availability cluster, only the cluster leader provisions the bootstrap token. Non-leader nodes do nothing, so a rolling restart with mixed values cannot make nodes revoke each other’s tokens.

When HA_ENABLED=true, acquiring leadership requires a Telegraf Enterprise license. Without one, no node becomes leader and no bootstrap token is provisioned. Telegraf Controller logs a warning at startup when OWNER_TOKEN is set and HA is enabled. Single-node instances provision the token in any edition.

Manage a bootstrap token

Once provisioned, a bootstrap token is an ordinary token. It appears in the token list with the source Env/flag-provided, and you can revoke or delete it like any other token.

Because the value is re-evaluated at startup, revoking and deleting behave differently while the variable or flag is still set:

  • Revoke to disable the token durably. Revocation survives restarts.
  • Delete only removes the token until the next startup, when it is provisioned again from the configured value.

The UI confirmation dialog for each action calls out this behavior.

Was this page helpful?

Thank you for your feedback!