From d5705a1956045064c96172d3be19932e55bf1d1d Mon Sep 17 00:00:00 2001 From: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Date: Thu, 18 Jul 2024 08:41:18 -0700 Subject: [PATCH] Kong entities (#21) * wip for a bunch of entities * add a plugins landing page * splitting out plugins page --- app/_kong_entities/plugin.md | 31 +++++ app/_kong_entities/route.md | 157 +++++++++++++++++++++++++ app/_kong_entities/service.md | 60 ++++++++++ app/_kong_entities/target.md | 20 ++++ app/_kong_entities/upstream.md | 20 ++++ app/_landing_pages/custom-plugins.yaml | 98 +++++++++++++++ app/_landing_pages/plugin-hub.yaml | 106 +++++++++++++++++ app/plugin-deployment-options.md | 18 +++ app/plugin-precedence.md | 39 ++++++ app/plugin-protocols.md | 9 ++ app/plugin-scopes.md | 41 +++++++ 11 files changed, 599 insertions(+) create mode 100644 app/_kong_entities/plugin.md create mode 100644 app/_kong_entities/route.md create mode 100644 app/_kong_entities/service.md create mode 100644 app/_kong_entities/target.md create mode 100644 app/_kong_entities/upstream.md create mode 100644 app/_landing_pages/custom-plugins.yaml create mode 100644 app/_landing_pages/plugin-hub.yaml create mode 100644 app/plugin-deployment-options.md create mode 100644 app/plugin-precedence.md create mode 100644 app/plugin-protocols.md create mode 100644 app/plugin-scopes.md diff --git a/app/_kong_entities/plugin.md b/app/_kong_entities/plugin.md new file mode 100644 index 00000000..b9e4a8dd --- /dev/null +++ b/app/_kong_entities/plugin.md @@ -0,0 +1,31 @@ +--- +title: Plugins +entities: + - plugin + +content_type: reference + +related_resources: + - text: Kong Plugin Hub + url: /hub/ + - text: Supported scopes by plugin + url: /hub/plugins/compatibility/#scopes + - text: Supported topologies by plugin + url: /hub/plugins/compatibility/ + - text: Supported protocols for each plugin + url: /hub/plugins/compatibility/#protocols + - text: Self-managed Kong Gateway license tiers + url: /hub/plugins/license-tiers/ + - text: Konnect pricing tiers + url: konnect/compatibility/#plugin-compatibility + +--- + +## What is a plugin? + +{{site.base_gateway}} is a Lua application designed to load and execute modules, which we commonly refer to as plugins. Plugins provide advanced functionality and extend the use of the Kong Gateway, allowing you to add more features to your implementation. + +Kong provides a set of standard Lua plugins that get bundled with {{site.base_gateway}} and {{site.konnect_short_name}}. +The set of plugins you have access to depends on your license tier. + +You can also develop custom plugins, adding your own custom functionality to {{site.base_gateway}}. diff --git a/app/_kong_entities/route.md b/app/_kong_entities/route.md new file mode 100644 index 00000000..f9f33a94 --- /dev/null +++ b/app/_kong_entities/route.md @@ -0,0 +1,157 @@ +--- +title: Routes +entities: + - route + +content_type: reference + +related_resources: + - text: Services + url: /kong-entity/service/ +--- + +## What is a route? + +A route is a path to a resource within an upstream application. Routes are added to services to allow access to the underlying application. In Kong Gateway, routes typically map to endpoints that are exposed through the Kong Gateway application. Routes can also define rules that match requests to associated services. Because of this, one route can reference multiple endpoints. A basic route should have a name, path or paths, and reference an existing service. + +You can also configure routes with: + +* Protocols: The protocol used to communicate with the upstream application. +* Hosts: Lists of domains that match a route +* Methods: HTTP methods that match a route +* Headers: Lists of values that are expected in the header of a request +* Redirect status codes: HTTPS status codes +* Tags: Optional set of strings to group routes with + + +{% contentfor setup_entity %} +{% entity_example %} +type: route +data: + name: example-route + paths: + - "/mock" +formats: + - admin-api + - konnect + - kic + - deck + - ui +{% endentity_example %} +{% endcontentfor %} + +## Route and service interaction + +Routes, in conjunction with [services](/kong-entities/service/), let you expose your services to applications with Kong Gateway. Kong Gateway abstracts the service from the applications by using routes. Since the application always uses the route to make a request, changes to the services, like versioning, don’t impact how applications make the request. Routes also allow the same service to be used by multiple applications and apply different policies based on the route used. + +For example, if you have an external application and an internal application that need to access the example_service service, but the external application should be limited in how often it can query the service to assure no denial of service. If a rate limit policy is configured for the service when the internal application calls the service, the internal application is limited as well. Routes can solve this problem. + +In the example above, two routes can be created, say /external and /internal, and both routes can point to example_service. A policy can be configured to limit how often the /external route is used and the route can be communicated to the external client for use. When the external client tries to access the service via Kong Gateway using /external, they are rate limited. But when the internal client accesses the service using Kong Gateway using /internal, the internal client will not be limited. + + +## How requests are routed + + +For each incoming request, {{site.base_gateway}} must determine which +service gets to handle it based on the routes that are defined. With +release 3.0, {{site.base_gateway}} introduced a new router that can be +running in two modes, the `traditional_compat` mode, which is +configured like prior releases, and the `expressions` mode which uses +a new configuration scheme. It is recommended that new deployments use +the expressions router as it is more powerful and expressive. + +The default mode of the router is `traditional_compat` and the +following sections describe how it operates. `traditional_compat` +mode is designed to behave like the router in versions before +{{site.base_gateway}} 3.x. For a description of the `expressions` mode, see +[How to Configure Routes using Expressions](expressions). + +In general, the router orders all defined routes by their priority and +uses the highest priority matching route to handle a request. If there +are multiple matching routes with the same priority, it is not defined +which of the matching routes will be used and {{site.base_gateway}} +will use either of them according to how its internal data structures +are organized. + +If a route contains prefix or regular expression paths, the priority +of the route will be calculated separately for each of the paths and +requests will be routed accordingly. + +In `traditional_compat` mode, the priority of a route is determined as +follows, by the order of descending significance: + +1. Priority points +2. Wildcard hosts +3. Header count +4. Regular expressions and prefix paths + +### Priority points + +For the presence of each of a route's `methods`, `host`, `headers`, +and `snis`, a "priority point" will be added to the route. The number +of "priority points" determines the overall order in which the routes +will be considered. Routes with a higher "priority point" values will +be considered before those with lower values. This means that if one +route has `methods` defined, and second one has `methods` and +`headers` defined, the second one will be considered before the first +one. + +### Wildcard hosts + +Among the routes with the same "priority point" value, those that have +any wildcard host specification will be considered after routes that +don't have any wildcard host (or no host) specified. + +### Header count + +The resulting groups are sorted so the routes with a higher number of +specified headers have higher priority than those with a lower number +of headers. + +### Regular expressions and prefix paths + +Within the resulting groups of routes with equal priority, the router +sorts the routes as follows: + + - Routes that have a regular expression path are considered first and + are ordered by their `regex_priority` value. Routes with a higher + `regex_priority` are considered before routes with lower + `regex_priority` values. + - Routes that have no regular expression path are ordered by the + length of their paths. Routes with longer paths are considered + before routes with shorter paths. + +For a route with multiple paths, each path will be considered +separately for priority determination. Effectively, this means that +separate routes exists for each of the paths. + +## Regular expressions + +Regular expressions used in routes use more resources to evaluate than +simple prefix routes. If many regular expressions must be evaluated +to route a request, the latency introduced by {{site.base_gateway}} +can suffer and its CPU usage can increase. In installations with +thousands of routes, replacing regular expression routes by simple +prefix routes can improve throughput and latency of +{{site.base_gateway}}. If regex must be used because an exact +path match must be performed, using the [expressions router](expressions) +will significantly improve {{site.base_gateway}}'s performance in this case. + +Starting with version 3.0, {{site.base_gateway}} uses the regular +expression engine shipped with the [Rust](https://docs.rs/regex/latest/regex/) programming language if the +router is operating in `expressions` or `traditional_compatible` mode. +Prior versions used the +[PCRE library](https://www.pcre.org/original/doc/html/pcrepattern.html) +to evaluate regular expression. While the two engines are largely +compatible, subtle differences exist between the two. Refer to +the documentation pertinent to the engine that you are using if you +have problems getting regular expression routes to work. + + +## Dynamically rewrite request URLs with routes + +Routes can be configured dynamically to rewrite the requested URL to a different URL for the upstream. For example, your legacy upstream endpoint may have a base URI like `/api/old/`. However, you want your publicly accessible API endpoint to now be named `/new/api`. To route the service's upstream endpoint to the new URL, you could set up a service with the path `/api/old/` and a route with the path `/new/api`. + +{{site.base_gateway}} can also handle more complex URL rewriting cases by using regular expression capture groups in the route path and the [Request Transformer Advanced](/hub/kong-inc/request-transformer-advanced/) plugin. For example, this can be used when you must replace `/api//old` with `/new/api/`. + +{{site.base_gateway}} 3.0.x or later ships with a new router. The new router can use regex expression capture groups to describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. For more information about how to configure the router using Expressions, see [How to configure routes using expressions](/gateway/{{page.release}}/key-concepts/routes/expressions/). diff --git a/app/_kong_entities/service.md b/app/_kong_entities/service.md new file mode 100644 index 00000000..ecef7c31 --- /dev/null +++ b/app/_kong_entities/service.md @@ -0,0 +1,60 @@ +--- +title: Services +entities: + - service + +content_type: reference + +related_resources: + - text: Routes entity + url: /kong-entities/route/ +--- + +## What is a service? + +In {{site.base_gateway}}, a service is an abstraction of an existing upstream application. Services can store collections of objects like plugin configurations, and policies, and they can be associated with routes. + +When defining a service, the administrator provides a name and the upstream application connection information. The connection details can be provided in the url field as a single string, or by providing individual values for protocol, host, port, and path individually. + +Services have a one-to-many relationship with upstream applications, which allows administrators to create sophisticated traffic management behaviors. + +Services, in conjunction with [routes](/kong-entities/route/), let you expose your services to clients with {{site.base_gateway}}. {{site.base_gateway}} abstracts the service from the clients by using routes. Since the client always calls the route, changes to the services (like versioning) don’t impact how clients make the call. Routes also allow the same service to be used by multiple clients and apply different policies based on the route used. + +{% mermaid %} +flowchart LR + A(API client) + B("`Route + (/mock)`") + C("`Service + (example-service)`") + D(Upstream + application) + + A <--requests + responses--> B + subgraph id1 ["` + **KONG GATEWAY**`"] + B <--requests + responses--> C + end + C <--requests + responses--> D + + style id1 rx:10,ry:10 + +{% endmermaid %} + +{% contentfor setup_entity %} +{% entity_example %} +type: service +data: + name: example-service + url: "http://httpbin.org" +formats: + - admin-api + - konnect + - kic + - deck + - ui +{% endentity_example %} +{% endcontentfor %} \ No newline at end of file diff --git a/app/_kong_entities/target.md b/app/_kong_entities/target.md new file mode 100644 index 00000000..6aa8808a --- /dev/null +++ b/app/_kong_entities/target.md @@ -0,0 +1,20 @@ +--- +title: Targets +entities: + - target + +content_type: reference + +related_resources: + - text: + url: + +--- + +## What is a target? + + +## Use cases for targets + +The following are examples of common use cases for targets: + diff --git a/app/_kong_entities/upstream.md b/app/_kong_entities/upstream.md new file mode 100644 index 00000000..f41aab97 --- /dev/null +++ b/app/_kong_entities/upstream.md @@ -0,0 +1,20 @@ +--- +title: Upstreams +entities: + - upstream + +content_type: reference + +related_resources: + - text: + url: +--- + +## What is an upstream? + +An upstream refers to the service applications sitting behind Kong Gateway, to which client requests are forwarded. In {{site.base_gateway}}, an upstream represents a virtual hostname and can be used to health check, circuit break, and load balance incoming requests over multiple [target](/kong-entity/target/) backend services. + +## Use cases for upstreams + +The following are examples of common use cases for upstreams: + diff --git a/app/_landing_pages/custom-plugins.yaml b/app/_landing_pages/custom-plugins.yaml new file mode 100644 index 00000000..0a06bb3c --- /dev/null +++ b/app/_landing_pages/custom-plugins.yaml @@ -0,0 +1,98 @@ +content: + - row: + - column: + - type: header + config: + type: h1 + text: "Custom plugins" + align: center + + - row: + - column: + - type: structured_text + config: + header: + text: "Developing custom plugins" + blocks: + - type: text + text: | + Kong provides an entire development environment for developing plugins, + including Plugin Development Kits (or PDKs), database abstractions, migrations, and more. + + Plugins consist of modules interacting with the request/response objects or + streams via a PDK to implement arbitrary logic. With custom plugins, you can configure these modules to provide custom functionality to Kong Gateway. + + To start creating your own plugins, review the [Getting Started documentation](/gateway/latest/plugin-development/get-started/), + or see the following references: + * [Plugin Development Kit reference](/gateway/latest/plugin-development/pdk/) + * [Other Language Support](/gateway/latest/plugin-development/pluginserver/go/) + + + - row: + - column: + - type: structured_text + config: + header: + text: "Plugin Development Kits (PDKs)" + blocks: + - type: text + text: "PDKs are sets of functions that a plugin can use to facilitate interactions between plugins + and the core (or other components) of Kong. Kong provides PDKs in the following languages:" + + - row: + - column: + - type: structured_text + config: + header: + text: "Lua" + blocks: + - type: text + text: Something about the Lua PDK + - type: text + text: Lua PDK → + + - column: + - type: structured_text + config: + header: + text: "Go" + blocks: + - type: text + text: Something about the Go PDK + - type: text + text: Go PDK → + - column: + - type: structured_text + config: + header: + text: "Python" + blocks: + - type: text + text: Something about the Python PDK + - type: text + text: Python PDK → + + - column: + - type: structured_text + config: + header: + text: "JavaScript" + blocks: + - type: text + text: Something about the JavaScript PDK + - type: text + text: JavaScript PDK → + + - row: + - column: + - type: structured_text + config: + header: + text: "Third-party plugins" + blocks: + - type: text + text: | + Through partnerships with third parties, Kong lists some [third-party custom plugins](/hub/?support=third-party-partner%2Ccommunity) on the Kong Plugin Hub. + These plugins are maintained by Kong partners. + If you would like to have your plugin featured on the Kong Plugin Hub, we encourage you to become a [Kong Partner](https://konghq.com/partners/). + diff --git a/app/_landing_pages/plugin-hub.yaml b/app/_landing_pages/plugin-hub.yaml new file mode 100644 index 00000000..73561e9a --- /dev/null +++ b/app/_landing_pages/plugin-hub.yaml @@ -0,0 +1,106 @@ +content: + - row: + - column: + - type: header + config: + type: h1 + text: "Kong Plugins" + align: center + + - row: + - column: + - type: structured_text + config: + header: + text: "What are plugins?" + blocks: + - type: text + text: Plugins provide advanced functionality and extend the use of the Kong Gateway, allowing you to add more features to your implementation. + Kong provides a set of standard Lua plugins that get bundled with Kong Gateway and Konnect. + The set of plugins you have access to depends on your license tier. + + You can also develop custom plugins, adding your own custom functionality to Kong Gateway. + + - row: + - column: + - type: structured_text + config: + header: + text: "AI" + blocks: + - type: text + text: Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins + - type: text + text: AI Gateway plugins → + - column: + - type: structured_text + config: + header: + text: "Authentication" + blocks: + - type: text + text: Protect your services with an authentication layer + - type: text + text: Authentication plugins → + - column: + - type: structured_text + config: + header: + text: "Security" + blocks: + - type: text + text: Protect your services with an additional security layer + - type: text + text: Security plugins → + - column: + - type: structured_text + config: + header: + text: "Traffic control" + blocks: + - type: text + text: Manage, throttle, and restrict inbound and outbound API traffic + - type: text + text: Traffic control plugins → + + - row: + - column: + - type: structured_text + config: + header: + text: "Serverless" + blocks: + - type: text + text: Invoke serverless functions in combination with other plugins + - type: text + text: Serverless plugins → + - column: + - type: structured_text + config: + header: + text: "Analytics and monitoring" + blocks: + - type: text + text: Vizualize, inspect, and monitor APIs and microservices traffic + - type: text + text: Analytics and monitoring plugins → + - column: + - type: structured_text + config: + header: + text: "Transformations" + blocks: + - type: text + text: Transform requests and responses on the fly with Kong + - type: text + text: Transformation plugins → + - column: + - type: structured_text + config: + header: + text: "Logging" + blocks: + - type: text + text: Log request and response data using the best transport for your infrastructure + - type: text + text: Logging plugins → diff --git a/app/plugin-deployment-options.md b/app/plugin-deployment-options.md new file mode 100644 index 00000000..31f53c0b --- /dev/null +++ b/app/plugin-deployment-options.md @@ -0,0 +1,18 @@ +--- +layout: default +title: Plugin deployment topologies + +content_type: reference + +related_resources: + - text: Kong Plugin Hub + url: /hub/ + + +--- + +## Plugin compatibility with deployment types + +{{site.base_gateway}} can be deployed in a variety of ways, and not all plugins +are fully compatible with each mode. See [Plugin Compatibility](/hub/plugins/compatibility#plugin-compatibility) +for a comparison. diff --git a/app/plugin-precedence.md b/app/plugin-precedence.md new file mode 100644 index 00000000..767d1e1a --- /dev/null +++ b/app/plugin-precedence.md @@ -0,0 +1,39 @@ +--- +layout: default +title: Plugin precedence + +content_type: reference + +related_resources: + - text: Kong Plugin Hub + url: /hub/ +--- + +A single plugin instance always runs _once_ per request. The +configuration with which it runs depends on the entities it has been +configured for. +Plugins can be configured for various entities, combinations of entities, or even globally. +This is useful, for example, when you want to configure a plugin a certain way for most requests but make _authenticated requests_ behave slightly differently. + +Therefore, there is an order of precedence for running a plugin when it has been applied to different entities with different configurations. The number of entities configured to a specific plugin directly correlates to its priority. The more entities a plugin is configured for, the higher its order of precedence. + +The complete order of precedence for plugins configured to multiple entities is: + +1. **Consumer** + **route** + **service**: Highest precedence, affecting authenticated requests that match a specific consumer on a particular route and service. +1. **Consumer group** + **service** + **route**: Affects groups of authenticated users across specific services and routes. +1. **Consumer** + **route**: Targets authenticated requests from a specific consumer on a particular route. +1. **Consumer** + **service**: Applies to authenticated requests from a specific consumer accessing any route within a given service. +1. **Consumer group** + **route**: Affects groups of authenticated users on specific routes. +1. **Consumer group** + **service**: Applies to all routes within a specific service for groups of authenticated users. +1. **Route** + **service**: Targets all consumers on a specific route and service. +1. **Consumer**: Applies to all requests from a specific, authenticated consumer across all routes and services. +1. **Consumer group**: Affects all routes and services for a designated group of authenticated users. +1. **Route**: Specific to given route. +1. **Service**: Specific to given service. +1. **Globally configured plugins**: Lowest precedence, applies to all requests across all services and routes regardless of consumer status. + +{:.note} +> **Note on precedence for consumer groups**: +When a consumer is a member of two consumer groups, each with a scoped plugin, +{{site.base_gateway}} ensures deterministic behavior by executing only one of these plugins. +However, the specific rules that govern this behavior are not defined and are subject to change in future releases. \ No newline at end of file diff --git a/app/plugin-protocols.md b/app/plugin-protocols.md new file mode 100644 index 00000000..d9ef0c1a --- /dev/null +++ b/app/plugin-protocols.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Supported protocols by plugin +content_type: reference + +related_resources: + - text: Kong Plugin Hub + url: /hub/ +--- diff --git a/app/plugin-scopes.md b/app/plugin-scopes.md new file mode 100644 index 00000000..b317b848 --- /dev/null +++ b/app/plugin-scopes.md @@ -0,0 +1,41 @@ +--- +layout: default +title: Supported scopes by plugin + +content_type: reference + +related_resources: + - text: Kong Plugin Hub + url: /hub/ +--- + +## Scoping plugins + +You can run plugins in various contexts, depending on your environment needs. +Each plugin can run globally, or be scoped to some combination of the following: +* Services +* Routes +* Consumers +* Consumer groups + +Using scopes, you can customize how Kong handles functions in your environment, +either before a request is sent to your backend services or after it receives a response. +For example, if you apply a plugin to a single [**route**](/kong-entities/route/), that plugin will trigger only on the specific path requests take through your system. +On the other hand, if you apply the plugin [**globally**](#global-scope), it will run on every request, regardless of any other configuration. + +### Global scope + +A global plugin is not associated to any service, route, consumer, or consumer group is considered global, and will be run on every request, +regardless of any other configuration. + +* In self-managed {{site.ee_product_name}}, the plugin applies to every entity in a given workspace. +* In self-managed {{site.ce_product_name}}, the plugin applies to your entire environment. +* In {{site.konnect_short_name}}, the plugin applies to every entity in a given control plane. + +Every plugin supports a subset of these scopes. + +## Supported scopes by plugin + +See the following table for plugins and their compatible scopes: + +[Placeholder for table that gets generated from plugin schemas, which will show all the plugin scope compatibilities (equivalent of [scopes](https://docs.konghq.com/hub/plugins/compatibility/#scopes).)] \ No newline at end of file