Kong's Kubernetes Ingress Controller v2.0.0 is currently in beta. Check out the
beta documentation and try out
v2.0.0 for yourself.
Kubernetes Ingress Controller and Ingress Class
The Kubernetes Ingress Controller uses ingress classes to filter Kubernetes Ingress
objects and other resources before converting them into Kong configuration.
This allows it to coexist with other ingress controllers and/or other
deployments of the Kubernetes Ingress Controller in the same cluster: a
Kubernetes Ingress Controller will only process configuration marked for its use.
Configuring the controller ingress class
--ingress-class flag (or
CONTROLLER_INGRESS_CLASS environment variable)
specify the ingress class expected by the Kubernetes Ingress Controller. By default,
it expects the
Loading resources by class
The Kubernetes Ingress Controller translates a variety of Kubernetes resources into
Kong configuration. Broadly speaking, we can separate these resources into two
- Resources that the controller translates directly into Kong configuration.
- Resources referenced by some other resource, where the other resource is
directly translated into Kong configuration.
For example, an Ingress is translated directly into a Kong route, and a
KongConsumer is translated directly into a
Kong consumer. A Secret containing
an authentication plugin credential is not translated directly: it is only
translated into Kong configuration if a KongConsumer resource references it.
Because they create Kong configuration indenpendent of any other resources,
directly-translated resources require an ingress class, and their class must
match the class configured for the controller. Referenced resources do not
require a class, but must be referenced by a directly-translated resource
that matches the controller.
Adding class information to resources
Most resources use a kubernetes.io/ingress-class annotation
to indicate their class. There are several exceptions:
- v1 Ingress resources have a dedicated
- Knative Services use the class specifed by the
ingress.class key of the Knative installation’s
You can optionally override this on a per-Service basis
by adding a
networking.knative.dev/ingress.class annotation to the Service.
Enabling support for classless resources
Specifying a class is optional for some resources. Although specifying a class
is recommended, you can instruct the controller to process resources without a
class annotation using flags:
--process-classless-ingress-v1beta1 instructs the controller to translate
v1beta1 Ingress resources with no class annotation.
--process-classless-kong-consumer instructs the controller to translate
KongConsumer resources with no class annotation.
These flags are primarily intended for compatibility with older configuration
(Kubernetes Ingress Controller before 0.10 had less strict class
requirements, and it was common to omit class annotations). If you are creating
new configuration and do not have older configuration without class
annotations, recommended best practice is to add class information to Ingress
and KongConsumer resources and not set the above flags. Doing so avoids
accidentally creating duplicate configuration in other ingress controller
These flags do not ignore
ingress.class annotations: they allow resources
with no such annotation, but will not allow resource that have a non-matching
When to use a custom class
Using the default
kong class is fine for simpler deployments, where only one
Kubernetes Ingress Controller instance is running in a cluster. Changing the class is
- You install multiple Kong environments in one Kubernetes cluster to handle
different types of ingress traffic, e.g. when using separate Kong instances
to handle traffic on internal and external load balancers, or deploying
different types of non-production environments in a single test cluster.
- You install multiple controller instances alongside a single Kong cluster to
separate configuration into different Kong workspaces (using the
--kong-workspace flag) or to restrict which Kubernetes namespaces any one
controller instance has access to.
This overview covers behavior in Kubernetes Ingress Controller version 0.10.0 onward.
Earlier versions had a special case for the default class and a bug affecting
- When using the default
kong class, the controller would always process
classless resources in addition to
kong-class resources. When using a
non-default controller class, the controller would only process resources
with that class, not classless resources. Although this was by design, it was
a source of user confusion.
- When using a custom controller class, some resources that should not have
required a class (because they were referenced by other resources)
effectively did require a class: while these resources were loaded initially,
the controller would not track updates to them unless they had a class
In versions 0.10.0+ you must instruct the controller to load classless
resources, which is allowed (but not recommended) for either the default or
custom classes. Resources referenced by another resource are always loaded and
updated correctly regardless of which class you set on the controller; you do
not need to add class annotations to these resources when using a custom class.
Typical configurations will include a mix of resources that have class
information and resources that are referenced by them. For example, consider
the following configuration for authenticating a request, using a KongConsumer,
credential Secret, Ingress, and KongPlugin (a Service is implied, but not
- path: /vsemznakom
The KongConsumer and Ingress resources both have class annotations, as they are
resources that the controller uses as a basis for building Kong configuration.
The Secret and KongPlugin do not have class annotations, as they are
referenced by other resources that do.