Workspaces

Workspaces are a way of namespacing Kong Gateway entities so they can be managed independently. Workspaces work in combination with RBAC to create isolated environments for teams to operate independently of each other. Workspaces can’t share entities, like Services, between them, and only Workspace Admins with the correct permissions, in the Workspace, can manage them.

Workspaces support multi-tenancy by isolating Kong Gateway configuration objects. When paired with RBAC, Kong Gateway administrators can effectively create tenants within the control plane. The Workspace administrators have segregated and secure access to only their portion of the Kong Gateway configuration in Kong Manager, the Admin API, and the declarative configuration tool decK.

 
flowchart LR
    subgraph Workspace1 [Workspace-1]
        A(Team A's - Service)
        B(Route)
    end 

    subgraph Workspace2 [Workspace-2]
        C(Team B's - Service)
        D(Route)

    end

    subgraph Workspace3 [Workspace-3]
        E(Team C's - Service)
        F(Route)
    end
    subgraph Gatewayorg [Gateway Organization]
    Workspace1
    Workspace2
    Workspace3
    end
 
  

How does Kong Gateway resolve entity conflicts between Workspaces?

Routing rules are configured at the Data Plane level. The Data Plane routes client traffic based on the configuration applied across all Workspaces. Configuring entities related to routing, such as Gateway Services and Routes, alter the client traffic routing behavior of the Data Plane, but Kong Gateway will always attempt to ensure that routing rules don’t contain conflicts.

To route traffic to the appropriate Workspace, Kong Gateway uses a conflict detection algorithm.

When a Service or Route is created or modified, the Kong Gateway Router checks for the existence of that object before allowing the operation to proceed in this order:

1. If the Service or Route created is unique across all Workspaces, the new entity is created.
2. If an existing Service or Route object in the current Workspace has the same routing rules as the one being created or modified, the operation proceeds.
3. If an equivalent Service or Route is found in a different Workspace, and the host is provided:
   1. If the host field matches in both Workspaces, a 409 Conflict error is returned.
   2. If the host field doesn’t match, the operation proceeds.
   3. If the host is an absolute value, a 409 Conflict error is returned.

Because Workspaces allow users to control Kong Gateway entities in isolation, users must have the correct permissions to configure a particular Workspace. Users will require either a Super Admin or Admin role to configure Workspaces.

The following table details which Workspace permissions each Admin role has:

For more information, see Roles and permissions.

The following decK flags must be used when interfacing with Workspaces using decK.

Manage multiple Workspaces

To manage all Workspaces at once, use the --all-workspaces flag with decK:

deck gateway dump --all-workspaces

This will dump your configuration into individual yaml files with the specific Workspace name including default.

You can set a Workspace specifically within a decK file like this:

_format_version: "3.0"
_workspace: default
services:
- name: example_service

Deploy Workspace-specific config

decK configurations must be deployed on a per-Workspace basis, individually. This is achieved using the --workspace flag:

deck gateway sync default.yaml --workspace default

Delete a Workspace configuration

decK can’t delete Workspaces. However, using deck gateway reset in combination with the --workspace or --all-workspaces flags forces decK to delete the entire configuration inside the Workspace, but not the Workspace itself.