Multi Tenant Support


Hi Team,

I’ve the following use scenario:

I’ve an upstream api let’s say identified by the uri /domain/function/operation, there are different upstream tenants that provide this API. So, lets say

  • User 1,2,3 are served by tenant A
  • User 4,5,6 are served by tenant B
  • User 7,8,9 are served by tenant C
    The users are identified by certain request headers.

I’ve a few questions in this regard:

  • is it possible to implement this routing out of the box or will I have to write a plugin to achieve this?
  • How do I go about the adding and configuring an API for this use case?



  • is it possible to implement this routing out of the box or will I have to write a plugin to achieve this?

Short answer: Not possible out of the box, I’m afraid you will need a custom plugin which resets the value of upstream_url depending on the consumer id.

Slightly longer answer: Kong’s load balancer can redirect to different targets depending on the consumer hash, but it’s not possible to specify which consumers are redirected to which targets, so the only option is a custom plutin. Your plugin will have to manually se ngx.var.upstream_uri and/or (if you use a load balancer) depending on the consumer_id. If you decide to store the different destinations in the database, make sure to memoize the results, so that you don’t hit the database on each request!

  • How do I go about the adding and configuring an API for this use case?

First you must register at least one API in your kong instance. You can do so with the admin api interface for adding new APIs. If the routing rules of all your domains/functions/operations are the same, you just need one api. If they differ, you will need one for each group. For example, if all requests to /users/registration/new are routed to one server, but /companies/report/sales goes to a different endpoint for each group of users, then you need to register two APIs.\

Next is registering your users. In kong, they are called consumers. The tutorial about consumers explains how you can set them up basically. See also the key-auth plugin docs for more details.

Finally you will need to configure your custom plugin (unless you have hardcoded the values). This depends on how you write it, but you will probably have to associate some consumer_id with some property (either the server uri/name or some sort of “user group”, to which you will assign the server later). The recommended way for doing this is that your plugin should include an admin API interface so you can do this with curl. Alternatively you can always write the data on the database.


Thanks for the reply @kikito.

Yes I understood the part about api registration. So my question about registration was more about how to register tenants for the same uri.

so if I’ve /users/registration/new let’s say user in different cities go to different upstreams urls, and these cities have to be looked up based on some fact on the request. So, would I’ve a dummy route /users/registration/new that’ll route to some default city and then in the plugin do the lookup for the actual upstream provider and set ngx.var.upstream_uri or Am I thinking right or is there a better way?



What you are saying makes sense, yes.

You could use the ACL plugin (source) is an example about how to do “consumer groups” (or cities) and how to minimize database access.


Thanks @kikito
That’s neat. It might not work for my use case though. I think I’ll have to write a custom plugin. In my case the user’s consumer group is not based on his authentication but will be based on his authorization.


Hey guys… sorry for bumping it up again after 9 odd months , i’m currently facing a similar scenario to what @sandy-adi had mentioned.
I have an upstream service with a finite number of targets and among those targets I have two segregation , lets say Test and Production Targets. I’m currently hashing load-balancer with consumers and passing custom apikeys by request headers. Kong is selecting targets for each requests on its own algorithm. Is it possible for me to map a particular target group to a particular set of consumers , as mentioned above consumers would be identified by a custom request header. I want to route requests from certain group of consumers to test and others to production targets based on request headers. I’m new to API gateway topics and kong so please excuse if i sound dumb.