1// Copyright 2018 the Istio Authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17// $title: Redis Quota
18// $description: Adapter for a Redis-based quota management system.
19// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/redisquota.html
20// $supported_templates: quota
21// $aliases:
22// $  - /docs/reference/config/adapters/redisquota.html
23
24// The `redisquota` adapter can be used to support Istio's quota management
25// system. It depends on a Redis server to store quota values.
26//
27// This adapter supports the [quota template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/quota/).
28package adapter.redisquota.config;
29
30import "google/protobuf/duration.proto";
31import "gogoproto/gogo.proto";
32
33option go_package = "config";
34option (gogoproto.goproto_getters_all) = false;
35option (gogoproto.equal_all) = false;
36option (gogoproto.gostring_all) = false;
37
38// redisquota adapter supports the rate limit quota using either fixed or
39// rolling window algorithm. And it is using Redis as a shared data storage.
40//
41// Example configuration:
42//
43// ```yaml
44// redisServerUrl: localhost:6379
45// connectionPoolSize: 10
46// quotas:
47// - name: requestcount.quota.istio-system
48//   maxAmount: 50
49//   validDuration: 60s
50//   bucketDuration: 1s
51//   rateLimitAlgorithm: ROLLING_WINDOW
52//   overrides:
53//   - dimensions:
54//       destination: ratings
55//       source: reviews
56//     maxAmount: 12
57//   - dimensions:
58//       destination: reviews
59//     maxAmount: 5
60// ```
61message Params {
62  message Override {
63    option (gogoproto.goproto_getters) = true;
64
65    // The specific dimensions for which this override applies.
66    // String representation of instance dimensions is used to check against configured dimensions.
67    // `dimensions` should not be empty
68    map <string, string> dimensions = 1 [(gogoproto.nullable) = false];
69
70    // The upper limit for this quota override.
71    // This value should be bigger than 0
72    int64 max_amount = 2;
73  }
74
75  // Algorithms for rate-limiting:
76  enum QuotaAlgorithm {
77    // `FIXED_WINDOW` The fixed window approach can allow 2x peak specified rate, whereas the rolling-window doesn't.
78    FIXED_WINDOW = 0;
79    // `ROLLING_WINDOW` The rolling window algorithm's additional precision comes at the cost of increased redis resource usage.
80    ROLLING_WINDOW = 1;
81  }
82
83  message Quota {
84    option (gogoproto.goproto_getters) = true;
85
86    // The name of the quota
87    string name = 1;
88
89    // The upper limit for this quota. max_amount should be bigger than 0
90    int64 max_amount = 2;
91
92    // The amount of time allocated quota remains valid before it is
93    // automatically released. This is only meaningful for rate limit quotas.
94    // value should be `0 < validDuration`
95    google.protobuf.Duration valid_duration = 3 [(gogoproto.nullable) = false, (gogoproto.stdduration) = true];
96
97    // The `bucketDuration` will be ignored if `rateLimitAlgorithm` is `FIXED_WINDOW`
98    // value should be `0 < bucketDuration < validDuration`
99    google.protobuf.Duration bucket_duration = 4 [(gogoproto.nullable) = false, (gogoproto.stdduration) = true];
100
101    // Quota management algorithm. The default value is `FIXED_WINDOW`
102    QuotaAlgorithm rate_limit_algorithm = 5;
103
104    // Overrides associated with this quota.
105    // The first matching override is applied.
106    repeated Override overrides = 6;
107  }
108
109  // The set of known quotas. At least one quota configuration is required
110  repeated Quota quotas = 1 [(gogoproto.nullable) = false];
111
112  // Redis connection string `<hostname>:<port number>`
113  // ex) localhost:6379
114  string redis_server_url = 2;
115
116  // Maximum number of idle connections to redis
117  // Default is 10 connections per every CPU as reported by runtime.NumCPU.
118  int64 connection_pool_size = 3;
119}
120