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