Skip to content

Commit f63ac1e

Browse files
dougslanddougsland
committed
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 <[email protected]>
1 parent b7a365e commit f63ac1e

File tree

1 file changed

+233
-0
lines changed

1 file changed

+233
-0
lines changed

‎keps/sig-cli/20201022-kubectl-xdg-base-dir.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# KEP-2111: kubectl-xdg-base-dir.md
2+
title: xdg-base-dir
3+
kep-number: 2111
4+
authors:
5+
- "@dougsland"
6+
owning-sig: sig-cli
7+
participating-sigs:
8+
- sig-usability
9+
status: implementable
10+
creation-date: 2020-10-22
11+
reviewers:
12+
- "@eddiezane"
13+
- "@soltysh"
14+
approvers:
15+
- "@eddiezane"
16+
- "@soltysh"
17+
prr-approvers:
18+
see-also:
19+
replaces:
20+
21+
# The target maturity stage in the current dev cycle for this KEP.
22+
stage: beta
23+
24+
# The most recent milestone for which work toward delivery of this KEP has been
25+
# done. This can be the current (upcoming) milestone, if it is being actively
26+
# worked on.
27+
latest-milestone: "v1.19"
28+
29+
# The milestone at which this feature was, or is targeted to be, at each stage.
30+
milestone:
31+
alpha: ""
32+
beta: "v1.21"
33+
stable: "v1.23"
34+
35+
# The following PRR answers are required at alpha release
36+
# List the feature gate name and the components for which it must be enabled
37+
feature-gates: []
38+
39+
# The following PRR answers are required at beta release
40+
metrics: []
41+
42+
## Table of Contents
43+
44+
<!-- toc -->
45+
- [Release Signoff Checklist](#release-signoff-checklist)
46+
- [Summary](#summary)
47+
- [Motivation](#motivation)
48+
- [Goals](#goals)
49+
- [Non-Goals](#non-goals)
50+
- [Proposal](#proposal)
51+
- [Risks and Mitigations](#risks-and-mitigations)
52+
- [Design Details](#design-details)
53+
- [Test Plan](#test-plan)
54+
- [Graduation Criteria](#graduation-criteria)
55+
- [Alpha -&gt; Beta Graduation](#alpha---beta-graduation)
56+
- [Beta -&gt; GA Graduation](#beta---ga-graduation)
57+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
58+
- [Version Skew Strategy](#version-skew-strategy)
59+
- [Drawbacks](#drawbacks)
60+
- [Alternatives](#Alternatives)
61+
- [Implementation History](#implementation-history)
62+
<!-- /toc -->
63+
64+
## Release Signoff Checklist
65+
66+
- [ ] 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)
67+
- [ ] KEP approvers have set the KEP status to `implementable`
68+
- [ ] Design details are appropriately documented
69+
- [ ] Test plan is in place, giving consideration to SIG Architecture and SIG Testing input
70+
- [ ] Graduation criteria is in place
71+
- [ ] "Implementation History" section is up-to-date for milestone
72+
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
73+
- [ ] Supporting documentation e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
74+
75+
[kubernetes.io]: https://kubernetes.io/
76+
[kubernetes/enhancements]: https://github.com/kubernetes/enhancements/issues
77+
[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes
78+
[kubernetes/website]: https://github.com/kubernetes/website
79+
80+
## Summary
81+
82+
This enhancement is focused in provide all requirements for kubectl
83+
use the [XDG Base Directory Specification (XDG Spec)](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
84+
The XDG Spec have been used for a long time as the standard location to tools
85+
and programs store configuration files.
86+
87+
## Motivation
88+
89+
Today the kubectl store the configuration file via ~/.kube/ dir.
90+
However, there are multiple [community requests like #56402](https://github.com/kubernetes/kubernetes/issues/56402),
91+
from real users that have been looking for:
92+
- A single place for managing the configuration files
93+
- Automation/Backup
94+
- Use the same environment [variables as others projects](https://specifications.freedesktop.org/basedir-spec/latest/ar01s03.html)
95+
96+
### Goals
97+
98+
The goal is make kubectl follow the XDG Spec and keep compatible with
99+
existing ~/.kube dir at least for three releases until it will be completed
100+
deprecated.
101+
102+
### Non-Goals
103+
104+
Deprecate any file under $HOME/.kube/
105+
106+
## Proposal
107+
108+
- kubectl should follow the XDG Base Directory Specification
109+
- Use $HOME/.config as default dir for configurations
110+
- Be compatible with $HOME/.kube for a period of time
111+
- Provide single place where other parts of code could load
112+
the current kubectl config dir instead of add static reference
113+
to $HOME/.kube
114+
- Users must have environment variable to override the default directory
115+
- Update documentation related to ~/.kube
116+
- Write a blog post to explain and communicate such change
117+
118+
### Risks and Mitigations
119+
120+
Risks are limited, as none of the cluster componenets, will be affected
121+
directly. Additionally, the original ~/.kube dir will be compatible
122+
for a period of time until it's fully deprecated. In case there is
123+
a bug in the new logic users will still be able to use the cluster
124+
via API calls or tools like curl.
125+
126+
## Design Details
127+
128+
In order to achieve the goal we must address and understand the logic in
129+
the following source code from the below table:
130+
131+
| Status | Code | Reason |
132+
|----------------|-----------------------------------------------------------------------------------------|-----------------------------------------|
133+
| Need to update | cmd/kubeadm/app/cmd/init.go | contains reference to $HOME/.kube |
134+
| Need to update | cluster/common.sh | contains reference to $HOME/.kube |
135+
| Need to update | cluster/gce/windows/README-GCE-Windows-kube-up.md | contains reference to $HOME/.kube |
136+
| Need to update | cmd/kubeadm/app/cmd/join.go | contains reference to $HOME/.kube |
137+
| Need to update | cmd/kubeadm/app/cmd/reset.go | contains reference to $HOME/.kube |
138+
| Need to update | cmd/kubeadm/app/cmd/completion.go | contains reference to $HOME/.kube |
139+
| Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/config_flags.go | contains reference to $HOME/.kube |
140+
| Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/client_config.go | contains reference to $HOME/.kube |
141+
| Need to update | staging/src/k8s.io/sample-controller/README.md | contains reference to $HOME/.kube |
142+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_cluster.go | contains reference to $HOME/.kube |
143+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_authinfo.go | contains reference to $HOME/.kube |
144+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/testing/fake.go | contains reference to $HOME/.kube/cache |
145+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/completion/completion.go | contains reference to $HOME/.kube |
146+
| Need to update | staging/src/k8s.io/kubectl/pkg/generated/bindata.go | contains reference to $HOME/.kube |
147+
| Need to update | staging/src/k8s.io/sample-apiserver/README.md | contains reference to $HOME/.kube |
148+
| Need to update | staging/src/k8s.io/client-go/util/homedir/homedir.go | contains reference to $HOME/.kube |
149+
| Need to update | staging/src/k8s.io/client-go/discovery/cached/disk/cached_discovery.go | contains reference to $HOME/.kube |
150+
| Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/main.go | contains reference to $HOME/.kube |
151+
| Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/README.md | contains reference to $HOME/.kube |
152+
| Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/main.go | contains reference to $HOME/.kube |
153+
| Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/README.md | contains reference to $HOME/.kube |
154+
| Need to update | staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration/main.go | contains reference to $HOME/.kube |
155+
| Need to update | staging/src/k8s.io/client-go/tools/clientcmd/loader.go | contains reference to $HOME/.kube |
156+
| Need to update | staging/src/k8s.io/apiserver/pkg/admission/config_test.go | contains reference to $HOME/.kube |
157+
| Need to update | test/cmd/legacy-script.sh | contains reference to $HOME/.kube |
158+
| Need to update | test/e2e/kubectl/kubectl.go | contains reference to $HOME/.kube |
159+
| Need to update | test/soak/serve_hostnames/serve_hostnames.go | contains reference to $HOME/.kube |
160+
| Need to update | test/e2e/network/scale/localrun/ingress_scale.go | contains reference to $HOME/.kube |
161+
| Need to update | test/soak/serve_hostnames/README.md | contains reference to $HOME/.kube |
162+
| Need to update | translations/kubectl/it_IT/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
163+
| Need to update | translations/kubectl/en_US/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
164+
| Need to update | translations/kubectl/ja_JP/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
165+
| Need to update | translations/kubectl/default/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
166+
| Need to update | translations/kubectl/template.pot | contains reference to $HOME/.kube |
167+
| Need to update | translations/kubectl/de_DE/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
168+
| Need to update | translations/kubectl/zh_CN/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
169+
| Need to update | https://github.com/kubernetes-sigs/controller-runtime/blob/cb7f85860a8cde7259b35bb84af1fdcb02c098f2/pkg/client/config/config.go#L129 | Check with project |
170+
171+
### Test Plan
172+
173+
Unit tests matching:
174+
- $HOME/.kube
175+
- $HOME/.config
176+
- Setting environment variables regarding to kubectl config dir
177+
- Execute kubectl changing the config dir
178+
179+
### Graduation Criteria
180+
181+
Successful Alpha Criteria
182+
- Support to $HOME/.kube and $HOME/.config
183+
- Unit tests
184+
185+
#### Alpha -> Beta Graduation
186+
187+
- [x] At least 2 release cycles pass to gather feedback and bug reports during
188+
real-world usage
189+
- [x] End-user documentation is written
190+
191+
#### Removing a Deprecated Flag
192+
193+
- Announce deprecation and support policy of the existing flag
194+
- Two versions passed since introducing the functionality that deprecates the flag (to address version skew)
195+
- Address feedback on usage/changed behavior, provided on GitHub issues
196+
- Deprecate the flag
197+
198+
**For non-optional features moving to GA, the graduation criteria must include
199+
[conformance tests].**
200+
201+
[conformance tests]: https://git.k8s.io/community/contributors/devel/sig-architecture/conformance-tests.md
202+
-->
203+
204+
#### Beta -> GA Graduation
205+
206+
- [x] At least 2 release cycles pass to gather feedback and bug reports during
207+
real-world usage
208+
- [x] Unit tests must pass and linked in the KEP
209+
- [x] Documentation exists
210+
211+
### Upgrade / Downgrade Strategy
212+
213+
Users that upgrade to a recent version of kubectl will be able to user $HOME/.kube
214+
or $HOME/.config until GA Graduation which will deprecate $HOME/.kube.
215+
216+
Downgrade will only allow users to use $HOME/.kube
217+
218+
### Version Skew Strategy
219+
220+
## Drawbacks
221+
222+
As soon the feature became achieve GA Graduation, automation scripts that use $HOME/.kube
223+
as static source will be broken.
224+
225+
## Alternatives
226+
227+
Keep using $HOME/.kube and avoid using XDG Base Directory Specification
228+
229+
## Implementation History
230+
231+
- *2020-10-22*: Created KEP
232+
- *2021-01-02*: Updated with comments from DirectXMan12 and kikisdeliveryservice
233+
- *2021-01-03*: Updated with comments from wojtek-t

0 commit comments

Comments
 (0)