-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
sig-cli: Use XDG Base Directory Specification
This KEP aim to provide all requirements for kubectl use XDG Base Directory Specification. Signed-off-by: Douglas Schilling Landgraf <dougsland@redhat.com>
- Loading branch information
Showing
2 changed files
with
235 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,195 @@ | ||
| # KEP-2229: kubectl xdg base dir | ||
|
|
||
| <!-- toc --> | ||
| - [Release Signoff Checklist](#release-signoff-checklist) | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Goals](#goals) | ||
| - [Non-Goals](#non-goals) | ||
| - [Proposal](#proposal) | ||
| - [Risks and Mitigations](#risks-and-mitigations) | ||
| - [Design Details](#design-details) | ||
| - [Test Plan](#test-plan) | ||
| - [Graduation Criteria](#graduation-criteria) | ||
| - [Alpha -> Beta Graduation](#alpha---beta-graduation) | ||
| - [Beta -> GA Graduation](#beta---ga-graduation) | ||
| - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) | ||
| - [Version Skew Strategy](#version-skew-strategy) | ||
| - [Drawbacks](#drawbacks) | ||
| - [Alternatives](#alternatives) | ||
| - [Implementation History](#implementation-history) | ||
| <!-- /toc --> | ||
|
|
||
| ## Release Signoff Checklist | ||
|
|
||
| - [ ] kubernetes/enhancements issue in release milestone, which links to KEP (this should be a link to the KEP location in kubernetes/enhancements, not the initial KEP PR) | ||
| - [ ] KEP approvers have set the KEP status to `implementable` | ||
| - [ ] Design details are appropriately documented | ||
| - [ ] Test plan is in place, giving consideration to SIG Architecture and SIG Testing input | ||
| - [ ] Graduation criteria is in place | ||
| - [ ] "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 | ||
|
|
||
| [kubernetes.io]: https://kubernetes.io/ | ||
| [kubernetes/enhancements]: https://github.com/kubernetes/enhancements/issues | ||
| [kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes | ||
| [kubernetes/website]: https://github.com/kubernetes/website | ||
|
|
||
| ## Summary | ||
|
|
||
| This enhancement is focused in provide all requirements for kubectl | ||
| use the [XDG Base Directory Specification (XDG Spec)](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). | ||
| The XDG Spec have been used for a long time as the standard location to tools | ||
| and programs store configuration files. | ||
|
|
||
| ## Motivation | ||
|
|
||
| Today the kubectl store the configuration file via ~/.kube/ dir. | ||
| However, there are multiple [community requests like #56402](https://github.com/kubernetes/kubernetes/issues/56402), | ||
| from real users that have been looking for: | ||
| - A single place for managing the configuration files | ||
| - Automation/Backup | ||
| - Use the same environment [variables as others projects](https://specifications.freedesktop.org/basedir-spec/latest/ar01s03.html) | ||
|
|
||
| ### Goals | ||
|
|
||
| The goal is make kubectl follow the XDG Spec and automatic migrate | ||
| the configuration from $HOME/.kube to $HOME/.config wihout downtime | ||
| for users. | ||
|
|
||
| Split the implementation in different patches (or more, for easy review): | ||
|
|
||
| 1. Update the logic from loader.go to migrate the config to the new recommended | ||
| location in a transparent way to users. | ||
| See: https://github.com/kubernetes/kubernetes/pull/97885 | ||
|
|
||
| 2. If 1 is approved and merged, update kubectl related code to the new location. | ||
|
|
||
| 3. If 2 is approved and merged, update the rest of the code in the kubernetes tree pointing statically to $HOME/.kube | ||
|
|
||
| ### Non-Goals | ||
|
|
||
| Deprecate any file under $HOME/.kube/ | ||
|
|
||
| ## Proposal | ||
|
|
||
| - kubectl should follow the XDG Base Directory Specification | ||
| - Use $HOME/.config/kube as default dir for configurations | ||
| - Be compatible with $HOME/.kube until config migrated to $HOME/.config/kube | ||
| - Smoothly migrate the config from $HOME/.kube to the new location | ||
| - Update documentation related to ~/.kube | ||
| - Write a blog post to explain and communicate such change | ||
|
|
||
| ### Risks and Mitigations | ||
|
|
||
| Risks are limited, as none of the cluster components, will be affected | ||
| directly. Additionally, the original ~/.kube dir will be compatible | ||
| until a migration fully happen or deprecation. In case there is | ||
| a bug in the new logic users will still be able to use the cluster | ||
| via API calls or tools like curl. | ||
|
|
||
| ## Design Details | ||
|
|
||
| In order to achieve the goal we must address and understand the logic in | ||
| the following source code from the below table: | ||
|
|
||
| | Status | Code | Reason | | ||
| |----------------|-----------------------------------------------------------------------------------------|-----------------------------------------| | ||
| | Need to update | cmd/kubeadm/app/cmd/init.go | contains reference to $HOME/.kube | | ||
| | Need to update | cluster/common.sh | contains reference to $HOME/.kube | | ||
| | Need to update | cluster/gce/windows/README-GCE-Windows-kube-up.md | contains reference to $HOME/.kube | | ||
| | Need to update | cmd/kubeadm/app/cmd/join.go | contains reference to $HOME/.kube | | ||
| | Need to update | cmd/kubeadm/app/cmd/reset.go | contains reference to $HOME/.kube | | ||
| | Need to update | cmd/kubeadm/app/cmd/completion.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/config_flags.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/client_config.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/sample-controller/README.md | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_cluster.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_authinfo.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/kubectl/pkg/cmd/testing/fake.go | contains reference to $HOME/.kube/cache | | ||
| | Need to update | staging/src/k8s.io/kubectl/pkg/cmd/completion/completion.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/sample-apiserver/README.md | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/util/homedir/homedir.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/discovery/cached/disk/cached_discovery.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/main.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/README.md | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/main.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/README.md | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration/main.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/client-go/tools/clientcmd/loader.go | contains reference to $HOME/.kube | | ||
| | Need to update | staging/src/k8s.io/apiserver/pkg/admission/config_test.go | contains reference to $HOME/.kube | | ||
| | Need to update | test/cmd/legacy-script.sh | contains reference to $HOME/.kube | | ||
| | Need to update | test/e2e/kubectl/kubectl.go | contains reference to $HOME/.kube | | ||
| | Need to update | test/soak/serve_hostnames/serve_hostnames.go | contains reference to $HOME/.kube | | ||
| | Need to update | test/e2e/network/scale/localrun/ingress_scale.go | contains reference to $HOME/.kube | | ||
| | Need to update | test/soak/serve_hostnames/README.md | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/it_IT/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/en_US/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/ja_JP/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/default/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/template.pot | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/de_DE/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube | | ||
| | Need to update | translations/kubectl/zh_CN/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube | | ||
| | Need to update | https://github.com/kubernetes-sigs/controller-runtime/blob/cb7f85860a8cde7259b35bb84af1fdcb02c098f2/pkg/client/config/config.go#L129 | Check with project | | ||
|
|
||
| ### Test Plan | ||
|
|
||
| #### Alpha milestones | ||
|
|
||
| Unit tests matching: | ||
| - update kubectl tests to the new location | ||
|
|
||
| #### Beta milestones | ||
|
|
||
| Review all unit tests in the main kubernetes tree | ||
|
|
||
| #### GA milestones | ||
| All code should be updated with the new config location | ||
|
|
||
| ### Graduation Criteria | ||
|
|
||
| Successful Alpha Criteria | ||
| - Migrate from $HOME/.kube to $HOME/.config in a transparent way to users | ||
| - Update Unit tests | ||
|
|
||
| #### Alpha -> Beta Graduation | ||
|
|
||
| - [x] At least 2 release cycles pass to gather feedback and bug reports during | ||
| real-world usage | ||
| - [x] End-user documentation is written | ||
|
|
||
| #### Beta -> GA Graduation | ||
|
|
||
| - [x] At least 2 release cycles pass to gather feedback and bug reports during | ||
| real-world usage | ||
| - [x] Unit tests must pass and linked in the KEP | ||
| - [x] Documentation exists | ||
|
|
||
| ### Upgrade / Downgrade Strategy | ||
|
|
||
| Users that upgrade to a recent version of kubectl will be able to migrate | ||
| to $HOME/.config/kube without intervention and the old configuration will | ||
| be kept in $HOME/.kube. If users decide to downgrade, they still can | ||
| use the configuration kept in $HOME/.kube. | ||
|
|
||
| ### Version Skew Strategy | ||
|
|
||
| ## Drawbacks | ||
|
|
||
| As soon the feature became achieve GA Graduation, automation scripts that use $HOME/.kube | ||
| as static source will outdated. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| Keep using $HOME/.kube with old versions kubectl and avoid using XDG Base | ||
| Directory Specification | ||
|
|
||
| ## Implementation History | ||
|
|
||
| - *2020-10-22*: Created KEP | ||
| - *2021-01-02*: Updated with comments from DirectXMan12 and kikisdeliveryservice | ||
| - *2021-01-03*: Updated with comments from wojtek-t | ||
| - *2021-01-04*: Updated with comments from rikatz | ||
| - *2021-01-08*: Fixed typo, thanks rikatz | ||
| - *2021-01-09*: Updated KEP new approach |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # KEP-2229: kubectl-xdg-base-dir.md | ||
| title: xdg-base-dir | ||
| kep-number: 2229 | ||
| authors: | ||
| - "@dougsland" | ||
| owning-sig: sig-cli | ||
| participating-sigs: | ||
| - sig-usability | ||
| status: implementable | ||
| creation-date: 2020-10-22 | ||
| reviewers: | ||
| - "@eddiezane" | ||
| - "@soltysh" | ||
| approvers: | ||
| - "@eddiezane" | ||
| - "@soltysh" | ||
| prr-approvers: | ||
| see-also: | ||
| replaces: | ||
|
|
||
| # The target maturity stage in the current dev cycle for this KEP. | ||
| 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.20" | ||
|
|
||
| # The milestone at which this feature was, or is targeted to be, at each stage. | ||
| milestone: | ||
| alpha: "v1.21" | ||
| beta: "v1.22" | ||
| stable: "v1.23" | ||
|
|
||
| # The following PRR answers are required at alpha release | ||
| # List the feature gate name and the components for which it must be enabled | ||
| feature-gates: [] | ||
|
|
||
| # The following PRR answers are required at beta release | ||
| metrics: [] |