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 Kong 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
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
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.
Exact paths 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
ImplementationSpecific to 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 Kong 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:
- host: example.com
- path: /test
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
- host: example.com
- path: /test
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
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