diff --git a/keps/1788-pass-parameters-to-ProvReq/README.md b/keps/1788-pass-parameters-to-ProvReq/README.md new file mode 100644 index 0000000000..afb5a2f853 --- /dev/null +++ b/keps/1788-pass-parameters-to-ProvReq/README.md @@ -0,0 +1,256 @@ +# KEP-1778: Passing parameters to ProvisioningRequest + + + + + + +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) + - [User Stories (Optional)](#user-stories-optional) + - [Story 1](#story-1) + - [Story 2](#story-2) + - [Risks and Mitigations](#risks-and-mitigations) +- [Design Details](#design-details) + - [Test Plan](#test-plan) + - [Unit Tests](#unit-tests) +- [Alternatives](#alternatives) + + +## Summary + +This KEP proposes a method for passing parameters to ProvisioningRequests. This will allow users to pass parameters specific to individual ProvisioningRequest classes. + + + +## Motivation +Currently, no mechanism exists to adjust these parameters for an individual Workload. Right now, users can only change the parameters with a ProvisioningRequestConfig, which then applies to all Workloads submitted to a specific ClusterQueue. This limits the usefulness/flexibility of ProvisioningRequests in Kueue. + + + +### Goals +- Provide a mechanism to pass parameters to ProvisioningRequest + + + +### Non-Goals +- Describe how the ProvisioningRequest controller handles these parameters + + + +## Proposal +We propose introducing a new group of annotations with the +***provreq.alpha.kueue.x-k8s.io/ prefix***. Annotations using this prefix will be directly copied to the ProvisioningRequest's Parameters field, including both name and value. +Kueue would act in the pass through manner, meaning it would pass the parameters without checking if such parameters actually exists or validating its type/value. +The annotations are set by a user in the definition of batch/v1.Job, Kubeflow Jobs, Pods, or other objects that are abstracted by Kueue Workload. + +Additionally, the annotations would override a default value set by an administrator in the ProvisioningRequestConfig. + + + +### User Stories (Optional) + + + +#### Story 1 +As a Kueue's user I want to use ProvisioningRequest with [**atomic-scale-up.kubernetes.io class**](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/proposals/provisioning-request.md#atomic-scale-upkubernetesio-class). +I would also like to pass the ```ValidUntilSeconds``` parameter. In the definition of my Job I add annotation ```provreq.alpha.kueue.x-k8s.io/ValidUntilSeconds: "60"``` to do so. + +### Story 2 +As an administrator I would like all workloads submitted to ClusterQueue X to use ProvisioningRequest with parameters ```ValidUntilSeconds``` set to 0. +In the definition of ProvisioningRequestConfig used by AdmissionCheck used in ClusterQueue X I specify the parameter ```ValidUntilSeconds: "0"```. +Unless a user of ClusterQueue X intentionally overrides it in the Job definition, it's set to 0. + + +### Risks and Mitigations +- R: Users can pass parameters with invalid name, type or value that exceeds ProvisioningRequest class bounds.\ + M: As long as a ProvisioningRequest controllers return some kind of error, we can propagate it into Workload's status. + However, it's user's responsibility to provide valid parameters. + + + +## Design Details + + + +### Test Plan + + + +[X] I/we understand the owners of the involved components may require updates to +existing tests to make this code solid enough prior to committing the changes necessary +to implement this enhancement. + + + +#### Unit Tests +- Check if annotations are passed during Workload creation +- Check if params are passed from Workload annotation to ProvisioningRequest params + + + + + + + + + + + + + + + + + + + + +## Alternatives +Using ProvisioningRequestConfig we could extend the annotation idea and leverage some mapping mechanism to provide validation. This could look alike: +``` + mapping: + - annotationName: myValidUntilSecondsAnnotation + - parameterName: ValidUntilSeconds + - type: Int + - minVal: 0 + - maxVal: 1 +``` +However, we decided to drop this idea as we believe Kueue should only act in the pass through manner, and such validation should be performed on the ProvisioningRequest side. + + diff --git a/keps/1788-pass-parameters-to-ProvReq/kep.yaml b/keps/1788-pass-parameters-to-ProvReq/kep.yaml new file mode 100644 index 0000000000..cc829c8e8f --- /dev/null +++ b/keps/1788-pass-parameters-to-ProvReq/kep.yaml @@ -0,0 +1,29 @@ +title: Pass parameters to ProvisioningRequest +kep-number: 1788 +authors: + - "@pbundyra" +status: implementable +creation-date: 2024-03-04 +reviewers: + - "@alculquicondor" + - "@mimowo" + - "@tenzen-y" +approvers: + - "@alculquicondor" + +see-also: + - +replaces: + - + +# The target maturity stage in the current dev cycle for this KEP. +stage: alpha + +# The most recent milestone for which work toward delivery of this KEP has been +# done. This can be the current (upcoming) milestone, if it is being actively +# worked on. +latest-milestone: "v0.7" + +# The milestone at which this feature was, or is targeted to be, at each stage. +milestone: + alpha: "v0.7"