Deploy data planes on an IPv6-only cluster

Deployment Platform
Related Documentation
Minimum Version
Kong Operator - 2.4
TL;DR

Install Kong Operator with the --ip-family=ipv6 argument, then create a Gateway. The data plane’s listeners bind to IPv6, and its ingress Service is a single-stack IPv6 Service.

Prerequisites

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

  1. The following Konnect items are required to complete this tutorial:
    • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

You will need Helm, a package manager for Kubernetes.

This guide requires a Kubernetes cluster with IPv6 networking configured, and kubectl configured to point at it. On AWS EKS, the VPC and subnets must have an IPv6 CIDR block.

The cluster’s Pods must also be able to reach IPv4 addresses. The Konnect API and control plane endpoints only have IPv4 addresses, so Kong Operator and the data plane can’t connect to Konnect from a cluster without IPv4 egress. For example, an Amazon EKS cluster with the IPv6 IP family provides IPv4 egress, but a local IPv6-only kind cluster doesn’t.

If you don’t have one, create a local IPv6-only cluster with kind:

  1. Create a kind configuration file that sets the cluster’s IP family to ipv6:

    cat <<EOF > kind-ipv6.yaml
    kind: Cluster
    apiVersion: kind.x-k8s.io/v1alpha4
    networking:
      ipFamily: ipv6
    EOF
  2. Create the cluster from the configuration file:

    kind create cluster --name kong-ipv6 --config kind-ipv6.yaml

    kind sets the current kubectl context to the new cluster.

Create the kong namespace

Create the kong namespace in your Kubernetes cluster, which is where the demo will run:

kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -

Install Kong Operator

Add the Kong Helm charts and update them:

helm repo add kong https://charts.konghq.com
helm repo update

Install Kong Operator with the --ip-family=ipv6 argument. With this argument, Kong Operator binds the data plane’s listeners to IPv6 and creates IPv6 ingress Services. Helm passes the argument to Kong Operator through the chart’s args value:

helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --wait \
  --set image.tag=2.4 \
  --set env.ENABLE_CONTROLLER_KONNECT=true \
  --set 'args[0]=--ip-family=ipv6'
helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --wait \
  --set image.tag=2.4 \
  --set 'args[0]=--ip-family=ipv6'

Apply your Kong Gateway Enterprise license as a KongLicense resource:

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongLicense
metadata:
  name: kong-license
rawLicenseString: '$(cat ./license.json)'
" | kubectl apply -f -

This assumes that your license is available in ./license.json.

Create a KonnectAPIAuthConfiguration resource that stores your Konnect personal access token:

echo "
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: konnect-api-auth
  namespace: kong
spec:
  type: token
  token: '$KONNECT_TOKEN'
  serverURL: us.api.konghq.com
" | kubectl apply -f -

Create a Gateway

Create a GatewayConfiguration, a GatewayClass, and a Gateway:

echo '
apiVersion: gateway-operator.konghq.com/v2beta1
kind: GatewayConfiguration
metadata:
  name: ipv6
  namespace: kong
spec:
  konnect:
    authRef:
      name: konnect-api-auth
  dataPlaneOptions:
    deployment:
      podTemplateSpec:
        spec:
          containers:
            - image: kong/kong-gateway:3.16
              name: proxy
    network:
      services:
        ingress:
          type: ClusterIP
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: ipv6
spec:
  controllerName: konghq.com/gateway-operator
  parametersRef:
    group: gateway-operator.konghq.com
    kind: GatewayConfiguration
    name: ipv6
    namespace: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
  namespace: kong
  annotations:
    gateway-operator.konghq.com/static-naming: "true"
spec:
  gatewayClassName: ipv6
  listeners:
    - name: http
      port: 80
      protocol: HTTP' | kubectl apply -f -
echo '
apiVersion: gateway-operator.konghq.com/v2beta1
kind: GatewayConfiguration
metadata:
  name: ipv6
  namespace: kong
