Consumers

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

What is a Consumer?

A Consumer is an entity that identifies an external client that consumes or uses the APIs managed by Kong Gateway. Consumers can represent applications, services, or users who interact with your APIs. Since they are not always human, Kong Gateway calls them Consumers, because they “consume” the service. Kong Gateway allows you to define and manage Consumers, apply access control policies, and monitor their API usage.

Consumers are essential for controlling access to your APIs, tracking usage, and ensuring security. They are identified by key authentication, OAuth, or other authentication and authorization mechanisms. For example, adding a Basic Auth plugin to a Gateway Service or Route allows it to identify a Consumer, or block access if credentials are invalid.

By attaching a plugin directly to a Consumer, you can manage specific controls at the Consumer level, such as rate limits.

Use cases for Consumers

Common use cases for Consumers:

Use case

Description

Authentication Client authentication is the most common reason for setting up a Consumer. If you’re using an authentication plugin, you’ll need a Consumer with credentials.
Rate limiting Rate limit specific Consumers based on tiers.
Transformation Add or remove values from response bodies based on the Consumer.

Centrally-managed Consumers v3.10+

Consumers can be scoped to a Konnect region and managed centrally, or be scoped to a Control Plane in Gateway Manager.

Centralized Consumer management provides the following benefits:

  • Set up a Consumer identity centrally: Only define a Consumer once, instead of defining it in multiple Control Planes.
  • Avoid conflicts from duplicate Consumer configuration: Users don’t need to replicate changes to Consumer identity in multiple Control Planes and Consumer configuration doesn’t conflict.
  • Reduce configuration sync issues between the Control Plane and the Data Planes: Consumers that are managed centrally aren’t part of the configuration that is pushed down from the Control Plane to the Data Planes, so it reduces config size and latency.

Centrally managed Consumers exist outside of Control Planes, so they can be used across Control Planes.

Use the following table to help you determine if you should use centrally-managed Consumers or Consumers scoped to Control Planes:

Centrally-managed Consumers Control Plane scoped Consumer
Share Consumer identity in more than one Control Plane
Supported authentication strategies Key auth All
Scope plugins directly to Consumer
Scope plugins to Consumer Groups

You can manage Consumers centrally using the Konnect Consumers API. Only Org Admins and Control Plane Admins have CRUD permissions for these Consumers.

When you create a Consumer centrally, you must assign it to a realm. A realm groups Consumers around an identity, defined by organizational boundaries, such as a production realm or a development realm. Realms are connected to a geographic region in Konnect. Additionally, centrally managed Consumers must have a specific Key Authentication configuration set up to allow these Consumers to authenticate.

For a complete tutorial, see Create a centrally-managed Consumer in Konnect.

Note: If you are using KIC to manage your Data Plane nodes in Konnect, ensure that you configure the cluster_telemetry_endpoint in the Data Plane. You can find your specific cluster_telemetry_endpoint in Gateway Manager, in the Data Plane node setup instructions.

Consumer schema

Set up a Consumer

FAQs

Did this doc help?

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!