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