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.
Deploy data planes on an IPv6-only cluster
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
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- 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.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
IPv6-only Kubernetes cluster
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.
If you don’t have one, create a local IPv6-only cluster with kind:
-
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 -
Create the cluster from the configuration file:
kind create cluster --name kong-ipv6 --config kind-ipv6.yamlkind sets the current
kubectlcontext 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 updateInstall 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=300sValidate
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"] SingleStackExport 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::64bbKong 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
How does Kong Operator detect the cluster’s IP family?
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.
Which data plane listeners use Kong Operator’s IP family?
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.
How do I expose a data plane outside the cluster over IPv6?
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: LoadBalancerThe 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.
How do I expose a data plane over IPv6 on AWS EKS?
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: ipCan I run data planes on a dual-stack cluster?
Yes. Kong Operator supports dual-stack clusters as a tech preview. See Deploy data planes on a dual-stack cluster.