Skip to content

Gateway API CRDs

Kubernetes Gateway API (GitHub) is the official successor to the Ingress resource, developed by the SIG-Network community. Unlike the legacy Ingress spec — which flattens routing, TLS termination, and traffic policy into a single resource owned by one persona — Gateway API separates concerns across distinct resource types with explicit role-oriented ownership: infrastructure providers manage GatewayClass, cluster operators manage Gateway, and application developers manage HTTPRoute/GRPCRoute.

What distinguishes Gateway API from Ingress and vendor-specific CRDs (Istio VirtualService, Traefik IngressRoute): it provides a portable, expressive routing model with first-class support for header-based matching, traffic splitting, cross-namespace references, and protocol-specific route types — all under a single upstream specification with a formal conformance test suite. Implementations are interchangeable at the API layer without rewriting route definitions.

The standard channel includes the graduated resource types — GatewayClass, Gateway, HTTPRoute, ReferenceGrant, and GRPCRoute — which have reached GA stability guarantees. Experimental-channel resources (TCPRoute, TLSRoute, BackendTLSPolicy) are excluded from this installation.

Overview

Property Value
Namespace gateway-api-crds
Type Kustomization
Layer AI agent platform
Status Enabled
Source apps/base/agentgateway/gateway-api-crds/

Dependencies

Upstream — required before Gateway API CRDs starts

No upstream Flux dependencies — starts immediately.

Downstream — services that depend on Gateway API CRDs

Service Dependency type Reason
agentgateway Flux dependsOn Requires Gateway API CRDs

Purpose

This Kustomization installs the Gateway API CRD definitions into the cluster so that downstream controllers — specifically agentgateway — can register a GatewayClass and instantiate Gateway/HTTPRoute resources. Without these CRDs present in the API server, any HelmRelease attempting to create Gateway API objects would fail at the admission stage with "no matches for kind" errors.

It is deployed as a standalone Flux Kustomization rather than bundled inside the agentgateway chart to decouple CRD lifecycle from application lifecycle — CRDs are cluster-scoped, shared resources that must outlive any single controller installation.

Why a dedicated Kustomization over Helm CRD hooks or chart dependencies: Helm's crds/ directory applies CRDs only on initial install and never upgrades or deletes them — leaving version drift unmanaged. Bundling CRDs inside chart templates risks accidental deletion on helm uninstall. A standalone Flux Kustomization with prune: false provides controlled, auditable CRD upgrades through Git while guaranteeing that uninstalling the consuming chart never removes the shared definitions. This is the pattern recommended by the Flux documentation for any CRD that multiple controllers or tenants may depend on.

Features

Feature Detail
Prune-safe CRD lifecycle prune: false ensures Flux never garbage-collects these CRDs during reconciliation, even if the Kustomization source is temporarily unreachable or the resource list changes
Dependency gate with wait wait: true blocks downstream Kustomizations (agentgateway) from reconciling until all CRDs report Established=True, preventing race conditions at cluster bootstrap
Standard channel pinning Pulls exclusively from the upstream standard-install.yaml release artifact, excluding experimental-channel resources that carry no stability guarantees
Remote source reference Resources are fetched directly from the upstream GitHub release tag rather than vendored into the repository, keeping the diff surface minimal during version bumps

Configuration

All values sourced from base/services/environment.env (base); per-environment overrides in clusters/stages/dev/.../environment.env.

No environment-specific configuration variables for this service.

Operations

CRD fetch fails due to GitHub rate limiting or network timeout

Symptoms: Flux Kustomization gateway-api-crds shows Ready: False with message containing failed to fetch remote resource or context deadline exceeded. The agentgateway HelmRelease remains suspended waiting on its dependency.

kubectl get kustomization gateway-api-crds -n flux-system -o yaml | grep -A5 'status:'
kubectl logs -n flux-system deploy/kustomize-controller --since=10m | grep gateway-api-crds
# Verify GitHub connectivity from inside the cluster:
kubectl run curl-test --rm -it --image=curlimages/curl -- curl -sI https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml
# Force reconciliation after transient failure resolves:
flux reconcile kustomization gateway-api-crds --with-source

CRD version conflict with pre-existing installation

Symptoms: Kustomization reports invalid: metadata.resourceVersion: Invalid value or the server could not find the requested resource for specific CRD fields. This occurs when another tool (Helm chart, manual kubectl apply) installed a different version of Gateway API CRDs.

# Check existing CRD versions and their managing field owners:
kubectl get crd gateways.gateway.networking.k8s.io -o jsonpath='{.metadata.labels}'
kubectl get crd gatewayclasses.gateway.networking.k8s.io -o yaml | grep -A3 'managedFields' | head -20
# If owned by another manager, force Flux to take ownership:
kubectl annotate crd gatewayclasses.gateway.networking.k8s.io kustomize.toolkit.fluxcd.io/force=enabled --overwrite
kubectl annotate crd gateways.gateway.networking.k8s.io kustomize.toolkit.fluxcd.io/force=enabled --overwrite
kubectl annotate crd httproutes.gateway.networking.k8s.io kustomize.toolkit.fluxcd.io/force=enabled --overwrite
flux reconcile kustomization gateway-api-crds

Downstream agentgateway fails with "no matches for kind GatewayClass"

Symptoms: The agentgateway HelmRelease shows install retries exhausted or no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1". The gateway-api-crds Kustomization may show Ready but CRDs are not actually registered.

# Verify CRDs are actually registered in the API server:
kubectl get crd | grep gateway.networking.k8s.io
# Check if the Kustomization applied successfully but CRDs failed silently:
kubectl get kustomization gateway-api-crds -n flux-system -o jsonpath='{.status.inventory.entries}'
# Verify the dependsOn chain is correctly wired:
kubectl get kustomization agentgateway -n flux-system -o jsonpath='{.spec.dependsOn}'
# If CRDs are missing, force a full reconciliation:
flux reconcile kustomization gateway-api-crds --with-source
# Wait for CRDs then retry downstream:
kubectl wait --for=condition=Established crd gatewayclasses.gateway.networking.k8s.io --timeout=60s
flux reconcile kustomization agentgateway

CRD accidentally deleted despite prune false

Symptoms: kubectl get gatewayclasses returns error: the server doesn't have a resource type "gatewayclasses". All existing Gateway and HTTPRoute resources vanish from the cluster. Flux logs show no deletion event (deletion was manual or from another controller).

# Confirm CRDs are gone:
kubectl get crd | grep gateway.networking.k8s.io || echo 'No Gateway API CRDs found'
# Check Flux did not delete them (prune: false should prevent this):
kubectl logs -n flux-system deploy/kustomize-controller --since=1h | grep -i 'delete\|prune' | grep gateway
# Re-apply immediately — downstream resources are already gone:
flux reconcile kustomization gateway-api-crds --with-source
# Verify restoration:
kubectl wait --for=condition=Established crd gatewayclasses.gateway.networking.k8s.io --timeout=120s
# Note: Custom resources (Gateways, HTTPRoutes) that existed are permanently lost. They must be re-created by reconciling their owning Kustomizations:
flux reconcile kustomization agentgateway

Generated from service-catalog.json at commit 165b485 · catalog sha 4d088b0b3a67b4c4