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!

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