openstack: document how overlays are matched and merged

[ideaship]

What

Two gaps in how the OpenStack configuration guide explains overlays.

1. Overlay files are matched by exact name and exact path. A file matching none of the supported locations is silently ignored.
2. An overlay does not replace the file OSISM generates. The two are merged key by key, so an overlay holds only the settings being changed.

Why

Exact matching. The section lists which locations are searched, but not what happens when a file matches none of them. Nothing does: the file is not read, no warning is emitted, and the deployment succeeds while the settings have no effect. Operators get no signal distinguishing "my override was applied" from "my override was ignored", and near-miss names look plausible.

Merging. The section never says what happens to the keys an overlay does not set. It shows single-option examples, which implies a merge, but the only sentence naming the mechanism sits near the end and its job there is to introduce the exception — ending on "In these cases OSISM supports overriding the entire config file". That is the sole occurrence of "entire config file" in the section, so a reader scanning for the rule can come away believing an overlay must be a full drop-in replacement.

That reading is not hypothetical: it came up in review of the neutron change stacked on top of this one, where a two-line [ovn] overlay was read as requiring a maintained copy of the whole generated file.

How

• Adds the exact-name/exact-path warning next to the existing description of the supported locations, with the two near-miss cases seen in the wild, and suggests confirming the setting arrived by checking /etc/kolla/SERVICENAME/ rather than assuming.
• States the merge rule before the first example, where it is needed, instead of leaving it to be inferred from them.
• Rewords the closing sentence so whole-file replacement reads as what it is — the exception for INI files that cannot be merged — rather than as something offered alongside merging.

Markdown-only changes to an existing page; yarn build has not been run locally.

Related

Bottom of a two-PR stack. The neutron change on top cross-references the section this PR repairs, so this one merges first:

• neutron: document DNS resolution for OVN #1041

🤖 Generated with Claude Code

[github-actions]

✅⚠️MegaLinter analysis: Success with warnings

Descriptor	Linter	Files	Fixed	Errors	Max errors	Warnings	Elapsed time
✅ ACTION	actionlint	5		0		0	0.03s
✅ JSON	jsonlint	4		0		0	0.07s
✅ JSON	prettier	4		0		0	0.43s
✅ JSON	v8r	4		0		0	6.77s
✅ MARKDOWN	markdownlint	169		0		0	1.95s
✅ MARKDOWN	markdown-table-formatter	169		0		0	0.3s
✅ REPOSITORY	betterleaks	yes		no		no	0.63s
✅ REPOSITORY	checkov	yes		no		no	16.89s
✅ REPOSITORY	git_diff	yes		no		no	0.07s
✅ REPOSITORY	secretlint	yes		no		no	3.06s
✅ REPOSITORY	trufflehog	yes		no		no	3.04s
✅ SPELL	codespell	179		0		0	0.52s
⚠️ SPELL	lychee	179		3		0	26.92s
✅ YAML	prettier	6		0		0	0.29s
✅ YAML	v8r	6		0		0	6.48s
✅ YAML	yamllint	6		0		0	0.47s

Detailed Issues

⚠️ SPELL / lychee - 3 errors

📝 Summary
---------------------
🔍 Total.........1099
🔗 Unique.........833
✅ Successful....1023
⏳ Timeouts.........0
🔀 Redirected.......5
👻 Excluded........73
❓ Unknown..........0
🚫 Errors...........3
⛔ Unsupported......3

Errors in docs/guides/deploy-guide/services/openstack.md
[ERROR] https://www.openstack.org/software/project-navigator/openstack-components#openstack-services (at 14:5) | Connection failed. Check network connectivity and firewall settings

Errors in docs/release-notes/osism-7.md
[ERROR] https://www.openstack.org/software/openstack-bobcat (at 978:38) | Connection failed. Check network connectivity and firewall settings

Errors in docs/release-notes/osism-8.md
[ERROR] https://www.openstack.org/software/openstack-caracal (at 223:38) | Connection failed. Check network connectivity and firewall settings

Hint: Followed 5 redirects. You might want to consider replacing redirecting URLs with the resolved URLs. Use verbose mode (`-v`/`-vv`) to see redirection details.

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

• Documentation: Custom Flavors
• Command: npx mega-linter-runner@10.0.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,JSON_JSONLINT,JSON_V8R,JSON_PRETTIER,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_BETTERLEAKS,REPOSITORY_SECRETLINT,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,SPELL_CODESPELL,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

Show us your support by starring ⭐ the repository