Using Custom Classes to split internal and external traffic

Kong Ingress Controller automatically creates a kong IngressClass when installed. All of the example ingress definitions in the documentation set spec.ingressClassName: kong, which allows things to work by default.

Advanced users of Kong Ingress Controller may want to split traffic into internal and external ingress definitions. This requires multiple Kong Ingress Controller instances, each pointing to a different IngressClass.

You can also split traffic into different gateways when you are using Gateway APIs with multiple Kong Ingress Controller instances and multiple Gateways.

The IngressClass resource binds an Ingress definition to an ingress controller. The value in the spec.controller field defines which ingress controller will process those ingress definitions. Kong Ingress Controller processes any IngressClass where spec.controller is set to ingress-controllers.konghq.com/kong.

You can use the following command to create internal and external ingress classes:

echo 'apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: internal
spec:
  controller: ingress-controllers.konghq.com/kong
---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: external
spec:
  controller: ingress-controllers.konghq.com/kong' | kubectl apply -f -

For splitting traffic into different gateways using the Kubernetes Gateway API, create two Gateways in the Kubernetes cluster, where each Gateway is reconciled by one Kong Ingress Controller instance:

echo 'apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: "true"
spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
  namespace: internal
spec:
  gatewayClassName: kong
  listeners:
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
  namespace: external
spec:
  gatewayClassName: kong
  listeners:
  - name: http
    protocol: HTTP
    port: 80' | kubectl apply -f -

Kong Ingress Controller processes one IngressClass per installation. Kong Ingress Controller requires two deployments to split internal and external traffic.

Each deployment lives in its namespace, and the controller.ingressController.ingressClass value is set depending on whether that deployment should handle internal or external traffic.

You can split traffic into different Gateways in the Kubernetes Gateway APIs by using the environment variable CONTROLLER_GATEWAY_TO_RECONCILE. Configure the variable to instruct Kong Ingress Controller to reconcile specific Gateway instances and routes attached to the gateway:

helm upgrade --install kong-internal kong/ingress -n internal --create-namespace --set controller.ingressController.ingressClass=internal --set controller.ingressController.env.gateway_to_reconcile=internal/kong

helm upgrade --install kong-external kong/ingress -n external --create-namespace --set controller.ingressController.ingressClass=external --set controller.ingressController.env.gateway_to_reconcile=external/kong

Rather than setting spec.ingressClassName: kong in your Ingress definitions, you should now use either internal or external. Ingress definitions that target internal will only be available via Kong Gateway running in the internal namespace. Definitions that target external will only be available via the external gateway.

For Routes in Kubernetes Gateway APIs (like HTTPRoute), refer to the corresponding Gateway in its spec.parentRef.

For example, this is how you can create a Ingress or HTTPRoute for routing internal traffic:

echo "
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-internal
  namespace: internal
  annotations:
    konghq.com/strip-path: 'true'
spec:
  parentRefs:
  - name: kong
    namespace: internal
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: '/echo'
    backendRefs:
    - name: echo
      kind: Service
      port: 1027
" | kubectl apply -f -

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo-internal
  namespace: internal
  annotations:
    konghq.com/strip-path: 'true'
spec:
  ingressClassName: internal
  rules:
  - http:
      paths:
      - path: '/echo'
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 1027
" | kubectl apply -f -