Provide Feedback

Gateway Operator

A next-generation deployment mechanism founded on the operator pattern allows Kong Gateways to be provisioned in a dynamic and Kubernetes-native way, as well as enabling automation of Kong cluster operations and management of the Gateway lifecycle.

Quick Start Guide

Before deployment, Kong and Gateway API CRDs need to be deployed:

kubectl kustomize https://github.com/Kong/kubernetes-ingress-controller/config/crd | kubectl apply -f -
kubectl kustomize "https://github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.1" | kubectl apply -f -

If using OpenShift, install the operator from the OperatorHub UI. Otherwise, deploy the operator with the following one-liner:

kubectl kustomize "https://github.com/kong/gateway-operator-docs/config/default?submodules=false" | kubectl apply -f -

Optionally, you can wait for the operator with:

kubectl -n kong-system wait --for=condition=Available=true --timeout=120s deployment/gateway-operator-controller-manager

Usage

After deployment, usage is driven primarily via the Gateway resource. You can deploy a Gateway resource to the cluster, which will result in the underlying control plane (the Kong Kubernetes Ingress Controller) and the data plane (the Kong Gateway).

For example, deploy the following GatewayClass:

echo '
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
name: kong
spec:
controllerName: konghq.com/gateway-operator
'
| kubectl apply -f -

and Gateway:

echo '
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
name: kong
spec:
gatewayClassName: kong
listeners:
- name: http
protocol: HTTP
port: 80
'
| kubectl apply -f -

Wait for the Gateway to be Ready:

kubectl wait --for=condition=Ready=true gateways.gateway.networking.k8s.io/kong

Once Ready, you'll be able to receive the default IP address of the Gateway:

$ kubectl get gateway kong
NAME CLASS ADDRESS READY AGE
kong kong 172.18.0.240 True 97s

The Gateway is now accessible via that IP:

$ curl -s -w '\n' http://172.18.0.240
{"message":"no Route matched with those values"}

Note: if your cluster can not provision LoadBalancer type Services then the IP you receive may only be routable from within the cluster.


Note: the no Route matched result is normal for a Gateway with no configuration. Create Ingress, HTTPRoute, and other resources to start routing traffic to your applications. See the Ingress Controller Guides for more information).


Configuring Gateways

A Gateway resource has subcomponents such as a ControlPlane and a DataPlane, which are created and managed on its behalf. At a deeper technical level, ControlPlane corresponds with the Kong Kubernetes Ingress Controller (KIC) and DataPlane corresponds with the Kong Gateway.

While not required for primary usage, it is possible to provide configuration for these subcomponents using the GatewayConfiguration API. That configuration can include the container image and image version to use for the subcomponents, as well as environment and volume mount overrides will be passed down toPods created for that component.

For example:

kind: GatewayConfiguration
apiVersion: gateway-operator.konghq.com/v1alpha1
metadata:
name: kong
namespace: default
spec:
dataPlaneDeploymentOptions:
containerImage: kong/kubernetes-ingress-controller
version: 2.4.2
env:
- name: TEST_VAR
value: TEST_VAL
controlPlaneDeploymentOptions:
containerImage: kong/kong
version: 2.8.0
env:
- name: TEST_VAR
value: TEST_VAL

Configurations like the above can be created on the API, but won't be active until referenced by a GatewayClass:

kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
name: kong
spec:
controllerName: konghq.com/gateway-operator
parametersRef:
group: gateway-operator.konghq.com
kind: GatewayConfiguration
name: kong
namespace: default

With the parametersRef in the above GatewayClass being used to attach the GatewayConfiguration, that configuration will start applying to all Gatewayresources created for that class, and will retroactively apply to any Gatewayresources previously created.

Gateway upgrades/downgrades

The GatewayConfiguration API can be used to provide the image and the image version desired for either the ControlPlane or DataPlane component of the Gateway e.g.:

