helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.4 \
--set env.ENABLE_CONTROLLER_KONNECT=true
kubectl -n kong-system wait --for=condition=Available=true --timeout=300s deployment/kong-operator-kong-operator-controller-managerConnect Kong Operator to Konnect over AWS PrivateLink
Create a VPC endpoint for your Konnect geo with Private DNS enabled, then set the serverURL of your KonnectAPIAuthConfiguration to the private host with the /api path, for example https://us.svc.konghq.com/api. Kong Operator and the data planes it deploys then reach Konnect through the private endpoints.
Prerequisites
AWS PrivateLink VPC endpoint
Your Kubernetes cluster must run in an AWS VPC that has an interface VPC endpoint for your Konnect geo:
- Create the endpoint for the PrivateLink service of your geo and AWS region. Regional PrivateLink service names lists the service names and DNS names.
- Enable Private DNS on the endpoint, so that the geo’s private host, for example
us.svc.konghq.com, resolves to the endpoint inside the VPC. - Attach a security group that allows inbound TCP traffic on port
443from your cluster nodes.
For the AWS steps, see AWS PrivateLink peering.
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'
Kong Operator running
If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:
--set global.webhooks.options.certManager.enabled=trueIf you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates.
Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane.
This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the certificateAuthority section
in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.
By default, Kong Operator and the data planes it deploys reach Konnect through its public hosts. With AWS PrivateLink, they can reach Konnect through a VPC endpoint instead, without public internet egress.
The only setting that changes is the serverURL of the KonnectAPIAuthConfiguration. Kong Operator uses it to call the Konnect API, and Konnect returns private control plane and telemetry endpoints for the data planes to connect to.
Export the private server URL
Export the private Konnect API URL for your geo.
The URL is the private host of your geo, followed by the /api path.
This example uses the US geo. For another geo, replace us with your geo:
export KONNECT_PRIVATE_SERVER_URL='https://us.svc.konghq.com/api'Create the KonnectAPIAuthConfiguration
Create the kong namespace and a KonnectAPIAuthConfiguration that uses the private server URL:
kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
name: konnect-api-auth-private
namespace: kong
spec:
type: token
token: '"$KONNECT_TOKEN"'
serverURL: '"$KONNECT_PRIVATE_SERVER_URL"'
' | kubectl apply -f -Check that the authentication is valid and that the organization was resolved:
kubectl get konnectapiauthconfiguration konnect-api-auth-private -n kong \
-o jsonpath='{.status.conditions[?(@.type=="APIAuthValid")].status} {.status.organizationID}{"\n"}'The command prints True followed by your organization ID.
Create the Gateway
Create a GatewayConfiguration that references the KonnectAPIAuthConfiguration, then a GatewayClass and a Gateway. The rest of the configuration is the same as for a deployment over the public hosts:
echo '
kind: GatewayConfiguration
apiVersion: gateway-operator.konghq.com/v2beta1
metadata:
name: gateway-configuration
namespace: kong
spec:
konnect:
authRef:
name: konnect-api-auth-private
dataPlaneOptions:
deployment:
podTemplateSpec:
spec:
containers:
- name: proxy
image: kong/kong-gateway:3.16
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: gateway-class
spec:
controllerName: konghq.com/gateway-operator
parametersRef:
group: gateway-operator.konghq.com
kind: GatewayConfiguration
name: gateway-configuration
namespace: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: kong
namespace: kong
spec:
gatewayClassName: gateway-class
listeners:
- name: http
port: 80
protocol: HTTP
' | kubectl apply -f -Validate
-
Wait for the
KonnectGatewayControlPlanethat Kong Operator created for theGatewayto be programmed:kubectl wait --for=condition=Programmed --all -n kong konnectgatewaycontrolplane --timeout=5m -
Check that Konnect returned private endpoints for the control plane:
kubectl get konnectgatewaycontrolplane -n kong \ -o jsonpath='{range .items[*]}{.status.konnectEndpoints.controlPlane}{"\n"}{.status.konnectEndpoints.telemetry}{"\n"}{end}'Both endpoints use the private host, for example:
https://us.svc.konghq.com/cp/PREFIX https://us.svc.konghq.com/tp/PREFIX -
Check that the data plane is configured with the private endpoints:
kubectl get deployment -n kong -o yaml \ | grep -A1 -E 'KONG_CLUSTER_(CONTROL_PLANE|SERVER_NAME|TELEMETRY_ENDPOINT)$'The values use the private host, for example:
- name: KONG_CLUSTER_CONTROL_PLANE value: us.svc.konghq.com/cp/PREFIX - name: KONG_CLUSTER_SERVER_NAME value: us.svc.konghq.com - name: KONG_CLUSTER_TELEMETRY_ENDPOINT value: us.svc.konghq.com:443/tp/PREFIX
Cleanup
Delete the resources created in this guide
Deleting the Gateway also deletes the KonnectGatewayControlPlane that Kong Operator
created for it, which removes the control plane from Konnect:
kubectl delete -n kong --ignore-not-found gateway/kong gatewayconfiguration/gateway-configuration
kubectl delete -n kong --ignore-not-found konnectgatewaycontrolplane --all
kubectl delete --ignore-not-found gatewayclass/gateway-class
kubectl delete -n kong --ignore-not-found konnectapiauthconfiguration/konnect-api-auth-privateFAQs
Do I need to distribute a CA certificate to connect Kong Operator to Konnect over AWS PrivateLink?
No. The private Konnect host serves the same publicly trusted certificate as the public host, and Kong Operator configures data planes to trust the system certificate bundle.
Which serverURL do I set for the global Konnect API over AWS PrivateLink?
You don’t set it.
You always set the regional form in the KonnectAPIAuthConfiguration, for example https://us.svc.konghq.com/api instead of the public https://us.api.konghq.com.
Kong Operator derives the global form, for example https://global.svc.konghq.com/api, from it.
Kong Operator uses the global API for Dedicated Cloud Gateways.
How do I move an existing Kong Operator installation from the public Konnect hosts to AWS PrivateLink?
You can’t change the serverURL of an existing KonnectAPIAuthConfiguration.
Create a new KonnectAPIAuthConfiguration with the private serverURL, and point your resources at it.
Which egress rules do Kong Operator and its data planes need with AWS PrivateLink?
With AWS PrivateLink, Kong Operator and the data planes only need outbound HTTPS (TCP port 443) to the VPC endpoint.
They don’t need any rule for the public Konnect hosts.
If a Kubernetes NetworkPolicy restricts egress from the Kong Operator or data plane namespaces, allow TCP port 443 to the IP addresses of the VPC endpoint.
Do I need to change the --konnect-server-url-domains flag to use AWS PrivateLink?
No. The private Konnect hosts are under konghq.com, which is one of the default allowed Konnect domains.
What does Kong Operator do when a component would connect to Konnect over the public internet?
When a KonnectAPIAuthConfiguration uses a private serverURL, Kong Operator doesn’t start a component with a configuration that would send its traffic over the public internet.
Instead, it holds the component and reports a condition that explains why.
A held data plane keeps serving traffic, but Kong Operator doesn’t apply spec, image, or certificate changes to it until the condition clears.
For example, a KonnectExtension reports EndpointMismatch when Konnect doesn’t return private endpoints for your geo yet.
The condition clears on its own once Konnect returns them, and you don’t need to change anything in your cluster.
For the full list of conditions, see Status in Konnect.
Which Kong Operator components can’t connect to Konnect over AWS PrivateLink?
The following components can’t connect over AWS PrivateLink yet:
- Kong Ingress Controller in Konnect: There’s no private route for its API, so Kong Operator holds a
KonnectExtensionfor it withInvalidEndpoint. - AI Gateway data planes: Kong Operator holds the
AIGatewayDataPlanewithEndpointMismatch. - Kong Event Gateway data planes: Kong Event Gateway data planes can’t use a
serverURLwith a path, so Kong Operator holds theKegDataPlanewithEndpointMismatch.