Gateway API

Overview

This package installs the upstream Gateway API standard-channel CRDs and safe-upgrade admission policy. It installs no controllers, workloads, services, UI, or persistent storage. Installing the API definitions does not route traffic or create GatewayClass, Gateway, or Route instances.

In Big Bang, Istiod provides the Gateway API controller implementation. Controller configuration, supported features, and gateway/waypoint workloads belong to the Istio packages, not this chart. See the upstream Gateway API guides and Istio Gateway API tutorial for product concepts and controller usage; select the documentation matching your deployed controller version before following its installation instructions. For licensing, refer to the upstream v1.6.2 license.

What gets installed

Chart 1.6.2-bb.0 vendors Gateway API v1.6.2 in chart/files/standard-install.yaml. chart/templates/crds.yml renders that bundle as ordinary Helm templates. It contains ten CRDs: BackendTLSPolicy, GatewayClass, Gateway, GRPCRoute, HTTPRoute, ListenerSet, ReferenceGrant, TCPRoute, TLSRoute, and UDPRoute.

The CRD objects themselves are cluster-scoped. Their spec.scope describes the instances they define: GatewayClass instances are cluster-scoped; the other nine resource types have namespaced instances. Big Bang’s HelmRelease uses kube-system as its target namespace, but that does not make CRDs namespaced or restrict their use to kube-system.

For the complete API contract, use the upstream API specification and the v1.6.2 API definitions corresponding to this bundle. A CRD’s presence is not a guarantee that a particular controller implements every feature.

It also installs a ValidatingAdmissionPolicy and its binding, both named safe-upgrades.gateway.networking.k8s.io. These come from upstream and reject two things: installing experimental channel CRDs on top of standard channel CRDs, and installing Gateway API CRDs with missing bundle-version annotations or release versions matching its v0/v1.0–v1.5 checks (with a release-candidate exception). The version check includes v1.5.x even though its rejection message says “before v1.5.0.” Treat the rendered policy expression, not just that message, as authoritative. Do not remove the policy as a routine upgrade workaround.

The policy does not reject experimental-to-standard replacement on channel alone; that is not evidence that such a migration preserves experimental fields or data. Review the upstream upgrade guidance before changing channels or versions.

Channels

Upstream publishes two release channels. This package ships the standard channel only — the experimental channel bundle is deliberately not vendored. The former unstableAPI option was removed in 1.6.1-bb.0; setting it does not enable experimental CRDs. Shipping both bundles previously exceeded the Kubernetes 1 MiB limit for the Helm release Secret, as recorded in the package changelog.

Big Bang integration

These examples are umbrella values, not standalone package values. When using the canonical built-in package configuration, explicitly opt in to v1:

packageConfiguration:
  version: v1
packages:
  gatewayAPI:
    enabled: true

The legacy entry point remains:

gatewayAPI:
  enabled: true

With packageConfiguration.version: v1, canonical packages.gatewayAPI settings take precedence over legacy gatewayAPI settings. Without that opt-in, packages entries follow the older custom-package model. See the umbrella package management contract.

The umbrella also selects Gateway API whenever ambient mode is effective: either global istio.ambient.enabled or the ztunnel package is enabled. Consequently, gatewayAPI.enabled: false alone does not suppress this release in ambient mode. This is umbrella orchestration, not a dependency or setting in the package chart. Use the umbrella ambient configuration guide for mesh enablement, enrollment, and cross-package behavior; ztunnel’s L4 data plane is not implemented by these CRDs.

The umbrella creates HelmRelease/release gateway-api, with target namespace kube-system, and source/values resources in the umbrella release namespace. It orders this release after Gatekeeper and Kyverno Policies when those packages are enabled, plus user-specified dependencies; dependsOnOverride replaces that default ordering. These Flux dependencies do not install a Gateway API controller.

chart/values.yaml is empty, and this chart has no chart dependencies or passthrough upstream parent. The umbrella’s packages.gatewayAPI.values (legacy gatewayAPI.values) entry exists, but the renderer does not consume values to customize the bundle. Shared umbrella values may still appear in its values Secret; they do not create mesh or NetworkPolicy resources here. Configure routing resources and controller settings with their respective owners rather than inventing values for this chart.

Lifecycle and existing installations

This chart renders CRDs under templates/, not Helm’s special crds/ directory. They are therefore ordinary release-managed resources: upgrades update them and uninstall can delete them. There is no helm.sh/resource-policy: keep annotation in this bundle. Deleting a CRD deletes its custom resources, potentially affecting every controller and application using Gateway API in the cluster. Do not treat package disablement or uninstall as harmless cleanup.

Before enabling this package on a cluster with existing Gateway API CRDs, establish one owner and review the installed bundle version, channel, and Helm ownership metadata. CRDs installed by a provider, another release, or a manual manifest may conflict with Helm ownership checks. This chart has no adoption or migration hook; do not blindly delete CRDs or take ownership to resolve an install failure.

Review upstream CRD management and release notes before upgrading. Test the actual upgrade path and controller compatibility in a disposable environment, including stored API versions and existing resources. Automatic rollback to an older bundle may be rejected by the safe-upgrade policy or lose fields; this package does not automate storage-version migration.

For comparison with Helm’s special CRD handling, see Helm CRD guidance. See DEVELOPMENT_MAINTENANCE.md for how the chart is maintained and upgraded.

Read-only local checks

From the package repository root:

helm lint chart
helm template gateway-api ./chart | yq '.spec.names.kind'

The render lists the ten CRD kinds and null entries for the admission policy and binding. These commands do not contact a cluster. They cannot establish API-server admission compatibility, Helm adoption, controller support, or upgrade safety; those require separate integration evidence.