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