Fix: Consumer groups docs (#8257)

* fix consumer groups docs; move PAT info to its own doc

* fix links

* typo

* Apply suggestions from code review

Co-authored-by: Diana <[email protected]>

---------

Co-authored-by: Diana <[email protected]>

app/_data/docs_nav_konnect.yml

@@ -108,7 +108,7 @@
               url: ../../gateway/latest/plugin-development/
               generate: false
         - text: Create Consumer Groups
-          url: ../../hub/kong-inc/rate-limiting-advanced/how-to
+          url: /gateway-manager/configuration/consumer-groups/
         - text: Secrets Management
           items:
             - text: Overview
@@ -283,6 +283,8 @@
           url: /org-management/users/
         - text: Manage System Accounts
           url: /org-management/system-accounts/
+        - text: Personal Access Tokens
+          url: /org-management/access-tokens/
         - text: Social Identity Login
           url: /org-management/social-identity-login/
         - text: Org Switcher

app/_src/gateway/kong-enterprise/consumer-groups/index.md

@@ -575,3 +575,5 @@ if you need to cycle the group for a new batch of users.
 * [Consumer group precedence information](/gateway/latest/key-concepts/plugins/#precedence).
 * [API documentation](/gateway/api/admin-ee/latest/#/consumer_groups/get-consumer_groups)
 * [Enforcing rate limiting tiers with the Rate Limiting Advanced plugin](/hub/kong-inc/rate-limiting-advanced/how-to/)
+* [Consumer groups in Kong Manager](/gateway/{{page.release}}/kong-manager/consumer-groups/)
+* [Consumer groups in {{site.konnect_short_name}}](/konnect/gateway-manager/configuration/consumer-groups/)

app/_src/gateway/kong-manager/consumer-groups.md

@@ -1,89 +1,20 @@
 ---
 title: Create Consumer Groups in Kong Manager
 content_type: tutorial
+badge: enterprise
 ---
-With consumer groups, you can define any number of rate limiting tiers and
-apply them to subsets of consumers, instead of managing each consumer
-individually.
+With [consumer groups](/gateway/latest/key-concepts/consumer-groups/), you can scope plugins to specifically defined 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 example, you could define three consumer groups:
-* A "gold tier" with 1000 requests per minute
-* A "silver tier" with 10 requests per second
-* A "bronze tier" with 6 requests per 30 seconds
+## Create a consumer group in Kong Manager
 
-The `consumer_groups` endpoint works together with a limited set of plugins. 
-See the [scopes compatibility table](/hub/plugins/compatibility/#scopes) for details.
+The following creates a new consumer group:
 
-Consumers that are not in a consumer group default to the Rate Limiting advanced
-plugin’s configuration, so you can define tier groups for some users and
-have a default behavior for consumers without groups.
-
-To use consumer groups for rate limiting, you need to:
-* Create one or more consumer groups
-* Create consumers
-* Assign consumers to groups
-* Configure the Rate Limiting Advanced plugin globally with the `enforce_consumer_groups`
-and `consumer_groups` parameters, setting up the list of consumer groups that
-the plugin accepts
-* Configure a rate limiting policy for each consumer group, overriding the 
-plugin's global configuration
-
-For all possible requests, see the
-[Consumer Groups reference](/gateway/api/admin-ee/latest/#/consumer_groups/get-consumer_groups).
-
-## Set up a consumer group with consumers
-
-In this section, you will create the Bronze tier consumer group with a consumer assigned to the group.
-
-1. Open the **default** workspace.
-1. From the menu, open **Consumers**, then click the **Groups** tab.
-1. Click **New Consumer Groups**.
-1. Enter `Bronze` for the consumer group name and click **Create**.
-1. From the menu, click **Consumers**, then click **New Consumer**.
-1. Enter a **Username** and **Custom ID**. For this example, you can use `Amal` for each field.
-1. Click **Create**.
-1. From the menu, click the **Groups** tab.
-1. Click the `Bronze` consumer group you just created.
-1. Click **Consumers** and **Add consumers** to add the `Amal` consumer you created to the `Bronze` consumer group.
-
-## Configure the Rate Limiting Advanced plugin for all consumers
-
-In this section, you will configure the Rate Limiting Advanced plugin to set the rate limit to 5 requests every 30 seconds for all consumers.
-
-1. Open the **default** workspace.
-1. From the menu, open **Plugins**, then click **Install Plugin**.
-1. Find the **Rate Limiting** plugin, then click **Enable**.
-1. Apply the plugin as **Global**, which means the rate limiting applies to all requests, including every service and route in the workspace.
-
-    If you switched it to **Scoped**, the rate limiting would apply the plugin to only one service, route, or consumer.
-
-    By default, the plugin is automatically enabled when the form is submitted.
-    You can also toggle the **This plugin is Enabled** button to configure the plugin without enabling it.
-    For this example, keep the plugin enabled.
-1. Complete only the following fields with the following parameters.
-    1. config.limit: `5`
-    1. config.window_size: `30`
-    1. config.window_type: `sliding`
-    1. config.retry_after_jitter_max: `0`
-    1. config.enforce_consumer_groups: `true` 
-    1. config.consumer_groups: `Bronze`
-
-
-    Besides the above fields, there may be others populated with default values. For this example, leave the rest of the fields as they are.
-1. Click **Install**.
-
-## Configure rate limiting for consumer groups
-
-In this section, you will configure the Rate Limiting Advanced plugin to set the rate limit to 6 requests every 30 seconds only for consumers in the Bronze tier.
-
-1. Open the **default** workspace.
-1. From the menu, open **Consumers**, then click the **Groups** tab.
-1. Click the `Bronze` consumer group you just created.
-1. Click the **Policy** tab.
-1. Complete only the following fields with the following parameters.
-    1. config.limit: `6`
-    1. config.window_size: `30`
-    1. config.window_type: `sliding`
-    1. config.retry_after_jitter_max: `0`
-1. Click **Save**.
+1. In Kong Manager, go to a {{site.base_gateway}} workspace > **Consumers**.
+2. Open the **Consumer Groups** tab.
+3. Click **New Consumer Group**.
+4. Enter a group name and select consumers to add to the group.
+5. Click **Save**.
 
+On the consumer group's overview page, you can now add any supported plugin. 
+This plugin will apply to all consumers in the group.

app/konnect/api/index.md

@@ -22,7 +22,7 @@ The geo-specific endpoints are used to manage {{site.konnect_short_name}} entiti
 
 ## Authentication
 
-The recommended method of authentication for {{site.konnect_short_name}} is [Personal Access Token (PAT)](/konnect/gateway-manager/declarative-config/#generate-a-personal-access-token), which can be obtained from the [personal access token page](https://cloud.konghq.com/global/account/tokens) in {{site.konnect_short_name}}. The PAT must be passed in the `Authorization` header of all requests, for example: 
+The recommended method of authentication for {{site.konnect_short_name}} is [Personal Access Token (PAT)](/konnect/org-management/access-tokens/), which can be obtained from the [personal access token page](https://cloud.konghq.com/global/account/tokens) in {{site.konnect_short_name}}. The PAT must be passed in the `Authorization` header of all requests, for example: 
 
 `curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer kpat_xgfT'`
 

app/konnect/dev-portal/access-and-approval/manage-teams.md

@@ -16,7 +16,7 @@ In this guide, you will set up two developer teams and then enable Portal RBAC u
 ## Prerequisites
 * Two test [developer accounts registered](/konnect/dev-portal/dev-reg/)
 * A [configured control plane](/konnect/getting-started/configure-data-plane-node/)
-* A [personal access token](/konnect/gateway-manager/declarative-config/#generate-a-personal-access-token) for authorization. This is only required if you plan to use the API to create developer teams.
+* A [personal access token](/konnect/org-management/access-tokens/) for authorization. This is only required if you plan to use the API to create developer teams.
 
 If you have existing registered developers in {{site.konnect_short_name}}, you must configure developer teams before enabling Portal RBAC. If you enable Portal RBAC before configuring teams for your developers, it will prevent *all* developers from seeing any API products in your Dev Portal. 
 

app/konnect/gateway-manager/configuration/consumer-groups.md

@@ -3,91 +3,157 @@ title: Create Consumer Groups in Konnect
 content_type: tutorial
 badge: enterprise
 ---
-With consumer groups, you can define any number of rate limiting tiers and
-apply them to subsets of consumers, instead of managing each consumer
-individually.
-
-For example, you could define three consumer groups:
-* **gold tier** with 1000 requests per minute
-* **silver tier** with 10 requests per second
-* **bronze tier** with 6 requests per 30 seconds
-
-The `consumer_groups` endpoint works together with the [Rate Limiting Advanced plugin](/hub/kong-inc/rate-limiting-advanced/).
-
-Consumers that are not in a consumer group default to the Rate Limiting advanced
-plugin’s configuration, so you can define tier groups for some users and
-have a default behavior for consumers without groups.
-
-To use consumer groups for rate limiting, you must:
-* Create a consumer group and create or add consumers to it
-* Configure the Rate Limiting Advanced plugin globally with the `enforce_consumer_groups`
-and `consumer_groups` parameters, setting up the list of consumer groups that
-the plugin accepts
-* Configure a rate limiting policy for each consumer group, overriding the 
-plugin's global configuration
-
-This tutorial will walk through creating a bronze tier consumer group that allows consumers in the group to make five requests every 30 seconds. 
-
-## Create a consumer
-
-In this section, you will create a consumer.
-
-1. From the {{site.konnect_short_name}} sidebar, open the **Gateway Manager** section.
-1. Select the **default** control plane.
-1. Open the **Consumers** tab, click **Add consumer**, and enter the following consumer information into the form:
-    * **Username**: Amal
-    * **Custom ID**: Amal
-
-## Assign a consumer to a consumer group
-
-In this section, you will assign the consumer you just created to the Bronze tier consumer group. 
-
-1. From the **Gateway Manager** section in the **default** {{site.konnect_short_name}} workspace, open the **Consumers** tab.
-1. Click the **Consumer Groups** tab, and then click **Add Consumer Group**.
-1. Enter "Bronze" for the consumer group name and select the "Amal" consumer you just created from the drop-down. 
-1. Click **Create**.
-
-## Configure the Rate Limiting Advanced plugin for all consumers
-
-In this section, you will configure the Rate Limiting Advanced plugin to set the rate limit to 5 requests every 30 seconds for all consumers.
-
-1. In {{site.konnect_short_name}}, click **Gateway Manager** in the sidebar.
-1. Click the **default** control plane.
-1. From the menu, open **Plugins**, then click **Add plugin**.
-1. Find the **Rate Limiting** plugin, then click **Select**.
-1. Apply the plugin as **Global**
-    This means the rate-limiting applies to all requests, including every service and route in the workspace.
-
-    If you switched it to **Scoped**, the rate limiting would apply the plugin to only one service, route, or consumer.
-
-    By default, the plugin is automatically enabled when the form is submitted.
-    You can also toggle the **This plugin is Enabled** button to configure the plugin without enabling it.
-    For this example, keep the plugin enabled.
-1. Complete only the following fields with the following parameters:
-    * **Config.limit:** 5
-    * **Config.window_size:** 30
-    * **Config.window_type:** Sliding
-    * **Config.retry_after_jitter_max:** 0
-    * **Config.enforce_consumer_groups:** true 
-    * **Config.consumer_groups:** Bronze
-
-    Besides the above fields, there may be others populated with default values. For this example, leave the rest of the fields as they are.
-1. Click **Save**.
-
-## Configure rate limiting for consumer groups
-
-In this section, you will configure the Rate Limiting Advanced plugin to set the rate limit to 6 requests every 30 seconds only for consumers in the Bronze tier.
-
-1. In {{site.konnect_short_name}}, click **Gateway Manager** in the sidebar.
-1. Select the **default** control plane.
-1. From the menu, open **Consumers**, then click the **Consumer Groups** tab.
-1. Click the **Bronze** consumer group you just created.
-1. Click **Add Configuration**.
-1. In the dialog, complete only the following fields with the following parameters:
-    * **Window Size:** 30
-    * **Window Type:** Sliding
-    * **Limit:** 6
-    * **Retry After Jitter Max:** 0
-1. Click **Save**.
-
-You have now set up a Bronze tier consumer group with one consumer, Amal, assigned to the group. Whenever the consumer Amal sends requests, they can make up to six requests every 30 seconds before hitting the rate limit. All other consumers are limited to only five requests every 30 seconds. 
+
+With [consumer groups](/gateway/latest/key-concepts/consumer-groups/), you can scope plugins to specifically defined 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).
+
+## Create a consumer group in {{site.konnect_short_name}}
+
+The following creates a new consumer group:
+
+1. In Gateway Manager, go to a {{site.base_gateway}} control plane > **Consumers**.
+2. Open the **Consumer Groups** tab.
+3. Click **New Consumer Group**.
+4. Enter a group name and select consumers to add to the group.
+5. Click **Save**.
+
+On the consumer group's overview page, you can now add any supported plugin. 
+This plugin will apply to all consumers in the group.
+
+## decK example
+
+Let's look at a more complex example where you define three consumer groups for rate limiting consumers. In this example, each consumer group represents a different tier of support, such as Free, Basic, and Premium. Each tier will have different rate limits. For example, the Free tier has lower rate limits than the Premium tier.
+
+We'll be using [decK](/deck/) to reduce the configuration complexity, but you can achieve all of this using the {{site.konnect_short_name}} admin interface or API as well.
+
+In the following decK file, you have:
+1. Consumer authentication via the Key Authentication plugin
+2. Three consumer groups (Free, Basic, Premium)
+3. Three consumers, each belonging to a different group
+4. The Rate Limiting Advanced plugin configured with a different rate limit on each consumer group 
+
+Save the following content to a file named `konnect.yaml`:
+```yaml
+_format_version: '3.0'
+services:
+  - name: example-service
+    url: http://httpbin.konghq.com/anything
+routes:
+  - name: example-route
+    paths:
+    - "/anything"
+    service:
+      name: example-service
+consumer_groups:
+  - name: Free
+  - name: Basic
+  - name: Premium
+consumers:
+  - username: Amal
+    groups:
+    - name: Free
+    keyauth_credentials:
+    - key: amal
+  - username: Dana
+    groups:
+    - name: Basic
+    keyauth_credentials:
+    - key: dana
+  - username: Mahan
+    groups:
+    - name: Premium
+    keyauth_credentials:
+    - key: mahan
+plugins:
+  - name: key-auth
+    config:
+      key_names:
+      - apikey
+  - name: rate-limiting-advanced
+    consumer_group: Free
+    config:
+      limit:
+      - 3
+      window_size:
+      - 30
+      window_type: fixed
+      retry_after_jitter_max: 0
+      namespace: free
+  - name: rate-limiting-advanced
+    consumer_group: Basic
+    config:
+      limit:
+      - 5
+      window_size:
+      - 30
+      window_type: sliding
+      retry_after_jitter_max: 0
+      namespace: basic
+  - name: rate-limiting-advanced
+    consumer_group: Premium
+    config:
+      limit:
+      - 500
+      window_size:
+      - 30
+      window_type: sliding
+      retry_after_jitter_max: 0
+      namespace: premium
+```
+
+Check your configuration with `deck gateway diff`, adding in your [{{site.konnect_short_name}} token](/konnect/org-management/access-tokens/) and control plane name:
+
+```sh
+deck gateway diff konnect.yaml \
+ --konnect-token $KONNECT_TOKEN \
+ --konnect-control-plane-name $KONNECT_CP_NAME
+```
+
+If everything looks right, synchronize the file to {{site.konnect_short_name}} to update your Gateway configuration:
+
+```sh
+deck gateway sync konnect.yaml \
+  --konnect-token $KONNECT_TOKEN \
+  --konnect-control-plane-name $KONNECT_CP_NAME
+```
+
+### Validate
+
+Now we can test that each rate limiting tier is working as expected by sending a series of HTTP requests (for example, six for Free Tier and seven for Basic Tier) to the endpoint with the appropriate API key with the goal of exceeding the configured rate limit for that tier. The tests wait for one second between requests to avoid overwhelming the server and test rate limits more clearly.
+
+Test the rate limiting of the Free tier:
+
+```sh
+echo "Testing Free Tier Rate Limit..."
+
+for i in {1..6}; do
+  curl -I http://localhost:8000/anything -H 'apikey:amal'
+  echo
+  sleep 1
+done
+```
+
+For the first few requests (up to the configured limit, which is 3 requests in 30 seconds), you should receive a `200 OK` status code. Once the limit is exceeded, you should receive a `429 Too Many Requests` status code with a message indicating the rate limit has been exceeded.
+
+You can do the same for the Basic tier:
+```sh
+echo "Testing Basic Tier Rate Limit..."
+
+for i in {1..7}; do
+  curl -I http://localhost:8000/anything -H 'apikey:dana'
+  echo
+  sleep 1
+done
+```
+
+And for the Premium tier:
+
+```sh
+echo "Testing Premium Tier Rate Limit..."
+
+for i in {1..11}; do
+  curl -I http://localhost:8000/anything -H 'apikey:mahan'
+  echo
+  sleep 1
+done
+```