Explicitly explain "plugin instance" and how it compares to "Plugin" used in Kong UI

[AndreasBrieg]

Where is the problem?

https://docs.konghq.com/gateway/latest/key-concepts/plugins/

What happened?

I started experimenting with kong and got stuck because different Request Transformer configurations on a route and the service the route targeted were not applied as I expected. In the end it boils down for me not having understood what https://docs.konghq.com/gateway/latest/key-concepts/plugins/#precedence actually means when it says "plugin instance".

Especially "plugin instance" isn't explained before hand on the page.

When looking at the Kong UI and Rest API there are only "Plugins" being mentioned. So I was thinking that I do create a plugin instance if I click on "+ New Plugin" in the UI or http POST to the corresponding endpoint, which isn't the case. It just creates a plugin configuration (or whatever the exact terminology is) which is then picked up according to the precedence rules by the plugin.

Exact details on my experimentation with kong can be found on https://stackoverflow.com/questions/79025767/how-to-use-different-request-transformer-instances-on-service-and-route-at-the-s

What did you expect to happen?

I expect the documentation to use a consistent terminology with regard to the UI and Kong Configuration Rest API that is explained unambigously. Especially the documentation must explain the term "Plugin instance" and how that compares to the term "Plugin" used in the UI and how these are applied to a request/response being processed clearly so that a reader does not make the false assumption that execution the "+ New Plugin" action doesn't create a plugin instance which is executed without dependencies on how other entities (routes, services, global plugins) are being configured.

Code of Conduct and Community Expectations

• [X] I agree to follow this project's Code of Conduct
• [X] I agree to abide by the Community Expectations

[lena-larionova]

The "plugin instance" term refers to the instance name field:

This is different from a "plugin", which is the general category of the plugin entity. You can have multiple instances of one plugin - say, Basic Auth applied globally, and Basic Auth applied to a service. So what this precedence order defines is how those instances get applied. So, if you have a Basic Auth plugin on a service and a separate instance applied globally:

Then based on the precedence order, the plugin associated to the service gets applied first, then the global one.

Does that help?

We can update the doc you linked to explain all of this as well.

[AndreasBrieg]

@lena-larionova Thanks a lot for explaining this.

Yes, at least for me, it would make the documentation much more helpful to have this explained on the page I linked.

However unfortunately Kong doesn't seem to behave the way you explained. I went back to the Kong instance I experimented with as described in the linked Stackoverflow post and added different instance names to the Request Transformer plugins in my case. I also see the instance name being mentioned in the UI list view of the plugins (like in your 2nd screenshot). But it has no effect on the request kong passes on to the actual service. That request is still missing the data that should be added on service level, but it only has the data added on route level by kong.

This is probably also in line with the hint for the "Instance Name" field

A custom name for this plugin instance to help identifying from the list view

which does not mention an effect on the actual on request processing by Kong itself.

@lena-larionova Is there something we both haven't understood when it comes to request processing by Kong? The Basic Auth plugin might also not be the best example in this case because this is just about modifying the same header of a request where you won't be able to see different results of plugins at different stages being applied.

[AndreasBrieg]

I have experimented a bit further, this time using "Kong Functions (Post-Plugins)". I'm in the same setup as before but also added 3 plugins with different instance names and on levels global, service and route. I can only observe the plugin on route level to be invoked. So this seems to me to confirm that the "Instance Name" doesn't actually have an effect on request processing.