Skip to content

neutron: document DNS resolution for OVN - #1041

Draft
ideaship wants to merge 1 commit into
mainfrom
doc-gap-ovn-dns
Draft

neutron: document DNS resolution for OVN#1041
ideaship wants to merge 1 commit into
mainfrom
doc-gap-ovn-dns

Conversation

@ideaship

@ideaship ideaship commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

What

Adds a DNS resolution for instances (OVN) section to the Neutron configuration
guide, documenting how Neutron decides which DNS servers instances are handed
and how to set 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: on an OSISM deployment it is
not a useful fallback, and nothing in the guide says so.

osism.commons.resolvconf points /etc/resolv.conf at the systemd-resolved
stub (127.0.0.53) and configures the real upstream resolvers in
resolved.conf instead. Neutron does not filter loopback addresses out of that
file, and the containers run in the host network namespace, so 127.0.0.53 is
what gets advertised to instances — where it resolves nothing. Instances on a
subnet without dns_nameservers therefore end up with no working DNS at all,
including internal name resolution.

How

  • States the three-level precedence and links to 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: [ovn] dns_servers via
    environments/kolla/files/overlays/neutron/ml2_conf.ini.
  • 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.

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

Related

Independent of, but found in the same investigation as:

🤖 Generated with Claude Code

The configuration guide does not mention instance DNS anywhere, yet every
OVN deployment has to make a decision about it, because the fallback that
applies when nothing is configured does not work on OSISM.

Neutron picks the DNS servers it advertises to instances from the subnet's
dns_nameservers, else the [ovn] dns_servers option, else the resolvers of
the host running neutron-server. That last step is the problem: the
osism.commons.resolvconf role deliberately points /etc/resolv.conf at the
systemd-resolved stub (127.0.0.53) and keeps the real upstream resolvers in
resolved.conf. Neutron does not filter loopback addresses out of that file,
and the containers run in the host network namespace, so 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.

This is not an upstream bug -- the precedence is deliberate and documented,
and per-subnet DNS is the recommended path -- but nothing told OSISM
operators about the interaction, so each one rediscovers it and hand-writes
the same overlay. Document the precedence, the fallback caveat, and the
[ovn] dns_servers override, next to the MTU section that already points at
the same overlay file.

Also note that neutron_dnsmasq_dns_servers, which defaults to public
resolvers, only applies to the ML2/OVS DHCP agent and does nothing on an OVN
deployment -- a reasonable thing to expect to help, and it does not.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Roger Luethi <luethi@osism.tech>
@github-actions

Copy link
Copy Markdown

⚠️MegaLinter analysis: Success with warnings

Descriptor Linter Files Fixed Errors Warnings Elapsed time
✅ ACTION actionlint 5 0 0 0.06s
✅ JSON jsonlint 4 0 0 0.09s
✅ JSON prettier 4 0 0 0.38s
✅ JSON v8r 4 0 0 7.54s
✅ MARKDOWN markdownlint 157 0 0 2.44s
✅ MARKDOWN markdown-table-formatter 157 0 0 0.34s
✅ REPOSITORY betterleaks yes no no 0.86s
✅ REPOSITORY checkov yes no no 18.47s
✅ REPOSITORY git_diff yes no no 0.1s
✅ REPOSITORY secretlint yes no no 1.8s
✅ REPOSITORY trufflehog yes no no 3.83s
✅ SPELL codespell 167 0 0 0.56s
⚠️ SPELL lychee 167 1 0 10.35s
✅ YAML prettier 6 0 0 0.44s
✅ YAML v8r 6 0 0 5.54s
✅ YAML yamllint 6 0 0 0.58s

Detailed Issues

⚠️ SPELL / lychee - 1 error
📝 Summary
---------------------
🔍 Total..........881
🔗 Unique.........714
✅ Successful.....834
⏳ Timeouts.........0
🔀 Redirected.......3
👻 Excluded........46
❓ Unknown..........0
🚫 Errors...........1
⛔ Unsupported......1

Errors in docs/concepts/index.md
[ERROR] file://docs/concepts/metalbox#sonic-ztp (at 70:1) | File not found. Check if file exists and path is correct

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

Notices

📣 MegaLinter 9.5.0 is out! Discover the new features and security recommendations in the release announcement. (Skip this info by defining SECURITY_SUGGESTIONS: false)

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@9.6.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

MegaLinter is graciously provided by OX Security
Show us your support by starring ⭐ the repository

@berendt berendt moved this from New to In progress in Human Board Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

3 participants