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.v1;
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/v1";
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 // +patchMergeKey=type
157 // +patchStrategy=merge
158 // +optional
159 repeated FlowSchemaCondition conditions = 1;
160}
161
162// GroupSubject holds detailed information for group-kind subject.
163message GroupSubject {
164 // name is the user group that matches, or "*" to match all user groups.
165 // See https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/user/user.go for some
166 // well-known group names.
167 // Required.
168 optional string name = 1;
169}
170
171// LimitResponse defines how to handle requests that can not be executed right now.
172// +union
173message LimitResponse {
174 // `type` is "Queue" or "Reject".
175 // "Queue" means that requests that can not be executed upon arrival
176 // are held in a queue until they can be executed or a queuing limit
177 // is reached.
178 // "Reject" means that requests that can not be executed upon arrival
179 // are rejected.
180 // Required.
181 // +unionDiscriminator
182 optional string type = 1;
183
184 // `queuing` holds the configuration parameters for queuing.
185 // This field may be non-empty only if `type` is `"Queue"`.
186 // +optional
187 optional QueuingConfiguration queuing = 2;
188}
189
190// LimitedPriorityLevelConfiguration specifies how to handle requests that are subject to limits.
191// It addresses two issues:
192// - How are requests for this priority level limited?
193// - What should be done with requests that exceed the limit?
194message LimitedPriorityLevelConfiguration {
195 // `nominalConcurrencyShares` (NCS) contributes to the computation of the
196 // NominalConcurrencyLimit (NominalCL) of this level.
197 // This is the number of execution seats available at this priority level.
198 // This is used both for requests dispatched from this priority level
199 // as well as requests dispatched from other priority levels
200 // borrowing seats from this level.
201 // The server's concurrency limit (ServerCL) is divided among the
202 // Limited priority levels in proportion to their NCS values:
203 //
204 // NominalCL(i) = ceil( ServerCL * NCS(i) / sum_ncs )
205 // sum_ncs = sum[priority level k] NCS(k)
206 //
207 // Bigger numbers mean a larger nominal concurrency limit,
208 // at the expense of every other priority level.
209 //
210 // If not specified, this field defaults to a value of 30.
211 //
212 // Setting this field to zero supports the construction of a
213 // "jail" for this priority level that is used to hold some request(s)
214 //
215 // +optional
216 optional int32 nominalConcurrencyShares = 1;
217
218 // `limitResponse` indicates what to do with requests that can not be executed right now
219 optional LimitResponse limitResponse = 2;
220
221 // `lendablePercent` prescribes the fraction of the level's NominalCL that
222 // can be borrowed by other priority levels. The value of this
223 // field must be between 0 and 100, inclusive, and it defaults to 0.
224 // The number of seats that other levels can borrow from this level, known
225 // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows.
226 //
227 // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 )
228 //
229 // +optional
230 optional int32 lendablePercent = 3;
231
232 // `borrowingLimitPercent`, if present, configures a limit on how many
233 // seats this priority level can borrow from other priority levels.
234 // The limit is known as this level's BorrowingConcurrencyLimit
235 // (BorrowingCL) and is a limit on the total number of seats that this
236 // level may borrow at any one time.
237 // This field holds the ratio of that limit to the level's nominal
238 // concurrency limit. When this field is non-nil, it must hold a
239 // non-negative integer and the limit is calculated as follows.
240 //
241 // BorrowingCL(i) = round( NominalCL(i) * borrowingLimitPercent(i)/100.0 )
242 //
243 // The value of this field can be more than 100, implying that this
244 // priority level can borrow a number of seats that is greater than
245 // its own nominal concurrency limit (NominalCL).
246 // When this field is left `nil`, the limit is effectively infinite.
247 // +optional
248 optional int32 borrowingLimitPercent = 4;
249}
250
251// NonResourcePolicyRule is a predicate that matches non-resource requests according to their verb and the
252// target non-resource URL. A NonResourcePolicyRule matches a request if and only if both (a) at least one member
253// of verbs matches the request and (b) at least one member of nonResourceURLs matches the request.
254message NonResourcePolicyRule {
255 // `verbs` is a list of matching verbs and may not be empty.
256 // "*" matches all verbs. If it is present, it must be the only entry.
257 // +listType=set
258 // Required.
259 repeated string verbs = 1;
260
261 // `nonResourceURLs` is a set of url prefixes that a user should have access to and may not be empty.
262 // For example:
263 // - "/healthz" is legal
264 // - "/hea*" is illegal
265 // - "/hea" is legal but matches nothing
266 // - "/hea/*" also matches nothing
267 // - "/healthz/*" matches all per-component health checks.
268 // "*" matches all non-resource urls. if it is present, it must be the only entry.
269 // +listType=set
270 // Required.
271 repeated string nonResourceURLs = 6;
272}
273
274// PolicyRulesWithSubjects prescribes a test that applies to a request to an apiserver. The test considers the subject
275// making the request, the verb being requested, and the resource to be acted upon. This PolicyRulesWithSubjects matches
276// a request if and only if both (a) at least one member of subjects matches the request and (b) at least one member
277// of resourceRules or nonResourceRules matches the request.
278message PolicyRulesWithSubjects {
279 // subjects is the list of normal user, serviceaccount, or group that this rule cares about.
280 // There must be at least one member in this slice.
281 // A slice that includes both the system:authenticated and system:unauthenticated user groups matches every request.
282 // +listType=atomic
283 // Required.
284 repeated Subject subjects = 1;
285
286 // `resourceRules` is a slice of ResourcePolicyRules that identify matching requests according to their verb and the
287 // target resource.
288 // At least one of `resourceRules` and `nonResourceRules` has to be non-empty.
289 // +listType=atomic
290 // +optional
291 repeated ResourcePolicyRule resourceRules = 2;
292
293 // `nonResourceRules` is a list of NonResourcePolicyRules that identify matching requests according to their verb
294 // and the target non-resource URL.
295 // +listType=atomic
296 // +optional
297 repeated NonResourcePolicyRule nonResourceRules = 3;
298}
299
300// PriorityLevelConfiguration represents the configuration of a priority level.
301message PriorityLevelConfiguration {
302 // `metadata` is the standard object's metadata.
303 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
304 // +optional
305 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
306
307 // `spec` is the specification of the desired behavior of a "request-priority".
308 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
309 // +optional
310 optional PriorityLevelConfigurationSpec spec = 2;
311
312 // `status` is the current status of a "request-priority".
313 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
314 // +optional
315 optional PriorityLevelConfigurationStatus status = 3;
316}
317
318// PriorityLevelConfigurationCondition defines the condition of priority level.
319message PriorityLevelConfigurationCondition {
320 // `type` is the type of the condition.
321 // Required.
322 optional string type = 1;
323
324 // `status` is the status of the condition.
325 // Can be True, False, Unknown.
326 // Required.
327 optional string status = 2;
328
329 // `lastTransitionTime` is the last time the condition transitioned from one status to another.
330 optional k8s.io.apimachinery.pkg.apis.meta.v1.Time lastTransitionTime = 3;
331
332 // `reason` is a unique, one-word, CamelCase reason for the condition's last transition.
333 optional string reason = 4;
334
335 // `message` is a human-readable message indicating details about last transition.
336 optional string message = 5;
337}
338
339// PriorityLevelConfigurationList is a list of PriorityLevelConfiguration objects.
340message PriorityLevelConfigurationList {
341 // `metadata` is the standard object's metadata.
342 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
343 // +optional
344 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
345
346 // `items` is a list of request-priorities.
347 repeated PriorityLevelConfiguration items = 2;
348}
349
350// PriorityLevelConfigurationReference contains information that points to the "request-priority" being used.
351message PriorityLevelConfigurationReference {
352 // `name` is the name of the priority level configuration being referenced
353 // Required.
354 optional string name = 1;
355}
356
357// PriorityLevelConfigurationSpec specifies the configuration of a priority level.
358// +union
359message PriorityLevelConfigurationSpec {
360 // `type` indicates whether this priority level is subject to
361 // limitation on request execution. A value of `"Exempt"` means
362 // that requests of this priority level are not subject to a limit
363 // (and thus are never queued) and do not detract from the
364 // capacity made available to other priority levels. A value of
365 // `"Limited"` means that (a) requests of this priority level
366 // _are_ subject to limits and (b) some of the server's limited
367 // capacity is made available exclusively to this priority level.
368 // Required.
369 // +unionDiscriminator
370 optional string type = 1;
371
372 // `limited` specifies how requests are handled for a Limited priority level.
373 // This field must be non-empty if and only if `type` is `"Limited"`.
374 // +optional
375 optional LimitedPriorityLevelConfiguration limited = 2;
376
377 // `exempt` specifies how requests are handled for an exempt priority level.
378 // This field MUST be empty if `type` is `"Limited"`.
379 // This field MAY be non-empty if `type` is `"Exempt"`.
380 // If empty and `type` is `"Exempt"` then the default values
381 // for `ExemptPriorityLevelConfiguration` apply.
382 // +optional
383 optional ExemptPriorityLevelConfiguration exempt = 3;
384}
385
386// PriorityLevelConfigurationStatus represents the current state of a "request-priority".
387message PriorityLevelConfigurationStatus {
388 // `conditions` is the current state of "request-priority".
389 // +listType=map
390 // +listMapKey=type
391 // +patchMergeKey=type
392 // +patchStrategy=merge
393 // +optional
394 repeated PriorityLevelConfigurationCondition conditions = 1;
395}
396
397// QueuingConfiguration holds the configuration parameters for queuing
398message QueuingConfiguration {
399 // `queues` is the number of queues for this priority level. The
400 // queues exist independently at each apiserver. The value must be
401 // positive. Setting it to 1 effectively precludes
402 // shufflesharding and thus makes the distinguisher method of
403 // associated flow schemas irrelevant. This field has a default
404 // value of 64.
405 // +optional
406 optional int32 queues = 1;
407
408 // `handSize` is a small positive number that configures the
409 // shuffle sharding of requests into queues. When enqueuing a request
410 // at this priority level the request's flow identifier (a string
411 // pair) is hashed and the hash value is used to shuffle the list
412 // of queues and deal a hand of the size specified here. The
413 // request is put into one of the shortest queues in that hand.
414 // `handSize` must be no larger than `queues`, and should be
415 // significantly smaller (so that a few heavy flows do not
416 // saturate most of the queues). See the user-facing
417 // documentation for more extensive guidance on setting this
418 // field. This field has a default value of 8.
419 // +optional
420 optional int32 handSize = 2;
421
422 // `queueLengthLimit` is the maximum number of requests allowed to
423 // be waiting in a given queue of this priority level at a time;
424 // excess requests are rejected. This value must be positive. If
425 // not specified, it will be defaulted to 50.
426 // +optional
427 optional int32 queueLengthLimit = 3;
428}
429
430// ResourcePolicyRule is a predicate that matches some resource
431// requests, testing the request's verb and the target resource. A
432// ResourcePolicyRule matches a resource request if and only if: (a)
433// at least one member of verbs matches the request, (b) at least one
434// member of apiGroups matches the request, (c) at least one member of
435// resources matches the request, and (d) either (d1) the request does
436// not specify a namespace (i.e., `Namespace==""`) and clusterScope is
437// true or (d2) the request specifies a namespace and least one member
438// of namespaces matches the request's namespace.
439message ResourcePolicyRule {
440 // `verbs` is a list of matching verbs and may not be empty.
441 // "*" matches all verbs and, if present, must be the only entry.
442 // +listType=set
443 // Required.
444 repeated string verbs = 1;
445
446 // `apiGroups` is a list of matching API groups and may not be empty.
447 // "*" matches all API groups and, if present, must be the only entry.
448 // +listType=set
449 // Required.
450 repeated string apiGroups = 2;
451
452 // `resources` is a list of matching resources (i.e., lowercase
453 // and plural) with, if desired, subresource. For example, [
454 // "services", "nodes/status" ]. This list may not be empty.
455 // "*" matches all resources and, if present, must be the only entry.
456 // Required.
457 // +listType=set
458 repeated string resources = 3;
459
460 // `clusterScope` indicates whether to match requests that do not
461 // specify a namespace (which happens either because the resource
462 // is not namespaced or the request targets all namespaces).
463 // If this field is omitted or false then the `namespaces` field
464 // must contain a non-empty list.
465 // +optional
466 optional bool clusterScope = 4;
467
468 // `namespaces` is a list of target namespaces that restricts
469 // matches. A request that specifies a target namespace matches
470 // only if either (a) this list contains that target namespace or
471 // (b) this list contains "*". Note that "*" matches any
472 // specified namespace but does not match a request that _does
473 // not specify_ a namespace (see the `clusterScope` field for
474 // that).
475 // This list may be empty, but only if `clusterScope` is true.
476 // +optional
477 // +listType=set
478 repeated string namespaces = 5;
479}
480
481// ServiceAccountSubject holds detailed information for service-account-kind subject.
482message ServiceAccountSubject {
483 // `namespace` is the namespace of matching ServiceAccount objects.
484 // Required.
485 optional string namespace = 1;
486
487 // `name` is the name of matching ServiceAccount objects, or "*" to match regardless of name.
488 // Required.
489 optional string name = 2;
490}
491
492// Subject matches the originator of a request, as identified by the request authentication system. There are three
493// ways of matching an originator; by user, group, or service account.
494// +union
495message Subject {
496 // `kind` indicates which one of the other fields is non-empty.
497 // Required
498 // +unionDiscriminator
499 optional string kind = 1;
500
501 // `user` matches based on username.
502 // +optional
503 optional UserSubject user = 2;
504
505 // `group` matches based on user group name.
506 // +optional
507 optional GroupSubject group = 3;
508
509 // `serviceAccount` matches ServiceAccounts.
510 // +optional
511 optional ServiceAccountSubject serviceAccount = 4;
512}
513
514// UserSubject holds detailed information for user-kind subject.
515message UserSubject {
516 // `name` is the username that matches, or "*" to match all usernames.
517 // Required.
518 optional string name = 1;
519}
520
View as plain text