Deploy data planes on a dual-stack cluster

This feature is currently in Tech Preview and should not be used in a production environment.
Deployment Platform
Related Documentation
Minimum Version
Kong Operator - 2.4
TL;DR

Install Kong Operator with the --ip-family=dual argument, then create a Gateway. Set ipFamilies and ipFamilyPolicy on the ingress Service in the GatewayConfiguration to control which IP families the ingress Service uses.

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 IPv4/IPv6 dual-stack networking configured, and kubectl configured to point at it.

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

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

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

    kind create cluster --name kong-dual-stack --config kind-dual-stack.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=dual argument. With this argument, Kong Operator can create ingress Services with both IPv4 and IPv6 addresses. 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=dual'
helm upgrade --install kong-operator kong/kong-operator -n kong-system \
  --create-namespace \
  --wait \
  --set image.tag=2.4 \
  --set 'args[0]=--ip-family=dual'

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: dual-stack
  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
          ipFamilies:
            - IPv4
            - IPv6
          ipFamilyPolicy: PreferDualStack
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: dual-stack
spec:
  controllerName: konghq.com/gateway-operator
  parametersRef:
    group: gateway-operator.konghq.com
    kind: GatewayConfiguration
    name: dual-stack
    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: dual-stack
  listeners:
    - name: http
      port: 80
      protocol: HTTP' | kubectl apply -f -
echo '
apiVersion: gateway-operator.konghq.com/v2beta1
kind: GatewayConfiguration
metadata:
  name: dual-stack
  namespace: kong
spec:
  dataPlaneOptions:
    deployment:
      podTemplateSpec:
        spec:
          containers:
            - image: kong/kong-gateway:3.16
              name: proxy
    network:
      services:
        ingress:
          type: ClusterIP
          ipFamilies:
            - IPv4
            - IPv6
          ipFamilyPolicy: PreferDualStack
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: dual-stack
spec:
  controllerName: konghq.com/gateway-operator
  parametersRef:
    group: gateway-operator.konghq.com
    kind: GatewayConfiguration
    name: dual-stack
    namespace: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
  namespace: kong
spec:
  gatewayClassName: dual-stack
  listeners:
    - name: http
      port: 80
      protocol: HTTP' | kubectl apply -f -

The GatewayConfiguration sets ipFamilies to IPv4 and IPv6 with the PreferDualStack policy, so the data plane’s ingress Service gets an IPv4 address and an IPv6 address, in that order. It also 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 dual-stack Service:

["IPv4","IPv6"]	PreferDualStack

Export the ingress Service’s IPv4 and IPv6 cluster IPs:

export PROXY_IPV4=$(kubectl get svc $INGRESS_SERVICE -n kong -o jsonpath='{.spec.clusterIPs[0]}')
export PROXY_IPV6=$(kubectl get svc $INGRESS_SERVICE -n kong -o jsonpath='{.spec.clusterIPs[1]}')

Send a request to the proxy over IPv4 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_IPV4"

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

{
  "message":"no Route matched with those values",
  "request_id":"b2c40d7291d8d0133a7b2f6c834d5464"
}
remote_ip: 10.96.249.178

The remote_ip value is a dotted decimal address, which means the request used IPv4.

Send a request to the proxy over IPv6:

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

The remote_ip value is a colon-separated hexadecimal address, which means the request used IPv6.

Kong Gateway returns a no Route matched error for both requests because the Gateway doesn’t have any Routes yet. These responses confirm that the data plane accepts connections over both IPv4 and IPv6.

FAQs

When --ip-family is set to dual and the GatewayConfiguration doesn’t set ipFamilies or ipFamilyPolicy, Kong Operator creates the ingress Service with the PreferDualStack policy. The data plane is exposed over both IPv4 and IPv6.

To expose a data plane over a single IP family on a dual-stack cluster, set ipFamilies on the ingress Service in the GatewayConfiguration to one family, for example [IPv6]. The ingress Service then stays single-stack.

The Kubernetes API server requires a dual-stack policy when a Service lists two IP families. When ipFamilies names both IPv4 and IPv6 and ipFamilyPolicy isn’t set, Kong Operator sets the ingress Service’s policy to PreferDualStack.

The cluster must support the IP families and policy set on the ingress Service. For example, setting ipFamilies: [IPv6] on a cluster without IPv6 networking fails.

Yes. The DataPlane resource accepts the same ipFamilies and ipFamilyPolicy fields under spec.network.services.ingress.

To expose a data plane outside the cluster over IPv4 and 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 over both IPv4 and IPv6 on EKS, 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

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!