Consumer Groups

Uses: Kong Gateway Admin API decK KIC Konnect API Terraform

What is a Consumer Group?

Consumer Groups enable the organization and categorization of Consumers (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.

For example, you could define two groups, Gold and Silver, assign different rate limits to them, then process each group using a different plugin:

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:

Use case	Description
Managing permissions	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	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	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	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.

Schema

* Additional properties are NOT allowed.

created_atinteger

Unix epoch when the resource was created.

idstring

namestringrequired

tagsarray[string]

updated_atinteger

Unix epoch when the resource was last updated.

Set up a Consumer Group

The following creates a new Consumer Group called my_group:

_format_version: "3.0"
consumer_groups:
  - name: my_group

Copied to clipboard!

To create a Consumer Group, call the Admin API’s /consumer_groups endpoint.

curl -i -X POST http://localhost:8001/consumer_groups/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "my_group"
    }
    '

      
        
      
    
Copied to clipboard!

To create a Consumer Group, call the Konnect control plane config API’s /consumer_groups endpoint.

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"
    }
    '

      
        
      
    
Copied to clipboard!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

apiVersion: configuration.konghq.com/v1
kind: KongConsumerGroup
metadata:
  name: { { include.presenter.data.name } }
  annotations:
    kubernetes.io/ingress.class: kong

Copied to clipboard!

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

      
        
      
    
Copied to clipboard!

resource "konnect_gateway_consumer_group" "my_consumer_group" {
  
  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied to clipboard!

FAQs

Why aren’t Consumer Group overrides working anymore?

How do I enable a plugin on a Consumer Group?

When a Consumer is part of multiple Consumer Groups, how is precedence determined?

Consumer Groups

What is a Consumer Group?

Use cases

Schema

Set up a Consumer Group

FAQs

Did this doc help?

Help us make these docs great!

Still need help