spec:
  dataPlaneOptions:
    deployment:
      podTemplateSpec:
        spec:
          containers:
            - image: kong/kong-gateway:3.16
              name: proxy
    network:
      services:
        ingress:
          type: ClusterIP
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: ipv6
spec:
  controllerName: konghq.com/gateway-operator
  parametersRef:
    group: gateway-operator.konghq.com
    kind: GatewayConfiguration
    name: ipv6
    namespace: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
  namespace: kong
spec:
  gatewayClassName: ipv6
  listeners:
    - name: http
      port: 80
      protocol: HTTP' | kubectl apply -f -

Because the IP family is set to ipv6, Kong Operator binds the data plane’s listeners to IPv6 and creates a single-stack IPv6 ingress Service without any IP family settings in the GatewayConfiguration. The GatewayConfiguration sets the ingress Service type to ClusterIP, so the Gateway is programmed without waiting for a load balancer address

Wait for the Gateway to be programmed:

kubectl wait --for=condition=programmed gateway/kong -n kong --timeout=300s

Validate

Export the name of the data plane’s ingress Service:

export INGRESS_SERVICE=$(kubectl get svc -n kong \
  -l gateway-operator.konghq.com/dataplane-service-type=ingress \
  -o jsonpath='{.items[0].metadata.name}')

Check the IP families of the ingress Service:

kubectl get svc $INGRESS_SERVICE -n kong \
  -o jsonpath='{.spec.ipFamilies}{"\t"}{.spec.ipFamilyPolicy}{"\n"}'

The ingress Service is a single-stack IPv6 Service:

["IPv6"]	SingleStack

Export the ingress Service’s IPv6 cluster IP:

export PROXY_IPV6=$(kubectl get svc $INGRESS_SERVICE -n kong -o jsonpath='{.spec.clusterIP}')

Send a request to the proxy over IPv6 from a temporary Pod in the cluster:

kubectl run curl -n kong --rm -it --restart=Never --image=curlimages/curl -- \
  curl -s -w '\nremote_ip: %{remote_ip}\n' "http://[$PROXY_IPV6]"

The output includes the response from Kong Gateway and the address that curl connected to:

{
  "message":"no Route matched with those values",
  "request_id":"780b0503694882228829e12c85c46462"
}
remote_ip: fd00:10:96::64bb

Kong Gateway returns a no Route matched error because the Gateway doesn’t have any Routes yet. The remote_ip value is a colon-separated hexadecimal address, which means the request used IPv6. This response confirms that the data plane accepts connections over IPv6.

FAQs

By default, the --ip-family argument is set to auto. With auto, Kong Operator reads the IP family of the default/kubernetes Service at startup. If detection fails, Kong Operator exits with an error. Setting --ip-family=ipv6 skips detection, so Kong Operator starts even when the default/kubernetes Service can’t be read.

Kong Operator binds the data plane’s Kong proxy, admin, status, and stream listeners to the IP family set by --ip-family. On an IPv6-only cluster, all of these listeners bind to IPv6 addresses.

To expose a data plane outside the cluster over IPv6, set the ingress Service type in the GatewayConfiguration to LoadBalancer:

spec:
  dataPlaneOptions:
    network:
      services:
        ingress:
          type: LoadBalancer

The Gateway is programmed only after the cluster assigns an external address to the load balancer. Local clusters such as kind don’t assign load balancer addresses by default.

On AWS EKS, the in-tree cloud provider only provisions IPv4-only Network Load Balancers. To expose a data plane externally on an IPv6-only EKS cluster, install the AWS Load Balancer Controller. Then, set the ingress Service type to LoadBalancer and add the following annotations to the ingress Service in your GatewayConfiguration so the AWS Load Balancer Controller provisions a dual-stack Network Load Balancer:

spec:
  dataPlaneOptions:
    network:
      services:
        ingress:
          type: LoadBalancer
          annotations:
            service.beta.kubernetes.io/aws-load-balancer-type: external
            service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
            service.beta.kubernetes.io/aws-load-balancer-ip-address-type: dualstack
            service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip

Yes. Kong Operator supports dual-stack clusters as a tech preview. See Deploy data planes on a dual-stack cluster.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!