How to Migrate from Kubernetes Ingress to the Gateway API

The Evolution of Kubernetes Gateway API, Istio, and Ingress

With the release of Istio 1.22, the Istio API has officially been upgraded to version v1, coinciding with the update of the Kubernetes Gateway API to v1.1. This article aims to explore the connections and differences between the Ingress API, Istio API, and Kubernetes Gateway API, detailing their selection and migration strategies in practical applications.

Background

Kubernetes and Service Mesh. The article pointed out that as Kubernetes’ original ingress gateway, Ingress’s resource model is too simple to meet the demands of today’s programmable networks. As its successor, the Gateway API has rapidly developed in recent years and has gained broad support, including many emerging open-source gateway projects like Envoy Gateway, which has chosen to develop based on the Gateway API. Additionally, some legacy gateway projects have started adapting to the Gateway API or using tools like ingress2gateway to migrate.

The Gateway API, as the latest evolution of Kubernetes ingress gateways, separates concerns through role division and supports cross-namespace capabilities, making it more suitable for multi-cloud environments. It integrates the overlapping functions of ingress gateways (north-south) and service meshes (east-west, intra-cluster routing) to provide a new reference model for unified traffic management in the cloud-native era.

Ingress API, Gateway API, and Istio API can all implement gateway functions, but what are their connections and differences? This article will unveil this mystery and provide strategies for selecting and migrating gateways in Kubernetes environments.

Tetrate offers an enterprise-ready, 100% upstream distribution of Envoy Gateway, Tetrate Enterprise Gateway for Envoy (TEG). TEG is the easiest way to get started with Envoy for production use cases. Get access now ›

Kubernetes Traffic Management

With the widespread adoption and increasing complexity of microservice architectures, Kubernetes’ traffic management tools have also evolved to meet various technical needs. The Ingress API, Istio API, and Kubernetes Gateway API each represent different stages of this evolution.

Ingress API offers basic traffic management capabilities in Kubernetes, allowing users to manage external access to services within the cluster through simple routing rules (e.g., HTTP and HTTPS). Although its design is straightforward, its functionality is limited and mainly suitable for smaller-scale, less complex applications.

In contrast, Istio API, as part of a service mesh, offers a range of advanced traffic management features, such as traffic mirroring, canary releases, and circuit breakers, suitable for large-scale microservice architectures requiring complex traffic management.

To overcome the limitations of the Ingress API and integrate advanced features similar to those of Istio, the Kubernetes Gateway API was developed. It provides greater flexibility and extensibility in its design and, through broad community support, serves as a bridge connecting traditional Ingress implementations and modern service mesh technologies like Istio, with most mainstream open-source gateways being based on or adapted to the Gateway API.

The following table summarizes the core features and recommended use cases for each API:

API Name	Object Type	Status	Recommended Use Cases
Ingress API	Ingress	Stable (Kubernetes v1.19)	Suitable for small-scale and simple scenarios, mainly for basic routing configurations
Istio API	VirtualService, Gateway	Stable (Istio 1.22)	Suitable for highly complex microservice architectures, requiring fine-grained control and advanced traffic management features
Gateway API	HTTPRoute, Gateway	Stable (Gateway API v1.1)	Suitable for new or existing deployments that require increased flexibility and scalability, especially when combined with Istio

The launch of Gateway API v1.1, especially its improvements in compatibility with existing Ingress configurations, provides a smooth migration path for users, making the transition from traditional Ingress solutions to more modern, feature-rich Gateway API easier.

Migrating from Ingress to Kubernetes Gateway API

To migrate from Ingress to Gateway API, follow these steps:

1. Understand Key Differences: Compared to Ingress, the Gateway API introduces several new concepts and resource types, such as Gateway, HTTPRoute, and TLSRoute. These resources offer more configuration options and flexibility; refer to the Gateway API documentation for their configurations.
2. Configure Entry Points: Create Gateway resource configurations, clearly defining how to receive external traffic, including protocols, ports, and TLS terminations.
3. Map Old Resources: Map existing Ingress resources to corresponding Gateway API resources. For example, host and path rules in Ingress need to be converted into route rules in HTTPRoute.
4. Test and Deploy: Before officially migrating, test the new Gateway API configurations in a test environment to ensure all traffic routing is normal and there are no security vulnerabilities.

