Skip to content

Commit 802f3a2

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 802f3a2

File tree

2 files changed

+234
-0
lines changed

2 files changed

+234
-0
lines changed

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

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

‎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.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: []

0 commit comments

Comments
 (0)