What's the official attitude to Kong admin API in kubernetes

Hi, I’m a new Kong user, and this is a question that really puzzles me.

When I’m reading Kong docs from official website, all docs/guides are talking about Admin API to configure Kong. I took some time to learn it and thought I’ll be ready to really use it.

Then when I was trying to deploy Kong to Kubernetes, all info goes to a Github project. The configuration talks about CRD all of a sudden. But what’s relationship with admin api? I don’t see any doc talking about what’s going on with admin api. Is it still supported? Are we encouraged to use CRD instead? Has CRD been mature enough to cover what all admin api does?

Searched the forum/issues and saw there are really many users like me looking for the missing admin api. Finally saw a comment saying that admin api should not be used in kubernetes case as it will be overwritten by ingress-controller. I thought I got the conclusion. But later, saw a newer comment saying it won’t be overwritten since 0.5 and again there’s no any doc saying anything about exposing the admin api.

So really want to know the official attitude about the admin api in Kubernetes.

Are we encouraged to use CRD? Has CRD been mature enough to cover what all admin api does?
Will there be any use/functional difference/missing features for admin api from what’s described in official website doc? Could we provide doc to expose admin api for both http and https?

Thanks a lot!


Thank you for the detailed post.

I totally understand your frustration and every point that you make above is accurate and perfectly reasonable.

I’ll try to explain the reason for the way it exists today:

Kong is a highly configurable piece of software that is deployed in a wide variety of installations and architectures.
Before Kubernetes became mainstream, Kong was completely configured using Admin API. Over the last couple of years, 2019 specifically, Kubernetes has taken over and we have seen high-adoption of our CRD based approach, aka Kong’s Ingress Controller. Even though the adoption of Kubernetes and our CRDs is growing very rapidly, it is still far from the traditional way to use Kong, via the Admin API.

And then there is the platform agnosticism side of Kong. Kong is designed to run on any platform of your choice. We treat Kubernetes specially because there is a very high demand and Kong adds a lot of value to the Kubernetes ecosystem by providing native-integrations with it. Every feature of Kong, works the same way, be it Kong running outside or inside Kubernetes.

The official recommendation is to use CRDs and Ingress Controller to configure Kong when running on Kubernetes, to leverage Kubernetes functionalities and increase automation in your infrastructure.

Kong’s CRDs provide full-coverage of the Admin API, meaning, you can use all the features of Kong, that you can use with Admin API.

Here a couple of documents that provide some relation between CRDs and Admin API:

It is possible to use Kong on Kubernetes with the Admin API (without CRDs) if that makes sense in your use-case.

While documentation exists, I admit that the way we present it is not ideal and needs work.
Hope this helps and let me know if you have any more questions.


Thank you very much for the answer. It’s much clearer to me now.
BTW. the docs don’t mention Admin API. It might help people to add something.

1 Like

I would rather put it a bit differently.

  1. Use Ingress Controller + Kong on K8s + CRDs when you have to configure kong for a lot of plugins, ingresses/services, routes, consumers, etc. for about 5k resources, where 1 resource equals 1 CRD. Beyond this scale, you will probably stress the ingress-controller + Kong in keeping track of all the configs and ensuring efficient sync.

  2. Use Kong backed with a DB if you are anywhere beyond that irrespective of whether you are on K8s or not.

I hope my understanding is right, although I might be a bit wrong on the numbers above wrt 5k.
Hopefully, this helps you design your platform better. I am in 1 right now, but might have to move to 2 down the line.

1 Like

@hbagdi In my case, consumers need to added/removed dynamically by an k8s app in Go. Which is the recommended way?

  1. KongConsumer CRD via kubernetes “client-go”, or
  2. Restfully via Admin API

Restfully via Admin API will be simpler if you have a lot of consumers (more than a few thousands).

Hi @hbagdi, I’ve read somewhere, which I forgot how it was exactly written. that if I create something via admin API, it will get deleted by the ingress controller.

my question is, it safe to add consumers via admin API ?


This used to be a thing in the past. Not anymore.


it is clear now, thank you!

By default, the deployment is dbless (https://bit.ly/k4k8s). The Admin API has to be ruled out, since it can’t add/remove consumers. Is this correct?

Update: I saw below documentation

A database driven deployment should be used if your use-case requires dynamica creation of Consumers and/or credentials in Kong at a scale large enough that the consumers will not fit entirely in memory.

But why? can’t dbless deployment support dynamic creation of consumers via CRD?

Do we have guide to setup the “with database” deployment?

If you have more than a few thousand consumers then we recommend using Kong with a database. It is not necessary that your use-case requires a database.

The Admin API has to be ruled out, since it can’t add/remove consumers. Is this correct?

The default deployment is DB-less. There is another deployment that can be used for DB.

My case needs dynamic creation, so per this quotation: “A database driven deployment should be used if your use-case requires dynamica creation of Consumers”, do i have to use database deployment?

Not necessarily. You can dynamically create KongConsumer resources in Kubernetes and it will have the same effect.

we have everything configured with kong 1.2 and ingress controller 0.5. Everything was perfect but we wanted to update everything and continue using API ADMIN. It seems impossible there is no documentation about it. did you find any documentation? In other case we’ll go back to older versions .

I think you should add this to you documentation in a very clear way, I’ve spent 2 hours trying to understand why I don’t have Admin API

You do not get an Admin API with Kong if you are using the DB-less mode of Kong, you can only configure using a declarative file in that case.
You have two options if you want to use the Admin API:

  • Use the traditional Kong, where Kong is backed by a database
  • Use Hybrid mode of Kong – introduced in Kong 2.0, which splits the control plane and data plane responsibilities of Kong into separate nodes.

But is it possible to expose the Admin API via K8s Service even with DB-less mode?

Yes, but it’s read-only aside from /config, and you shouldn’t manually POST to /config when using the ingress controller.

Exposing the admin API inside the container only works as a simple security measure, so unless you have a topology that requires exposing it via a Service for some reason, I wouldn’t recommend doing so. Occasional interactions to debug if the controller has misconfigured something can be handled using port-forwards.