Skip to main content
Gateway API Learning
← Back to Examples

Migration

This document provides a side-by-side comparison of the migration from Nginx Ingress to Gateway API.

Before: Nginx Ingress Configuration

Here's the original Nginx Ingress configuration:

After: Gateway API Configuration

Here's the migrated Gateway API configuration:

Resource Mapping

Nginx IngressGateway APINotes
IngressClassGatewayClassDefines controller type
Ingress Controller SetupGatewayNetwork endpoints and TLS
Ingress ResourceHTTPRouteRouting rules
Ingress TLSGateway TLSCentralized at Gateway level
Ingress BackendBackendRefMore powerful in Gateway API

Annotation Mapping

Nginx AnnotationGateway API Equivalent
nginx.ingress.kubernetes.io/rewrite-targetURLRewrite filter
nginx.ingress.kubernetes.io/canary-weightweight in backendRefs
nginx.ingress.kubernetes.io/limit-rpsRateLimitPolicy
nginx.ingress.kubernetes.io/proxy-connect-timeoutTimeoutPolicy
nginx.ingress.kubernetes.io/enable-corsCORSPolicy
nginx.ingress.kubernetes.io/permanent-redirectRequestRedirect filter

Key Differences

1. Architecture

Nginx Ingress:

  • Single Ingress resource for all configuration
  • Controller deployed separately
  • TLS configured per Ingress

Gateway API:

  • Separate Gateway (infrastructure) and HTTPRoute (application)
  • Gateway is a Kubernetes resource
  • TLS configured once at Gateway level

2. Role Separation

Nginx Ingress:

  • Infrastructure and application teams modify same resource
  • Limited role separation

Gateway API:

  • Infrastructure team: Gateway
  • Application team: HTTPRoute
  • Clear separation of concerns

3. Portability

Nginx Ingress:

  • Nginx-specific annotations
  • Not portable across implementations

Gateway API:

  • Standard API
  • Works across implementations (Nginx, Istio, Contour, etc.)

4. Expressiveness

Nginx Ingress:

  • Limited native features
  • Requires annotations for advanced features

Gateway API:

  • Native support for advanced routing
  • Rich filter system
  • Policy attachments

Migration Benefits

  1. Better Organization: Clear separation between infrastructure and application
  2. Portability: Works with any Gateway API implementation
  3. Native Features: Advanced features built-in, not via annotations
  4. Scalability: Application teams can create routes independently
  5. Standard API: Follows Kubernetes API patterns

Migration Challenges

  1. Learning Curve: New concepts and resources
  2. Implementation Support: Some features vary by implementation
  3. Migration Effort: Requires updating all Ingress resources
  4. Testing: Need to test thoroughly after migration

Migration Checklist

  • Install Gateway API CRDs
  • Install Gateway implementation
  • Create GatewayClass
  • Create Gateway with TLS
  • Migrate Ingress to HTTPRoute
  • Migrate annotations to filters/policies
  • Test routing
  • Test TLS
  • Test advanced features
  • Monitor metrics
  • Remove old Ingress resources

Related Documentation

Sources & References

•
•