Skip to content

Commit 10b1e7c

Browse files
committed
docs(gateway-api): document publishing.exposure flag and ingress-nginx Service modes
Address review feedback from @myasnikovdaniil: the Migration section referenced `exposure: loadBalancer` in a YAML example without explaining what the flag does. Add a subsection covering both modes (externalIPs vs loadBalancer), the KEP-5707 deprecation timeline that motivates the flip, and the loadBalancer-mode caveats (non-empty externalIPs, externalTrafficPolicy: Local, no built-in Cilium announcement, brief ingress interruption on switch, scope limited to ingress-nginx). Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 9113a50 commit 10b1e7c

1 file changed

Lines changed: 19 additions & 0 deletions

File tree

‎content/en/docs/next/networking/gateway-api.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,25 @@ publishing:
260260

261261
Tenants then enable `spec.gateway: true` at creation time.
262262

263+
### `publishing.exposure` — ingress-nginx Service mode
264+
265+
`publishing.exposure` controls how the ingress-nginx `Service` itself is provisioned. It is independent of `gateway.enabled` — Gateway API always uses the per-tenant `CiliumLoadBalancerIPPool` regardless of this flag — but a Gateway API rollout is the natural moment to flip it, so ingress-nginx (still in place for unmigrated tenants and for chart-level features that have not yet moved) and the per-tenant Gateway draw from the same Cilium-managed pool.
266+
267+
| Value | Service shape | IP source |
268+
| ----------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
269+
| `externalIPs` (default) | `ClusterIP` with `Service.spec.externalIPs` set from `publishing.externalIPs` | Operator-managed routing of those IPs to a cluster node |
270+
| `loadBalancer` | `type: LoadBalancer` | Cilium LB IPAM allocates from a `CiliumLoadBalancerIPPool` populated with `publishing.externalIPs` |
271+
272+
`Service.spec.externalIPs` is deprecated upstream in Kubernetes v1.36 ([KEP-5707](https://github.com/kubernetes/enhancements/issues/5707)). The `AllowServiceExternalIPs` feature gate is expected to default to `false` around v1.40 and the implementation removed around v1.43 — switch to `loadBalancer` before upgrading past v1.40.
273+
274+
Caveats for `loadBalancer` mode:
275+
276+
- `publishing.externalIPs` must contain at least one non-empty address; otherwise the chart render fails fast (a LoadBalancer Service without a pool would sit in `<pending>` forever).
277+
- The ingress-nginx Service is created with `externalTrafficPolicy: Local` to preserve the client source IP. The external IP must therefore be routed to a node that runs an ingress-nginx pod (floating IP, keepalived, upstream router, or `podAntiAffinity` to constrain pod placement).
278+
- Cilium does not announce the IP on its own unless L2 announcements or BGP are enabled in Cilium values (disabled by default in Cozystack). This mode assumes the operator already routes `publishing.externalIPs` to a cluster node.
279+
- Switching this value on a running cluster recreates the ingress-nginx Service (the kind changes between `ClusterIP` and `LoadBalancer`, and the `HelmRelease` has `upgrade.force: true`). Expect a brief ingress traffic interruption.
280+
- Scope: this setting controls only the ingress-nginx Service. Other components that write `Service.spec.externalIPs` directly (for example `packages/apps/vpn/templates/service.yaml`) are unaffected and must be migrated separately before the `AllowServiceExternalIPs` gate flips off.
281+
263282
### For an existing cluster
264283

265284
1. Flip `gateway.enabled: true` on the platform Package. This rerenders cert-manager ClusterIssuers and the exposed-service templates. Existing `Ingress` objects for dashboard / keycloak / cozystack-api (Kubernetes API) / vm-exportproxy / cdi-uploadproxy are deleted by Flux as they are replaced by `HTTPRoute` / `TLSRoute`.

0 commit comments

Comments
 (0)