Dedicated Cloud Gateways reference

Dedicated Cloud Gateways domain breaking changes: Review domain breaking changes for Dedicated Cloud Gateways and migrate to the new domain before September 30, 2025.

When you create a Dedicated Cloud Gateway, Konnect creates a Control Plane. This Control Plane, like other Konnect Control Planes, is hosted by Konnect. You can then deploy Data Planes in different regions.

Dedicated Cloud Gateways support two different configuration modes:

• Autopilot Mode: Configure expected requests per second, and Konnect pre-warms and autoscales the Data Plane nodes automatically.
• Custom Mode: Manually specify the instance size, type, and number of nodes per cluster.

 
flowchart TD
A(Dedicated Cloud Gateway Control Plane)
B(Managed Data Plane Node 
 Region 1)
C(Managed Data Plane Node 
 Region 2)

subgraph id1 [Konnect]
A
end

A --auto-scale configuration---> B
A --auto-scale configuration---> C


  

1. Create a Dedicated Cloud Gateway Control Plane using by issuing a POST request to the Control Plane API:

    curl -X POST "$KONNECT_CONTROL_PLANE_URL/v2/control-planes/" \
        -H "Accept: application/json"\
        -H "Content-Type: application/json"\
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "cloud-gateway-control-plane",
          "description": "A test Control Plane for Dedicated Cloud Gateways.",
          "cluster_type": "CLUSTER_TYPE_CONTROL_PLANE",
          "cloud_gateway": true,
          "proxy_urls": [
            {
              "host": "example.com"
            },
            {
              "port": 443
            },
            {
              "protocol": "https"
            }
          ]
        }'
   

   Copied!

2. Create a Dedicated Cloud Gateway Data Plane by issuing a PUT request to the Cloud Gateways API:

    curl -X PUT "$KONNECT_CONTROL_PLANE_URL/v2/cloud-gateways/configurations" \
        -H "Accept: application/json"\
        -H "Content-Type: application/json"\
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "control_plane_id": "'$CONTROL_PLANE_ID'",
          "version": 3.9,
          "control_plane_geo": "ap-northeast-1",
          "dataplane_groups": [
            {
              "provider": "aws"
            },
            {
              "region": "na"
            },
            {
              "cloud_gateway_network_id": "'$CLOUD_GATEWAY_NETWORK_ID'"
            },
            {
              "autoscale": [
                {
                  "kind": "autopilot"
                },
                {
                  "base_rps": 100
                }
              ]
            }
          ]
        }'
   

   Copied!

Dedicated Cloud Gateways support AWS workload identities for data plane instances, enabling secure integration with your own AWS-managed services using IAM AssumeRole. This allows native and custom Kong plugins running in the data plane to access AWS services (like S3, Secrets Manager, Lambda, and DynamoDB) without static credentials, improving both security and operational simplicity.

Using AWS workload identities with Dedicated Cloud Gateways provides the following benefits:

• Credential-less integration: No need to manage or rotate static AWS credentials.
• Security-first: Workload identity is scoped to assume specific roles defined by you.
• Compatibility: Native and custom Kong plugins can seamlessly use AssumeRole credentials.

This is currently only available for AWS.

How AWS workload identities works

1. When an AWS Dedicated Cloud Gateway is provisioned, Konnect automatically creates the following:
   • An IAM Role in your dedicated tenant AWS account named after the network UUID. You can derive this IAM Role ARN.
   • A trust policy that enables AssumeRoleWithWebIdentity for the EKS service account used by the Kong Gateway data planes. For example:

     {
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::*:root"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringLike": {
            "aws:PrincipalArn": "arn:aws:iam::*:role/*"
          }
        }
      }]
      }
     

     Copied!
2. You define a trust relationship in your AWS account, allowing the Dedicated Cloud Gateway IAM role to assume a target role in your account.
3. The workload identity annotation on Konnect’s service account is used to connect to this IAM role.

Keep the following security considerations in mind:

• The IAM role created by Konnect is assume-only and has no permissions to manage infrastructure or cloud resources.
• You control which of your IAM roles Konnect is allowed to assume by configuring trust relationships.

Derive the Konnect IAM Role ARN

You can compute the ARN for Konnect’s IAM role using this pattern:

arn:aws:iam::$KONNECT_AWS_ACCOUNT_ID:role/$NETWORK_ID

1. To get the AWS account ID, do the following:

   UI API

   1. In Konnect, navigate to API Gateway in the sidebar.
   2. Click your Dedicated Cloud Gateway.
   3. Navigate to Networks in the sidebar.
   4. Configure private networking and click Transit Gateway.
   5. Copy the AWS account ID.

   Send a GET request to the /cloud-gateways/provider-accounts endpoint:

    curl -X GET "https://global.api.konghq.com/v2/cloud-gateways/provider-accounts" \
        -H "Authorization: Bearer $KONNECT_TOKEN"
   

   Copied!

2. To fetch the UUID of the Network, do the following:

   UI API

   1. In Konnect, navigate to API Gateway in the sidebar.
   2. Click your Dedicated Cloud Gateway.
   3. Navigate to Data Plane Nodes in the sidebar.
   4. Copy the network ID from the data plane group table.

   Send a GET request to the /cloud-gateways/networks endpoint:

    curl -X GET "https://global.api.konghq.com/v2/cloud-gateways/networks" \
        -H "Authorization: Bearer $KONNECT_TOKEN"
   

   Copied!

Konnect integrates domain name management and configuration with Dedicated Cloud Gateways.

Konnect configuration

1. In Konnect, navigate to API Gateway in the sidebar.
2. Click your control plane
3. Click Connect.
4. From the Connect menu, save the Public Edge DNS URL.
5. Navigate to Custom Domains in the sidebar.
6. Click New Custom Domain.

