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.

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 to clipboard!

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 to clipboard!

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 to clipboard!
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, click Gateway Manager in the sidebar.
   2. Click your Dedicated Cloud Gateway.
   3. Click 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 to clipboard!

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

   UI API

   1. In Konnect, click Gateway Manager in the sidebar.
   2. Click your Dedicated Cloud Gateway.
   3. Click 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 to clipboard!

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

Konnect configuration

1. Open Gateway Manager, choose a Control Plane to open the Overview dashboard, then click Connect.

   The Connect menu will open and display the URL for the Public Edge DNS. Save this URL.

2. Select Custom Domains from the side navigation, then New Custom Domain, and 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:

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 to clipboard!

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.

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

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