Repository navigation
docs(controller): Telegraf Controller 1.2.0 follow-up updates - #7945
Merged
sanderson merged 9 commits intoOct 26, 2026
Merged
Conversation
…the Compose example What changed: The Docker Compose example on the Docker install page uses the `postgres_user` and `postgres_password` placeholders for the database credentials in `DATABASE_URL`, the `db` service environment, and the `pg_isready` health check, with a "Replace the following" list after the block. Why: The example shipped `postgres:postgres` as literal credentials, which readers copy as is. Verification: Vale (error level) on the page: no errors.
What changed: Both heartbeat output blocks on the get-started page (Linux/macOS and Windows tabs) add "logs" to the `include` list and an `[outputs.heartbeat.logs]` table with `limit = 50`. Why: Telegraf Controller 1.2.0 generates this template for new configurations, so agents report log entries out of the box. The page now matches what the product generates. The log level stays at the plugin default of `error`. Verification: Vale (error level): 0 errors. `yarn lint-codeblocks` on the page: all TOML blocks pass. Rendered with `hugo server` and confirmed both blocks in the HTML.
…cation What changed: - admin/audit-logs/_index.md: "Tamper detection" explains the HMAC-SHA256 chain, the configured signing key and its `secretId` fingerprint, startup and on-demand verification, a trust-boundary callout, and how entries written before 1.2.0 are treated as legacy entries. "License and permissions" names the `audit:read` permission and the key requirement. - admin/audit-logs/enable-configure.md: "Enable audit logging" lists the three ways to supply the key (`AUDIT_HMAC_KEY`, `AUDIT_HMAC_KEY_FILE`, `--audit-hmac-key-file`), adds "Generate a signing key" with openssl and PowerShell examples, passes the key file in every startup tab, and adds "Start without a key" (disabled state, log line, terminal prompt). "Forward audit events" notes which events are forwarded and that forwarder failures are logged, not fatal. - admin/audit-logs/view.md: prerequisites use `audit:read` and warn that Administrator tokens created before 1.2.0 lack it; the response example gains `secretId`; "Verify integrity" is rewritten around `GET /api/audit-logger/verify` with the response shape, field meanings, break reasons, and the startup log lines. - reference/config-options.md: new `audit-hmac-key` and `audit-hmac-key-file` entries, the key requirement on `audit-enabled`, and both tables of contents. - admin/high-availability/_index.md: key configuration per node and how a rotated key appears in verification. - admin/monitor.md: "Audit chain errors" in the log messages to watch for. Why: Telegraf Controller 1.2.0 signs audit entries with a configured key instead of a built-in one, verifies the chain at startup and through a new endpoint, and gates audit routes behind `audit:read`. Without a key, audit logging stays disabled, so the enable instructions were incomplete. Facts verified against telegraf_ui `development` (libs/audit-logger, scripts/entrypoint.js, libs/shared-types permissions). Impact: Six existing pages; no URL or alias changes. Verification: Vale (warning level) on the six pages: 0 errors, 0 warnings. `yarn lint-codeblocks`: all blocks pass. Rendered with `hugo server`; every new heading and internal link, including fragments, resolves.
…rship transfer flow What changed: - tokens/_index.md: "Token permissions" explains that requested permissions are clamped to the role (wildcards expand to the role's grants, a token cannot mint a broader token). "Token visibility" distinguishes a signed-in session from a request authenticated with an API token: Owners and Administrators manage every user's tokens only from a session, and a token manages only its own user's tokens and cannot reassign. - tokens/reassign.md: the permissions callout requires a signed-in Owner or Administrator and states that token-authenticated requests receive 403. - reference/authentication-authorization.md: clamping, re-clamping after an ownership transfer, and session-versus-token management under "API tokens"; a new "Session-only endpoints" section with the 403 message and the self-service and transfer routes; the Administrator role row notes it cannot manage the license and reads the audit log. - users/transfer-ownership.md: rewritten around the request-and-accept flow: a pending request with a 72-hour default expiry (1 to 168 hours from the API), one pending request at a time, acceptance through `POST /api/users/transfer-owner/accept` from the target's session with a recovery password when the target has no local password, decline and cancel routes, expiry, and the atomic role swap with the former owner's tokens re-clamped. A callout states that the web interface only sends the request and reports success before the target accepts. Why: Telegraf Controller 1.2.0 limits token-authenticated requests to their own user's tokens, makes account self-service and ownership transfer routes session-only, and re-clamps the former owner's tokens after a transfer. The transfer page also described an immediate atomic transfer, but the backend has used a pending-and-accept model since 1.0.0 and the web interface has no acceptance screen. Facts verified against telegraf_ui `development` (modules auth, tokens, users, ownership-transfers; libs/shared-types permissions and ownership-transfers schemas). Impact: Four existing pages; no URL or alias changes. The transfer page now tells target administrators to accept through the interactive API reference. Verification: Vale (warning level): 0 errors; the only warnings are on untouched lines of tokens/reassign.md. `yarn lint-codeblocks`: all blocks pass. Rendered with `hugo server`; every new heading and internal link, including fragments, resolves.
…lt rule What changed: - agents/reporting-rules.md: the intro states that exactly one default rule exists and describes the first-run default (one-hour threshold, auto-delete off). A new "How reporting rules work" section covers both thresholds measured from the last heartbeat, the once-a-minute evaluation, storage as whole seconds from 1 to 2147483647, and the duration formats the web interface accepts. "Set a default reporting rule" explains that making another rule the default moves it, that the current default cannot be switched off, and that existing agents keep their rule. A new "Run a status check" section documents the button and `POST /api/agents/status-check`. - reference/architecture.md: the stale "Heartbeat Interval" and "Threshold Multiplier" bullets are replaced with the actual rule fields and the status check cadence. Why: Telegraf Controller 1.2.0 validates thresholds (whole seconds, 1 to the int4 maximum, 400 otherwise), keeps exactly one default rule (400 when switching the default off), and moved the status check to `POST /api/agents/status-check`. The architecture page described fields the product does not have. Facts verified against telegraf_ui `development` (libs/shared-types reporting-rules schema, modules/reporting-rules, libs/heartbeat-napi scheduler, database/helpers/constants.ts). Impact: Two existing pages; no URL or alias changes. Verification: Vale (warning level): 0 errors, 0 warnings. `yarn lint-codeblocks`: no failures. Rendered with `hugo server`; the new headings resolve.
…ster What changed: - telegraf-enterprise/license-enforcement.md: "Scale limits" says the limits apply per installation and, in a high-availability cluster, to the cluster as a whole because every node counts against the same database. "What happens when a limit is reached" adds the heartbeat endpoint's `402 Payment Required` response for unregistered agents, with its body, and notes that registered agents keep reporting, deleted agents free their slots immediately, refused agents are remembered for 60 seconds, and the Agents page shows the count against the limit. - admin/high-availability/_index.md: "How licensing affects high availability" states that scale limits are cluster-wide and links to the scale limits section. Why: Telegraf Controller 1.2.0 reserves an agent's row in the shared database only while the agents table holds fewer rows than the limit, so a cluster no longer admits one limit per node and deleted agents no longer occupy slots until a restart. Facts verified against telegraf_ui `development` (libs/heartbeat-napi server/routes.rs, db/pool.rs, config/constants.rs; libs/shared-types license constants). Impact: Two existing pages; no URL or alias changes. Verification: Vale (warning level): 0 errors, 0 warnings. `yarn lint-codeblocks`: no failures. Rendered with `hugo server`; the headings and the new link resolve.
What changed: - configs/create.md: the name step states that names are unique among configurations (matched exactly, including case) and up to 255 characters, quotes the "already exists" message the dialog shows, notes the API's `409 Conflict` with `config_name_taken`, and says a configuration and a group can share a name. - configs/update.md: the rename step notes the same rules and that the field stays open with the error when the name is taken. - config-groups/manage.md: the create step and "Edit the group name and description" carry the group equivalents, with `config_group_name_taken`. Why: Telegraf Controller 1.2.0 enforces unique configuration and configuration group names with a 255-character limit; the create forms promised uniqueness that was never enforced. Facts verified against telegraf_ui `development` (libs/shared-types configs and config-groups schemas, errors/response.ts, modules/configs and config-groups services). The upgrade migration that renames existing duplicates is reserved for the 1.2.0 release notes. Impact: Three existing pages; no URL or alias changes. Verification: Vale (warning level): 0 errors; one warning on an untouched heading of config-groups/manage.md. `yarn lint-codeblocks`: no failures. Rendered with `hugo server`; the sections resolve.
What changed: agents/heartbeat-data.md: the "Retrieve heartbeat data with the API" section now documents `GET /api/agents/:id/heartbeat/latest` and `GET /api/agents/:id/heartbeat/logs`, identified by the agent's `id` from `GET /api/agents` rather than the reported agent ID, requiring read permission on the Agents API, with 404 for an unknown id. The curl examples and placeholder descriptions follow. Why: Telegraf Controller 1.2.0 moved these endpoints from `/api/heartbeat/agent/:agentId/...` to the agents controller under `agents:read`. The documented paths no longer exist. Verified against telegraf_ui `development` (modules/agents/agents.controller.ts). Impact: One existing page; no URL or alias changes. Verification: Vale (warning level): 0 errors, 0 warnings on the page. `yarn lint-codeblocks`: no failures. Rendered with `hugo server`; the new paths appear and no old path remains in the source.
…list What changed: agents/monitor.md: a new "Agent list columns" subsection under "The Agents page at a glance" lists the Agent Details, Telegraf Version, Advisories (Telegraf Enterprise), Status, and Last Reported columns, describes the Compact View and Detailed View toggle, the Show labels button, and which columns sort. Why: Telegraf Controller 1.2.0 adds a Telegraf Version column and reorders the agent list, and no page described the columns. Verified against telegraf_ui `development` (pages/TelegrafAgents/ui/AgentsTable). Impact: One existing page; no URL or alias changes. Verification: Vale (warning level): 0 errors; two pre-existing `regex` word-list warnings on untouched lines. `yarn lint-codeblocks`: no failures. Rendered with `hugo server`; the new heading and the advisories link resolve.
Contributor
Vale Style Check Results
Warnings (9)
✅ Check passed |
Contributor
🔗 Link Check Results — Link Check Bot❌ 41 broken link(s) found — fix them before merging.
Broken Links
|
| Source File | URL | Issue |
|---|---|---|
content/telegraf/controller/admin/audit-logs/enable-configure/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/controller/admin/audit-logs/enable-configure/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/admin/audit-logs/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/admin/audit-logs/view/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/admin/high-availability/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/admin/monitor/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/admin/monitor/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/agents/heartbeat-data/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/agents/heartbeat-data/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/agents/monitor/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/agents/reporting-rules/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/agents/reporting-rules/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/config-groups/manage/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/configs/create/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/configs/update/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/configs/update/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/get-started/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/telegraf/controller/install/docker/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/telegraf/controller/install/docker/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/telegraf/controller/reference/architecture/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
Showing first 20 of 28 warnings. See the workflow run for full results.
Full details: workflow run summary and artifact. Last updated: 2026-10-26 19:39:37 UTC
sanderson
merged commit Oct 26, 2026
ced3960
into
docs/telegraf-controller-1.2.0
21 of 22 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Nine commits, one per topic, updating 20 pages under
content/telegraf/controller/for behavior that changed in Telegraf Controller 1.2.0 after the docs branch was cut. Each commit message carries its own What changed / Why / Verification detail.postgres_userandpostgres_passwordplaceholders instead of literal credentials."logs"toincludeand a[outputs.heartbeat.logs]table withlimit = 50, matching the template Controller now generates.AUDIT_HMAC_KEY,AUDIT_HMAC_KEY_FILE, or--audit-hmac-key-file, 32 characters or more). Audit logging stays disabled without a key, and the executable prompts for one in a terminal. New "Generate a signing key" and "Start without a key" sections, the key in every startup example, two new config option entries, the newGET /api/audit-logger/verifyendpoint with its response shape and break reasons, thesecretIdfield, theaudit:readpermission, how pre-1.2.0 entries are reported as legacy entries, key handling per HA node, and the audit chain log lines to alert on.POST /api/users/transfer-owner/acceptwith a recovery password for LDAP and OIDC users, decline and cancel, and the atomic role swap. A callout explains that the web interface only sends the request and reports success before the target accepts.POST /api/agents/status-check). The architecture page's "Heartbeat Interval" and "Threshold Multiplier" bullets are replaced with the real fields.402body.409codes.GET /api/agents/:id/heartbeat/latestand/logsunderagents:read.Why
These behaviors shipped on telegraf_ui
developmentfor 1.2.0 after the docs branch was written, so several pages described settings, endpoints, and rules that no longer exist. Every fact was verified against the telegraf_ui source rather than READMEs or PR descriptions. Two findings go beyond the 1.2.0 changes: the transfer-ownership page described an immediate transfer the backend stopped doing in May, and the web interface has no screen to accept a pending transfer, which is now tracked as a telegraf_ui issue.Deliberately left out of this PR: the 1.2.0 release-notes entry and version-specific upgrade notes (handled in the release commit), the download shortcode switch to the new release host (a pre-release step), and the in-app registration prompt.
Impact
Twenty existing pages change. No pages move, no URLs or aliases change, no shared content is touched, and no new images are required. Readers of the audit-logging pages will see that a signing key is now required, and target administrators are directed to the interactive API reference to accept an ownership transfer until the UI supports it.
Verification
regexword-list flags and sentence-case headings).yarn lint-codeblockson every touched page: no failures.hugo server; every new heading, anchor, and internal link, including fragments, was checked against the HTML.npx hugo --quietfull build: exit 0.Checklist
npx hugo --quiet)