このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Ingress v1 and v1beta1 Differences
Introduction
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
equivalent networking.k8s.io/v1beta1
and networking.k8s.io/v1
resources for comparison.
Paths
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.
networking.k8s.io/v1beta1
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
following:
/foo
/foo/
/foobar
/foo/bar
networking.k8s.io/v1
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
, Prefix
, or ImplementationSpecific
.
Exact
If pathType
is 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
If pathType
is 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.
ImplementationSpecific
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.
Both
Prefix
andExact
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, useImplementationSpecific
to avoid unexpected behavior.
Ingress class
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
their ingressClassName
field.
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
process kong
class Ingresses will process it.
In v1, the equivalent configuration declares a kong
IngressClass resource
whose metadata.name
field indicates the class name. The ingressClassName
value of the Ingress object must match the value of the name
field in the
IngressClass metadata:
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
Hostnames
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
hostname like *.example.com
will match requests for both foo.example.com
and bar.example.com
with either v1 or v1beta1 Ingresses.
Backend types
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
v1beta1 Ingresses.