Skip to content

Commit 80066d4

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 f4de431 commit 80066d4

File tree

2 files changed

+272
-0
lines changed

2 files changed

+272
-0
lines changed

‎keps/sig-cli/2229-kubectl-xdg-base-dir/README

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# KEP-2229: kubectl xdg base dir
2+
3+
<!-- toc -->
4+
- [Release Signoff Checklist](#release-signoff-checklist)
5+
- [Summary](#summary)
6+
- [Motivation](#motivation)
7+
- [Goals](#goals)
8+
- [Non-Goals](#non-goals)
9+
- [Proposal](#proposal)
10+
- [Risks and Mitigations](#risks-and-mitigations)
11+
- [Design Details](#design-details)
12+
- [Test Plan](#test-plan)
13+
- [Graduation Criteria](#graduation-criteria)
14+
- [Alpha -&gt; Beta Graduation](#alpha---beta-graduation)
15+
- [Beta -&gt; GA Graduation](#beta---ga-graduation)
16+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
17+
- [Version Skew Strategy](#version-skew-strategy)
18+
- [Drawbacks](#drawbacks)
19+
- [Alternatives](#alternatives)
20+
- [Implementation History](#implementation-history)
21+
<!-- /toc -->
22+
23+
## Release Signoff Checklist
24+
25+
- [ ] 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)
26+
- [ ] KEP approvers have set the KEP status to `implementable`
27+
- [ ] Design details are appropriately documented
28+
- [ ] Test plan is in place, giving consideration to SIG Architecture and SIG Testing input
29+
- [ ] Graduation criteria is in place
30+
- [ ] "Implementation History" section is up-to-date for milestone
31+
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
32+
- [ ] Supporting documentation e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
33+
34+
[kubernetes.io]: https://kubernetes.io/
35+
[kubernetes/enhancements]: https://github.com/kubernetes/enhancements/issues
36+
[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes
37+
[kubernetes/website]: https://github.com/kubernetes/website
38+
39+
## Summary
40+
41+
This enhancement is focused in provide all requirements for kubectl
42+
use the [XDG Base Directory Specification (XDG Spec)](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
43+
The XDG Spec have been used for a long time as the standard location to tools
44+
and programs store configuration files.
45+
46+
## Motivation
47+
48+
Today the kubectl store the configuration file via ~/.kube/ dir.
49+
However, there are multiple [community requests like #56402](https://github.com/kubernetes/kubernetes/issues/56402),
50+
from real users that have been looking for:
51+
- A single place for managing the configuration files
52+
- Automation/Backup
53+
- Use the same environment [variables as others projects](https://specifications.freedesktop.org/basedir-spec/latest/ar01s03.html)
54+
55+
### Goals
56+
57+
The goal is make kubectl follow the XDG Spec and automatic migrate
58+
the configuration from $HOME/.kube to $HOME/.config/kube wihout stopping
59+
kubectl to work.
60+
61+
### Non-Goals
62+
63+
Deprecate any file under $HOME/.kube/
64+
65+
## Proposal
66+
67+
- kubectl should follow the XDG Base Directory Specification
68+
- Use $HOME/.config/kube as default dir for configurations
69+
- Be compatible with $HOME/.kube until config migrated to $HOME/.config/kube
70+
- Smoothly migrate the config from $HOME/.kube to the new location
71+
- Update documentation related to ~/.kube
72+
- Write a blog post to explain and communicate such change
73+
74+
### Risks and Mitigations
75+
76+
Risks are limited, as none of the cluster components, will be affected
77+
directly. Additionally, the original ~/.kube dir will be compatible
78+
until a migration fully happen or deprecation. In case there is
79+
a bug in the new logic users will still be able to KUBECONFIG env var
80+
or use the cluster via API calls or tools like curl.
81+
82+
## Design Details
83+
84+
There are few possibilities to address this request.
85+
86+
### Option 1: Replace .kubeconfig in loader.go
87+
88+
$HOME/.kube/.kubeconfig seems to be deprecated place for the configuration and
89+
has been a long time since it's migrated to $HOME/.kube/config. A good reference from 2015:
90+
https://github.com/kubernetes/kubernetes/issues/4615
91+
92+
It's possible to set the oldRecommendedHomeFileName to $HOME/.kube/config but we lost
93+
the support of $HOME/.kube/.kubeconfig
94+
95+
Reference:
96+
https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/client-go/tools/clientcmd/loader.go#L62
97+
98+
The drawback:
99+
- Users using $HOME/.kube/.kubeconfig will not migrate to the new place as we are going to replace
100+
the static reference for oldRecommendedHomeFileName.
101+
- Tools that use static reference to $HOME/.kube/config will require to be updated
102+
- It's required to spread the world about this change as the config will move location ($HOME/.config/kube/config)
103+
104+
### Option 2: Set new RecommendedHomeFile to use XDG Base Directory Specification
105+
106+
This option will use the current logic of Migration already available in the code and seems modular
107+
enough as expected by the original author.
108+
109+
This implementation will be split in different patches (for easy review):
110+
111+
1. Update the logic from loader.go to migrate the config to the new recommended
112+
location in a transparent way to users.
113+
See: https://github.com/kubernetes/kubernetes/pull/97885
114+
115+
2. If 1 is approved and merged, update kubectl related code to the new location.
116+
117+
3. If 2 is approved and merged, update the rest of the code in the kubernetes tree pointing statically to $HOME/.kube
118+
119+
The drawback:
120+
- Tools that use static reference to $HOME/.kube/config will require to be updated
121+
- It's required to spread the world about this change as the config will move location ($HOME/.config/kube/config)
122+
123+
### Option 3: Recommend users to use KUBECONFIG
124+
125+
No changes in the code. Just close all requests from users suggesting to use KUBECONFIG env var.
126+
127+
```
128+
$ mkdir -p $HOME/.config/kube
129+
$ mv $HOME/.kube/config $HOME/.config/kube
130+
$ export KUBECONFIG=$HOME/.config/kube/config
131+
```
132+
133+
### Additional info
134+
135+
The following source codes are ref. to $HOME/.kube/config
136+
137+
| Status | Code | Reason |
138+
|----------------|-----------------------------------------------------------------------------------------|-----------------------------------------|
139+
| Need to update | cmd/kubeadm/app/cmd/init.go | contains reference to $HOME/.kube |
140+
| Need to update | cluster/common.sh | contains reference to $HOME/.kube |
141+
| Need to update | cluster/gce/windows/README-GCE-Windows-kube-up.md | contains reference to $HOME/.kube |
142+
| Need to update | cmd/kubeadm/app/cmd/join.go | contains reference to $HOME/.kube |
143+
| Need to update | cmd/kubeadm/app/cmd/reset.go | contains reference to $HOME/.kube |
144+
| Need to update | cmd/kubeadm/app/cmd/completion.go | contains reference to $HOME/.kube |
145+
| Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/config_flags.go | contains reference to $HOME/.kube |
146+
| Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/client_config.go | contains reference to $HOME/.kube |
147+
| Need to update | staging/src/k8s.io/sample-controller/README.md | contains reference to $HOME/.kube |
148+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_cluster.go | contains reference to $HOME/.kube |
149+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_authinfo.go | contains reference to $HOME/.kube |
150+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/testing/fake.go | contains reference to $HOME/.kube/cache |
151+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/completion/completion.go | contains reference to $HOME/.kube |
152+
| Need to update | staging/src/k8s.io/sample-apiserver/README.md | contains reference to $HOME/.kube |
153+
| Need to update | staging/src/k8s.io/client-go/util/homedir/homedir.go | contains reference to $HOME/.kube |
154+
| Need to update | staging/src/k8s.io/client-go/discovery/cached/disk/cached_discovery.go | contains reference to $HOME/.kube |
155+
| Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/main.go | contains reference to $HOME/.kube |
156+
| Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/README.md | contains reference to $HOME/.kube |
157+
| Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/main.go | contains reference to $HOME/.kube |
158+
| Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/README.md | contains reference to $HOME/.kube |
159+
| Need to update | staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration/main.go | contains reference to $HOME/.kube |
160+
| Need to update | staging/src/k8s.io/client-go/tools/clientcmd/loader.go | contains reference to $HOME/.kube |
161+
| Need to update | staging/src/k8s.io/apiserver/pkg/admission/config_test.go | contains reference to $HOME/.kube |
162+
| Need to update | test/cmd/legacy-script.sh | contains reference to $HOME/.kube |
163+
| Need to update | test/e2e/kubectl/kubectl.go | contains reference to $HOME/.kube |
164+
| Need to update | test/soak/serve_hostnames/serve_hostnames.go | contains reference to $HOME/.kube |
165+
| Need to update | test/e2e/network/scale/localrun/ingress_scale.go | contains reference to $HOME/.kube |
166+
| Need to update | test/soak/serve_hostnames/README.md | contains reference to $HOME/.kube |
167+
| Need to update | translations/kubectl/it_IT/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
168+
| Need to update | translations/kubectl/en_US/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
169+
| Need to update | translations/kubectl/ja_JP/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
170+
| Need to update | translations/kubectl/default/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
171+
| Need to update | translations/kubectl/template.pot | contains reference to $HOME/.kube |
172+
| Need to update | translations/kubectl/de_DE/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
173+
| Need to update | translations/kubectl/zh_CN/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
174+
| Need to update | https://github.com/kubernetes-sigs/controller-runtime/blob/cb7f85860a8cde7259b35bb84af1fdcb02c098f2/pkg/client/config/config.go#L129 | Check with project |
175+
176+
### Test Plan
177+
178+
#### Alpha milestones
179+
180+
Unit tests matching:
181+
- update kubectl tests to the new location
182+
183+
#### Beta milestones
184+
185+
Review all unit tests in the main kubernetes tree
186+
187+
#### GA milestones
188+
All code should be updated with the new config location
189+
190+
### Graduation Criteria
191+
192+
Successful Alpha Criteria
193+
- Migrate from $HOME/.kube to $HOME/.config in a transparent way to users
194+
- Update Unit tests
195+
196+
#### Alpha -> Beta Graduation
197+
198+
- [x] At least 2 release cycles pass to gather feedback and bug reports during
199+
real-world usage
200+
- [x] End-user documentation is written
201+
202+
#### Beta -> GA Graduation
203+
204+
- [x] At least 2 release cycles pass to gather feedback and bug reports during
205+
real-world usage
206+
- [x] Unit tests must pass and linked in the KEP
207+
- [x] Documentation exists
208+
209+
### Upgrade / Downgrade Strategy
210+
211+
Users that upgrade to a recent version of kubectl will be able to migrate
212+
to $HOME/.config/kube without intervention. If users decide to downgrade, they still can
213+
use the configuration in $HOME/.kube.
214+
215+
### Version Skew Strategy
216+
217+
## Drawbacks
218+
219+
As soon the feature became achieve GA Graduation, automation scripts that use $HOME/.kube
220+
as static source will outdated.
221+
222+
## Alternatives
223+
224+
- Use KUBECONFIG env var
225+
- Keep using $HOME/.kube with old versions kubectl and avoid using XDG Base Directory Specification
226+
227+
## Implementation History
228+
229+
- *2020-10-22*: Created KEP
230+
- *2021-01-02*: Updated with comments from DirectXMan12 and kikisdeliveryservice
231+
- *2021-01-03*: Updated with comments from wojtek-t
232+
- *2021-01-04*: Updated with comments from rikatz
233+
- *2021-01-08*: Fixed typo, thanks rikatz
234+
- *2021-01-09*: Updated KEP new approach
235+
- *2021-01-12*: Updated KEP comments from liggitt

‎keps/sig-cli/2229-kubectl-xdg-base-dir/kep.yaml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# KEP-2229: kubectl-xdg-base-dir.md
2+
title: xdg-base-dir
3+
kep-number: 2229
4+
authors:
5+
- "@dougsland"
6+
owning-sig: sig-cli
7+
participating-sigs:
8+
- sig-usability
9+
status: rejected
10+
creation-date: 2020-10-22
11+
reviewers:
12+
- "@eddiezane"
13+
- "@soltysh"
14+
approvers:
15+
- "@eddiezane"
16+
- "@soltysh"
17+
18+
# The target maturity stage in the current dev cycle for this KEP.
19+
stage:
20+
21+
# The most recent milestone for which work toward delivery of this KEP has been
22+
# done. This can be the current (upcoming) milestone, if it is being actively
23+
# worked on.
24+
latest-milestone:
25+
26+
# The milestone at which this feature was, or is targeted to be, at each stage.
27+
milestone:
28+
alpha:
29+
beta:
30+
stable:
31+
32+
# The following PRR answers are required at alpha release
33+
# List the feature gate name and the components for which it must be enabled
34+
feature-gates: []
35+
36+
# The following PRR answers are required at beta release
37+
metrics: []

0 commit comments

Comments
 (0)