feat(plugin): add an optional instance_name field for plugin entity

[vm-001]

Summary

Currently, a Plugin instance must be identified by id, and users are unable to give a custom name for a Plugin instance. This is very user-unfriendly, and causes users confusion on Kong Manager.

Therefore, adding an optional instance_name field for Plugin entity could address this kind of situation.

Not only the instance_name can be used in the request body for CRUD of /plugins/{id}, but also

• /plugins/{instance_name}
• /services/{service}/plugins/{instance_name}
• /routes/{route}/plugins/{instance_name}

Checklist

• The Pull Request has tests
• There's an entry in the CHANGELOG
• There is a user-facing docs PR against https://github.com/Kong/docs.konghq.com - PUT DOCS PR HERE

Full changelog

• Add an optional instance_name field for Plugin entity

Issue reference

KAG-134

[chronolaw]

It looks good, did you consider the clustering compatibility?

Refer to #9972 .

[GGabriele]

@vm-001 I think Kong should validate that custom_name is not set to any "reserved" plugin name (basically, custom_name not in plugins.available_on_server).

WDYT?

[vm-001]

@vm-001 I think Kong should validate that custom_name is not set to any "reserved" plugin name (basically, custom_name not in plugins.available_on_server).

WDYT?

Kong will has more and more official plugins during its iteration. I'm concerned if I do so, then a valid custom_name will become invalid after upgrading Kong, because it conflicts with the new plugin. Therefore, I suggest not adding this kind of validation.

[vm-001]

When doing the operation upsert by field, if that field is used as endpoint_key, then it is most likely unique(based Kong RESTful style), and should be used as SQL conflict condition, instead of using the composite cache_key.

[vm-001]

It looks good, did you consider the clustering compatibility?

Refer to #9972 .

Done. d80e10b

[bungle]

Yes, it is unfortunate that plugin.name is reserved and hard to break (as name we use in general with other entities to have a freeform name for them). Aka have plugin.handler=request-transformer, plugin.name=my-transformer. But I am pretty sure we cannot do that (especially in minor release).

Alternatives to custom_name:

• title
• alias
• nick or nickname

Do we need to think about name more broadly if we in a future use this to make it possible to run same plugin multiple times?

[vm-001]

Alternatives to custom_name: title, alias, nick or nickname.

Let's do a very simple poll in the community. Adding emoji on this comment to vote.

🚀 to vote custom_name
👍 to vote title
😄 to vote alias
🎉 to vote nickname

[hanshuebner]

Sorry to come up with another suggestion. What we're naming is the plugin instance, so why not be explicit and use instance_name? alias implies that there is a 1:1 correspondence with another name, but as we are using name to name the plugin type, it would be misleading. Likewise for nickname and custom_name. title sounds too descriptive.

[bungle]

Sorry to come up with another suggestion. What we're naming is the plugin instance, so why not be explicit and use instance_name? alias implies that there is a 1:1 correspondence with another name, but as we are using name to name the plugin type, it would be misleading. Likewise for nickname and custom_name. title sounds too descriptive.

I was thinking about that too. But my personal self hates the long names with underscores and it means a lot more to type with everyone (users/customers included). Internally we talk about instances, but I am not sure if that is right term either. We don't create instances of plugins, we just call the same static "class" like plugin with different configuration. Of course here by instance we mean applying logic (aka run on this route/service/consumer or global or combination) and the configuration which to call the plugin. All that said, I am fine with instance_name, it just wouldn't be my pick, ;-).

Edit: on the otherhand if we allow to run same plugin multiple times, the instance_name is quite good.

[bungle]

but as we are using name to name the plugin type, it would be misleading

Yes that is unfortunate. If I were to choose without thinking about legacy and tooling we would have type/handler field that replaces current name field, and then name field for free form name of the "instance".

[jschmid1]

What we're naming is the plugin instance, so why not be explicit and use instance_name? alias implies that there is a 1:1 correspondence with another name, but as we are using name to name the plugin type, it would be misleading.

Imo, this is the right hint. It is really just a way to customize the identifier to a plugin instance. Also bearing in mind that we may eventually have support for multiple plugin instances, this is the right path 👍🏻

[chronolaw]

Should we add a field in kong/include/kong/model/plugin.proto?

[StarlightIbuki]

Should we add a field in kong/include/kong/model/plugin.proto?

Seems this file is not needed anymore. Will confirm tomorrow.