Usage plans describe the combination of policies that control how much end users can use your APIs products.

About usage plans

Usage plans describe two main restrictions for end users:

  • Rate limiting: Control how many requests within a time period are allowed to your APIs, such as 100 requests per minute.
  • External auth: Require users to authenticate through an API key to access your APIs. Later, you can use the developer portal to generate these API keys that you give to your users.

You might prepare several usage plans that reflect your product pricing, such as a free plan that requires no external auth but is limited to 10 requests a day, or an unlimited plan that has no rate limiting but strict external auth. The following examples in this guide set up rate limiting for three usage plans as follows.

  • Bronze: Requests to your APIs are limited to 1 per minute.
  • Silver: Requests to your APIs are limited to 3 per minute.
  • Gold: Requests to your APIs are limited to 5 per minute.

Gloo implementation for usage plans

To implement usage plans for your API products, you combine several Gloo custom resources as shown in the following diagram.

Figure: Usage plan implementation overview
Figure: Usage plan implementation overview
Figure: Usage plan implementation overview
Figure: Usage plan implementation overview

  1. Backend setup: As part of the Gloo Platform installation, the platform admin sets up the required components to run Portal. These components relate to usage plans as follows. For more setup information, see Administer the portal.
    • The rate-limiter deployment runs the server that you use for the rate limiting rules in your usage plan.
    • The ext-auth-service deployment runs the server that you use to enforce API key external authentication for your usage plan.
    • The gloo-mesh-portal-server deployment runs the server that exposes the Portal API you use to build a frontend developer portal. The Portal resource that configures the server refers to the usage plans that you set up in the RateLimitServerConfig. Your end users can see and generate API keys for the APIs based on the usage plans that they have access to.
    • The redis deployment can be a local Redis instance that Gloo installs by default, or an external Redis in your own cloud provider. You must configure the portal and external auth servers to use the same backing Redis to read and write API keys from.
  2. Rate limit setup: Rate limiting resources form the core of your usage plan. These resources are used to control how many requests within a time period are allowed to your API products, such as 100 requests per minute. For more information about how these resource work together, see Rate limit. To set up rate limiting, see Set rate limits for your API products.
    • The RateLimitServerSettings resource selects the backing rate limiter to use.
    • The RateLimitClientConfig resource configures the action to take for the usage plan descriptor that you set up in the RateLimitServerConfig. The action uses the API key external auth from the request header that you enforce with the ExtAuthPolicy.
    • The RateLimitServerConfig resource configures the descriptors for each usage plan that you want to set up, such as bronze, silver, and gold. Each usage plan has different rate limits, such as 1 request per minute.
    • The RateLimitPolicy resource tells the rate limiter to use the other rate limiting resources that you previously configured. You apply the policy via labels to the routes of your APIs in the API product’s route table.
  3. Ext auth setup: External auth secures your API products by requiring that users authenticate. Additional details from the external auth, such as user IDs and usage plans, are passed along in authenticated requests in the X-Solo-Plan header (or whatever you set the header name to). These details can be used to enforce rate limiting on the requests. Just as with rate limiting, you apply the policy via labels to the routes of your APIs in the API product’s route table. You have the following options for external auth:
  4. Portal setup: The Portal resource collects the details about the usage plans and API products that you previously created. Later, this information is shown to end users in the frontend developer portal that you create. For more information, see Configure the developer portal and Build a developer portal frontend.
  5. API setup: The policies that make up your usage plans are applied to the API products that you previously set up. For more information, see Create your API products.

Next steps