doc: Added doc for running ingress/GwAPI in host network mode

[PhilipSchmid]

This PR adds documentation for #30840 and #31646.

• Added documentation about how to expose the Cilium Ingress Controller / GwAPI Envoy listener on the host network
• Fixed faulty Helm flag in Helm values comment
• Unified GwAPI l7Proxy=true requirement to work everywhere with Helm flags, not agent flags.
• Fixed RST title level inconsistency in the troubleshooting guide

ToDos:

• Wait with merging until the following two PRs are merged:
  • Ingress/Gateway API: merge Envoy listeners for HTTP(S) and TLS passthrough #31646
  • starter: introduce possibility to keep capability NET_BIND_SERVICE proxy#650
• Incorporate the new config flag from starter: introduce possibility to keep capability NET_BIND_SERVICE proxy#650 to grant NET_BIND_SERVICE permissions to use privileged ports.
• Fix the following Sphinx warning:

    /src/Documentation/network/servicemesh/gateway-api/host-network-mode.rst:4: WARNING: duplicate label gs_gateway_host_network_mode, other instance in /src/Documentation/network/servicemesh/gateway-api/gateway-api.rst

  • The problem is that I'm defining .. _gs_gateway_host_network_mode: within host-network-mode.rst, which is also included in gateway-api.rst. Hence, it's included twice as we define source_suffix = ['.rst', '.md'] within cilium/Documentation/conf.py. Possible workaround: Rename host-network-mode.rst to host-network-mode.inc. It's basically the same issue as described here: "WARNING: duplicate label" because of include sphinx-doc/sphinx#1668
  • @docs: Any suggestion to get rid of this warning nicely? Fixed via 421ceaa. Thanks for the input, @qmonnet!

Release note:

doc: Added doc for ingress/GwAPI host network mode

cc @mhofstetter, @networkop

[networkop]

left a few suggestions but overall lgtm

[mhofstetter]

Looks good to me - except one small change. But this is definitely ready for review (undraft) 🎉 Thanks @PhilipSchmid

side note: maybe squashing the commits into one (with an updated commit message)?

[sayboras]

Thanks ✔️

[learnitall]

This is great, thank you! I left a couple of small nits for you on grammar, wording and structure. Let me know what you think!

There are some suggestions which are applicable to both the Ingress and Gateway API sections. For brevity, I just left them in the Gateway API section.

[PhilipSchmid]

Thanks, @learnitall, for your feedback! I addressed everything directly in c1b09de and will squash all commits as soon as we have all reviews in.

[learnitall]

Great thank you! LGTM! I found one small grammar nit, but it's non-blocking.

[PhilipSchmid]

Squashed and rebased in the hope we can soon merge it 🤞.

[mhofstetter]

/test

[mhofstetter]

Checks passing and relevant reviews are in -> marking as ready-to-merge 🎉

[julianwiedmann]

I see that #31646 was also backported to v1.15. Do we want some docs there as well?

[mhofstetter]

I see that #31646 was also backported to v1.15. Do we want some docs there as well?

@julianwiedmann Thanks for mentioning this. But it's not necessary to backport this PR.

The author backport of the partially related PR only backported the actual fix (merge of envoy listeners) - and not the part that was related to the feature that gets documented with this PR.

See backport note:

HostNetwork support isn't available on v1.15, other smaller conflicts due to refactorings not being backported