Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.9.x (latest)
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • FAQ
    • Version Support Policy
    • Stages of Software Availability
    • Changelog
    • Architecture
    • Custom Resources
    • Deployment Methods
    • Kong for Kubernetes with Kong Enterprise
    • High-Availability and Scaling
    • Resource Classes
    • Security
    • Ingress Resource API Versions
    • Gateway API
    • Kong Ingress on Minikube
    • Kong for Kubernetes
    • Kong for Kubernetes Enterprise
    • Kong for Kubernetes with Kong Enterprise
    • Kong Ingress on AKS
    • Kong Ingress on EKS
    • Kong Ingress on GKE
    • Admission Controller
    • Installing Gateway APIs
    • Getting Started with KIC
    • Upgrading from previous versions
    • Upgrading to Kong 3.x
    • Getting Started using Istio
      • Using the Kong(Cluster)Plugin Resource
      • Using the KongIngress Resource
      • Using KongConsumer and Credential Resources
      • Using the TCPIngress Resource
      • Using the UDPIngress Resource
    • Using the ACL and JWT Plugins
    • Using cert-manager with Kong
    • Allowing Multiple Authentication Methods
    • Configuring a Fallback Service
    • Using an External Service
    • Configuring HTTPS Redirects for Services
    • Using Redis for Rate Limiting
    • Integrate KIC with Prometheus/Grafana
    • Configuring Circuit-Breaker and Health-Checking
    • Setting up a Custom Plugin
    • Using Ingress with gRPC
    • Setting up Upstream mTLS
    • Exposing a TCP Service
    • Exposing a UDP Service
    • Using the mTLS Auth Plugin
    • Configuring Custom Entities
    • Using the OpenID Connect Plugin
    • Rewriting Hosts and Paths
    • Preserving Client IP Address
    • Using Kong with Knative
    • Using Multiple Backend Services
    • KIC Annotations
    • CLI Arguments
    • Custom Resource Definitions
    • Plugin Compatibility
    • Version Compatibility
    • Supported Kong Router Flavors
    • Troubleshooting
    • Prometheus Metrics
    • Feature Gates
    • Supported Gateway API Features

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Introduction
  • Configuring the controller ingress class
  • Loading resources by class
    • Adding class information to resources
  • When to use a custom class
  • Examples
Kubernetes Ingress Controller
2.7.x
  • Home
  • Kubernetes Ingress Controller
  • Concepts
  • Kubernetes Ingress Controller and Ingress Class
You are browsing documentation for an outdated version. See the latest documentation here.

Kubernetes Ingress Controller and Ingress Class

Introduction

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

The --ingress-class flag (or CONTROLLER_INGRESS_CLASS environment variable) specifies the ingress class expected by the Kubernetes Ingress Controller. By default, it expects the kong class.

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 categories:

  • 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 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.

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 ingressClassName field.
  • Knative Services use the class specified by the ingress.class key of the Knative installation’s config-network ConfigMap. You can optionally override this on a per-Service basis by adding a networking.knative.dev/ingress.class annotation to the Service.

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 typical when:

  • 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.

Examples

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 shown):

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

---

kind: Secret
apiVersion: v1
stringData:
  key: bylkogdatomoryakom
  kongCredType: key-auth
metadata:
  name: styopa-key

---

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

---

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

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.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023