Add auto-generated configuration documentation by agrawalkaushik · Pull Request #1018 · 128technology/docs

agrawalkaushik · 2026-05-17T19:47:34Z

Summary

Adds a new config_autogenerated.md page documenting the SSR auto-generated configuration system, including:

The three-phase auto-generation lifecycle (removal, generation, metadata update)
Two categories of subsystems: leaf-only vs leaf+metadata
How to take ownership using the create config autogenerated single-commit workflow
Per-element override methods (generated false vs override-generated true)
Per-subsystem reference (shared service-routes, conductor services, BGP, DHCP, plugins, etc.)
Protection mechanism internals and interaction matrix
Import/export behavior (full preservation of generated state)
Quick reference table

Also adds a sidebar entry in the Administration Guide section after config_basics.

Documents the auto-generation lifecycle, two categories of subsystems (leaf-only vs leaf+metadata), how to take ownership of generated elements using the single-commit workflow, per-subsystem reference, protection mechanisms, and import/export behavior. Adds config_autogenerated.md and sidebar entry after config_basics.

Use the more appropriate 'Peer Topology builder' term throughout the documentation instead of 'shared-service-route' to better reflect the internal component name and reduce confusion.

Each auto-generated configuration section now includes a clear purpose statement explaining what that configuration accomplishes and why it exists, improving clarity for readers.

Remove Purpose labels and integrate them as natural intro paragraphs for each configuration section. Combine with existing intro text where applicable.

Documents MOFI auto-generation for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS, and Audit services. Includes trigger, generated elements, override methods, and quick reference entry.

Repositioned the Management Over Forwarding Interface (MOFI) section to immediately follow the Conductor/Management Services section, as MOFI services are logically part of the management infrastructure.

Since management services (NTP, DNS, SNMP, etc.) are now covered by the MOFI section, simplify the Conductor section name to reflect its focus on conductor connectivity and configuration management.

…frastructure config - Add Secure Conductor Onboarding (SCO) section documenting auto-generation of operating mode and pre-shared keys - Add Resource Groups section documenting automatic resource-to-role associations for RBAC with list of supported resource types - Reorganize per-config sections into two clear groupings: * User-Facing Configuration: elements users typically interact with * Infrastructure and System Configuration: internal platform-managed settings - Split Quick Reference table to match the new section organization

MichaelBaj · 2026-05-18T13:51:55Z

+sidebar_label: Auto-Generated Configuration
+---
+
+During every `commit`, the SSR platform automatically generates certain configuration elements based on the current topology and feature configuration. These elements are removed and re-created on each commit by default, meaning any manual edits to them are lost unless you take explicit ownership first.


This document is good, but some of the introductory content at the end. For example, the list of all generated configuration, and what is needed to identify generated configuration. That would be very useful information in the introduction. (e.g., generated true)

Fixed in 144d997 — added a "How To Identify Auto-Generated Elements" subsection to the intro that mentions generated true and links to the Quick Reference table at the end.

Chr1st0ph3rTurn3r · 2026-05-18T12:56:50Z

+
+1. **Removal** — The system deletes all previously auto-generated elements so they can be rebuilt from scratch. There are two independent removal paths:
+   - **Element-level:** All services, service-routes, peers, adjacencies, tenants, and service-policies where `generated` is set to `true` are collected and removed.
+   - **Metadata-level:** A hidden authority metadata list (`authority > generated`) tracks elements created by certain subsystems (plugins, DHCP server KNI, port-forwarding, software-update). All paths recorded in that list are removed, and the metadata entries are cleared.


I don't think it's necessary to mention that it is a "hidden" authority metadata list. Most of this is hidden from the user anyway. I think it distracts the reader from the information.

The reason to include that is for import/export to ensure that is done in the right way. I'll see how we can re-word it while still keeping it.

Fixed in 144d997 — removed "hidden" from the overview description. The detail is preserved in the Import/Export section where it's actionable.

Chr1st0ph3rTurn3r · 2026-05-18T13:05:26Z

+
+| Category | Subsystems | Removal Path | Override Method |
+|----------|-----------|-------------|-----------------|
+| **Leaf-only** | Peer Topology builder, conductor services, BGP services, DHCP relay, PIM/MSDP, alarm shelving, internal tenants | Element-level (`generated` leaf) only | Set `generated` to `false` directly |


In a table, or bullets, if you have punctuation (comma, colon, semi-colon) in the text, you have to use a period to close the sentence. If a table or bulleted list only has one instance of punctuation in the text, all sentences in that table need to have a period to close. The exception to that are the names (category) or if an entry is just one or two words.

