代码拉取完成，页面将自动刷新
Gubernator is a distributed, high performance, cloud native and stateless rate-limiting service.
Gubernator is stateless in that it doesn’t require disk space to operate. No configuration or cache data is ever synced to disk. This is because every request to gubernator includes the config for the rate limit. At first you might think this an unnecessary overhead to each request. However, In reality a rate limit config is made up of only 4, 64bit integers.
# Download the docker-compose file
$ curl -O https://raw.githubusercontent.com/mailgun/gubernator/master/docker-compose.yaml
# Run the docker container
$ docker-compose up -d
Now you can make rate limit requests via CURL
# Hit the HTTP API at localhost:9080 (GRPC is at 9081)
$ curl http://localhost:9080/v1/HealthCheck
# Make a rate limit request
$ curl http://localhost:9080/v1/GetRateLimits \
--header 'Content-Type: application/json' \
--data '{
"requests": [
{
"name": "requests_per_sec",
"uniqueKey": "account:12345",
"hits": "1",
"limit": "10",
"duration": "1000"
}
]
}'
An example rate limit request sent via GRPC might look like the following
rate_limits:
# Scopes the request to a specific rate limit
- name: requests_per_sec
# A unique_key that identifies this instance of a rate limit request
unique_key: account_id=123|source_ip=172.0.0.1
# The number of hits we are requesting
hits: 1
# The total number of requests allowed for this rate limit
limit: 100
# The duration of the rate limit in milliseconds
duration: 1000
# The algorithm used to calculate the rate limit
# 0 = Token Bucket
# 1 = Leaky Bucket
algorithm: 0
# The behavior of the rate limit in gubernator.
# 0 = BATCHING (Enables batching of requests to peers)
# 1 = NO_BATCHING (Disables batching)
# 2 = GLOBAL (Enable global caching for this rate limit)
behavior: 0
An example response would be
rate_limits:
# The status of the rate limit. OK = 0, OVER_LIMIT = 1
- status: 0,
# The current configured limit
limit: 10,
# The number of requests remaining
remaining: 7,
# A unix timestamp in milliseconds of when the bucket will reset, or if
# OVER_LIMIT is set it is the time at which the rate limit will no
# longer return OVER_LIMIT.
reset_time: 1551309219226,
# Additional metadata about the request the client might find useful
metadata:
# This is the name of the coordinator that rate limited this request
"owner": "api-n03.staging.us-east-1.mailgun.org:9041"
Gubernator currently supports 2 rate limit algorithms.
Token Bucket implementation starts with an empty bucket, then each Hit
adds a token to the bucket until the bucket is full. Once the bucket is
full, requests will return OVER_LIMIT until the reset_time is reached at
which point the bucket is emptied and requests will return UNDER_LIMIT.
This algorithm is useful for enforcing very bursty limits. (IE: Applications
where a single request can add more than 1 hit to the bucket; or non network
based queuing systems.) The downside to this implementation is that once you
have hit the limit no more requests are allowed until the configured rate
limit duration resets the bucket to zero.
Leaky Bucket is implemented
similarly to Token Bucket where OVER_LIMIT is returned when the bucket
is full. However tokens leak from the bucket at a consistent rate which is
calculated as duration / limit. This algorithm is useful for metering, as
the bucket leaks allowing traffic to continue without the need to wait for
the configured rate limit duration to reset the bucket to zero.
In our production environment, for every request to our API we send 2 rate limit requests to gubernator for rate limit evaluation, one to rate the HTTP request and the other is to rate the number of recipients a user can send an email too within the specific duration. Under this setup a single gubernator node fields over 2,000 requests a second with most batched responses returned in under 1 millisecond.
Peer requests forwarded to owning nodes typically respond in under 30 microseconds.
NOTE The above graphs only report the slowest request within the 1 second sample time. So you are seeing the slowest requests that gubernator fields to clients.
Gubernator allows users to choose non-batching behavior which would further reduce latency for client rate limit requests. However because of throughput requirements our production environment uses Behaviour=BATCHING with the default 500 microsecond window. In production we have observed batch sizes of 1,000 during peak API usage. Other users who don’t have the same high traffic demands could disable batching and would see lower latencies but at the cost of throughput.
Users may choose a behavior called DURATION_IS_GREGORIAN which changes the
behavior of the Duration field. When Behavior is set to DURATION_IS_GREGORIAN
the Duration of the rate limit is reset whenever the end of selected gregorian
calendar interval is reached.
This is useful when you want to impose daily or monthly limits on a resource. Using this behavior you know when the end of the day or month is reached the limit on the resource is reset regardless of when the first rate limit request was received by Gubernator.
Given the following Duration values
Examples when using Behavior = DURATION_IS_GREGORIAN
Duration = 2 (Days) then the rate limit will reset to Current = 0 at the end of the current day the rate limit was created.Duration = 0 (Minutes) then the rate limit will reset to Current = 0 at the end of the minute the rate limit was created.Duration = 4 (Months) then the rate limit will reset to Current = 0 at the end of the month the rate limit was created.Users may add behavior Behavior_RESET_REMAINING to the rate check request.
This will reset the rate limit as if created new on first use.
When using Reset Remaining, the Hits field should be 0.
Users may add behavior Behavior_DRAIN_OVER_LIMIT to the rate check request.
A GetRateLimits call drains the remaining counter on first over limit event.
Then, successive GetRateLimits calls will return zero remaining counter and
not any residual value. This behavior works best with token bucket algorithm
because the Remaining counter will stay zero after an over limit until reset
time, whereas leaky bucket algorithm will immediately update Remaining to a
non-zero value.
This facilitates scenarios that require an over limit event to stay over limit
until the rate limit resets. This approach is necessary if a process must make
two rate checks, before and after a process, and the Hit amount is not known
until after the process.
GetRateLimits with Hits=0 to check the value of
Remaining counter. If Remaining is zero, it's known
that the rate limit is depleted and the process can be aborted.GetRateLimits with a user specified Hits value. If
the call returns over limit, the process cannot be aborted because it had
already completed. Using DRAIN_OVER_LIMIT behavior, the Remaining count
will be drained to zero.Once an over limit occurs in the "After" step, successive processes will detect the over limit state in the "Before" step.
If you are using golang, you can use Gubernator as a library. This is useful if
you wish to implement a rate limit service with your own company specific model
on top. We do this internally here at mailgun with a service we creatively
called ratelimits which keeps track of the limits imposed on a per account
basis. In this way you can utilize the power and speed of Gubernator but still
layer business logic and integrate domain specific problems into your rate
limiting service.
When you use the library, your service becomes a full member of the cluster
participating in the same consistent hashing and caching as a stand alone
Gubernator server would. All you need to do is provide the GRPC server instance
and tell Gubernator where the peers in your cluster are located. The
cmd/gubernator/main.go is a great example of how to use Gubernator as a
library.
While the Gubernator server currently doesn't directly support disk
persistence, the Gubernator library does provide interfaces through which
library users can implement persistence. The Gubernator library has two
interfaces available for disk persistence. Depending on the use case an
implementor can implement the Loader interface and only support persistence
of rate limits at startup and shutdown, or users can implement the Store
interface and Gubernator will continuously call OnChange() and Get() to
keep the in memory cache and persistent store up to date with the latest rate
limit data. Both interfaces can be implemented simultaneously to ensure data
is always saved to persistent storage.
For those who choose to implement the Store interface, it is not required to
store ALL the rate limits received via OnChange(). For instance; If you wish
to support rate limit durations longer than a minute, day or month, calls to
OnChange() can check the duration of a rate limit and decide to only persist
those rate limits that have durations over a self determined limit.
All methods are accessed via GRPC but are also exposed via HTTP using the GRPC Gateway
Health check returns unhealthy in the event a peer is reported by etcd or kubernetes
as up but the server instance is unable to contact that peer via it's advertised address.
rpc HealthCheck (HealthCheckReq) returns (HealthCheckResp)
GET /v1/HealthCheck
Example response:
{
"status": "healthy",
"peer_count": 3
}
Rate limits can be applied or retrieved using this interface. If the client
makes a request to the server with hits: 0 then current state of the rate
limit is retrieved but not incremented.
rpc GetRateLimits (GetRateLimitsReq) returns (GetRateLimitsResp)
POST /v1/GetRateLimits
Example Payload
{
"requests": [
{
"name": "requests_per_sec",
"uniqueKey": "account:12345",
"hits": "1",
"limit": "10",
"duration": "1000"
}
]
}
Example response:
{
"responses": [
{
"status": "UNDER_LIMIT",
"limit": "10",
"remaining": "9",
"reset_time": "1690855128786",
"error": "",
"metadata": {
"owner": "gubernator:81"
}
}
]
}
NOTE: Gubernator uses etcd, Kubernetes or round-robin DNS to discover peers and
establish a cluster. If you don't have either, the docker-compose method is the
simplest way to try gubernator out.
$ docker run -p 8081:81 -p 9080:80 -e GUBER_ETCD_ENDPOINTS=etcd1:2379,etcd2:2379 \
ghcr.io/mailgun/gubernator:latest
# Hit the HTTP API at localhost:9080
$ curl http://localhost:9080/v1/HealthCheck
# Download the kubernetes deployment spec
$ curl -O https://raw.githubusercontent.com/mailgun/gubernator/master/k8s-deployment.yaml
# Edit the deployment file to change the environment config variables
$ vi k8s-deployment.yaml
# Create the deployment (includes headless service spec)
$ kubectl create -f k8s-deployment.yaml
If your DNS service supports auto-registration, for example AWS Route53 service discovery,
you can use same fully-qualified domain name to both let your business logic containers or
instances to find gubernator and for gubernator containers/instances to find each other.
Gubernator supports TLS for both HTTP and GRPC connections. You can see an example with
self signed certs by running docker-compose-tls.yaml
# Run docker compose
$ docker-compose -f docker-compose-tls.yaml up -d
# Hit the HTTP API at localhost:9080 (GRPC is at 9081)
$ curl --cacert certs/ca.cert --cert certs/gubernator.pem --key certs/gubernator.key https://localhost:9080/v1/HealthCheck
Gubernator is configured via environment variables with an optional --config flag
which takes a file of key/values and places them into the local environment before startup.
See the example.conf for all available config options and their descriptions.
See architecture.md for a full description of the architecture and the inner workings of gubernator.
Gubernator publishes Prometheus metrics for realtime monitoring. See prometheus.md for details.
Gubernator supports OpenTelemetry. See tracing.md for details.
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
1. 开源生态
2. 协作、人、软件
3. 评估模型