Home / How-to Guides
Edit
Report

Manage Workspaces in Konnect

Uses: Kong Gateway deck Konnect API
Incompatible with
on-prem
Related Documentation
Gateway Documentation
Tags
#rbac
Related Resources
Workspace entity reference
TL;DR

Create a Workspace by sending a POST request to the /control-planes/$CONTROL_PLANE_ID/core-entities/workspaces endpoint. You can manage Workspace entities by sending a POST request to the entities endpoint, for example: /control-planes/$CONTROL_PLANE_ID/core-entities/$WORKSPACE/services.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

    export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN \
     --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

    export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
export DECK_KONNECT_ADDR=https://us.api.konghq.com
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

decK   v1.69.0+

To complete this tutorial, install decK. We recommend keeping decK up to date with the latest version (1.69.0).

decK is a CLI tool for managing Kong Gateway declaratively with state files. This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance.

You can check your current decK version with deck version.

Konnect roles

To use this tutorial, you need one of the following Konnect roles:

  • Admin on the control plane, or Workspace Creator, to create a Workspace
  • Workspace Admin on the Workspace you want to manage

Create a Workspace

A Workspace is a namespace for Gateway entities inside a Konnect control plane. Entities in one Workspace are invisible to and independent of entities in another. Data planes attach to the parent control plane and serve traffic across all of its Workspaces.

Every control plane has a default Workspace. Any entities created before additional Workspaces are added live there, as well as any CA certificates. For example, a plugin in the default Workspace applies only to entities in the default Workspace, not across all Workspaces. Entity names can repeat across Workspaces: two Workspaces can each have a Consumer named alice, with different credentials on each.

  1. Look up the ID of the control plane you want to add Workspaces to, by name, and capture it as $CONTROL_PLANE_ID:

    curl -X GET "https://us.api.konghq.com/v2/control-planes" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"
    export CONTROL_PLANE_ID='YOUR CONTROL PLANE ID'

  2. List existing Workspaces on the control plane:

    curl -X GET "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/workspaces" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

  3. Create a new Workspace:

    curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/workspaces" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "team-payments"
     }'

    You can reference a Workspace by name or by ID in any subsequent API path.

Manage entities in a Workspace

  1. Export the Workspace name:

    export WORKSPACE='team-payments'

  2. Create a Gateway Service in the Workspace, and capture its ID as $SERVICE_ID:

    SERVICE_ID=$(curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/$WORKSPACE/services" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "payment-api",
       "url": "http://payment-service.internal:8080"
     }' | jq -r ".id"
)

  3. Create a Route in the Workspace, referencing the Service:

    curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/$WORKSPACE/routes" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "payment-route",
       "paths": [
         "/payments"
       ],
       "service": {
         "id": "'$SERVICE_ID'"
       }
     }'

Entities in the default Workspace use the existing un-prefixed path, for example .../core-entities/services.

Custom plugins

Install custom plugin schemas at the control plane level, in the default Workspace. Once installed, you can create plugin instances of that custom plugin in any Workspace on the control plane, the same way you would with a bundled plugin.

  1. Upload a custom plugin schema at the control plane level, by sending a POST request to the /custom-plugins endpoint:

    curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/custom-plugins" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "set-header",
       "handler": "return { VERSION = \"1.0.0\", PRIORITY = 500, access = function(self, config) kong.service.request.set_header(config.name, config.value) end }",
       "schema": "return { name = \"set-header\", fields = { { config = { type = \"record\", fields = { { name = { type = \"string\", required = true } }, { value = { type = \"string\", required = true } } } } } } }"
     }'

  2. Create an instance of the plugin in the Workspace, by sending a POST request to the /plugins endpoint:

    curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/$WORKSPACE/plugins" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "set-header",
       "config": {
         "name": "X-Team",
         "value": "payments"
       }
     }'

You can’t install schemas in a non-default Workspace.

Use decK

To use decK with Konnect Workspaces, you need decK 1.69 or later.

Set your decK environment variables: You must set decK environment variables with your Konnect access token and address for the following decK commands to work. For example:

export DECK_KONNECT_TOKEN="kpat_..."
export DECK_KONNECT_ADDR="https://us.api.konghq.com"

If you created a control plane in the prerequisites, your environment variables should already be set.

  1. Dump one Workspace:

    deck gateway dump --konnect-control-plane-name quickstart --workspace team-payments -o team-payments.yaml

  2. Dump every Workspace into separate files:

    deck gateway dump --konnect-control-plane-name quickstart --all-workspaces

  3. Apply a config file into a Workspace:

    deck gateway sync team-payments.yaml --konnect-control-plane-name quickstart --workspace team-payments

A dumped file carries a _workspace: header, so deck gateway sync will target the right Workspace even without the --workspace flag.

Konnect Workspace limitations
  • Supported control planes: Workspaces are supported on hybrid and Dedicated Cloud control planes. They aren’t supported on serverless control planes, Kong Ingress Controller control planes, or control planes that belong to a control plane group. A control plane can’t be both Workspace-enabled and a member of a control plane group.
  • AI Gateway 2.x: AI Gateway 2.x doesn’t support Workspaces. AI plugins, such as AI Proxy and AI Proxy Advanced, work inside a Workspace when running on a standard Kong Gateway control plane.
  • Workspace analytics: Konnect doesn’t report analytics per Workspace. Analytics for a control plane include traffic from every Workspace in it.
  • Route collisions: Collision detection always uses an exact match on path, method, host, and SNI. The configurable “smart” collision strategies available for Kong Gateway aren’t available for Workspaces.
  • Shared entities: A plugin or Consumer configured in one Workspace applies only to that Workspace. Konnect doesn’t support sharing a plugin or Consumer configuration across Workspaces.

Route collisions

When you create or modify a Route, Konnect checks it against Routes in every Workspace on the control plane, including the default one. If it overlaps with an existing Route on path, method, host, and SNI, the request is rejected with a 409 naming the collision. This catches the cross-team conflicts that can come up when several teams share a data plane.

This is deliberately simpler than the on-prem behavior. On-prem Kong Gateway defaults to a configurable “smart” strategy that also reasons about path patterns and regexes. Configurable strategies for Konnect Workspaces are planned for a later phase. In practice, the deterministic check covers the same conflicts for plain-text Routes. If you rely on regex-Route collision detection on-prem, reach out to your account team.

Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

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!
Contribute

Still need help?

Ask in our Slack Community
Contact Support