kind: GatewayConfiguration
apiVersion: gateway-operator.konghq.com/v1alpha1
metadata:
name: kong
namespace: default
spec:
dataPlaneDeploymentOptions:
containerImage: kong/kong
version: 2.7.0
controlPlaneDeploymentOptions:
containerImage: kong/kubernetes-ingress-controller
version: 2.4.2

The above configuration will deploy all DataPlane resources connected to the GatewayConfiguration (by way of GatewayClass) using kong/kong:2.7.0 and any ControlPlane will be deployed with kong/kubernetes-ingress-controller:2.4.2.

Given the above, a manual upgrade or downgrade can be performed simply by changing the version. For example: assuming that at least one Gateway is currently deployed and running using the above GatewayConfiguration, an upgrade could be performed by running the following:

kubectl edit gatewayconfiguration kong

And updating the dataPlaneDeploymentOptions.version to 2.8.0. The result will be a replacement Pod will roll out with the new version and once healthy the old Pod will be terminated.

Usage with Kong Enterprise as data plane

You can use Kong Enterprise as the data plane by doing as follows:

  1. Create a secret with the Kong license in the namespace you intend to use for deploying the gateway.

    kubectl create secret generic kong-enterprise-license --from-file=license=<license-file> -n <your-namespace>
  2. Create a GatewayConfiguration specifying the enterprise container image and the environment variable referencing the license secret. The operator will use the image and the environment variable specified in the GatewayConfiguration to customize the dataplane. As the result, the dataplane will use kong/kong-gateway:2.8 as the image and mount the license secret.

    kind: GatewayConfiguration
    apiVersion: gateway-operator.konghq.com/v1alpha1
    metadata:
    name: kong
    namespace: <your-namespace>
    spec:
    dataPlaneDeploymentOptions:
    containerImage: kong/kong-gateway:2.8
    env:
    - name: KONG_LICENSE_DATA
    valueFrom:
    secretKeyRef:
    key: license
    name: kong-enterprise-license
  3. Create a GatewayClass that references the GatewayConfiguration above.

    kind: GatewayClass
    apiVersion: gateway.networking.k8s.io/v1beta1
    metadata:
    name: kong
    spec:
    controllerName: konghq.com/gateway-operator
    parametersRef:
    group: gateway-operator.konghq.com
    kind: GatewayConfiguration
    name: kong
    namespace: <your-namespace>
  4. And finally create a Gateway that uses the GatewayClass above:

    kind: Gateway
    apiVersion: gateway.networking.k8s.io/v1beta1
    metadata:
    name: kong
    namespace: <your-namespace>
    spec:
    gatewayClassName: kong
    listeners:
    - name: http
    protocol: HTTP
    port: 80
  5. Wait for the Gateway to be Ready:

    kubectl wait --for=condition=Ready=true gateways.gateway.networking.k8s.io/kong
  6. Check that the data plane is using the enterprise image:

    $ kubectl get deployment -l konghq.com/gateway-operator=dataplane -o jsonpath='{.items[0].spec.template.spec.containers[0].image}'

    kong/kong-gateway:2.8
  7. A log message should describe the status of the provided license.

    $ kubectl logs $(kubectl get po -l app=$(kubectl get dataplane -o=jsonpath='{.items[0].metadata.name}') -o=jsonpath="{.items[0].metadata.name}") | grep license_helpers.lua

    2022/08/29 10:50:55 [error] 2111#0: *8 [lua] license_helpers.lua:194: log_license_state(): The Kong Enterprise license will expire on 2022-09-20. Please contact <support@konghq.com> to renew your license., context: ngx.timer

Note: the license secret, the GatewayConfiguration, and the Gateway MUST be created in the same namespace.

Gateway API support status

The latest supported version of Gateway API is v1beta1 released in v0.5.0.

The following matrix summarizes support for the Gateway API resources:

CRD Name Supported Notes
v1beta1.GatewayClass yes
v1beta1.Gateway yes
v1beta1.HTTPRoute no Use Ingress from networking.k8s.io/v1 instead
v1alpha2.TLSRoute no
v1alpha2.TCPRoute no
v1alpha2.UDPRoute no