The Kubernetes
Ingress API, first introduced in late 2015 as an experimental beta feature, has finally graduated as a stable API and is included in the recent
1.19 release of Kubernetes.
The goal of the Ingress API is to provide a simple uniform means of describing the routing of HTTP or HTTPS traffic from outside a cluster to backend services within a cluster; independent of the
Ingress Controller being used. An Ingress controller is a 3rd party application, such as
Nginx or an external service like the
Google Cloud Load Balancer (GCLB), that performs the actual routing of the HTTP(S) traffic. This uniform API, supported by the Ingress Controllers made it easy to create simple HTTP(S) load balancers, however most use-cases required something more complex.
By early 2019, the Ingress API had remained in beta for close to four years. Beta APIs are not intended to be relied upon for
business-critical production use, yet
many users were using the Ingress API in some level of production capacity. After much discussion, the
Kubernetes Networking Special Interest Group (SIG) proposed a path forward to
bring the Ingress API to GA primarily by introducing
two changes in Kubernetes 1.18. These were: a new field,
pathType, to the Ingress API; and a new Ingress resource type,
IngressClass. Combined, they provide a means of guaranteeing a base level of compatibility between different
path prefix matching implementations, along with opening the door to further extension by the Ingress Controller developers in a uniform and consistent pattern.
What does this mean for you? You can be assured that the path prefixes you use will be evaluated the same way across Ingress Controllers implementations, and the Ingress configuration sprawl across
Annotations,
ConfigMaps and
CustomResourceDefinitions (CRDs) will be consolidated into a single
IngressClass resource type.
pathType
The
pathType field specifies one of three ways that an Ingress Object’s path should be interpreted:
- ImplementationSpecific: Path prefix matching is delegated to the Ingress Controller (IngressClass).
- Exact: Matches the URL path exactly (case sensitive)
- Prefix: Matches based on a URL path prefix split by /. Matching is case sensitive and done on a path element by element basis.
NOTE: ImplementationSpecific was configured as the default pathType in the 1.18 release. In 1.19 the defaulting behavior was removed and it
MUST be specified. Paths that do not include an explicit
pathType will fail validation.
Pre Kubernetes 1.18 | Kubernetes 1.19+ |
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: minimal-ingress
annotations:
kubernetes.io/ingress.class: nginx
spec:
rules:
- http:
paths:
- path: /testpath
backend:
serviceName: test
servicePort: 80 | apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: minimal-ingress
spec:
ingressClassName: external-lb
rules:
- http:
paths:
- path: /testpath
pathType: Prefix
backend:
service:
name: test
port:
number: 80 |
These changes not only make room for backwards-compatible configurations with the
ImplementationSpecific pathType, but also enables more portable workloads between Ingress Controllers with
Exact or
Prefix pathType.
IngressClass
The new
IngressClass resource takes the place of various different Annotations, ConfigMaps, Environment Variables or Command Line Parameters that you would regularly pass to an Ingress Controller directly. Instead, it has a generic
parameters field that can be used to reference controller specific configuration.
Example IngressClass ResourceapiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: external-lb
spec:
controller: example.com/ingress-controller
parameters:
apiGroup: k8s.example.com
kind: IngressParameters
name: external-lb |
Source:
https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-classIn this example, the parameters resource would include configuration options implemented by the
example.com/ingress-controller ingress controller. These items would not need to be passed as Annotations or a ConfigMap as they would in versions prior to Kubernetes 1.18.
How do you use
IngressClass with an Ingress Object? You may have caught it in the earlier example, but the Ingress resource’s spec has been updated to include an
ingressClassName field. This field is similar to the previous
kubernetes.io/ingress.class annotation but refers to the name of the corresponding
IngressClass resource.
Other Changes
Several other small changes went into effect with the graduation of Ingress to GA in 1.19. A few fields have
been remapped/renamed and support for
resource backends has been added.
Remapped Ingress FieldsResource BackendA
Resource Backend is essentially a pointer or
ObjectRef (
apiGroup,
kind,
name) to another resource in the same namespace. Why would you want to do this? Well, it opens the door to all sorts of future possibilities such as routing to static object storage hosted in GCS or S3, or another internal form of storage.
NOTE: Resource Backend and Service Backends are
mutually exclusive. Only one field can be specified at a time.
Deprecation Notice
With the graduation of Ingress in the 1.19 release, it officially puts the older iterations of the API (
extensions/v1beta1 and networking.k8s.io/v1beta1) on a clock. Following the
Kubernetes Deprecation Policy, the older APIs are slated to be removed in
Kubernetes 1.22.
Should you migrate right now (September 2020)? Not yet. The majority of Ingress Controllers have not added support for the new GA Ingress API.
Ingress-GCE, the Ingress Controller for
Google Kubernetes Engine (GKE) should be updated to support the Ingress GA API in Q4 2020. Keep your eyes on the
GKE rapid release channel to stay up to date on it, and Kubernetes 1.19’s availability.
What’s Next for Ingress?
The Ingress API has had a rough road getting to GA. It is an essential resource for many, and the changes that have been introduced help manage that complexity while keeping it relatively light-weight. However, even with the added flexibility that has been introduced it doesn’t cover a variety of complex use-cases.
SIG Network has been working on a new API referred to as “
Service APIs” that takes into account the lessons learned from the previous efforts of working on Ingress. These Service APIs are not intended to replace Ingress, but instead compliment it by providing several new resources that could enable more complex workflows.
By Bob Killen, Program Manager, Google Open Source Programs Office