--- title: Consumer Groups description: Consumer Groups let you apply common configurations to groups of Consumers, such as rate limiting policies or request and response transformation. url: "/gateway/entities/consumer-group/" canonical_url: "/gateway/entities/consumer-group/" content_type: reference products: - Kong Gateway tools: - Admin API - Konnect API - KIC - deck - Terraform canonical: true works_on: - on-prem - konnect --- # Consumer Groups ## 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](/gateway/entities/plugin/#supported-scopes-by-plugin). For example, you could define two groups, Gold and Silver, assign different rate limits to them, then process each group using a different plugin: 
 
flowchart LR
    A((fa:fa-user Consumers 1-5))

    B(Consumer Group Gold

    fa:fa-user Consumer 1, fa:fa-user Consumer 2,
    fa:fa-user Consumer 5 )

    C(Consumer Group Silver

    fa:fa-user Consumer 3, fa:fa-user Consumer 4)

    D(Rate Limiting Advanced
    10 requests/second)
    E(Rate Limiting Advanced
    2 requests/second)
    F(Gateway Service
    QR Code Generation)
    H(QR Code Generation
    service)

    A--> B & C
    subgraph id1 [Kong Gateway]
    direction LR
    B --> D --> F
    C --> E --> F
    end

    F --> H
Without Consumer Groups, you would have to use five Rate Limiting Advanced plugins, once for each consumer. Any time you change the rate limit, you would need to update every consumer individually. Consumer Groups allow you to manage your plugin configuration centrally, and reduce the size of your Kong Gateway configuration at the same time. In this example, it's the difference between using two plugins or five plugins. In your production environment, it could be the difference between two plugins and five _million_ plugins. ## Use cases Common use cases for Consumer Groups: ### Managing permissions Description: You can use Consumer Groups to define different sets of users with varying levels of permissions. For example, you can create distinct Consumer Groups for regular users, premium users, and administrators. ### Managing roles Description: Within an organization, there may be various departments or teams that interact with APIs differently. By creating Consumer Groups for these different roles, you can customize the API usage experience. For instance, an organization could have separate Consumer Groups for the marketing team, development team, and support team. ### Resource quotas and rate limiting Description: Consumer Groups can be used to enforce resource quotas and rate limiting on different sets of Consumers. For instance, you can apply different rate limits to different Consumer Groups based on their subscription plans. ### Customizing plugin configurations Description: With the ability to scope plugins specifically to defined groups, different Consumer Groups can have distinct plugin configurations based on their requirements. For example, one group may require additional request transformations while another may not need them at all. ## Set up a Consumer Group ### decK The following creates a new Consumer Group called **my_group**: ```yaml _format_version: "3.0" consumer_groups: - name: my_group ``` {: data-file="kong.yaml" data-tool="deck" } ### Admin API To create a Consumer Group, call the [Admin API's `/consumer_groups` endpoint](/api/gateway/admin-ee/#/operations/create-consumer_group). ```bash curl -i -X POST http://localhost:8001/consumer_groups/ \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data ' { "name": "my_group" } ' ``` ### Konnect API To create a Consumer Group, call the Konnect [control plane config API's `/consumer_groups` endpoint](/api/konnect/control-planes-config/#/operations/create-consumer_group). ```bash curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/consumer_groups/ \ --header "accept: application/json" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $KONNECT_TOKEN" \ --data ' { "name": "my_group" } ' ``` Make sure to replace the following placeholders with your own values: * `region`: Geographic region where your Kong Konnect is hosted and operates. * `KONNECT_TOKEN`: Your Personal Access Token (PAT) associated with your Konnect account. * `controlPlaneId`: The `id` of the control plane. See the [Konnect Control Planes Config API reference](/api/konnect/control-planes-config/) to learn about region-specific URLs and personal access tokens. ### KIC ```yaml apiVersion: configuration.konghq.com/v1 kind: KongConsumerGroup metadata: name: { { include.presenter.data.name } } annotations: kubernetes.io/ingress.class: kong ``` ### Terraform ##### **Prerequisite:** Configure your Personal Access Token ```hcl terraform { required_providers { konnect = { source = "kong/konnect" } } } provider "konnect" { personal_access_token = "$KONNECT_TOKEN" server_url = "https://us.api.konghq.com/" } ``` Add the following to your Terraform configuration: ```hcl resource "konnect_gateway_consumer_group" "my_consumer_group" { control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id } ``` ## Schema ```json { "additionalProperties": false, "properties": { "created_at": { "description": "Unix epoch when the resource was created.", "nullable": true, "type": "integer" }, "id": { "description": "A string representing a UUID (universally unique identifier).", "nullable": true, "type": "string" }, "name": { "description": "The name of the consumer group.", "type": "string" }, "tags": { "description": "A set of strings representing tags.", "items": { "description": "A string representing a tag.", "type": "string" }, "nullable": true, "type": "array" }, "updated_at": { "description": "Unix epoch when the resource was last updated.", "nullable": true, "type": "integer" } }, "required": [ "name" ], "type": "object" } ``` ## FAQs - Why aren't Consumer Group overrides working anymore? 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. - How do I enable a plugin on a Consumer Group? First, [find out](/gateway/entities/plugin/#supported-scopes-by-plugin) 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. - When a Consumer is part of multiple Consumer Groups, how is precedence determined? Currently, this is determined by the Group name, in alphabetical order. For more details, see [Plugin precedence](/gateway/entities/plugin/#plugin-precedence). ## Related Resources - [Create rate limiting tiers with Kong Gateway](/how-to/add-rate-limiting-tiers-with-kong-gateway/) - [Consumer entity](/gateway/entities/consumer/) - [Plugins that can be scoped to Consumer Groups](/gateway/entities/plugin/#supported-scopes-by-plugin) - [Reserved entity names](/gateway/reserved-entity-names/) - [Konnect Control Plane resource limits](/gateway/control-plane-resource-limits/)