Navigation :

Rate limiting setup

Learn about different setup options for rate limiting in Gloo Edge. For more information about how rate limiting works, see Rate limiting.

Before you begin

Create your environment, such as a Kubernetes cluster in a cloud provider.
Install Gloo Edge.
- Gloo Edge Enterprise: You can use all supported rate limiting APIs, including Envoy, Set-Style, and Gloo Edge. The Envoy-based rate limit server is automatically included in your installation.
- Gloo Edge Open Source: You can use only the Envoy API rate limiting. Additionally, you must build your own rate limit server.
Install a test app, such as Pet Store from the Hello World tutorial.
Optional (Enterprise-only): Configure your rate limiting server to change the defaults, such as to update the query behavior or to use a different backing database.

Decide which rate limiting API to use

Depending on the type of Gloo Edge that you installed, you have multiple options for rate limiting.

Rate limiting API Supported Product Description

Rate limiting API	Supported Product	Description
Envoy API	Gloo Edge Open Source or Enterprise	To use the Envoy rate limiting API, you configure descriptors (required key and optional value pairs to attach to a request) and actions (counters to use for the request). The order of descriptors matter, and requests are only limited if the ordered descriptors match a rule exactly. For example, say that you want to have two different rate limiting behaviors for requests: Limit requests with an `x-type` header. Limit requests with both `x-type` and `x-number: 5` headers. To set this rate limiting up, you must have two corresponding actions: Get only the value of `x-type` header. Get the values of both the `x-type` and `x-number` headers. This approach lets you set up many rate limiting use cases. As such, the Envoy API is well-suited for any of your rate limiting needs, but you might choose a different API style if you have more complex (set-style) or simpler (Gloo Edge) use cases.
Set-Style API	Gloo Edge Enterprise	Like the Envoy API, the set-style API is based on descriptors (`setDescriptors`) and actions (`setActions`). Unlike the Envoy API, the set-style descriptors are unordered and can be used in combination with other descriptors. For example, you might set up a wildcard matching rule to rate limit requests with: An `x-type: a` header. An `x-number: 1` header. Any `x-color` header (`x-color: *`). At scale, this approach is more flexible than the Envoy API approach. You can also use Envoy and set-style APIs together.
Gloo Edge API	Gloo Edge Enterprise	For simple rate limiting per route or host, you can use the Gloo Edge rate limiting API. In this approach, you do not have to set up complicated descriptors and actions. Instead, you simply specify the requests per unit and time unit for each route or host directly within the virtual service resource. You can also have different rate limiting behavior for authorized versus anonymous requests.

Envoy API

Gloo Edge Open Source or Enterprise

To use the Envoy rate limiting API, you configure descriptors (required key and optional value pairs to attach to a request) and actions (counters to use for the request). The order of descriptors matter, and requests are only limited if the ordered descriptors match a rule exactly. For example, say that you want to have two different rate limiting behaviors for requests:

Limit requests with an x-type header.
Limit requests with both x-type and x-number: 5 headers.

To set this rate limiting up, you must have two corresponding actions:

Get only the value of x-type header.
Get the values of both the x-type and x-number headers.

This approach lets you set up many rate limiting use cases. As such, the Envoy API is well-suited for any of your rate limiting needs, but you might choose a different API style if you have more complex (set-style) or simpler (Gloo Edge) use cases.

Set-Style API

Gloo Edge Enterprise

Like the Envoy API, the set-style API is based on descriptors (setDescriptors) and actions (setActions). Unlike the Envoy API, the set-style descriptors are unordered and can be used in combination with other descriptors. For example, you might set up a wildcard matching rule to rate limit requests with:

An x-type: a header.
An x-number: 1 header.
Any x-color header (x-color: *).

At scale, this approach is more flexible than the Envoy API approach. You can also use Envoy and set-style APIs together.

Gloo Edge API Gloo Edge Enterprise For simple rate limiting per route or host, you can use the Gloo Edge rate limiting API. In this approach, you do not have to set up complicated descriptors and actions. Instead, you simply specify the requests per unit and time unit for each route or host directly within the virtual service resource. You can also have different rate limiting behavior for authorized versus anonymous requests.

Implement rate limiting

Depending on the rate limiting API that you chose to use, you have several options on how to implement rate limiting in your Gloo Edge routing, host, and settings resources.

Envoy or Set-Style API
Gloo Edge API

For testing purposes, the following examples across all rate limiting API styles apply a limit of one request per minute. You can update the examples with the descriptors and actions that you configured in the previous section.

Envoy or Set-Style API

Choose between two implementation approaches:

Enterprise-only: In the RateLimitConfig resource. The Gloo Edge RateLimitConfig custom resource is a flexible way to keep together and reuse your rate limiting descriptors and actions across virtual services. This approach is more flexible at scale, and less likely to cause errors in configuring your resources.
Open Source or Enterprise: In separate Gloo Edge resources. You configure descriptors in the Gloo Edge Settings for the entire cluster. Then, you configure the actions directly in each VirtualService that you want to rate limit. This approach is not as flexible at scale. Also, because you have to edit the Settings and VirtualServices resources more extensively, you might be likelier to make a configuration error or encounter merge conflicts if multiple people edit a configuration at once. If you use Gloo Edge Open Source, you must take this implementation approach.

In the RateLimitConfig resource

The Gloo Edge RateLimitConfig custom resource is a flexible way to keep together and reuse your rate limiting descriptors and actions across virtual services. This approach is available only with a Gloo Edge Enterprise license.

