1/*
2Copyright 2017 The Kubernetes Authors.
3
4Licensed under the Apache License, Version 2.0 (the "License");
5you may not use this file except in compliance with the License.
6You may obtain a copy of the License at
7
8    http://www.apache.org/licenses/LICENSE-2.0
9
10Unless required by applicable law or agreed to in writing, software
11distributed under the License is distributed on an "AS IS" BASIS,
12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13See the License for the specific language governing permissions and
14limitations under the License.
15*/
16
17package eventratelimit
18
19import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
20
21// LimitType is the type of the limit (e.g., per-namespace)
22type LimitType string
23
24const (
25	// ServerLimitType is a type of limit where there is one bucket shared by
26	// all of the event queries received by the API Server.
27	ServerLimitType LimitType = "Server"
28	// NamespaceLimitType is a type of limit where there is one bucket used by
29	// each namespace
30	NamespaceLimitType LimitType = "Namespace"
31	// UserLimitType is a type of limit where there is one bucket used by each
32	// user
33	UserLimitType LimitType = "User"
34	// SourceAndObjectLimitType is a type of limit where there is one bucket used
35	// by each combination of source and involved object of the event.
36	SourceAndObjectLimitType LimitType = "SourceAndObject"
37)
38
39// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
40
41// Configuration provides configuration for the EventRateLimit admission
42// controller.
43type Configuration struct {
44	metav1.TypeMeta `json:",inline"`
45
46	// limits are the limits to place on event queries received.
47	// Limits can be placed on events received server-wide, per namespace,
48	// per user, and per source+object.
49	// At least one limit is required.
50	Limits []Limit `json:"limits"`
51}
52
53// Limit is the configuration for a particular limit type
54type Limit struct {
55	// type is the type of limit to which this configuration applies
56	Type LimitType `json:"type"`
57
58	// qps is the number of event queries per second that are allowed for this
59	// type of limit. The qps and burst fields are used together to determine if
60	// a particular event query is accepted. The qps determines how many queries
61	// are accepted once the burst amount of queries has been exhausted.
62	QPS int32 `json:"qps"`
63
64	// burst is the burst number of event queries that are allowed for this type
65	// of limit. The qps and burst fields are used together to determine if a
66	// particular event query is accepted. The burst determines the maximum size
67	// of the allowance granted for a particular bucket. For example, if the burst
68	// is 10 and the qps is 3, then the admission control will accept 10 queries
69	// before blocking any queries. Every second, 3 more queries will be allowed.
70	// If some of that allowance is not used, then it will roll over to the next
71	// second, until the maximum allowance of 10 is reached.
72	Burst int32 `json:"burst"`
73
74	// cacheSize is the size of the LRU cache for this type of limit. If a bucket
75	// is evicted from the cache, then the allowance for that bucket is reset. If
76	// more queries are later received for an evicted bucket, then that bucket
77	// will re-enter the cache with a clean slate, giving that bucket a full
78	// allowance of burst queries.
79	//
80	// The default cache size is 4096.
81	//
82	// If limitType is 'server', then cacheSize is ignored.
83	// +optional
84	CacheSize int32 `json:"cacheSize,omitempty"`
85}
86