7. Enter your domain name.

   Save the value that appears under CNAME.

Dedicated Cloud Gateways domain registrar configuration

The following settings must be configured in your domain registrar using the values in Konnect. For example, in AWS Route 53, it would look like this:

The Kong Gateway configuration for your data plane nodes can be customized using environment variables.

The following table lists the environment variables that you can set while creating a Dedicated Cloud Gateway.

local template = require "resty.template"
local split = require "kong.tools.string".split

untrusted_lua_sandbox_requires = resty.template, kong.tools.utils

How do I set environment variables?

In the Konnect UI, you can add environment variables to a Dedicated Cloud Gateway when you create the data plane node. Navigate to your Dedicated Cloud Gateway control plane and from the Actions dropdown menu, select “Edit or Resize Cluster”. Click Advanced options and enter the environment variable key and value pairs you want to use.

You can add environment variables using the Cloud Gateways API. When you create a Dedicated Cloud Gateway Data Plane with a PUT request to the /cloud-gateways/configurations endpoint, add the environment array containing the name and value of each variable:

 curl -X PUT "https://global.api.konghq.com/v2/cloud-gateways/configurations" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "control_plane_id": "'$CONTROL_PLANE_ID'",
       "version": "3.11",
       "control_plane_geo": "us",
       "dataplane_groups": [
         {
           "provider": "aws",
           "region": "us-east-2",
           "cloud_gateway_network_id": "'$CLOUD_GATEWAY_NETWORK_ID'",
           "autoscale": {
             "kind": "autopilot",
             "base_rps": 100
           },
           "environment": [
             {
               "name": "KONG_TRACING_SAMPLING_RATE",
               "value": "0.01"
             }
           ]
         }
       ]
     }'

Dedicated Cloud Gateways only support public networking. If your use case requires private connectivity, consider using Dedicated Cloud Gateways with AWS Transit Gateways.

To securely connect a Dedicated Cloud Gateway to your backend, you can inject a shared secret into each request using the Request Transformer plugin.

1. Ensure the backend accepts a known token like an Authorization header.

2. Attach the Request Transformer plugin to the Control Plane and Gateway Service that you want to secure:

    curl -X POST "$KONNECT_CONTROL_PLANE_URL/v2/control-planes/$CONTROL_PLANE_ID/core-entities/services/$SERVICE_ID/plugins" \
        -H "accept: application/json"\
        -H "Content-Type: application/json"\
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "request-transformer",
          "config": {
            "add": {
              "headers": [
                "Authorization:Bearer '$SECRET_TOKEN_VALUE'"
              ]
            }
          }
        }'
   

   Copied!

AWS Transit Gateway

If you are using Dedicated Cloud Gateways and your upstream services are hosted in AWS, AWS Transit Gateway is the preferred method for most users. For more information and a guide on how to attach your Dedicated Cloud Gateway, see the Transit Gateways documentation.

Azure VNet Peering

If you are using Dedicated Cloud Gateways and your upstream services are hosted in Azure, VNet Peering is the preferred method for most users. For more information and a guide on how to attach your Dedicated Cloud Gateway, see the Azure Peering documentation.

GCP VPC Peering

If you are using Dedicated Cloud Gateways and your upstream services are hosted in GCP, VPC Network Peering is the preferred method for most users. For more information and a guide on how to attach your Dedicated Cloud Gateway, see the GCP VPC Peering documentation.

With Dedicated Cloud Gateways, Konnect can stream custom plugins from the Control Plane to the Data Plane. This means that the Control Plane becomes a single source of truth for plugin versions. You only need to upload a plugin once, to the Control Plane, and Konnect handles distributing the plugin code to all Data Planes in that Control Plane.

How does custom plugin streaming work?

With Dedicated Cloud Gateways, Konnect can stream custom plugins from the Control Plane to the Data Plane. The Control Plane becomes the single source of truth for plugin versions. You only need to upload the plugin once, and Konnect handles distribution to all Data Planes in the same Control Plane.

A custom plugin must meet the following requirements:

• Unique name per plugin
• One handler.lua and one schema.lua file
• Cannot run in the init_worker phase or create timers
• Must be written in Lua
• A personal or system access token for the Konnect API

Custom plugin limitations

Keep the following custom plugin limitations in mind when adding them to Dedicated Cloud Gateways:

• Only schema.lua and handler.lua files are supported. Plugin logic must be self-contained in these two files. You can’t use DAOs, custom APIs, migrations, or multiple Lua modules.
• Custom modules cannot be required when plugin sandboxing is enabled. Eternal Lua files or shared libraries can’t be loaded.
• Custom validation must be implemented in handler.lua, not schema.lua. In handler.lua, it can be logged and handled as part of plugin business logic.
• Plugin files are limited to 100 KB per upload.
• Plugins cannot read/write to the Kong Gateway filesystem.
• The LuaJIT version is fixed per Kong Gateway version. Any future major Lua/LuaJIT upgrade will be communicated in advance due to potential breaking changes.

How do I add a custom plugin?

Plugins can be uploaded to Konnect using the Konnect UI. You can also use jq with the following request template to add the plugin using the API:

curl -X POST $KONNECT_CONTROL_PLANE_URL/v2/control-planes/$CONTROL_PLANE_ID/core-entities/custom-plugins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KONNECT_TOKEN" \
  -d "$(jq -n \
      --arg handler "$(cat handler.lua)" \
      --arg schema "$(cat schema.lua)" \
      '{"handler":$handler,"name":"streaming-headers","schema":$schema}')" \
    | jq

Once uploaded, you can manage custom plugins using any of the following methods:

• decK
• Control Plane Config API
• Konnect UI