From 2af8305562c3fe0d8a1d99db922b958266cf7223 Mon Sep 17 00:00:00 2001 From: Roger Luethi Date: Sun, 26 Jul 2026 18:40:10 +0200 Subject: [PATCH] openstack: warn that overlays match by exact name The overlay section explains which locations are searched, but not what happens when a file does not match one of them. Nothing does: the file is not read, no warning is emitted, and the deployment succeeds while the settings have no effect. Operators therefore have no signal distinguishing "my override was applied" from "my override was ignored", and the failure is easy to hit because near-miss names look plausible. Both examples given are ones seen in the wild: an ml2_conf.ini placed at the overlays top level instead of under neutron/, and a neutron/ml2.conf that is simply a misspelling of ml2_conf.ini. In both cases the DNS and MTU settings they contained silently did nothing. Add a warning admonition next to the existing description of the supported locations, and suggest verifying the rendered configuration under /etc/kolla/SERVICENAME/ rather than assuming the overlay took effect. Assisted-by: Claude:claude-opus-5 Signed-off-by: Roger Luethi --- .../configuration-guide/openstack/index.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/guides/configuration-guide/openstack/index.md b/docs/guides/configuration-guide/openstack/index.md index af47414ab1..8b04aa900e 100644 --- a/docs/guides/configuration-guide/openstack/index.md +++ b/docs/guides/configuration-guide/openstack/index.md @@ -195,6 +195,26 @@ supported, assuming that you have services using `nova.conf` running on hosts ca Using this mechanism, overrides can be configured per-project (Nova), per-project-service (Nova scheduler service) or per-project-service-on-specified-host (Nova services on ctl1). +:::warning + +Overlay files are picked up by exact name and exact path. A file whose name or +location does not match one of the supported locations is not an error and +produces no warning — it is simply never read, and the deployment succeeds with +the settings silently having no effect. + +Two examples that look right but are ignored: + +* `environments/kolla/files/overlays/ml2_conf.ini` — `ml2_conf.ini` is only read + from the `neutron/` subdirectory, so a copy at the top level does nothing. +* `environments/kolla/files/overlays/neutron/ml2.conf` — a misspelling of + `ml2_conf.ini`; nothing matches `ml2.conf`. + +After adding an overlay, confirm the setting actually arrived rather than +assuming it did, for example by checking the generated configuration on the +target host under `/etc/kolla/SERVICENAME/`. + +::: + Overriding an option is as simple as setting the option under the relevant section. For example, to set override `scheduler_max_attempts` in the Nova scheduler service, the operator could create `environments/kolla/files/overlays/nova/nova-scheduler.conf` in the configuration repository with this content: