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'Deploy data planes on a dual-stack cluster
This feature is currently in Tech Preview and should not be used in a production environment.
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
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'
Dual-stack Kubernetes cluster
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:
-
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 -
Create the cluster from the configuration file:
kind create cluster --name kong-dual-stack --config kind-dual-stack.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=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 '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=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 dual-stack Service:
["IPv4","IPv6"] PreferDualStackExport 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.178The 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::64bbThe 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
What IP family policy does the ingress Service use when ipFamilies and ipFamilyPolicy aren’t set on a dual-stack cluster?
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.
How do I expose a data plane over a single IP family on a dual-stack cluster?
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.
Why does the ingress Service use PreferDualStack when ipFamilies lists both families?
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.
What happens if the cluster doesn’t support the requested IP families?
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.
Can I set ipFamilies and ipFamilyPolicy on a DataPlane resource?
Yes. The DataPlane resource accepts the same ipFamilies and ipFamilyPolicy fields under spec.network.services.ingress.
How do I expose a data plane outside the cluster over IPv4 and IPv6?
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: 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 IPv4 and 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 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