You are browsing documentation for an outdated version.
See the latest documentation here.
Workspaces provide a way to segment Kong entities—entities in a workspace
are isolated from those in other workspaces. That said, entities
such as Services and Routes have “routing rules”, which are pieces of info
attached to Services or Routes—such as HTTP method, URI, or host—that allow a
given proxy-side request to be routed to its corresponding upstream service.
Admins configuring Services (or Routes) in their workspaces do not want traffic
directed to their Services or Routes to be swallowed by Services or Routes in other
workspaces; Kong allows them to prevent such undesired behavior—as long as
certain measures are taken. Below we outline the conflict detection algorithm
used by Kong to determine if a conflict occurs.
- At Service or Route creation or modification time, Kong runs its internal
- If no Services or Routes are found with matching routing rules, the creation
or modification proceeds
- If Services or Routes with matching routing rules are found within the same
- If Services or Routes are found in a different workspace:
- If the matching Service or Route does not have an associated
- If the matching Service or Route’s
host is a wildcard
- If they are the same, a conflict is reported—
- If they are not equal, proceed
- If the matching Service or Route’s
host is an absolute value, a
conflict is reported—
The default workspace
Kong starts with a default workspace named
default. This workspace
groups all existing entities in Kong:
- Entities that were created in operation in previous versions & in case
one is migrating from an older Kong version;
- Entities that Kong creates at migration time—e.g., RBAC credentials, which
are provisioned at migration time as a convenience
It will also hold entities that are created without being explicitly assigned to
a specific workspace.
That said, it’s worth noting that the default workspace is a workspace as any
other, the only difference being that it’s created by Kong, at migration time.
Using the API in workspaces
Any requests that don’t specify a workspace target the
To target a different workspace, prefix any endpoint with the workspace name or ID:
For example, if you don’t specify a workspace,
this request retrieves a list of services from the
curl -i -X GET http://localhost:8001/services
While this request retrieves all services from the workspace
curl -i -X GET http://localhost:8001/SRE/services
Listing workspaces and its entities
In a fresh Kong Gateway install, submit the
http GET :8001/workspaces
Creating a workspace
A more interesting example would be segmenting entities by teams; for the sake of
example, let’s say they are teamA, teamB, and teamC.
Each of these teams has its own set of entities—say, upstream services and
routes—and want to segregate their configurations and traffic; they can
achieve that with workspaces.
http POST :8001/workspaces name=teamA
http POST :8001/workspaces name=teamB
http POST :8001/workspaces name=teamC
At this point, if we list workspaces, we will get a total of 4—remember,
Kong provisions a “default” workspace and, on top of that, we created other
Entities in different workspaces can have the same name!
Different teams—belonging to different workspaces—are allowed to give any
name to their entities. To provide an example of that, let’s say that Teams A, B,
and C want a particular consumer named
guest—a different consumer for each
team, sharing the same username.
http :8001/teamA/consumers username=guest
http :8001/teamB/consumers username=guest
http :8001/teamC/consumers username=guest
With this, Teams A, B, and C will have the freedom to operate their
consumer independently, choosing authentication plugins or doing any other
operation that is allowed in the non-workspaced Kong world.