You are browsing documentation for an outdated version. See the
latest documentation here.
This chapter aims to provide a step-by-step tutorial on how to set up
workspaces, entities, and see it in action.
Important Note: Conflicting Services or Routes in workspaces
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 creates a default workspace—unsurprisingly named
is to group all existing entities in Kong, where “existing entities” refers to:
- 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.
(Examples will be shown using the httpie HTTP command line client.)
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.