To simplify the migration process, you can use tools like ingress2gateway, which can automatically convert Ingress configurations into Gateway API formats.

Practical Migration Example

Here is a simple example of an HTTP gateway configuration demonstrating how to migrate from Ingress to the Gateway API.

Assume you have an existing Ingress configuration as follows:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

To migrate it to the Gateway API, first create a Gateway object:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        kinds:
          - kind: HTTPRoute

Ensure that the gatewayClassName refers to a valid GatewayClass configured in your cluster. The GatewayClass is usually set by the cluster administrator and provides a resource to configure the Gateway.

Next, create an HTTPRoute resource to define routing rules that route traffic to the backend service:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: "/"
    backendRefs:
    - name: example-service
      port: 80

In this example, we see:

• The rules from the Ingress object are directly mapped to the HTTPRoute object.
• The hostname matching, path matching, and backend service configurations remain unchanged, but the object and field names differ.

Considerations and Challenges

Although it is possible to migrate from Ingress to Gateway API and potentially run them simultaneously, there are several challenges and considerations for the necessity of migration:

• Feature Differences: Certain features specific to some Ingress controllers may not have direct equivalents in the Gateway API, requiring additional configurations or implementation of custom resources to achieve similar functionalities.
•  Multi-Resource Management: Using the Gateway API may involve managing more resource types and complex configurations than Ingress, potentially increasing the complexity of administration.

For existing users of Ingress and Istio API, whether to migrate to the Gateway API depends on specific circumstances. Here are some migration recommendations:

• For New Deployments: It is advisable to use the Gateway API directly to take advantage of its advanced features and anticipate future developments.
• For Existing Deployments: If the existing system operates stably and does not require advanced features, you can continue using the current APIs. If you seek to leverage new features of the Gateway API or plan for long-term development, a gradual migration is a prudent choice.

For the support status of different gateways for the Gateway API, refer to the Gateway API Implementation Conformance Report for more details.

Conclusion

The Ingress API, Istio API, and Kubernetes Gateway API each have distinct features suitable for different application scenarios and needs. Selecting the appropriate API and planning and managing effectively can significantly enhance system flexibility and stability. As the Gateway API continues to develop and mature, it is increasingly becoming the mainstream choice for future traffic management.

Choosing the right gateway technology, combined with your specific needs and existing architecture, can better manage and optimize traffic to ensure efficient and stable application operation. As technology progresses and the community evolves, the Gateway API provides a powerful and flexible framework, making the transition from traditional Ingress to more modern solutions simpler and more effective.

References

• Migrating from Ingress – gateway-api.sigs.k8s.io
• Extending Gateway API support in Istio – istio.io

###

If you’re new to service mesh, Tetrate has a bunch of free online courses available at Tetrate Academy that will quickly get you up to speed with Istio and Envoy.

Are you using Kubernetes? Tetrate Enterprise Gateway for Envoy (TEG) is the easiest way to get started with Envoy Gateway for production use cases. Get the power of Envoy Proxy in an easy-to-consume package managed by the Kubernetes Gateway API. Learn more ›

Getting started with Istio? If you’re looking for the surest way to get to production with Istio, check out Tetrate Istio Subscription. Tetrate Istio Subscription has everything you need to run Istio and Envoy in highly regulated and mission-critical production environments. It includes Tetrate Istio Distro, a 100% upstream distribution of Istio and Envoy that is FIPS-verified and FedRAMP ready. For teams requiring open source Istio and Envoy without proprietary vendor dependencies, Tetrate offers the ONLY 100% upstream Istio enterprise support offering.

Need global visibility for Istio? TIS+ is a hosted Day 2 operations solution for Istio designed to simplify and enhance the workflows of platform and support teams. Key features include: a global service dashboard, multi-cluster visibility, service topology visualization, and workspace-based access control.

Get a Demo