1 /* 2 Copyright 2019 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package v1beta1 18 19 import ( 20 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 ) 22 23 // These are valid wildcards. 24 const ( 25 APIGroupAll = "*" 26 ResourceAll = "*" 27 VerbAll = "*" 28 NonResourceAll = "*" 29 NameAll = "*" 30 31 NamespaceEvery = "*" // matches every particular namespace 32 ) 33 34 // System preset priority level names 35 const ( 36 PriorityLevelConfigurationNameExempt = "exempt" 37 PriorityLevelConfigurationNameCatchAll = "catch-all" 38 FlowSchemaNameExempt = "exempt" 39 FlowSchemaNameCatchAll = "catch-all" 40 ) 41 42 // Conditions 43 const ( 44 FlowSchemaConditionDangling = "Dangling" 45 46 PriorityLevelConfigurationConditionConcurrencyShared = "ConcurrencyShared" 47 ) 48 49 // Constants used by api validation. 50 const ( 51 FlowSchemaMaxMatchingPrecedence int32 = 10000 52 ) 53 54 // Constants for apiserver response headers. 55 const ( 56 ResponseHeaderMatchedPriorityLevelConfigurationUID = "X-Kubernetes-PF-PriorityLevel-UID" 57 ResponseHeaderMatchedFlowSchemaUID = "X-Kubernetes-PF-FlowSchema-UID" 58 ) 59 60 const ( 61 // AutoUpdateAnnotationKey is the name of an annotation that enables 62 // automatic update of the spec of the bootstrap configuration 63 // object(s), if set to 'true'. 64 // 65 // On a fresh install, all bootstrap configuration objects will have auto 66 // update enabled with the following annotation key: 67 // apf.kubernetes.io/autoupdate-spec: 'true' 68 // 69 // The kube-apiserver periodically checks the bootstrap configuration 70 // objects on the cluster and applies updates if necessary. 71 // 72 // kube-apiserver enforces an 'always auto-update' policy for the 73 // mandatory configuration object(s). This implies: 74 // - the auto-update annotation key is added with a value of 'true' 75 // if it is missing. 76 // - the auto-update annotation key is set to 'true' if its current value 77 // is a boolean false or has an invalid boolean representation 78 // (if the cluster operator sets it to 'false' it will be stomped) 79 // - any changes to the spec made by the cluster operator will be 80 // stomped, except for changes to the `nominalConcurrencyShares` 81 // and `lendablePercent` fields of the PriorityLevelConfiguration 82 // named "exempt". 83 // 84 // The kube-apiserver will apply updates on the suggested configuration if: 85 // - the cluster operator has enabled auto-update by setting the annotation 86 // (apf.kubernetes.io/autoupdate-spec: 'true') or 87 // - the annotation key is missing but the generation is 1 88 // 89 // If the suggested configuration object is missing the annotation key, 90 // kube-apiserver will update the annotation appropriately: 91 // - it is set to 'true' if generation of the object is '1' which usually 92 // indicates that the spec of the object has not been changed. 93 // - it is set to 'false' if generation of the object is greater than 1. 94 // 95 // The goal is to enable the kube-apiserver to apply update on suggested 96 // configuration objects installed by previous releases but not overwrite 97 // changes made by the cluster operators. 98 // Note that this distinction is imperfectly detected: in the case where an 99 // operator deletes a suggested configuration object and later creates it 100 // but with a variant spec and then does no updates of the object 101 // (generation is 1), the technique outlined above will incorrectly 102 // determine that the object should be auto-updated. 103 AutoUpdateAnnotationKey = "apf.kubernetes.io/autoupdate-spec" 104 ) 105 106 // +genclient 107 // +genclient:nonNamespaced 108 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 109 // +k8s:prerelease-lifecycle-gen:introduced=1.20 110 // +k8s:prerelease-lifecycle-gen:replacement=flowcontrol.apiserver.k8s.io,v1beta3,FlowSchema 111 112 // FlowSchema defines the schema of a group of flows. Note that a flow is made up of a set of inbound API requests with 113 // similar attributes and is identified by a pair of strings: the name of the FlowSchema and a "flow distinguisher". 114 type FlowSchema struct { 115 metav1.TypeMeta `json:",inline"` 116 // `metadata` is the standard object's metadata. 117 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 118 // +optional 119 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 120 // `spec` is the specification of the desired behavior of a FlowSchema. 121 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 122 // +optional 123 Spec FlowSchemaSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` 124 // `status` is the current status of a FlowSchema. 125 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 126 // +optional 127 Status FlowSchemaStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` 128 } 129 130 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 131 // +k8s:prerelease-lifecycle-gen:introduced=1.20 132 // +k8s:prerelease-lifecycle-gen:replacement=flowcontrol.apiserver.k8s.io,v1beta3,FlowSchemaList 133 134 // FlowSchemaList is a list of FlowSchema objects. 135 type FlowSchemaList struct { 136 metav1.TypeMeta `json:",inline"` 137 // `metadata` is the standard list metadata. 138 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 139 // +optional 140 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 141 142 // `items` is a list of FlowSchemas. 143 Items []FlowSchema `json:"items" protobuf:"bytes,2,rep,name=items"` 144 } 145 146 // FlowSchemaSpec describes how the FlowSchema's specification looks like. 147 type FlowSchemaSpec struct { 148 // `priorityLevelConfiguration` should reference a PriorityLevelConfiguration in the cluster. If the reference cannot 149 // be resolved, the FlowSchema will be ignored and marked as invalid in its status. 150 // Required. 151 PriorityLevelConfiguration PriorityLevelConfigurationReference `json:"priorityLevelConfiguration" protobuf:"bytes,1,opt,name=priorityLevelConfiguration"` 152 // `matchingPrecedence` is used to choose among the FlowSchemas that match a given request. The chosen 153 // FlowSchema is among those with the numerically lowest (which we take to be logically highest) 154 // MatchingPrecedence. Each MatchingPrecedence value must be ranged in [1,10000]. 155 // Note that if the precedence is not specified, it will be set to 1000 as default. 156 // +optional 157 MatchingPrecedence int32 `json:"matchingPrecedence" protobuf:"varint,2,opt,name=matchingPrecedence"` 158 // `distinguisherMethod` defines how to compute the flow distinguisher for requests that match this schema. 159 // `nil` specifies that the distinguisher is disabled and thus will always be the empty string. 160 // +optional 161 DistinguisherMethod *FlowDistinguisherMethod `json:"distinguisherMethod,omitempty" protobuf:"bytes,3,opt,name=distinguisherMethod"` 162 // `rules` describes which requests will match this flow schema. This FlowSchema matches a request if and only if 163 // at least one member of rules matches the request. 164 // if it is an empty slice, there will be no requests matching the FlowSchema. 165 // +listType=atomic 166 // +optional 167 Rules []PolicyRulesWithSubjects `json:"rules,omitempty" protobuf:"bytes,4,rep,name=rules"` 168 } 169 170 // FlowDistinguisherMethodType is the type of flow distinguisher method 171 type FlowDistinguisherMethodType string 172 173 // These are valid flow-distinguisher methods. 174 const ( 175 // FlowDistinguisherMethodByUserType specifies that the flow distinguisher is the username in the request. 176 // This type is used to provide some insulation between users. 177 FlowDistinguisherMethodByUserType FlowDistinguisherMethodType = "ByUser" 178 179 // FlowDistinguisherMethodByNamespaceType specifies that the flow distinguisher is the namespace of the 180 // object that the request acts upon. If the object is not namespaced, or if the request is a non-resource 181 // request, then the distinguisher will be the empty string. An example usage of this type is to provide 182 // some insulation between tenants in a situation where there are multiple tenants and each namespace 183 // is dedicated to a tenant. 184 FlowDistinguisherMethodByNamespaceType FlowDistinguisherMethodType = "ByNamespace" 185 ) 186 187 // FlowDistinguisherMethod specifies the method of a flow distinguisher. 188 type FlowDistinguisherMethod struct { 189 // `type` is the type of flow distinguisher method 190 // The supported types are "ByUser" and "ByNamespace". 191 // Required. 192 Type FlowDistinguisherMethodType `json:"type" protobuf:"bytes,1,opt,name=type"` 193 } 194 195 // PriorityLevelConfigurationReference contains information that points to the "request-priority" being used. 196 type PriorityLevelConfigurationReference struct { 197 // `name` is the name of the priority level configuration being referenced 198 // Required. 199 Name string `json:"name" protobuf:"bytes,1,opt,name=name"` 200 } 201 202 // PolicyRulesWithSubjects prescribes a test that applies to a request to an apiserver. The test considers the subject 203 // making the request, the verb being requested, and the resource to be acted upon. This PolicyRulesWithSubjects matches 204 // a request if and only if both (a) at least one member of subjects matches the request and (b) at least one member 205 // of resourceRules or nonResourceRules matches the request. 206 type PolicyRulesWithSubjects struct { 207 // subjects is the list of normal user, serviceaccount, or group that this rule cares about. 208 // There must be at least one member in this slice. 209 // A slice that includes both the system:authenticated and system:unauthenticated user groups matches every request. 210 // +listType=atomic 211 // Required. 212 Subjects []Subject `json:"subjects" protobuf:"bytes,1,rep,name=subjects"` 213 // `resourceRules` is a slice of ResourcePolicyRules that identify matching requests according to their verb and the 214 // target resource. 215 // At least one of `resourceRules` and `nonResourceRules` has to be non-empty. 216 // +listType=atomic 217 // +optional 218 ResourceRules []ResourcePolicyRule `json:"resourceRules,omitempty" protobuf:"bytes,2,opt,name=resourceRules"` 219 // `nonResourceRules` is a list of NonResourcePolicyRules that identify matching requests according to their verb 220 // and the target non-resource URL. 221 // +listType=atomic 222 // +optional 223 NonResourceRules []NonResourcePolicyRule `json:"nonResourceRules,omitempty" protobuf:"bytes,3,opt,name=nonResourceRules"` 224 } 225 226 // Subject matches the originator of a request, as identified by the request authentication system. There are three 227 // ways of matching an originator; by user, group, or service account. 228 // +union 229 type Subject struct { 230 // `kind` indicates which one of the other fields is non-empty. 231 // Required 232 // +unionDiscriminator 233 Kind SubjectKind `json:"kind" protobuf:"bytes,1,opt,name=kind"` 234 // `user` matches based on username. 235 // +optional 236 User *UserSubject `json:"user,omitempty" protobuf:"bytes,2,opt,name=user"` 237 // `group` matches based on user group name. 238 // +optional 239 Group *GroupSubject `json:"group,omitempty" protobuf:"bytes,3,opt,name=group"` 240 // `serviceAccount` matches ServiceAccounts. 241 // +optional 242 ServiceAccount *ServiceAccountSubject `json:"serviceAccount,omitempty" protobuf:"bytes,4,opt,name=serviceAccount"` 243 } 244 245 // SubjectKind is the kind of subject. 246 type SubjectKind string 247 248 // Supported subject's kinds. 249 const ( 250 SubjectKindUser SubjectKind = "User" 251 SubjectKindGroup SubjectKind = "Group" 252 SubjectKindServiceAccount SubjectKind = "ServiceAccount" 253 ) 254 255 // UserSubject holds detailed information for user-kind subject. 256 type UserSubject struct { 257 // `name` is the username that matches, or "*" to match all usernames. 258 // Required. 259 Name string `json:"name" protobuf:"bytes,1,opt,name=name"` 260 } 261 262 // GroupSubject holds detailed information for group-kind subject. 263 type GroupSubject struct { 264 // name is the user group that matches, or "*" to match all user groups. 265 // See https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/user/user.go for some 266 // well-known group names. 267 // Required. 268 Name string `json:"name" protobuf:"bytes,1,opt,name=name"` 269 } 270 271 // ServiceAccountSubject holds detailed information for service-account-kind subject. 272 type ServiceAccountSubject struct { 273 // `namespace` is the namespace of matching ServiceAccount objects. 274 // Required. 275 Namespace string `json:"namespace" protobuf:"bytes,1,opt,name=namespace"` 276 // `name` is the name of matching ServiceAccount objects, or "*" to match regardless of name. 277 // Required. 278 Name string `json:"name" protobuf:"bytes,2,opt,name=name"` 279 } 280 281 // ResourcePolicyRule is a predicate that matches some resource 282 // requests, testing the request's verb and the target resource. A 283 // ResourcePolicyRule matches a resource request if and only if: (a) 284 // at least one member of verbs matches the request, (b) at least one 285 // member of apiGroups matches the request, (c) at least one member of 286 // resources matches the request, and (d) either (d1) the request does 287 // not specify a namespace (i.e., `Namespace==""`) and clusterScope is 288 // true or (d2) the request specifies a namespace and least one member 289 // of namespaces matches the request's namespace. 290 type ResourcePolicyRule struct { 291 // `verbs` is a list of matching verbs and may not be empty. 292 // "*" matches all verbs and, if present, must be the only entry. 293 // +listType=set 294 // Required. 295 Verbs []string `json:"verbs" protobuf:"bytes,1,rep,name=verbs"` 296 297 // `apiGroups` is a list of matching API groups and may not be empty. 298 // "*" matches all API groups and, if present, must be the only entry. 299 // +listType=set 300 // Required. 301 APIGroups []string `json:"apiGroups" protobuf:"bytes,2,rep,name=apiGroups"` 302 303 // `resources` is a list of matching resources (i.e., lowercase 304 // and plural) with, if desired, subresource. For example, [ 305 // "services", "nodes/status" ]. This list may not be empty. 306 // "*" matches all resources and, if present, must be the only entry. 307 // Required. 308 // +listType=set 309 Resources []string `json:"resources" protobuf:"bytes,3,rep,name=resources"` 310 311 // `clusterScope` indicates whether to match requests that do not 312 // specify a namespace (which happens either because the resource 313 // is not namespaced or the request targets all namespaces). 314 // If this field is omitted or false then the `namespaces` field 315 // must contain a non-empty list. 316 // +optional 317 ClusterScope bool `json:"clusterScope,omitempty" protobuf:"varint,4,opt,name=clusterScope"` 318 319 // `namespaces` is a list of target namespaces that restricts 320 // matches. A request that specifies a target namespace matches 321 // only if either (a) this list contains that target namespace or 322 // (b) this list contains "*". Note that "*" matches any 323 // specified namespace but does not match a request that _does 324 // not specify_ a namespace (see the `clusterScope` field for 325 // that). 326 // This list may be empty, but only if `clusterScope` is true. 327 // +optional 328 // +listType=set 329 Namespaces []string `json:"namespaces" protobuf:"bytes,5,rep,name=namespaces"` 330 } 331 332 // NonResourcePolicyRule is a predicate that matches non-resource requests according to their verb and the 333 // target non-resource URL. A NonResourcePolicyRule matches a request if and only if both (a) at least one member 334 // of verbs matches the request and (b) at least one member of nonResourceURLs matches the request. 335 type NonResourcePolicyRule struct { 336 // `verbs` is a list of matching verbs and may not be empty. 337 // "*" matches all verbs. If it is present, it must be the only entry. 338 // +listType=set 339 // Required. 340 Verbs []string `json:"verbs" protobuf:"bytes,1,rep,name=verbs"` 341 // `nonResourceURLs` is a set of url prefixes that a user should have access to and may not be empty. 342 // For example: 343 // - "/healthz" is legal 344 // - "/hea*" is illegal 345 // - "/hea" is legal but matches nothing 346 // - "/hea/*" also matches nothing 347 // - "/healthz/*" matches all per-component health checks. 348 // "*" matches all non-resource urls. if it is present, it must be the only entry. 349 // +listType=set 350 // Required. 351 NonResourceURLs []string `json:"nonResourceURLs" protobuf:"bytes,6,rep,name=nonResourceURLs"` 352 } 353 354 // FlowSchemaStatus represents the current state of a FlowSchema. 355 type FlowSchemaStatus struct { 356 // `conditions` is a list of the current states of FlowSchema. 357 // +listType=map 358 // +listMapKey=type 359 // +optional 360 Conditions []FlowSchemaCondition `json:"conditions,omitempty" protobuf:"bytes,1,rep,name=conditions"` 361 } 362 363 // FlowSchemaCondition describes conditions for a FlowSchema. 364 type FlowSchemaCondition struct { 365 // `type` is the type of the condition. 366 // Required. 367 Type FlowSchemaConditionType `json:"type,omitempty" protobuf:"bytes,1,opt,name=type"` 368 // `status` is the status of the condition. 369 // Can be True, False, Unknown. 370 // Required. 371 Status ConditionStatus `json:"status,omitempty" protobuf:"bytes,2,opt,name=status"` 372 // `lastTransitionTime` is the last time the condition transitioned from one status to another. 373 LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,3,opt,name=lastTransitionTime"` 374 // `reason` is a unique, one-word, CamelCase reason for the condition's last transition. 375 Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` 376 // `message` is a human-readable message indicating details about last transition. 377 Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` 378 } 379 380 // FlowSchemaConditionType is a valid value for FlowSchemaStatusCondition.Type 381 type FlowSchemaConditionType string 382 383 // +genclient 384 // +genclient:nonNamespaced 385 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 386 // +k8s:prerelease-lifecycle-gen:introduced=1.20 387 // +k8s:prerelease-lifecycle-gen:replacement=flowcontrol.apiserver.k8s.io,v1beta3,PriorityLevelConfiguration 388 389 // PriorityLevelConfiguration represents the configuration of a priority level. 390 type PriorityLevelConfiguration struct { 391 metav1.TypeMeta `json:",inline"` 392 // `metadata` is the standard object's metadata. 393 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 394 // +optional 395 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 396 // `spec` is the specification of the desired behavior of a "request-priority". 397 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 398 // +optional 399 Spec PriorityLevelConfigurationSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` 400 // `status` is the current status of a "request-priority". 401 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status 402 // +optional 403 Status PriorityLevelConfigurationStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` 404 } 405 406 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 407 // +k8s:prerelease-lifecycle-gen:introduced=1.20 408 // +k8s:prerelease-lifecycle-gen:replacement=flowcontrol.apiserver.k8s.io,v1beta3,PriorityLevelConfigurationList 409 410 // PriorityLevelConfigurationList is a list of PriorityLevelConfiguration objects. 411 type PriorityLevelConfigurationList struct { 412 metav1.TypeMeta `json:",inline"` 413 // `metadata` is the standard object's metadata. 414 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 415 // +optional 416 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 417 // `items` is a list of request-priorities. 418 Items []PriorityLevelConfiguration `json:"items" protobuf:"bytes,2,rep,name=items"` 419 } 420 421 // PriorityLevelConfigurationSpec specifies the configuration of a priority level. 422 // +union 423 type PriorityLevelConfigurationSpec struct { 424 // `type` indicates whether this priority level is subject to 425 // limitation on request execution. A value of `"Exempt"` means 426 // that requests of this priority level are not subject to a limit 427 // (and thus are never queued) and do not detract from the 428 // capacity made available to other priority levels. A value of 429 // `"Limited"` means that (a) requests of this priority level 430 // _are_ subject to limits and (b) some of the server's limited 431 // capacity is made available exclusively to this priority level. 432 // Required. 433 // +unionDiscriminator 434 Type PriorityLevelEnablement `json:"type" protobuf:"bytes,1,opt,name=type"` 435 436 // `limited` specifies how requests are handled for a Limited priority level. 437 // This field must be non-empty if and only if `type` is `"Limited"`. 438 // +optional 439 Limited *LimitedPriorityLevelConfiguration `json:"limited,omitempty" protobuf:"bytes,2,opt,name=limited"` 440 441 // `exempt` specifies how requests are handled for an exempt priority level. 442 // This field MUST be empty if `type` is `"Limited"`. 443 // This field MAY be non-empty if `type` is `"Exempt"`. 444 // If empty and `type` is `"Exempt"` then the default values 445 // for `ExemptPriorityLevelConfiguration` apply. 446 // +optional 447 Exempt *ExemptPriorityLevelConfiguration `json:"exempt,omitempty" protobuf:"bytes,3,opt,name=exempt"` 448 } 449 450 // PriorityLevelEnablement indicates whether limits on execution are enabled for the priority level 451 type PriorityLevelEnablement string 452 453 // Supported priority level enablement values. 454 const ( 455 // PriorityLevelEnablementExempt means that requests are not subject to limits 456 PriorityLevelEnablementExempt PriorityLevelEnablement = "Exempt" 457 458 // PriorityLevelEnablementLimited means that requests are subject to limits 459 PriorityLevelEnablementLimited PriorityLevelEnablement = "Limited" 460 ) 461 462 // LimitedPriorityLevelConfiguration specifies how to handle requests that are subject to limits. 463 // It addresses two issues: 464 // - How are requests for this priority level limited? 465 // - What should be done with requests that exceed the limit? 466 type LimitedPriorityLevelConfiguration struct { 467 // `assuredConcurrencyShares` (ACS) configures the execution 468 // limit, which is a limit on the number of requests of this 469 // priority level that may be executing at a given time. ACS must 470 // be a positive number. The server's concurrency limit (SCL) is 471 // divided among the concurrency-controlled priority levels in 472 // proportion to their assured concurrency shares. This produces 473 // the assured concurrency value (ACV) --- the number of requests 474 // that may be executing at a time --- for each such priority 475 // level: 476 // 477 // ACV(l) = ceil( SCL * ACS(l) / ( sum[priority levels k] ACS(k) ) ) 478 // 479 // bigger numbers of ACS mean more reserved concurrent requests (at the 480 // expense of every other PL). 481 // This field has a default value of 30. 482 // +optional 483 AssuredConcurrencyShares int32 `json:"assuredConcurrencyShares" protobuf:"varint,1,opt,name=assuredConcurrencyShares"` 484 485 // `limitResponse` indicates what to do with requests that can not be executed right now 486 LimitResponse LimitResponse `json:"limitResponse,omitempty" protobuf:"bytes,2,opt,name=limitResponse"` 487 488 // `lendablePercent` prescribes the fraction of the level's NominalCL that 489 // can be borrowed by other priority levels. The value of this 490 // field must be between 0 and 100, inclusive, and it defaults to 0. 491 // The number of seats that other levels can borrow from this level, known 492 // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows. 493 // 494 // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 ) 495 // 496 // +optional 497 LendablePercent *int32 `json:"lendablePercent,omitempty" protobuf:"varint,3,opt,name=lendablePercent"` 498 499 // `borrowingLimitPercent`, if present, configures a limit on how many 500 // seats this priority level can borrow from other priority levels. 501 // The limit is known as this level's BorrowingConcurrencyLimit 502 // (BorrowingCL) and is a limit on the total number of seats that this 503 // level may borrow at any one time. 504 // This field holds the ratio of that limit to the level's nominal 505 // concurrency limit. When this field is non-nil, it must hold a 506 // non-negative integer and the limit is calculated as follows. 507 // 508 // BorrowingCL(i) = round( NominalCL(i) * borrowingLimitPercent(i)/100.0 ) 509 // 510 // The value of this field can be more than 100, implying that this 511 // priority level can borrow a number of seats that is greater than 512 // its own nominal concurrency limit (NominalCL). 513 // When this field is left `nil`, the limit is effectively infinite. 514 // +optional 515 BorrowingLimitPercent *int32 `json:"borrowingLimitPercent,omitempty" protobuf:"varint,4,opt,name=borrowingLimitPercent"` 516 } 517 518 // ExemptPriorityLevelConfiguration describes the configurable aspects 519 // of the handling of exempt requests. 520 // In the mandatory exempt configuration object the values in the fields 521 // here can be modified by authorized users, unlike the rest of the `spec`. 522 type ExemptPriorityLevelConfiguration struct { 523 // `nominalConcurrencyShares` (NCS) contributes to the computation of the 524 // NominalConcurrencyLimit (NominalCL) of this level. 525 // This is the number of execution seats nominally reserved for this priority level. 526 // This DOES NOT limit the dispatching from this priority level 527 // but affects the other priority levels through the borrowing mechanism. 528 // The server's concurrency limit (ServerCL) is divided among all the 529 // priority levels in proportion to their NCS values: 530 // 531 // NominalCL(i) = ceil( ServerCL * NCS(i) / sum_ncs ) 532 // sum_ncs = sum[priority level k] NCS(k) 533 // 534 // Bigger numbers mean a larger nominal concurrency limit, 535 // at the expense of every other priority level. 536 // This field has a default value of zero. 537 // +optional 538 NominalConcurrencyShares *int32 `json:"nominalConcurrencyShares,omitempty" protobuf:"varint,1,opt,name=nominalConcurrencyShares"` 539 // `lendablePercent` prescribes the fraction of the level's NominalCL that 540 // can be borrowed by other priority levels. This value of this 541 // field must be between 0 and 100, inclusive, and it defaults to 0. 542 // The number of seats that other levels can borrow from this level, known 543 // as this level's LendableConcurrencyLimit (LendableCL), is defined as follows. 544 // 545 // LendableCL(i) = round( NominalCL(i) * lendablePercent(i)/100.0 ) 546 // 547 // +optional 548 LendablePercent *int32 `json:"lendablePercent,omitempty" protobuf:"varint,2,opt,name=lendablePercent"` 549 // The `BorrowingCL` of an Exempt priority level is implicitly `ServerCL`. 550 // In other words, an exempt priority level 551 // has no meaningful limit on how much it borrows. 552 // There is no explicit representation of that here. 553 } 554 555 // LimitResponse defines how to handle requests that can not be executed right now. 556 // +union 557 type LimitResponse struct { 558 // `type` is "Queue" or "Reject". 559 // "Queue" means that requests that can not be executed upon arrival 560 // are held in a queue until they can be executed or a queuing limit 561 // is reached. 562 // "Reject" means that requests that can not be executed upon arrival 563 // are rejected. 564 // Required. 565 // +unionDiscriminator 566 Type LimitResponseType `json:"type" protobuf:"bytes,1,opt,name=type"` 567 568 // `queuing` holds the configuration parameters for queuing. 569 // This field may be non-empty only if `type` is `"Queue"`. 570 // +optional 571 Queuing *QueuingConfiguration `json:"queuing,omitempty" protobuf:"bytes,2,opt,name=queuing"` 572 } 573 574 // LimitResponseType identifies how a Limited priority level handles a request that can not be executed right now 575 type LimitResponseType string 576 577 // Supported limit responses. 578 const ( 579 // LimitResponseTypeQueue means that requests that can not be executed right now are queued until they can be executed or a queuing limit is hit 580 LimitResponseTypeQueue LimitResponseType = "Queue" 581 582 // LimitResponseTypeReject means that requests that can not be executed right now are rejected 583 LimitResponseTypeReject LimitResponseType = "Reject" 584 ) 585 586 // QueuingConfiguration holds the configuration parameters for queuing 587 type QueuingConfiguration struct { 588 // `queues` is the number of queues for this priority level. The 589 // queues exist independently at each apiserver. The value must be 590 // positive. Setting it to 1 effectively precludes 591 // shufflesharding and thus makes the distinguisher method of 592 // associated flow schemas irrelevant. This field has a default 593 // value of 64. 594 // +optional 595 Queues int32 `json:"queues" protobuf:"varint,1,opt,name=queues"` 596 597 // `handSize` is a small positive number that configures the 598 // shuffle sharding of requests into queues. When enqueuing a request 599 // at this priority level the request's flow identifier (a string 600 // pair) is hashed and the hash value is used to shuffle the list 601 // of queues and deal a hand of the size specified here. The 602 // request is put into one of the shortest queues in that hand. 603 // `handSize` must be no larger than `queues`, and should be 604 // significantly smaller (so that a few heavy flows do not 605 // saturate most of the queues). See the user-facing 606 // documentation for more extensive guidance on setting this 607 // field. This field has a default value of 8. 608 // +optional 609 HandSize int32 `json:"handSize" protobuf:"varint,2,opt,name=handSize"` 610 611 // `queueLengthLimit` is the maximum number of requests allowed to 612 // be waiting in a given queue of this priority level at a time; 613 // excess requests are rejected. This value must be positive. If 614 // not specified, it will be defaulted to 50. 615 // +optional 616 QueueLengthLimit int32 `json:"queueLengthLimit" protobuf:"varint,3,opt,name=queueLengthLimit"` 617 } 618 619 // PriorityLevelConfigurationConditionType is a valid value for PriorityLevelConfigurationStatusCondition.Type 620 type PriorityLevelConfigurationConditionType string 621 622 // PriorityLevelConfigurationStatus represents the current state of a "request-priority". 623 type PriorityLevelConfigurationStatus struct { 624 // `conditions` is the current state of "request-priority". 625 // +listType=map 626 // +listMapKey=type 627 // +optional 628 Conditions []PriorityLevelConfigurationCondition `json:"conditions,omitempty" protobuf:"bytes,1,rep,name=conditions"` 629 } 630 631 // PriorityLevelConfigurationCondition defines the condition of priority level. 632 type PriorityLevelConfigurationCondition struct { 633 // `type` is the type of the condition. 634 // Required. 635 Type PriorityLevelConfigurationConditionType `json:"type,omitempty" protobuf:"bytes,1,opt,name=type"` 636 // `status` is the status of the condition. 637 // Can be True, False, Unknown. 638 // Required. 639 Status ConditionStatus `json:"status,omitempty" protobuf:"bytes,2,opt,name=status"` 640 // `lastTransitionTime` is the last time the condition transitioned from one status to another. 641 LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,3,opt,name=lastTransitionTime"` 642 // `reason` is a unique, one-word, CamelCase reason for the condition's last transition. 643 Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` 644 // `message` is a human-readable message indicating details about last transition. 645 Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` 646 } 647 648 // ConditionStatus is the status of the condition. 649 type ConditionStatus string 650 651 // These are valid condition statuses. "ConditionTrue" means a resource is in the condition. 652 // "ConditionFalse" means a resource is not in the condition. "ConditionUnknown" means kubernetes 653 // can't decide if a resource is in the condition or not. In the future, we could add other 654 // intermediate conditions, e.g. ConditionDegraded. 655 const ( 656 ConditionTrue ConditionStatus = "True" 657 ConditionFalse ConditionStatus = "False" 658 ConditionUnknown ConditionStatus = "Unknown" 659 ) 660