KEP-3104: promote kuberc to beta

Signed-off-by: Maciej Szulik <[email protected]>

Author: soltysh

keps/prod-readiness/sig-cli/3104.yaml

@@ -1,3 +1,5 @@
 kep-number: 3104
 alpha:
   approver: "@johnbelamaric"
+beta:
+  approver: "@johnbelamaric"

keps/sig-cli/3104-introduce-kuberc/README.md

@@ -137,17 +137,17 @@ Items marked with (R) are required *prior to targeting to a milestone / release*
 - [x] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
 - [x] (R) KEP approvers have approved the KEP status as `implementable`
 - [x] (R) Design details are appropriately documented
-- [ ] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
-  - [ ] e2e Tests for all Beta API Operations (endpoints)
+- [x] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
+  - [x] e2e Tests for all Beta API Operations (endpoints)
   - [ ] (R) Ensure GA e2e tests for meet requirements for [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
   - [ ] (R) Minimum Two Week Window for GA e2e tests to prove flake free
-- [ ] (R) Graduation criteria is in place
-  - [ ] (R) [all GA Endpoints](https://github.com/kubernetes/community/pull/1806) must be hit by [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
+- [x] (R) Graduation criteria is in place
+  - [x] (R) [all GA Endpoints](https://github.com/kubernetes/community/pull/1806) must be hit by [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
 - [x] (R) Production readiness review completed
 - [x] (R) Production readiness review approved
 - [x] "Implementation History" section is up-to-date for milestone
-- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
-- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
+- [x] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
+- [x] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
 
 <!--
 **Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
@@ -261,6 +261,12 @@ As a user I would like to be able to opt out of deprecation warnings.
 
 https://github.com/kubernetes/kubectl/issues/1317
 
+#### Story 5
+
+As a user I'd like to be warned if my kuberc file is no longer being used after first use.
+
+https://github.com/kubernetes/enhancements/issues/3104#issuecomment-2775086160
+
 ### Notes/Constraints/Caveats (Optional)
 
 <!--
@@ -295,6 +301,7 @@ Consider including folks who also work outside the SIG or subproject.
 | Risk | Impact | Mitigation |
 | --- | --- | --- |
 | Confusing users with a new config file | Low | Documentation and education |
+| Users trust the kuberc is being used | High | Provide mechanism warning users default kuberc is not being picked up |
 
 ## Design Details
 
@@ -305,21 +312,32 @@ required) or even code snippets. If there's any ambiguity about HOW your
 proposal will be implemented, this is the place to discuss them.
 -->
 
-During alpha this feature will be enabled through the `KUBECTL_KUBERC=true` environment variable. The file will default to being located in `~/.kube/kuberc`. A flag will allow overriding this default location with a path i.e. `kubectl --kuberc /var/kube/rc`.
+For beta this feature will be enabled by default. However users can disable it
+setting the `KUBECTL_KUBERC` environment variable to `false`.
 
-Three initial top level keys are proposed.
+By default, the configuration file will be located in `~/.kube/kuberc`. A flag
+will allow overriding this default location with a specific path, for example:
+`kubectl --kuberc /var/kube/rc`.
 
-* `apiVersion` to determine the version of the config.
-* `kind` to keep consistency with Kubernetes resources.
-* `aliases` for users to declare their own aliases for commands with flags and values.
-* `overrides` for users to set default flags to apply to commands.
+The following top-level keys are proposed, alongside the kubernetes `metav1.TypeMeta`
+fields (`apiVersion`, `kind`):
 
-`aliases` will not be allowed to override builtins but take precedence of plugins i.e. builtins -> aliases -> plugins. Additional flags and values will be appended to the end of the aliased command. It is the responsibility of the user to define aliases with this in mind.
+* `aliases` Allows users to declare their own command aliases, including flags and values.
+* `overrides` Enables users to set default flags to be applied to commands.
 
-`overrides` is modeled after all configurable behavior being implemented as flags first. This is a design decision that was made after modeling out the intended behavior and realizing that targeting flags filled the use cases. A merge will be done in the execution of the command for flags with inline overrides taking precedence.
+`aliases` will not be permitted to override built-in commands but will take
+precedence over plugins (builtins -> aliases -> plugins). Any additional flags
+and values will be appended to the end of the aliased command. Users are
+responsible for defining aliases with this behavior in mind.
+
+`overrides` is designed based on the principle that all configurable behavior is
+initially implemented as flags. This design decision was made after analyzing the
+intended behavior and realizing that targeting flags effectively addresses the
+use cases. During command execution, a merge will be occur, with inline overrides
+taking precedence over the defaults.
 
 ```
-apiVersion: kubectl.config.k8s.io/v1alpha1
+apiVersion: kubectl.config.k8s.io/v1beta1
 kind: Preference
 
 aliases:
@@ -369,7 +387,11 @@ Based on reviewers feedback describe what additional tests need to be added prio
 implementing this enhancement to ensure the enhancements have also solid foundations.
 -->
 
-Aside from standard testing we will also be skew testing.
+We're planning to expand tests adding:
+- config API fuzzy tests
+- cross API config loading
+- input validation and correctness
+- simple e2e using kuberc
 
 ##### Unit tests
 
@@ -395,10 +417,9 @@ extending the production code to implement this enhancement.
 
 -->
 
-We're planning unit tests covering:
-- basic functionality
-- config API fuzzy tests
-- input validation and correctness
+- `k8s.io/kubectl/pkg/cmd/`: `2025-05-13` - `57.0%`
+- `k8s.io/kubectl/pkg/config/`: `2025-05-13` - `0.0%`
+- `k8s.io/kubectl/pkg/kuberc/`: `2025-05-13` - `64.5%`
 
 ##### Integration tests
 
@@ -413,9 +434,7 @@ https://storage.googleapis.com/k8s-triage/index.html
 
 -->
 
-We're planning at least the following integration tests:
-- `KUBECTL_KUBERC` enablement and disablement
-- basic functionality
+- [test-cmd.run_kuberc_tests](https://github.com/kubernetes/kubernetes/blob/fd15e3fd5566fb0a65ded1883fbf51ce7a68fe28/test/cmd/kuberc.sh): [integration cmd-master](https://testgrid.k8s.io/sig-release-master-blocking#cmd-master)
 
 ##### e2e tests
 
@@ -540,6 +559,12 @@ enhancement:
 
 This feature will follow the [version skew policy of kubectl](https://kubernetes.io/releases/version-skew-policy/#kubectl).
 
+Furthermore, kubectl will be equipped with a mechanism which will allow it to
+read all past versions of the kuberc file, and pick the latest known one.
+This mechanism will ensure that users can continue using whatever version of
+kuberc they started with, unless they are interested in newer feature available
+only in newer releases.
+
 ## Production Readiness Review Questionnaire
 
 <!--
@@ -747,13 +772,6 @@ Not applicable.
 Pick one more of these and delete the rest.
 -->
 
-- [ ] Metrics
-  - Metric name:
-  - [Optional] Aggregation method:
-  - Components exposing the metric:
-- [ ] Other (treat as last resort)
-  - Details:
-  -
 Not applicable.
 
 ###### Are there any missing metrics that would be useful to have to improve observability of this feature?
@@ -905,6 +923,8 @@ details). For now, we leave it here.
 
 ###### How does this feature react if the API server and/or etcd is unavailable?
 
+`kubectl` is not resilient to API server unavailability.
+
 ###### What are other known failure modes?
 
 <!--
@@ -920,8 +940,12 @@ For each of them, fill in the following information by copying the below templat
     - Testing: Are there any tests for failure mode? If not, describe why.
 -->
 
+Not applicable.
+
 ###### What steps should be taken if SLOs are not being met to determine the problem?
 
+Not applicable.
+
 ## Implementation History
 
 <!--
@@ -938,12 +962,11 @@ Major milestones might include:
 * 2021-06-02: [Proposal to add delete confirmation](https://github.com/kubernetes/enhancements/issues/2775)
 * 2022-06-13: This KEP created.
 * 2024-06-07: Update KEP with new env var name and template.
+* 2025-05-13: Update KEP for beta promotion.
 
 ## Drawbacks
 
-<!--
-Why should this KEP _not_ be implemented?
--->
+None considered.
 
 ## Alternatives
 
@@ -953,10 +976,14 @@ not need to be as detailed as the proposal, but should include enough
 information to express the idea and why it was not acceptable.
 -->
 
+None considered.
+
 ## Infrastructure Needed (Optional)
 
 <!--
 Use this section if you need things from the project/SIG. Examples include a
 new subproject, repos requested, or GitHub details. Listing these here allows a
 SIG to get the process for these resources started right away.
 -->
+
+Not applicable.

keps/sig-cli/3104-introduce-kuberc/kep.yaml

@@ -21,17 +21,17 @@ see-also:
 replaces: []
 
 # The target maturity stage in the current dev cycle for this KEP.
-stage: alpha
+stage: beta
 
 # 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: "v1.33"
+latest-milestone: "v1.34"
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
   alpha: "v1.33"
-  beta: ""
+  beta: "1.34"
   stable: ""
 
 # The following PRR answers are required at alpha release