1/*
2Copyright 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
17
18// This file was autogenerated by go-to-protobuf. Do not edit it manually!
19
20syntax = "proto2";
21
22package k8s.io.api.flowcontrol.v1beta2;
23
24import "k8s.io/apimachinery/pkg/apis/meta/v1/generated.proto";
25import "k8s.io/apimachinery/pkg/runtime/generated.proto";
26import "k8s.io/apimachinery/pkg/runtime/schema/generated.proto";
27
28// Package-wide variables from generator "generated".
29option go_package = "k8s.io/api/flowcontrol/v1beta2";
30
31// ExemptPriorityLevelConfiguration describes the configurable aspects
32// of the handling of exempt requests.
33// In the mandatory exempt configuration object the values in the fields
34// here can be modified by authorized users, unlike the rest of the `spec`.
35message ExemptPriorityLevelConfiguration {
36 // `nominalConcurrencyShares` (NCS) contributes to the computation of the
37 // NominalConcurrencyLimit (NominalCL) of this level.
38 // This is the number of execution seats nominally reserved for this priority level.
39 // This DOES NOT limit the dispatching from this priority level
40 // but affects the other priority levels through the borrowing mechanism.
41 // The server's concurrency limit (ServerCL) is divided among all the
42 // priority levels in proportion to their NCS values:
43 //
44 // NominalCL(i) = ceil( ServerCL * NCS(i) / sum_ncs )
45 // sum_ncs = sum[priority level k] NCS(k)
46 //
47 // Bigger numbers mean a larger nominal concurrency limit,
48 // at the expense of every other priority level.
49 // This field has a default value of zero.
50 // +optional
51 optional int32 nominalConcurrencyShares = 1;
52
53 // `lendablePercent` prescribes the fraction of the level's NominalCL that
54 // can be borrowed by other priority levels. This value of this
55 // field must be between 0 and 100, inclusive, and it defaults to 0.
56 // The number of seats that other levels can borrow from this level, known
57 // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows.
58 //
59 // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 )
60 //
61 // +optional
62 optional int32 lendablePercent = 2;
63}
64
65// FlowDistinguisherMethod specifies the method of a flow distinguisher.
66message FlowDistinguisherMethod {
67 // `type` is the type of flow distinguisher method
68 // The supported types are "ByUser" and "ByNamespace".
69 // Required.
70 optional string type = 1;
71}
72
73// FlowSchema defines the schema of a group of flows. Note that a flow is made up of a set of inbound API requests with
74// similar attributes and is identified by a pair of strings: the name of the FlowSchema and a "flow distinguisher".
75message FlowSchema {
76 // `metadata` is the standard object's metadata.
77 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
78 // +optional
79 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
80
81 // `spec` is the specification of the desired behavior of a FlowSchema.
82 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
83 // +optional
84 optional FlowSchemaSpec spec = 2;
85
86 // `status` is the current status of a FlowSchema.
87 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
88 // +optional
89 optional FlowSchemaStatus status = 3;
90}
91
92// FlowSchemaCondition describes conditions for a FlowSchema.
93message FlowSchemaCondition {
94 // `type` is the type of the condition.
95 // Required.
96 optional string type = 1;
97
98 // `status` is the status of the condition.
99 // Can be True, False, Unknown.
100 // Required.
101 optional string status = 2;
102
103 // `lastTransitionTime` is the last time the condition transitioned from one status to another.
104 optional k8s.io.apimachinery.pkg.apis.meta.v1.Time lastTransitionTime = 3;
105
106 // `reason` is a unique, one-word, CamelCase reason for the condition's last transition.
107 optional string reason = 4;
108
109 // `message` is a human-readable message indicating details about last transition.
110 optional string message = 5;
111}
112
113// FlowSchemaList is a list of FlowSchema objects.
114message FlowSchemaList {
115 // `metadata` is the standard list metadata.
116 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
117 // +optional
118 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
119
120 // `items` is a list of FlowSchemas.
121 repeated FlowSchema items = 2;
122}
123
124// FlowSchemaSpec describes how the FlowSchema's specification looks like.
125message FlowSchemaSpec {
126 // `priorityLevelConfiguration` should reference a PriorityLevelConfiguration in the cluster. If the reference cannot
127 // be resolved, the FlowSchema will be ignored and marked as invalid in its status.
128 // Required.
129 optional PriorityLevelConfigurationReference priorityLevelConfiguration = 1;
130
131 // `matchingPrecedence` is used to choose among the FlowSchemas that match a given request. The chosen
132 // FlowSchema is among those with the numerically lowest (which we take to be logically highest)
133 // MatchingPrecedence. Each MatchingPrecedence value must be ranged in [1,10000].
134 // Note that if the precedence is not specified, it will be set to 1000 as default.
135 // +optional
136 optional int32 matchingPrecedence = 2;
137
138 // `distinguisherMethod` defines how to compute the flow distinguisher for requests that match this schema.
139 // `nil` specifies that the distinguisher is disabled and thus will always be the empty string.
140 // +optional
141 optional FlowDistinguisherMethod distinguisherMethod = 3;
142
143 // `rules` describes which requests will match this flow schema. This FlowSchema matches a request if and only if
144 // at least one member of rules matches the request.
145 // if it is an empty slice, there will be no requests matching the FlowSchema.
146 // +listType=atomic
147 // +optional
148 repeated PolicyRulesWithSubjects rules = 4;
149}
150
151// FlowSchemaStatus represents the current state of a FlowSchema.
152message FlowSchemaStatus {
153 // `conditions` is a list of the current states of FlowSchema.
154 // +listType=map
155 // +listMapKey=type
156 // +optional
157 repeated FlowSchemaCondition conditions = 1;
158}
159
160// GroupSubject holds detailed information for group-kind subject.
161message GroupSubject {
162 // name is the user group that matches, or "*" to match all user groups.
163 // See https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/user/user.go for some
164 // well-known group names.
165 // Required.
166 optional string name = 1;
167}
168
169// LimitResponse defines how to handle requests that can not be executed right now.
170// +union
171message LimitResponse {
172 // `type` is "Queue" or "Reject".
173 // "Queue" means that requests that can not be executed upon arrival
174 // are held in a queue until they can be executed or a queuing limit
175 // is reached.
176 // "Reject" means that requests that can not be executed upon arrival
177 // are rejected.
178 // Required.
179 // +unionDiscriminator
180 optional string type = 1;
181
182 // `queuing` holds the configuration parameters for queuing.
183 // This field may be non-empty only if `type` is `"Queue"`.
184 // +optional
185 optional QueuingConfiguration queuing = 2;
186}
187
188// LimitedPriorityLevelConfiguration specifies how to handle requests that are subject to limits.
189// It addresses two issues:
190// - How are requests for this priority level limited?
191// - What should be done with requests that exceed the limit?
192message LimitedPriorityLevelConfiguration {
193 // `assuredConcurrencyShares` (ACS) configures the execution
194 // limit, which is a limit on the number of requests of this
195 // priority level that may be executing at a given time. ACS must
196 // be a positive number. The server's concurrency limit (SCL) is
197 // divided among the concurrency-controlled priority levels in
198 // proportion to their assured concurrency shares. This produces
199 // the assured concurrency value (ACV) --- the number of requests
200 // that may be executing at a time --- for each such priority
201 // level:
202 //
203 // ACV(l) = ceil( SCL * ACS(l) / ( sum[priority levels k] ACS(k) ) )
204 //
205 // bigger numbers of ACS mean more reserved concurrent requests (at the
206 // expense of every other PL).
207 // This field has a default value of 30.
208 // +optional
209 optional int32 assuredConcurrencyShares = 1;
210
211 // `limitResponse` indicates what to do with requests that can not be executed right now
212 optional LimitResponse limitResponse = 2;
213
214 // `lendablePercent` prescribes the fraction of the level's NominalCL that
215 // can be borrowed by other priority levels. The value of this
216 // field must be between 0 and 100, inclusive, and it defaults to 0.
217 // The number of seats that other levels can borrow from this level, known
218 // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows.
219 //
220 // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 )
221 //
222 // +optional
223 optional int32 lendablePercent = 3;
224
225 // `borrowingLimitPercent`, if present, configures a limit on how many
226 // seats this priority level can borrow from other priority levels.
227 // The limit is known as this level's BorrowingConcurrencyLimit
228 // (BorrowingCL) and is a limit on the total number of seats that this
229 // level may borrow at any one time.
230 // This field holds the ratio of that limit to the level's nominal
231 // concurrency limit. When this field is non-nil, it must hold a
232 // non-negative integer and the limit is calculated as follows.
233 //
234 // BorrowingCL(i) = round( NominalCL(i) * borrowingLimitPercent(i)/100.0 )
235 //
236 // The value of this field can be more than 100, implying that this
237 // priority level can borrow a number of seats that is greater than
238 // its own nominal concurrency limit (NominalCL).
239 // When this field is left `nil`, the limit is effectively infinite.
240 // +optional
241 optional int32 borrowingLimitPercent = 4;
242}
243
244// NonResourcePolicyRule is a predicate that matches non-resource requests according to their verb and the
245// target non-resource URL. A NonResourcePolicyRule matches a request if and only if both (a) at least one member
246// of verbs matches the request and (b) at least one member of nonResourceURLs matches the request.
247message NonResourcePolicyRule {
248 // `verbs` is a list of matching verbs and may not be empty.
249 // "*" matches all verbs. If it is present, it must be the only entry.
250 // +listType=set
251 // Required.
252 repeated string verbs = 1;
253
254 // `nonResourceURLs` is a set of url prefixes that a user should have access to and may not be empty.
255 // For example:
256 // - "/healthz" is legal
257 // - "/hea*" is illegal
258 // - "/hea" is legal but matches nothing
259 // - "/hea/*" also matches nothing
260 // - "/healthz/*" matches all per-component health checks.
261 // "*" matches all non-resource urls. if it is present, it must be the only entry.
262 // +listType=set
263 // Required.
264 repeated string nonResourceURLs = 6;
265}
266
267// PolicyRulesWithSubjects prescribes a test that applies to a request to an apiserver. The test considers the subject
268// making the request, the verb being requested, and the resource to be acted upon. This PolicyRulesWithSubjects matches
269// a request if and only if both (a) at least one member of subjects matches the request and (b) at least one member
270// of resourceRules or nonResourceRules matches the request.
271message PolicyRulesWithSubjects {
272 // subjects is the list of normal user, serviceaccount, or group that this rule cares about.
273 // There must be at least one member in this slice.
274 // A slice that includes both the system:authenticated and system:unauthenticated user groups matches every request.
275 // +listType=atomic
276 // Required.
277 repeated Subject subjects = 1;
278
279 // `resourceRules` is a slice of ResourcePolicyRules that identify matching requests according to their verb and the
280 // target resource.
281 // At least one of `resourceRules` and `nonResourceRules` has to be non-empty.
282 // +listType=atomic
283 // +optional
284 repeated ResourcePolicyRule resourceRules = 2;
285
286 // `nonResourceRules` is a list of NonResourcePolicyRules that identify matching requests according to their verb
287 // and the target non-resource URL.
288 // +listType=atomic
289 // +optional
290 repeated NonResourcePolicyRule nonResourceRules = 3;
291}
292
293// PriorityLevelConfiguration represents the configuration of a priority level.
294message PriorityLevelConfiguration {
295 // `metadata` is the standard object's metadata.
296 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
297 // +optional
298 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
299
300 // `spec` is the specification of the desired behavior of a "request-priority".
301 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
302 // +optional
303 optional PriorityLevelConfigurationSpec spec = 2;
304
305 // `status` is the current status of a "request-priority".
306 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
307 // +optional
308 optional PriorityLevelConfigurationStatus status = 3;
309}
310
311// PriorityLevelConfigurationCondition defines the condition of priority level.
312message PriorityLevelConfigurationCondition {
313 // `type` is the type of the condition.
314 // Required.
315 optional string type = 1;
316
317 // `status` is the status of the condition.
318 // Can be True, False, Unknown.
319 // Required.
320 optional string status = 2;
321
322 // `lastTransitionTime` is the last time the condition transitioned from one status to another.
323 optional k8s.io.apimachinery.pkg.apis.meta.v1.Time lastTransitionTime = 3;
324
325 // `reason` is a unique, one-word, CamelCase reason for the condition's last transition.
326 optional string reason = 4;
327
328 // `message` is a human-readable message indicating details about last transition.
329 optional string message = 5;
330}
331
332// PriorityLevelConfigurationList is a list of PriorityLevelConfiguration objects.
333message PriorityLevelConfigurationList {
334 // `metadata` is the standard object's metadata.
335 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
336 // +optional
337 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
338
339 // `items` is a list of request-priorities.
340 repeated PriorityLevelConfiguration items = 2;
341}
342
343// PriorityLevelConfigurationReference contains information that points to the "request-priority" being used.
344message PriorityLevelConfigurationReference {
345 // `name` is the name of the priority level configuration being referenced
346 // Required.
347 optional string name = 1;
348}
349
350// PriorityLevelConfigurationSpec specifies the configuration of a priority level.
351// +union
352message PriorityLevelConfigurationSpec {
353 // `type` indicates whether this priority level is subject to
354 // limitation on request execution. A value of `"Exempt"` means
355 // that requests of this priority level are not subject to a limit
356 // (and thus are never queued) and do not detract from the
357 // capacity made available to other priority levels. A value of
358 // `"Limited"` means that (a) requests of this priority level
359 // _are_ subject to limits and (b) some of the server's limited
360 // capacity is made available exclusively to this priority level.
361 // Required.
362 // +unionDiscriminator
363 optional string type = 1;
364
365 // `limited` specifies how requests are handled for a Limited priority level.
366 // This field must be non-empty if and only if `type` is `"Limited"`.
367 // +optional
368 optional LimitedPriorityLevelConfiguration limited = 2;
369
370 // `exempt` specifies how requests are handled for an exempt priority level.
371 // This field MUST be empty if `type` is `"Limited"`.
372 // This field MAY be non-empty if `type` is `"Exempt"`.
373 // If empty and `type` is `"Exempt"` then the default values
374 // for `ExemptPriorityLevelConfiguration` apply.
375 // +optional
376 optional ExemptPriorityLevelConfiguration exempt = 3;
377}
378
379// PriorityLevelConfigurationStatus represents the current state of a "request-priority".
380message PriorityLevelConfigurationStatus {
381 // `conditions` is the current state of "request-priority".
382 // +listType=map
383 // +listMapKey=type
384 // +optional
385 repeated PriorityLevelConfigurationCondition conditions = 1;
386}
387
388// QueuingConfiguration holds the configuration parameters for queuing
389message QueuingConfiguration {
390 // `queues` is the number of queues for this priority level. The
391 // queues exist independently at each apiserver. The value must be
392 // positive. Setting it to 1 effectively precludes
393 // shufflesharding and thus makes the distinguisher method of
394 // associated flow schemas irrelevant. This field has a default
395 // value of 64.
396 // +optional
397 optional int32 queues = 1;
398
399 // `handSize` is a small positive number that configures the
400 // shuffle sharding of requests into queues. When enqueuing a request
401 // at this priority level the request's flow identifier (a string
402 // pair) is hashed and the hash value is used to shuffle the list
403 // of queues and deal a hand of the size specified here. The
404 // request is put into one of the shortest queues in that hand.
405 // `handSize` must be no larger than `queues`, and should be
406 // significantly smaller (so that a few heavy flows do not
407 // saturate most of the queues). See the user-facing
408 // documentation for more extensive guidance on setting this
409 // field. This field has a default value of 8.
410 // +optional
411 optional int32 handSize = 2;
412
413 // `queueLengthLimit` is the maximum number of requests allowed to
414 // be waiting in a given queue of this priority level at a time;
415 // excess requests are rejected. This value must be positive. If
416 // not specified, it will be defaulted to 50.
417 // +optional
418 optional int32 queueLengthLimit = 3;
419}
420
421// ResourcePolicyRule is a predicate that matches some resource
422// requests, testing the request's verb and the target resource. A
423// ResourcePolicyRule matches a resource request if and only if: (a)
424// at least one member of verbs matches the request, (b) at least one
425// member of apiGroups matches the request, (c) at least one member of
426// resources matches the request, and (d) either (d1) the request does
427// not specify a namespace (i.e., `Namespace==""`) and clusterScope is
428// true or (d2) the request specifies a namespace and least one member
429// of namespaces matches the request's namespace.
430message ResourcePolicyRule {
431 // `verbs` is a list of matching verbs and may not be empty.
432 // "*" matches all verbs and, if present, must be the only entry.
433 // +listType=set
434 // Required.
435 repeated string verbs = 1;
436
437 // `apiGroups` is a list of matching API groups and may not be empty.
438 // "*" matches all API groups and, if present, must be the only entry.
439 // +listType=set
440 // Required.
441 repeated string apiGroups = 2;
442
443 // `resources` is a list of matching resources (i.e., lowercase
444 // and plural) with, if desired, subresource. For example, [
445 // "services", "nodes/status" ]. This list may not be empty.
446 // "*" matches all resources and, if present, must be the only entry.
447 // Required.
448 // +listType=set
449 repeated string resources = 3;
450
451 // `clusterScope` indicates whether to match requests that do not
452 // specify a namespace (which happens either because the resource
453 // is not namespaced or the request targets all namespaces).
454 // If this field is omitted or false then the `namespaces` field
455 // must contain a non-empty list.
456 // +optional
457 optional bool clusterScope = 4;
458
459 // `namespaces` is a list of target namespaces that restricts
460 // matches. A request that specifies a target namespace matches
461 // only if either (a) this list contains that target namespace or
462 // (b) this list contains "*". Note that "*" matches any
463 // specified namespace but does not match a request that _does
464 // not specify_ a namespace (see the `clusterScope` field for
465 // that).
466 // This list may be empty, but only if `clusterScope` is true.
467 // +optional
468 // +listType=set
469 repeated string namespaces = 5;
470}
471
472// ServiceAccountSubject holds detailed information for service-account-kind subject.
473message ServiceAccountSubject {
474 // `namespace` is the namespace of matching ServiceAccount objects.
475 // Required.
476 optional string namespace = 1;
477
478 // `name` is the name of matching ServiceAccount objects, or "*" to match regardless of name.
479 // Required.
480 optional string name = 2;
481}
482
483// Subject matches the originator of a request, as identified by the request authentication system. There are three
484// ways of matching an originator; by user, group, or service account.
485// +union
486message Subject {
487 // `kind` indicates which one of the other fields is non-empty.
488 // Required
489 // +unionDiscriminator
490 optional string kind = 1;
491
492 // `user` matches based on username.
493 // +optional
494 optional UserSubject user = 2;
495
496 // `group` matches based on user group name.
497 // +optional
498 optional GroupSubject group = 3;
499
500 // `serviceAccount` matches ServiceAccounts.
501 // +optional
502 optional ServiceAccountSubject serviceAccount = 4;
503}
504
505// UserSubject holds detailed information for user-kind subject.
506message UserSubject {
507 // `name` is the username that matches, or "*" to match all usernames.
508 // Required.
509 optional string name = 1;
510}
511
View as plain text