faqs; move precedence info; clean up + better API links

app/_gateway_entities/consumer-group.md

@@ -20,26 +20,35 @@ related_resources:
       url: /how-to/add-rate-limiting-tiers-with-kong-gateway/
 
 api_specs:
-    - text: Gateway Admin - EE
-      url: '/api/gateway/admin-ee/#/operations/get-consumer_groups'
-      insomnia_link: 'https://insomnia.rest/run/?label=Gateway%20Admin%20Enterprise%20API&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FGateway-EE%2Flatest%2Fkong-ee.yaml'
-    - text: Gateway Admin - OSS
-      url: '/api/gateway/admin-oss/#/operations/get-consumer_groups'
-      insomnia_link: 'https://insomnia.rest/run/?label=Gateway%20Admin%20OSS%20API&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FGateway-OSS%2Flatest%2Fkong-oss.yaml'
-    - text: Konnect Control Planes Config
-      url: '/api/konnect/control-planes-config/#/operations/get-consumer_groups'
-      insomnia_link: 'https://insomnia.rest/run/?label=Konnect%20Control%20Plane%20Config&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FKonnect%2Fcontrol-planes-config%2Fcontrol-planes-config.yaml'
-
+    - gateway/admin-ee
+    - konnect/control-planes-config
+
+faqs:
+  - q: Why aren't Consumer Group overrides working anymore?
+    a: |
+      Consumer Groups became a core Gateway entity in 3.4, which opened up a wide range of use cases for grouping Consumers.
+      
+      Before 3.4, Consumer Groups were limited to rate limiting plugins, where they were configured through overrides. This is no longer necessary. Instead, you can enable any rate limiting plugin directly on a consumer group without worrying about extra configuration.
+  - q: How do I enable a plugin on a Consumer Group?
+    a: |
+      First, [find out](/plugins/scopes/) if the plugin you want supports Consumer Groups. 
+      
+      If it does, head over to the plugin's documentation, open the "Get Started" tab, and choose "Consumer Groups" from the dropdown for any available example.
+
+  - q: When a Consumer is part of multiple Consumer Groups, how is precedence determined?
+    a: |
+      When a Consumer is a member of two Consumer Groups, each with a scoped plugin, Kong Gateway ensures deterministic behavior by executing only one of these plugins. Currently, this is determined by the Group name, in alphabetical order. 
+      However, the specific rules that govern this behavior are not defined and are subject to change in future releases.
 ---
 
 ## What is a Consumer Group?
 
 Consumer Groups enable the organization and categorization of [Consumers](/gateway/entities/consumer/) (users or applications) within an API ecosystem. By grouping Consumers together, you eliminate the need to manage them individually, providing a scalable, efficient approach to managing configurations.
 
 With Consumer Groups, you can scope plugins to specifically defined Consumer Groups and a new plugin instance will be created for each individual Consumer Group, making configurations and customizations more flexible and convenient.
-For all plugins available on the consumer groups scope, see the [Plugin Scopes Reference](/hub/plugins/compatibility/#scopes).
+For all plugins available on the consumer groups scope, see the [Plugin Scopes Reference](/plugins/scopes/).
 
-{:.note}
+{:.info}
 > **Note**: Consumer Groups plugin scoping is a feature that was added in {{site.base_gateway}} version 3.4. Running a mixed-version {{site.base_gateway}} cluster (3.4 control plane, and <=3.3 data planes) is not supported when using plugins scoped to Consumer Groups. 
 
 For example, you could define two groups, Gold and Silver, assign different rate limits to them, then process each group using a different plugin:
@@ -52,13 +61,13 @@ flowchart LR
     B(<b>Consumer Group Gold</b>
     10 requests/second
 
-    <i>fa:fa-user Consumer 1, fa:fa-user Consumer 2, 
-    fa:fa-user Consumer 5</i> )
+    fa:fa-user Consumer 1, fa:fa-user Consumer 2, 
+    fa:fa-user Consumer 5 )
 
     C(<b>Consumer Group Silver</b>
     5 requests/minute
 
-    <i>fa:fa-user Consumer 3, fa:fa-user Consumer 4</i>)
+    fa:fa-user Consumer 3, fa:fa-user Consumer 4)
 
     D(Rate Limiting Advanced)
     E(Request Transformer Advanced)

app/_gateway_entities/consumer.md

@@ -4,10 +4,10 @@ content_type: reference
 entities:
   - consumer # we could use this to pull the schema too
 
-description: A Consumer typically refers to an entity that consumes or uses the APIs managed by Kong Gateway.
+description: A Consumer typically refers to an entity that consumes or uses the APIs managed by {{site.base_gateway}}.
 
 related_resources:
-  - text: Authentication in Kong Gateway
+  - text: Authentication in {{site.base_gateway}}
     url: /authentication/
   - text: Consumer Groups API reference
     url: /api/gateway/admin-ee/#/operations/get-consumer_groups
@@ -24,7 +24,7 @@ faqs:
 
   - q: What is the difference between Consumers and Applications?
     a: |
-      Applications provide developers the ability to get access to APIs managed by Kong Gateway or Konnect
+      Applications provide developers the ability to get access to APIs managed by {{site.base_gateway}} or {{site.konnect_short_name}}
       with no interaction from the Kong admin team to generate the required credentials.
       <br><br>
       With Consumers, the Kong team creates Consumers, generates credentials, and shares them with the developers that need access to the APIs.

app/_gateway_entities/plugin.md

@@ -10,15 +10,11 @@ related_resources:
   - text: Plugin Hub
     url: /plugins/
   - text: Supported scopes by plugin
