Skip to content

Commit 31212f8

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 31212f8

File tree

2 files changed

+225
-0
lines changed

2 files changed

+225
-0
lines changed

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

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
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 wihout downtime
59+
for users.
60+
61+
Split the implementation in different patches (or more, for easy review):
62+
63+
1. Update the logic from loader.go to migrate the config to the new recommended
64+
location in a transparent way to users.
65+
66+
2. If 1 is approved and merged, update kubectl related code to the new location.
67+
68+
3. If 2 is approved and merged, update the rest of the code in the kubernetes tree pointing statically to $HOME/.kube
69+
70+
### Non-Goals
71+
72+
Deprecate any file under $HOME/.kube/
73+
74+
## Proposal
75+
76+
- kubectl should follow the XDG Base Directory Specification
77+
- Use $HOME/.config/kube as default dir for configurations
78+
- Be compatible with $HOME/.kube until config migrated to $HOME/.config/kube
79+
- Smoothly migrate the config from $HOME/.kube to the new location
80+
- Update documentation related to ~/.kube
81+
- Write a blog post to explain and communicate such change
82+
83+
### Risks and Mitigations
84+
85+
Risks are limited, as none of the cluster components, will be affected
86+
directly. Additionally, the original ~/.kube dir will be compatible
87+
until a migration fully happen or deprecation. In case there is
88+
a bug in the new logic users will still be able to use the cluster
89+
via API calls or tools like curl.
90+
91+
## Design Details
92+
93+
In order to achieve the goal we must address and understand the logic in
94+
the following source code from the below table:
95+
96+
| Status | Code | Reason |
97+
|----------------|-----------------------------------------------------------------------------------------|-----------------------------------------|
98+
| Need to update | cmd/kubeadm/app/cmd/init.go | contains reference to $HOME/.kube |
99+
| Need to update | cluster/common.sh | contains reference to $HOME/.kube |
100+
| Need to update | cluster/gce/windows/README-GCE-Windows-kube-up.md | contains reference to $HOME/.kube |
101+
| Need to update | cmd/kubeadm/app/cmd/join.go | contains reference to $HOME/.kube |
102+
| Need to update | cmd/kubeadm/app/cmd/reset.go | contains reference to $HOME/.kube |
103+
| Need to update | cmd/kubeadm/app/cmd/completion.go | contains reference to $HOME/.kube |
104+
| Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/config_flags.go | contains reference to $HOME/.kube |
105+
| Need to update | staging/src/k8s.io/cli-runtime/pkg/genericclioptions/client_config.go | contains reference to $HOME/.kube |
106+
| Need to update | staging/src/k8s.io/sample-controller/README.md | contains reference to $HOME/.kube |
107+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_cluster.go | contains reference to $HOME/.kube |
108+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/config/create_authinfo.go | contains reference to $HOME/.kube |
109+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/testing/fake.go | contains reference to $HOME/.kube/cache |
110+
| Need to update | staging/src/k8s.io/kubectl/pkg/cmd/completion/completion.go | contains reference to $HOME/.kube |
111+
| Need to update | staging/src/k8s.io/sample-apiserver/README.md | contains reference to $HOME/.kube |
112+
| Need to update | staging/src/k8s.io/client-go/util/homedir/homedir.go | contains reference to $HOME/.kube |
113+
| Need to update | staging/src/k8s.io/client-go/discovery/cached/disk/cached_discovery.go | contains reference to $HOME/.kube |
114+
| Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/main.go | contains reference to $HOME/.kube |
115+
| Need to update | staging/src/k8s.io/client-go/examples/dynamic-create-update-delete-deployment/README.md | contains reference to $HOME/.kube |
116+
| Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/main.go | contains reference to $HOME/.kube |
117+
| Need to update | staging/src/k8s.io/client-go/examples/create-update-delete-deployment/README.md | contains reference to $HOME/.kube |
118+
| Need to update | staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration/main.go | contains reference to $HOME/.kube |
119+
| Need to update | staging/src/k8s.io/client-go/tools/clientcmd/loader.go | contains reference to $HOME/.kube |
120+
| Need to update | staging/src/k8s.io/apiserver/pkg/admission/config_test.go | contains reference to $HOME/.kube |
121+
| Need to update | test/cmd/legacy-script.sh | contains reference to $HOME/.kube |
122+
| Need to update | test/e2e/kubectl/kubectl.go | contains reference to $HOME/.kube |
123+
| Need to update | test/soak/serve_hostnames/serve_hostnames.go | contains reference to $HOME/.kube |
124+
| Need to update | test/e2e/network/scale/localrun/ingress_scale.go | contains reference to $HOME/.kube |
125+
| Need to update | test/soak/serve_hostnames/README.md | contains reference to $HOME/.kube |
126+
| Need to update | translations/kubectl/it_IT/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
127+
| Need to update | translations/kubectl/en_US/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
128+
| Need to update | translations/kubectl/ja_JP/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
129+
| Need to update | translations/kubectl/default/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
130+
| Need to update | translations/kubectl/template.pot | contains reference to $HOME/.kube |
131+
| Need to update | translations/kubectl/de_DE/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
132+
| Need to update | translations/kubectl/zh_CN/LC_MESSAGES/k8s.po | contains reference to $HOME/.kube |
133+
| Need to update | https://github.com/kubernetes-sigs/controller-runtime/blob/cb7f85860a8cde7259b35bb84af1fdcb02c098f2/pkg/client/config/config.go#L129 | Check with project |
134+
135+
### Test Plan
136+
137+
Unit tests matching:
138+
- update kubectl tests to the new location
139+
140+
### Graduation Criteria
141+
142+
Successful Alpha Criteria
143+
- Migrate from $HOME/.kube to $HOME/.config in a transparent way to users
144+
- Update Unit tests
145+
146+
#### Alpha -> Beta Graduation
147+
148+
- [x] At least 2 release cycles pass to gather feedback and bug reports during
149+
real-world usage
150+
- [x] End-user documentation is written
151+
152+
#### Beta -> GA Graduation
153+
154+
- [x] At least 2 release cycles pass to gather feedback and bug reports during
155+
real-world usage
156+
- [x] Unit tests must pass and linked in the KEP
157+
- [x] Documentation exists
158+
159+
### Upgrade / Downgrade Strategy
160+
161+
Users that upgrade to a recent version of kubectl will be able to migrate
162+
to $HOME/.config/kube without intervention and the old configuration will
163+
be kept in $HOME/.kube. If users decide to downgrade, they still can
164+
use the configuration kept in $HOME/.kube.
165+
166+
### Version Skew Strategy
167+
168+
## Drawbacks
169+
170+
As soon the feature became achieve GA Graduation, automation scripts that use $HOME/.kube
171+
as static source will outdated.
172+
173+
## Alternatives
174+
175+
Keep using $HOME/.kube with old versions kubectl and avoid using XDG Base
176+
Directory Specification
177+
178+
## Implementation History
179+
180+
- *2020-10-22*: Created KEP
181+
- *2021-01-02*: Updated with comments from DirectXMan12 and kikisdeliveryservice
182+
- *2021-01-03*: Updated with comments from wojtek-t
183+
- *2021-01-04*: Updated with comments from rikatz
184+
- *2021-01-08*: Fixed typo, thanks rikatz
185+
- *2021-01-09*: Updated KEP new approach

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

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
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: 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.20"
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: []

0 commit comments

Comments
 (0)