The Kubernetes Gateway API has rapidly evolved from its experimental roots to become the standard for ingress and service mesh traffic management. But with multiple versions released and various maturity levels, understanding which version to use, how it relates to your Kubernetes cluster, and when to upgrade can be challenging.
In this comprehensive guide, we’ll explore the different Gateway API versions, their relationship to Kubernetes releases, provider support levels, and the upgrade philosophy that will help you make informed decisions for your infrastructure.
Understanding Gateway API Versioning
The Gateway API follows a unique versioning model that differs from standard Kubernetes APIs. Unlike built-in Kubernetes resources that are tied to specific cluster versions, Gateway API CRDs can be installed independently as long as your cluster meets the minimum requirements.
Minimum Kubernetes Version Requirements
As of Gateway API v1.1 and later versions, you need Kubernetes 1.26 or later to run the latest Gateway API releases. The API commits to supporting a minimum of the most recent 5 Kubernetes minor versions, providing a reasonable window for cluster upgrades.
This rolling support window means that if you’re running Kubernetes 1.26, 1.27, 1.28, 1.29, or 1.30, you can safely install and use the latest Gateway API without concerns about compatibility.
Release Channels: Standard vs Experimental
Gateway API uses two distinct release channels to balance stability with innovation. Understanding these channels is critical for choosing the right version for your use case.
Standard Channel
The Standard channel contains only GA (Generally Available, v1) and Beta (v1beta1) level resources and fields. When you install from the Standard channel, you get:
- Stability guarantees: No breaking changes once a resource reaches Beta or GA
- Backwards compatibility: Safe to upgrade between minor versions
- Production readiness: Extensively tested features with multiple implementations
- Conformance coverage: Full test coverage ensuring portability
Resources in the Standard channel include GatewayClass, Gateway, HTTPRoute, and ReferenceGrant at the v1 level, plus stable features like GRPCRoute.
Experimental Channel
The Experimental channel includes everything from the Standard channel plus Alpha-level resources and experimental fields. This channel is for:
- Early feature testing: Try new capabilities before they stabilize
- Cutting-edge functionality: Access the latest Gateway API innovations
- No stability guarantees: Breaking changes can occur between releases
- Feature feedback: Help shape the API by testing experimental features
Features may graduate from Experimental to Standard or be dropped entirely based on implementation experience and community feedback.
Gateway API Version History and Features
Let’s explore the major Gateway API releases and what each introduced.
v1.0 (October 2023)
The v1.0 release marked a significant milestone, graduating core resources to GA status. This release included:
- Gateway, GatewayClass, and HTTPRoute at v1 (stable)
- Full backwards compatibility guarantees for v1 resources
- Production-ready status for ingress traffic management
- Multiple conformant implementations across vendors
v1.1 (May 2024)
Version 1.1 expanded the API significantly with service mesh support:
- GRPCRoute: Native support for gRPC traffic routing
- Service mesh capabilities: East-west traffic management alongside north-south
- Multiple implementations: Both Istio and other service meshes achieved conformance
- Enhanced features: Additional matching criteria and routing capabilities
This version bridged the gap between traditional ingress controllers and full service mesh implementations.
v1.2 and v1.3
These intermediate releases introduced structured release cycles and additional features:
- Refined conformance testing
- BackendTLSPolicy (experimental in v1.3)
- Enhanced observability and debugging capabilities
- Improved cross-namespace routing
v1.4 (October 2025)
The latest GA release as of this writing, v1.4.0 brought:
- Continued API refinement
- Additional experimental features for community testing
- Enhanced conformance profiles
- Improved documentation and migration guides
Kubernetes Version Compatibility Matrix
Here’s how Gateway API versions relate to Kubernetes releases:
| Gateway API Version | Minimum Kubernetes | Recommended Kubernetes | Release Date |
|---|---|---|---|
| v1.0.x | 1.25 | 1.26+ | October 2023 |
| v1.1.x | 1.26 | 1.27+ | May 2024 |
| v1.2.x | 1.26 | 1.28+ | 2024 |
| v1.3.x | 1.26 | 1.29+ | 2024 |
| v1.4.x | 1.26 | 1.30+ | October 2025 |
The key takeaway: Gateway API v1.1 and later all support Kubernetes 1.26+, meaning you can run the latest Gateway API on any reasonably modern cluster.
Gateway Provider Support Levels
Different Gateway API implementations support various versions and feature sets. Understanding provider support helps you choose the right implementation for your needs.
Conformance Levels
Gateway API defines three conformance levels for features:
- Core: Features that must be supported for an implementation to claim conformance. These are portable across all implementations.
- Extended: Standardized optional features. Implementations indicate Extended support separately from Core.
- Implementation-specific: Vendor-specific features without conformance requirements.
Major Provider Support
Istio
Istio reached Gateway API GA support in version 1.22 (May 2024). Istio provides:
- Full Standard channel support (v1 resources)
- Service mesh (east-west) traffic management via GAMMA
- Ingress (north-south) traffic control
- Experimental support for BackendTLSPolicy (Istio 1.26+)
Istio is particularly strong for organizations needing both ingress and service mesh capabilities in a single solution.
Envoy Gateway
Envoy Gateway tracks Gateway API releases closely. Version 1.4.0 includes:
- Gateway API v1.3.0 support
- Compatibility matrix for Envoy Proxy versions
- Focus on ingress use cases
- Strong experimental feature adoption
Check the Envoy Gateway compatibility matrix to ensure your Envoy Proxy version aligns with your Gateway API and Kubernetes versions.
Cilium
Cilium integrates Gateway API deeply with its CNI implementation:
- Per-node Envoy proxy architecture
- Network policy enforcement for Gateway traffic
- Both ingress and service mesh support
- eBPF-based packet processing
Cilium’s unique architecture makes it a strong choice for organizations already using Cilium for networking.
Contour
Contour v1.31.0 implements Gateway API v1.2.1, supporting:
- All Standard channel v1 resources
- Most v1alpha2 resources (TLSRoute, TCPRoute, GRPCRoute)
- BackendTLSPolicy support
Checking Provider Conformance
To verify which Gateway API version and features your provider supports:
- Visit the official implementations page: The Gateway API project maintains a comprehensive list of implementations with their conformance levels.
- Check provider documentation: Most providers publish compatibility matrices showing Gateway API, Kubernetes, and proxy version relationships.
- Review conformance reports: Providers submit conformance test results that detail exactly which Core and Extended features they support.
- Test in non-production: Before upgrading production, validate your specific use cases in a staging environment.
Upgrade Philosophy: When and How to Upgrade
One of the most common questions about Gateway API is: “Do I need to run the latest version?” The answer depends on your specific needs and risk tolerance.
Staying on Older Versions
You don’t need to always run the latest Gateway API version. It’s perfectly acceptable to:
- Stay on an older stable release if it meets your needs
- Upgrade only when you need specific new features
- Wait for your Gateway provider to officially support newer versions
- Maintain stability over having the latest features
The Standard channel’s backwards compatibility guarantees mean that when you do upgrade, your existing configurations will continue to work.
When to Consider Upgrading
Consider upgrading when:
- You need a specific feature: A new HTTPRoute matcher, GRPCRoute support, or other functionality only available in newer versions
- Your provider recommends it: Gateway providers often optimize for specific Gateway API versions
- Security considerations: While rare, security issues could prompt upgrades
- Kubernetes cluster upgrades: When upgrading Kubernetes, verify your Gateway API version is compatible with the new cluster version
Safe Upgrade Practices
Follow these best practices for Gateway API upgrades:
1. Stick with Standard Channel
Using Standard channel CRDs makes upgrades simpler and safer. Experimental features can introduce breaking changes, while Standard features maintain compatibility.
2. Upgrade One Minor Version at a Time
While it’s usually safe to skip versions, the most tested upgrade path is incremental. Going from v1.2 to v1.3 to v1.4 is safer than jumping directly from v1.2 to v1.4.
3. Test Before Upgrading
Always test upgrades in non-production environments:
# Install specific Gateway API version in test cluster
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml
4. Review Release Notes
Each Gateway API release publishes comprehensive release notes detailing:
- New features and capabilities
- Graduation of experimental features to standard
- Deprecation notices
- Upgrade considerations
5. Check Provider Compatibility
Before upgrading Gateway API CRDs, verify your Gateway provider supports the target version. Installing Gateway API v1.4 won’t help if your controller only supports v1.2.
6. Never Overwrite Different Channels
Implementations should never overwrite Gateway API CRDs that use a different release channel. Keep track of whether you’re using Standard or Experimental channel installations.
CRD Management Best Practices
Gateway API CRD management requires attention to detail:
# Check currently installed Gateway API version
kubectl get crd gateways.gateway.networking.k8s.io -o yaml | grep 'gateway.networking.k8s.io/bundle-version'
# Verify which channel is installed
kubectl get crd gateways.gateway.networking.k8s.io -o yaml | grep 'gateway.networking.k8s.io/channel'
Staying Informed About New Releases
Gateway API releases follow a structured release cycle with clear communication channels.
How to Know When New Versions Are Released
- GitHub Releases Page: Watch the kubernetes-sigs/gateway-api repository for release announcements
- Kubernetes Blog: Major Gateway API releases are announced on the official Kubernetes blog
- Mailing Lists and Slack: Join the Gateway API community channels for discussions and announcements
- Provider Announcements: Gateway providers announce support for new Gateway API versions through their own channels
Release Cadence
Gateway API follows a quarterly release schedule for minor versions, with patch releases as needed for bug fixes and security issues. This predictable cadence helps teams plan upgrades.
Practical Decision Framework
Here’s a framework to help you decide which Gateway API version to run:
For New Deployments
- Production workloads: Use the latest GA version supported by your provider
- Innovation-focused: Consider Experimental channel if you need cutting-edge features
- Conservative approach: Use v1.1 or later with Standard channel
For Existing Deployments
- If things are working: Stay on your current version until you need new features
- If provider recommends upgrade: Follow provider guidance, especially for security
- If Kubernetes upgrade planned: Verify compatibility, may need to upgrade Gateway API first or simultaneously
Feature-Driven Upgrades
- Need service mesh support: Upgrade to v1.1 minimum
- Need GRPCRoute: Upgrade to v1.1 minimum
- Need BackendTLSPolicy: Requires v1.3+ and provider support for experimental features
Conclusion
Kubernetes Gateway API represents the future of traffic management in Kubernetes, offering a standardized, extensible, and role-oriented API for both ingress and service mesh use cases. Understanding the versioning model, compatibility requirements, and upgrade philosophy empowers you to make informed decisions that balance innovation with stability.
Key takeaways:
- Gateway API versions install independently from Kubernetes, requiring only version 1.26 or later for recent releases
- Standard channel provides stability, Experimental channel provides early access to new features
- You don’t need to always run the latest version—upgrade when you need specific features
- Verify provider support before upgrading Gateway API CRDs
- Follow safe upgrade practices: test first, upgrade incrementally, review release notes
By following these guidelines, you can confidently deploy and maintain Gateway API in your Kubernetes infrastructure while making upgrade decisions that align with your organization’s needs and risk tolerance.
Frequently Asked Questions
What is the difference between Kubernetes Ingress and the Gateway API?
Kubernetes Ingress is a legacy API focused mainly on HTTP(S) traffic with limited extensibility. The Gateway API is its successor, offering a more expressive, role-oriented model that supports multiple protocols, advanced routing, better separation of concerns, and consistent behavior across implementations
Which Gateway API version should I use in production today?
For most production environments, you should use the latest GA (v1.x) release supported by your Gateway provider, installed from the Standard channel. This ensures stability, backwards compatibility, and conformance guarantees while still benefiting from ongoing improvements.
Can I upgrade the Gateway API without upgrading my Kubernetes cluster?
Yes. Gateway API CRDs are installed independently of Kubernetes itself. As long as your cluster meets the minimum supported Kubernetes version (1.26+ for recent releases), you can upgrade the Gateway API without upgrading the cluster.
What happens if my Gateway provider does not support the latest Gateway API version?
If your provider lags behind, you should stay on the latest version officially supported by that provider. Installing newer Gateway API CRDs than your controller supports can lead to missing features or undefined behavior. Provider compatibility should always take precedence over running the newest API version.
Is it safe to upgrade Gateway API CRDs without downtime?
In most cases, yes—when using the Standard channel. The Gateway API provides strong backwards compatibility guarantees for GA and Beta resources. However, you should always test upgrades in a non-production environment and verify that your Gateway provider supports the target version.