-    url: 'https://docs.konghq.com/hub/plugins/compatibility/#scopes'
-  - text: Supported topologies by plugin
-    url:  'https://docs.konghq.com/hub/plugins/compatibility/'
+    url: '/plugins/scopes/'
+  - text: Supported topologies and deployment options by plugin
+    url:  '/plugins/deployment-options/'
   - text: Supported protocols for each plugin
-    url:  'https://docs.konghq.com/hub/plugins/compatibility/#protocols'
-  - text: Self-managed {{site.base_gateway}} license tiers
-    url:  'https://docs.konghq.com/hub/plugins/license-tiers/'
-  - text: Konnect pricing tiers
-    url: 'https://docs.konghq.com/konnect/compatibility/#plugin-compatibility'
+    url:  '/plugins/protocols/'
 
 tools:
     - admin-api
@@ -32,15 +28,9 @@ schema:
     path: /schemas/Plugin
 
 api_specs:
-    - text: Gateway Admin - EE
-      url: '/api/gateway/admin-ee/#/operations/list-plugin'
-      insomnia_link: 'https://insomnia.rest/run/?label=Gateway%20Admin%20Enterprise%20API&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FGateway-EE%2Flatest%2Fkong-ee.yaml'
-    - text: Gateway Admin - OSS
-      url: '/api/gateway/admin-oss/#/operations/list-plugin'
-      insomnia_link: 'https://insomnia.rest/run/?label=Gateway%20Admin%20OSS%20API&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FGateway-OSS%2Flatest%2Fkong-oss.yaml'
-    - text: Konnect Control Planes Config
-      url: '/api/konnect/control-planes-config/#/operations/list-plugin'
-      insomnia_link: 'https://insomnia.rest/run/?label=Konnect%20Control%20Plane%20Config&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FKonnect%2Fcontrol-planes-config%2Fcontrol-planes-config.yaml'
+    - gateway/admin-oss
+    - gateway/admin-ee
+    - konnect/control-planes-config
 
 ---
 
@@ -53,6 +43,73 @@ 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}}.
 
+## Plugin precedence
+
+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.
+2. **Consumer group** + **Service** + **Route**: Affects groups of authenticated users across specific Services and Routes.
+3. **Consumer** + **Route**: Targets authenticated requests from a specific Consumer on a particular Route.
+4. **Consumer** + **Service**: Applies to authenticated requests from a specific Consumer accessing any Route within a given Service.
+5. **Consumer group** + **Route**: Affects groups of authenticated users on specific Routes.
+6. **Consumer group** + **Service**: Applies to all Routes within a specific Service for groups of authenticated users.
+7. **Route** + **Service**: Targets all Consumers on a specific Route and Service.
+8. **Consumer**: Applies to all requests from a specific, authenticated Consumer across all Routes and Services.
+9. **Consumer Group**: Affects all Routes and Services for a designated group of authenticated users.
+10. **Route**: Specific to given Route.
+11. **Service**: Specific to given Service. 
+12. **Globally configured plugins**: Lowest precedence, applies to all requests across all Services and Routes regardless of Consumer status.
+
+{:.info}
+> **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.
+
+## Custom plugins
+
+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. Kong provides PDKs in the following languages:
+
+* Lua
+* Go
+* Python
+* JavaScript
+
+These PDKs are sets of functions that a plugin can use to facilitate interactions between plugins and the core (or other components) of Kong.
+
+To start creating your own plugins, review the Getting Started documentation, or see the following references:
+
+* Plugin Development Kit reference
+* Other Language Support
+
 ## Schema
 
 {% entity_schema %}
+
+## Set up a Plugin
+
+Kong has many bundled plugins available, all of which have their own specific configurations and examples. See all 
+[Kong plugins](/plugins/) for their individual configurations.
+
+Here's an example of configuration for the ACL plugin:
+
+{% entity_example %}
+type: plugin
+data:
+  name: acl
+  config:
+    allow:
+      - dev
+      - admin
+    hide_groups_header: false
+{% endentity_example %}

app/_gateway_entities/service.md

@@ -26,15 +26,9 @@ schema:
     path: /schemas/Service
 
 api_specs:
-    - text: Gateway Admin - EE
-      url: '/api/gateway/admin-ee/#/operations/list-service'
-      insomnia_link: 'https://insomnia.rest/run/?label=Gateway%20Admin%20Enterprise%20API&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FGateway-EE%2Flatest%2Fkong-ee.yaml'
-    - text: Gateway Admin - OSS
-      url: '/api/gateway/admin-oss/#/operations/list-service'
-      insomnia_link: 'https://insomnia.rest/run/?label=Gateway%20Admin%20OSS%20API&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FGateway-OSS%2Flatest%2Fkong-oss.yaml'
-    - text: Konnect Control Planes Config
-      url: '/api/konnect/control-planes-config/#/operations/list-service'
-      insomnia_link: 'https://insomnia.rest/run/?label=Konnect%20Control%20Plane%20Config&uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2FKonnect%2Fcontrol-planes-config%2Fcontrol-planes-config.yaml'
+    - gateway/admin-oss
+    - gateway/admin-ee
+    - konnect/control-planes-config
 
 ---
 

tools/track-docs-changes/config/sources.yml

@@ -105,8 +105,6 @@ app/gateway/routing/index.md:
   - app/_src/gateway/key-concepts/routes/index.md
 app/plugins/deployment-options.md:
   - app/hub/plugins/compatibility/index.md
-app/plugins/precedence.md:
-  - app/hub/plugins/overview/index.md
 app/plugins/protocols.md:
   - app/hub/plugins/compatibility/index.md
 app/plugins/scopes.md: