Skip to content

Commit e047d78

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 e047d78

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

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

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

0 commit comments

Comments
 (0)