Ingress

Uses: Kong Ingress Controller

Configure the controller ingress class

The --ingress-class flag (or CONTROLLER_INGRESS_CLASS environment variable) specifies the ingress class expected by the Kong Ingress Controller. If you don’t set a value, Kong Ingress Controller will default to --ingress-class=kong.

Load resources by class

The Kong Ingress Controller translates a number of Kubernetes resources into Kong Gateway configuration. These resources can be sorted into two categories:

Resources that the controller translates directly into Kong Gateway configuration.

For example, an Ingress is translated directly into a Kong Route, and a KongConsumer is translated directly into a Kong Consumer.
Resources referenced by some other resource, where the other resource is directly translated into Kong Gateway configuration.

For example, a Secret containing an authentication plugin credential is not translated directly. It’s only translated into Kong Gateway configuration if a KongConsumer resource references it.

Because they create Kong Gateway configuration independent 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.

Add class information to resources

Most resources use a kubernetes.io/ingress-class annotation to indicate their class. However, v1 Ingress resources have a dedicated ingressClassName field that should contain the ingressClassName.

When to use a custom class

Using the default kong class is fine for simple deployments, where only one Kong Ingress Controller instance is running in a cluster.

You need to use a custom class when:

You install multiple Kong environments in one Kubernetes cluster to handle different types of ingress traffic. For example, 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 (DB-backed mode only) using the --kong-workspace flag or to restrict which Kubernetes namespaces any one controller instance has access to.

Examples

Typical configurations include a mix of resources that have class information and resources that are referenced by them. For example, consider this configuration for authenticating a request, using a KongConsumer, credential Secret, Ingress, and KongPlugin (a Service is implied, but not shown):

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: alice
  annotations:
    kubernetes.io/ingress.class: "kong"
username: alice
credentials:
- alice-key

---

kind: Secret
apiVersion: v1
metadata:
  name: alice-key
  labels:
    konghq.com/credential: key-auth
stringData:
  key: bylkogdatomoryakom

---

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: key-auth-example
plugin: key-auth

---

kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: echo-ingress
  annotations:
    konghq.com/plugins: "key-auth-example"
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 1027

The KongConsumer and Ingress resources both have class annotations, as they are resources that the controller uses as a basis for building Kong Gateway configuration. The Secret and KongPlugin do not have class annotations, as they are referenced by other resources that do.