neutron: document DNS resolution for OVN

[ideaship]

What

Adds a DNS Resolution for Instances (OVN) section to the Neutron configuration guide, documenting which DNS servers Neutron hands to instances and how to control them on an OSISM deployment.

Why

The precedence itself is upstream-documented — subnet dns_nameservers, then dns_servers in the [ovn] section, then the resolvers of the host running neutron-server. The third level is the problem, and nothing in the guide says so.

osism.commons.resolvconf points /etc/resolv.conf at the systemd-resolved stub (127.0.0.53) and keeps the real upstream resolvers in resolved.conf. Syntactic validity is the only test Neutron applies to the entries it reads there, so the loopback stub passes, and the containers run in the host network namespace — 127.0.0.53 is what reaches the instances, where it resolves nothing. An instance on a subnet without dns_nameservers then has no working DNS at all, internal name resolution included.

The failure is silent on both DHCP paths: for IPv4 Neutron warns only when it finds no resolver, and the stub is a valid address; the DHCPv6 path omits the option without warning either way.

How

• States the three-level precedence, notes that levels 2 and 3 are filtered by the subnet's IP version while level 1 is not, and links the upstream admin guide.
• Names per-subnet dns_nameservers as the recommended approach.
• Explains why the host-resolvers level does not work on OSISM, and gives the deployment-wide fix via environments/kolla/files/overlays/neutron/ml2_conf.ini.
• Covers three behaviours an operator meets after setting the option: an IPv4-only list leaves IPv6 subnets with no resolver at all; 0.0.0.0 / :: suppress the DHCP option, but only as the sole remaining entry for that IP version; and a changed [ovn] dns_servers does not reach subnets that already exist, because neutron_sync_mode defaults to log.
• Notes that neutron_dnsmasq_dns_servers, which defaults to public resolvers, applies only to the ML2/OVS DHCP agent and has no effect under OVN.

Verification

Checked against a live OVN deployment, not only against the source:

• neutron_server runs with NetworkMode: host, and /etc/resolv.conf inside the container is nameserver 127.0.0.53 — the exact file Neutron reads for level 3.
• A tenant subnet with empty dns_nameservers received dns_server="{9.9.9.9, 149.112.112.9}" from [ovn] dns_servers; its IPv6 sibling received no dns_server key at all, the config list being IPv4-only.
• After changing [ovn] dns_servers and restarting neutron-server on all three control nodes, existing subnets kept their old resolvers across six minutes with no API activity; a subnet created afterwards got the new ones; a subnet update then flipped the existing one. An update that changes no attribute has no effect — the client sends no request and still exits successfully.

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

Related

Top of a two-PR stack. This section cross-references Customization of the service configurations, which the PR below repairs, so that one merges first:

• openstack: document how overlays are matched and merged #1042

🤖 Generated with Claude Code

[github-actions]

✅MegaLinter analysis: Success

Descriptor	Linter	Files	Fixed	Errors	Max errors	Warnings	Elapsed time
✅ ACTION	actionlint	5		0		0	0.08s
✅ JSON	jsonlint	4		0		0	0.08s
✅ JSON	prettier	4		0		0	0.35s
✅ JSON	v8r	4		0		0	7.79s
✅ MARKDOWN	markdownlint	169		0		0	2.36s
✅ MARKDOWN	markdown-table-formatter	169		0		0	0.36s
✅ REPOSITORY	betterleaks	yes		no		no	0.68s
✅ REPOSITORY	checkov	yes		no		no	17.21s
✅ REPOSITORY	git_diff	yes		no		no	0.1s
✅ REPOSITORY	secretlint	yes		no		no	3.27s
✅ REPOSITORY	trufflehog	yes		no		no	4.58s
✅ SPELL	codespell	179		0		0	0.62s
✅ SPELL	lychee	179		0		0	41.41s
✅ YAML	prettier	6		0		0	0.34s
✅ YAML	v8r	6		0		0	7.96s
✅ YAML	yamllint	6		0		0	0.47s

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

[garloff]

Ideally, we'd have an optional setting in https://github.com/openstack/kolla-ansible/blob/master/ansible/roles/neutron/templates/ml2_conf.ini.j2, no?
If we don't, we'd need to create a full drop-in replacement as overlay, which I always want to avoid (as it kills robustness and flexibility and introduces the risk for errors -- or did I overlook some intelligent merge strategy for config files ...?)

[ideaship]

Ideally, we'd have an optional setting in https://github.com/openstack/kolla-ansible/blob/master/ansible/roles/neutron/templates/ml2_conf.ini.j2, no? If we don't, we'd need to create a full drop-in replacement as overlay, which I always want to avoid (as it kills robustness and flexibility and introduces the risk for errors -- or did I overlook some intelligent merge strategy for config files ...?)

kolla's merge_configs already merges custom configs. Having the two lines as documented in the file is sufficient.