Clarify duplicate host management in federated reporting docs by larsewi · Pull Request #3645 · cfengine/documentation

larsewi · 2026-05-12T11:41:20Z

Summary

Reframe the "Duplicate host management" intro around the approach distinction (source-side vs destination-side) rather than treating distributed cleanup and handle-duplicate-hostkeys as if they addressed different lifecycle scenarios. Both mechanisms address the same underlying problem: the same hostkey appearing on multiple feeders.
Distributed cleanup is now described as a source-side cleanup (deletes stale records from the feeders via API, before re-import).
Handle duplicate hostkeys is described as a destination-side filter (moves older duplicates into a dup schema on the superhub during import).
Added a caveat that neither mechanism deduplicates clones reporting to the same feeder, since the feeder's __hosts table is keyed on hostkey (verified against nova/db/schema.sql).
Dropped "fail over" from the list of causes — there is no automatic failover for federated reporting agents, only operator-driven re-bootstrap.
Updated the distributed_cleanup.py prompts in the bullet list and the example console session to match the current script: separate admin username/password prompts (defaulting to admin), and 2FA prompts when enabled.

Example output

# /opt/cfengine/federation/bin/distributed_cleanup.py
Enter admin username for superhub ip-172-31-12-171 [admin]: larsewi
Enter admin password for superhub ip-172-31-12-171: 
Enter email for fr_distributed_cleanup accounts: larsewi@doofus.com

Enter admin username for ip-172-31-6-8 [admin]: larsewi
Enter admin password for ip-172-31-6-8:

olehermanse · 2026-05-12T23:09:06Z

+  A script on the superhub identifies the feeder with the most recent contact for each hostkey and then calls back into the other feeders to delete the stale records at the source, so they are never re-imported.

-There are two options available for handling these situations depending on your environment: Distributed Cleanup or Handle Duplicate Hostkeys.
+- [Handle duplicate hostkeys][Federated reporting#Handle duplicate hostkeys] is a _destination-side_ filter.


Out of scope for this PR, but: Handle sounds a bit vague and might be confusing, especially when there is also distributed cleanup, I guess we could rename this mechanism and section to simply Filter duplicate hostkeys.

Reframe the "Duplicate host management" intro around the approach distinction rather than separate lifecycle scenarios: both mechanisms address the same underlying problem (same hostkey across multiple feeders), with distributed cleanup as a source-side cleanup and handle duplicate hostkeys as a destination-side filter. Note that neither deduplicates clones reporting to the same feeder, since a feeder's __hosts table is keyed on hostkey. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Ole Herman Schumacher Elgesem <4048546+olehermanse@users.noreply.github.com>

olehermanse

Looks good, just one small suggestion.

Reframe the "Duplicate host management" intro around the approach distinction rather than separate lifecycle scenarios: both mechanisms address the same underlying problem (same hostkey across multiple feeders), with distributed cleanup as a source-side cleanup and handle duplicate hostkeys as a destination-side filter. Note that neither deduplicates clones reporting to the same feeder, since a feeder's __hosts table is keyed on hostkey. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Ole Herman Schumacher Elgesem <4048546+olehermanse@users.noreply.github.com>

The script has since been changed to ask for admin username and password separately (defaulting to admin) and to prompt for a 2FA code when the admin account has 2FA enabled. Update the bullet list and the example console session to match the current prompts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

olehermanse · 2026-05-13T13:49:05Z

@cf-bottom jenkins, please

cf-bottom · 2026-05-13T13:57:51Z

Alright, I triggered a build:

Jenkins: https://ci.cfengine.com/job/fast-build-and-deploy-docs-master/28/

Documentation: http://buildcache.cfengine.com/packages/build-documentation-pr/jenkins-fast-build-and-deploy-docs-master-28/output/_site/

Fixed

olehermanse · 2026-05-13T14:55:04Z

Should be cherry-picked to 3.27 branch

larsewi force-pushed the federated-reporting-duplicate-hosts branch from 571c83a to 1d4687e Compare May 12, 2026 13:08

larsewi marked this pull request as ready for review May 12, 2026 13:11

larsewi requested review from aleksandrychev, craigcomstock and olehermanse May 12, 2026 13:11

craigcomstock previously requested changes May 12, 2026

View reviewed changes

Comment thread content/web-ui/federated-reporting.markdown Outdated

larsewi force-pushed the federated-reporting-duplicate-hosts branch from 1d4687e to e21408e Compare May 12, 2026 14:19

larsewi requested a review from craigcomstock May 12, 2026 14:21