-
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
1 changed file
with
212 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,212 @@ | ||
| --- | ||
| title: xdg-base-dir | ||
| authors: | ||
| - "@dougsland" | ||
| owning-sig: sig-cli | ||
| participating-sigs: | ||
| - sig-usability | ||
| reviewers: | ||
| - "@eddiezane" | ||
| - "@soltysh" | ||
| approvers: | ||
| - "@soltysh" | ||
| - "@eddiezane" | ||
| editor: TBD | ||
| creation-date: 2020-10-22 | ||
| last-updated: 2021-01-02 | ||
| status: provisional | ||
| --- | ||
|
|
||
| # 20201022-kubectl-xdg-base-dir.md | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| <!-- 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 keep compatible with | ||
| existing ~/.kube dir at least for three releases until it will be completed | ||
| deprecated. | ||
|
|
||
| ### Non-Goals | ||
|
|
||
| Deprecate any file under $HOME/.kube/ | ||
|
|
||
| ## Proposal | ||
|
|
||
| - kubectl should follow the XDG Base Directory Specification | ||
| - Use $HOME/.config as default dir for configurations | ||
| - Be compatible with $HOME/.kube for a period of time | ||
| - Provide single place where other parts of code could load | ||
| the current kubectl config dir instead of add static reference | ||
| to $HOME/.kube | ||
| - Users must have environment variable to override the default directory | ||
| - 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 componenets, will be affected | ||
| directly. Additionally, the original ~/.kube dir will be compatible | ||
| for a period of time until it's fully deprecated. 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/kubectl/pkg/generated/bindata.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 | ||
|
|
||
| Unit tests matching: | ||
| - $HOME/.kube | ||
| - $HOME/.config | ||
| - Setting environment variables regarding to kubectl config dir | ||
| - Execute kubectl changing the config dir | ||
|
|
||
| ### Graduation Criteria | ||
|
|
||
| Successful Alpha Criteria | ||
| - Support to $HOME/.kube and $HOME/.config | ||
| - 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 | ||
|
|
||
| #### Removing a Deprecated Flag | ||
|
|
||
| - Announce deprecation and support policy of the existing flag | ||
| - Two versions passed since introducing the functionality that deprecates the flag (to address version skew) | ||
| - Address feedback on usage/changed behavior, provided on GitHub issues | ||
| - Deprecate the flag | ||
|
|
||
| **For non-optional features moving to GA, the graduation criteria must include | ||
| [conformance tests].** | ||
|
|
||
| [conformance tests]: https://git.k8s.io/community/contributors/devel/sig-architecture/conformance-tests.md | ||
| --> | ||
|
|
||
| #### 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 user $HOME/.kube | ||
| or $HOME/.config until GA Graduation which will deprecate $HOME/.kube. | ||
|
|
||
| Downgrade will only allow users to use $HOME/.kube | ||
|
|
||
| ### Version Skew Strategy | ||
|
|
||
| ## Drawbacks | ||
|
|
||
| As soon the feature became achieve GA Graduation, automation scripts that use $HOME/.kube | ||
| as static source will be broken. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| Keep using $HOME/.kube and avoid using XDG Base Directory Specification | ||
|
|
||
| ## Implementation History | ||
|
|
||
| - *2020-10-22*: Created KEP | ||
| - *2021-01-02*: Updated with comments from DirectXMan12 and kikisdeliveryservice |