Connect Kong Operator to Konnect over AWS PrivateLink

TL;DR

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

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 443 from your cluster nodes.

For the AWS steps, see AWS PrivateLink peering.

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'

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=true

If 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

  1. Wait for the KonnectGatewayControlPlane that Kong Operator created for the Gateway to be programmed:

    kubectl wait --for=condition=Programmed --all -n kong konnectgatewaycontrolplane --timeout=5m
  2. 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
  3. 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

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-private

FAQs

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.

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.

You can’t change the serverURL of an existing KonnectAPIAuthConfiguration. Create a new KonnectAPIAuthConfiguration with the private serverURL, and point your resources at it.

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.

No. The private Konnect hosts are under konghq.com, which is one of the default allowed Konnect domains.

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.

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 KonnectExtension for it with InvalidEndpoint.
  • AI Gateway data planes: Kong Operator holds the AIGatewayDataPlane with EndpointMismatch.
  • Kong Event Gateway data planes: Kong Event Gateway data planes can’t use a serverURL with a path, so Kong Operator holds the KegDataPlane with EndpointMismatch.

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!