Thanks @Chr1st0ph3rTurn3r - these rules would be good to capture in the repo's copilot instructions. Copilot did a good job of capturing other rules that exist in the repo. It's not generally reasonable for humans to remember all these rules.

Fixed in 144d997 — added closing periods to all table cells and bulleted/numbered lists that contain internal punctuation. Also captured this rule in .github/copilot-instructions.md for future docs.

Chr1st0ph3rTurn3r · 2026-05-18T13:06:52Z

+4. Override those elements (see below)
+5. Make your modifications
+6. Commit **once** — the removal phase skips your overridden elements, and the generation phase sees them as user-provisioned
+


Closing periods

Fixed in 144d997 — closing periods added throughout all affected tables and lists.

Chr1st0ph3rTurn3r · 2026-05-18T13:35:24Z

+During the commit, elements with `generated` set to `false` survive the removal phase and are skipped during regeneration, preserving your customizations in a single commit.
+
+:::note
+If the underlying trigger configuration changes (e.g., new neighborhoods, new conductor addresses), re-run `create config autogenerated` to preview newly generated elements before committing.


Not clear - if the underlying what trigger config changes?

the e.g. address that, no?

Ah, I see. How about this for readability:
"If the underlying changes (e.g., new neighborhoods, new conductor addresses) trigger configuration changes, re-run create config autogenerated to preview newly generated elements before committing."

Chr1st0ph3rTurn3r · 2026-05-18T14:04:51Z

+
+The PIM subsystem automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network.
+
+| | |


empty header - I'm not going to flag the rest of these, but they do need to be addressed.

possibly - they seem to something copilot/llms like. It might be worth adding a rule in the repo for this.

Fixed in 144d997 — all empty table headers replaced with | Field | Description |. Also added a rule to .github/copilot-instructions.md to prevent this in the future.

- Replace empty table headers (| | |) with Field/Description headers - Add closing periods to table cells and lists with internal punctuation - Remove unnecessary horizontal rules between same-level subsections - Fix voice: 'users typically interact' -> 'you typically interact' - Capitalize after colon in Peer Topology paragraph - Title Case heading: 'Peers and Adjacencies' - Remove 'hidden' from metadata list description in overview - Reword BGP disable sentence per reviewer suggestion - Add 'How To Identify Auto-Generated Elements' subsection to intro - Update copilot-instructions.md with new style rules from review

agrawalkaushik requested review from Chr1st0ph3rTurn3r and MichaelBaj as code owners May 17, 2026 19:47

agrawalkaushik added 7 commits May 17, 2026 15:52

Rename Shared Service Routes to Peer Topology builder

22215ce

Use the more appropriate 'Peer Topology builder' term throughout the documentation instead of 'shared-service-route' to better reflect the internal component name and reduce confusion.

Add purpose statements to each per-config section

6df0751

Each auto-generated configuration section now includes a clear purpose statement explaining what that configuration accomplishes and why it exists, improving clarity for readers.

Convert Purpose statements to intro paragraphs

46ac50d

Remove Purpose labels and integrate them as natural intro paragraphs for each configuration section. Combine with existing intro text where applicable.

Add Management Over Forwarding Interface (MOFI) services section

19997f2

Documents MOFI auto-generation for NTP, DNS, SNMP, Syslog, IPFIX, HTTP-HTTPS, and Audit services. Includes trigger, generated elements, override methods, and quick reference entry.

Move MOFI services section next to Conductor services

804eeec

Repositioned the Management Over Forwarding Interface (MOFI) section to immediately follow the Conductor/Management Services section, as MOFI services are logically part of the management infrastructure.

Rename Conductor/Management Services to Conductor Services

c2a2ba7

Since management services (NTP, DNS, SNMP, etc.) are now covered by the MOFI section, simplify the Conductor section name to reflect its focus on conductor connectivity and configuration management.

MichaelBaj requested changes May 18, 2026

View reviewed changes

Chr1st0ph3rTurn3r requested changes May 18, 2026

View reviewed changes

agrawalkaushik requested review from Chr1st0ph3rTurn3r and MichaelBaj May 18, 2026 16:04

address remaining comments

9c4d0e6

Chr1st0ph3rTurn3r approved these changes May 18, 2026

View reviewed changes

MichaelBaj approved these changes May 18, 2026

View reviewed changes


		The PIM subsystem automatically establishes reachability for Protocol Independent Multicast (PIM) control traffic, enabling multicast routing operation across the network.

		\| \| \|

Conversation

agrawalkaushik commented May 17, 2026

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants