You are browsing documentation for an outdated version. See the latest documentation here.
Ingress v1 and v1beta1 Differences
Kubernetes 1.19 introduced a new
networking.k8s.io/v1 API for the Ingress resource.
It standardizes common practices and clarifies implementation requirements that
were previously up to individual controller vendors. This document covers those
changes as they relate to Kubernetes Ingress Controller and provides sample
networking.k8s.io/v1 resources for comparison.
Both Ingress v1beta1 and v1 HTTP rules require a path, which represents a URI path. Although v1beta1 had specified that paths were POSIX regular expressions and enforced this, in practice most controllers used other implementations that did not match the specification. v1 seeks to reduce confusion by introducing several path types and lifting restrictions on regular expression grammars used by controllers.
The controller passes paths directly to Kong and relies on its path handling
logic. The Kong proxy treats paths as a prefix unless they include
characters not allowed in RFC 3986 paths, in which case the
proxy assumes they are a regular expression, and does not treat slashes as
special characters. For example, the prefix
/foo can match any of the
/foo /foo/ /foobar /foo/bar
Although v1 Ingresses provide path types with more clearly-defined logic, the
controller must still create Kong routes and work within the Kong proxy’s
routing logic. As such, the controller translates Ingress rule paths to create
Kong routes that match one of the following specifications:
Exact, the controller creates a Kong route with a regular
expression that matches the rule path only. For example, an exact rule for
/foo in an
Ingress translates to a Kong route with a
/foo$ regular expression path.
Prefix, the controller creates a Kong route with two path
criteria. For example,
/foo will create a route with a
/foo$ regular expression and
/foo/ plain path.
The controller leaves
ImplementationSpecific path rules entirely up to the Kong
router. It creates a route with the exact same path string as the Ingress rule.
Exactpaths modify the paths you provide, and those modifications may interfere with user-provided regular expressions. If you are using your own regular expressions in paths, use
ImplementationSpecificto avoid unexpected behavior.
Ingress class indicates which resources an ingress controller should process. It provides a means to separate out configuration intended for other controllers or other instances of the Kubernetes Ingress Controller.
In v1beta1, ingress class was handled informally using
kubernetes.io/ingress.class annotations. v1
introduces a new IngressClass resource which provides
richer information about the controller. v1 Ingresses are bound to a class via
For example, consider this v1beta1 Ingress:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: example-ingress annotations: kubernetes.io/ingress.class: "kong" spec: rules: - host: example.com http: paths: - path: /test backend: serviceName: echo servicePort: 80
Its ingress class annotation is set to
kong, and ingress controllers set to
kong class Ingresses will process it.
In v1, the equivalent configuration declares a
kong IngressClass resource
metadata.name field indicates the class name. The
value of the Ingress object must match the value of the
name field in the
apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: kong spec: controller: ingress-controllers.konghq.com/kong --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: example-ingress spec: ingressClassName: kong rules: - host: example.com http: paths: - path: /test pathType: Prefix backend: service: name: echo port: number: 80
Ingress v1 formally codifies support for wildcard hostnames. v1beta1 Ingresses did not reject wildcard hostnames, however, and Kong had existing support for them.
As such, while the v1beta1 specification did not officially support wildcard
hostnames, you can use wildcard hostnames with either version. Setting a
*.example.com will match requests for both
bar.example.com with either v1 or v1beta1 Ingresses.
Ingress v1 introduces support for backends other than Kubernetes Services through resource backends.
Kong does not support any dedicated resource backend configurations, though it
does have support for Routes without Services in some cases (for example, when
using the AWS Lambda plugin). For these routes, you should
create a placeholder Kubernetes Service for them, using an ExternalName
Service with an RFC 2606 invalid hostname, e.g.
kong.invalid. You can use these placeholder services with either v1 or