Define the descriptors and actions in the RateLimitConfig resource. For more information, see RateLimitConfigs (Enterprise).

kubectl apply -f - <<EOF
apiVersion: ratelimit.solo.io/v1alpha1
kind: RateLimitConfig
metadata:
  name: my-rate-limit-policy
  namespace: gloo-system
spec:
  raw:
    descriptors:
    - key: generic_key
      value: counter
      rateLimit:
        requestsPerUnit: 1
        unit: MINUTE
    rateLimits:
    - actions:
      - genericKey:
          descriptorValue: counter
EOF

Refer to the RateLimitConfig in each VirtualService that you want to rate limit. The following example updates the default virtual service that you created when you installed the sample Pet Store app.

Get the virtual service configuration file.

kubectl get vs default -n gloo-system -o yaml > vs.yaml

Refer to the rate limit config that you previously created for all the routes in the virtual host or on a per-route basis.

All routes in the virtual host
Per route

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: default
  namespace: gloo-system
spec:
  virtualHost:
    domains:
    - '*'
    routes:
    - matchers:
      - exact: /all-pets
      options:
        prefixRewrite: /api/pets
      routeAction:
        single:
          upstream:
            name: default-petstore-8080
            namespace: gloo-system
    options:
      rateLimitConfigs:
        refs:
        - name: my-rate-limit-policy
          namespace: gloo-system

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: default
  namespace: gloo-system
spec:
  virtualHost:
    domains:
    - '*'
    routes:
    - matchers:
      - exact: /all-pets
      options:
        prefixRewrite: /api/pets
        rateLimitConfigs:
          refs:
          - name: my-rate-limit-policy
            namespace: gloo-system
      routeAction:
        single:
          upstream:
            name: default-petstore-8080
            namespace: gloo-system

Apply the updated virtual service.

kubectl apply -n gloo-system -f vs.yaml

Verify that the virtual service status is Accepted. If not, review the error message and update the virtual service. For example, you might have a missing resource, such as an upstream.
```
kubectl describe vs default -n gloo-system
```

In separate resources

You can configure descriptors in the Gloo Edge Settings for the entire cluster. Then, you configure the actions directly in each VirtualService that you want to rate limit. If you have an Enterprise license, consider using a RateLimitConfig resource instead. If you have an Open Source license, you must take this approach for Envoy API rate limiting.

Define the rate limit descriptors in the Settings resource.

Create a file with your rate limit descriptors.

cat > settings-rl-patch.yaml - <<EOF
spec:
  ratelimit:
    descriptors:
      - key: generic_key
        value: "per-minute"
        rateLimit:
          requestsPerUnit: 1
          unit: MINUTE
EOF

Patch the default settings in the gloo-system namespace.

kubectl patch -n gloo-system settings default --type merge --patch "$(cat settings-rl-patch.yaml)"

Define the actions in each VirtualService resource. You can apply actions at the virtual host level to apply to all routes or per route.

Create a file with your rate limit actions.

All routes in the virtual host
Per route

cat > vs-host-patch.yaml - <<EOF
spec:
  virtualHost:
    options:
      ratelimit:
        rateLimits:
          - actions:
              - genericKey:
                  descriptorValue: "per-minute"
EOF

cat > vs-route-patch.yaml - <<EOF
        options:
          ratelimit:
            rateLimits:
              - actions:
                  - genericKey:
                      descriptorValue: "per-minute"
EOF

Patch the virtual service that you want to rate limit.

All routes in the virtual host
Per route

kubectl patch -n gloo-system vs default --type merge --patch "$(cat vs-host-patch.yaml)"

kubectl patch -n gloo-system vs default --type merge --patch "$(cat vs-route-patch.yaml)"

Verify that the virtual service status is Accepted. If not, review the error message and update the virtual service. For example, you might have a missing resource, such as an upstream.
```
kubectl describe vs default -n gloo-system
```

Gloo Edge API

To apply basic Gloo Edge rate limiting, update the virtual service. You can apply rate limiting at the virtual host level to apply to all routes or per route. This approach is a simple way to meet your basic rate limiting needs, and is available only with a Gloo Edge Enterprise license.

Create a file with your basic Gloo Edge rate limiting configuration.

All routes in the virtual host
Per route

cat > vs-host-patch.yaml - <<EOF
    options:
      ratelimitBasic:
        anonymous_limits:
          requests_per_unit: 1
          unit: MINUTE
        authorized_limits:
          requests_per_unit: 1000
          unit: SECOND
EOF

cat > vs-route-patch.yaml - <<EOF
        options:
          ratelimitBasic:
            anonymous_limits:
              requests_per_unit: 1
              unit: MINUTE
            authorized_limits:
              requests_per_unit: 1000
              unit: SECOND
EOF

Patch the virtual service that you want to rate limit.

All routes in the virtual host
Per route

kubectl patch -n gloo-system vs default --type merge --patch "$(cat > vs-host-patch.yaml)"

kubectl patch -n gloo-system vs default --type merge --patch "$(cat > vs-route-patch.yaml)"

Verify that the virtual service status is Accepted. If not, review the error message and update the virtual service. For example, you might have a missing resource, such as an upstream.
```
kubectl describe vs default -n gloo-system
```

Next steps

Now that you know the basic steps to set up rate limiting, you might explore the following options.

Use rate limiting metrics or access logs to improve rate limiting.
Try out more examples of the Envoy, Set-Style, and Gloo Edge rate limiting API.
Explore other ways to secure network traffic with Gloo Edge.