Skip to content

Commit 26d03a0

Browse files
adoheadohe
authored
Merge pull request #287 from pwittrock/master
Proposal for porcelain commands to make working with the last-applied…
2 parents b9bc5f4 + 572c1e0 commit 26d03a0

File tree

1 file changed

+196
-0
lines changed

1 file changed

+196
-0
lines changed

‎contributors/design-proposals/sig-cli/kubectl_apply_getsetdiff_last_applied_config.md

+196
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Kubectl apply subcommands for last-config
2+
3+
## Abstract
4+
5+
`kubectl apply` uses the `last-applied-config` annotation to compute
6+
the removal of fields from local object configuration files and then
7+
send patches to delete those fields from the live object. Reading or
8+
updating the `last-applied-config` is complex as it requires parsing
9+
out and writing to the annotation. Here we propose a set of porcelain
10+
commands for users to better understand what is going on in the system
11+
and make updates.
12+
13+
## Motivation
14+
15+
What is going on behind the scenes with `kubectl apply` is opaque. Users
16+
have to interact directly with annotations on the object to view
17+
and make changes. In order to stop having `apply` manage a field on
18+
an object, it must be manually removed from the annotation and then be removed
19+
from the local object configuration. Users should be able to simply edit
20+
the local object configuration and set it as the last-applied-config
21+
to be used for the next diff base. Storing the last-applied-config
22+
in an annotation adds black magic to `kubectl apply`, and it would
23+
help users learn and understand if the value was exposed in a discoverable
24+
manner.
25+
26+
## Use Cases
27+
28+
1. As a user, I want to be able to diff the last-applied-configuration
29+
against the current local configuration to see which changes the command is seeing
30+
2. As a user, I want to remove fields from being managed by the local
31+
object configuration by removing them from the local object configuration
32+
and setting the last-applied-configuration to match.
33+
3. As a user, I want to be able to view the last-applied-configuration
34+
on the live object that will be used to calculate the diff patch
35+
to update the live object from the configuration file.
36+
37+
## Naming and Format possibilities
38+
39+
### Naming
40+
41+
1. *cmd*-last-applied
42+
43+
Rejected alternatives:
44+
45+
2. ~~last-config~~
46+
3. ~~last-applied-config~~
47+
4. ~~last-configuration~~
48+
5. ~~last-applied-configuration~~
49+
6. ~~last~~
50+
51+
### Formats
52+
53+
1. Apply subcommands
54+
- `kubectl apply set-last-applied/view-last-applied/diff-last-applied
55+
- a little bit odd to have 2 verbs in a row
56+
- improves discoverability to have these as subcommands so they are tied to apply
57+
58+
Rejected alternatives:
59+
60+
2. ~~Set/View subcommands~~
61+
- `kubectl set/view/diff last-applied
62+
- consistent with other set/view commands
63+
- clutters discoverability of set/view commands since these are only for apply
64+
- clutters discoverability for last-applied commands since they are for apply
65+
3. ~~Apply flags~~
66+
- `kubectl apply [--set-last-applied | --view-last-applied | --diff-last-applied]
67+
- Not a fan of these
68+
69+
## view last-applied
70+
71+
Porcelain command that retrieves the object and prints the annotation value as yaml or json.
72+
73+
Prints an error message if the object is not managed by `apply`.
74+
75+
1. Get the last-applied by type/name
76+
77+
```sh
78+
kubectl apply view-last-applied deployment/nginx
79+
```
80+
81+
```yaml
82+
apiVersion: extensions/v1beta1
83+
kind: Deployment
84+
metadata:
85+
name: nginx
86+
spec:
87+
replicas: 1
88+
template:
89+
metadata:
90+
labels:
91+
run: nginx
92+
spec:
93+
containers:
94+
- image: nginx
95+
name: nginx
96+
```
97+
98+
2. Get the last-applied by file, print as json
99+
100+
```sh
101+
kubectl apply view-last-applied -f deployment_nginx.yaml -o json
102+
```
103+
104+
Same as above, but in json
105+
106+
## diff last-applied
107+
108+
Porcelain command that retrieves the object and displays a diff against
109+
the local configuration
110+
111+
1. Diff the last-applied
112+
113+
```sh
114+
kubectl apply diff-last-applied -f deployment_nginx.yaml
115+
```
116+
117+
Opens up a 2-way diff in the default diff viewer. This should
118+
follow the same semantics as `git diff`. It should accept either a
119+
flag `--diff-viewer=meld` or check the environment variable
120+
`KUBECTL_EXTERNAL_DIFF=meld`. If neither is specified, the `diff`
121+
command should be used.
122+
123+
This is meant to show the user what they changed in the configuration,
124+
since it was last applied, but not show what has changed in the server.
125+
126+
The supported output formats should be `yaml` and `json`, as specified
127+
by the `-o` flag.
128+
129+
A future goal is to provide a 3-way diff with `kubectl apply diff -f deployment_nginx.yaml`.
130+
Together these tools would give the user the ability to see what is going
131+
on and compare changes made to the configuration file vs other
132+
changes made to the server independent of the configuration file.
133+
134+
## set last-applied
135+
136+
Porcelain command that sets the last-applied-config annotation to as
137+
if the local configuration file had just been applied.
138+
139+
1. Set the last-applied-config
140+
141+
```sh
142+
kubectl apply set-last-applied -f deployment_nginx.yaml
143+
```
144+
145+
Sends a Patch request to set the last-applied-config as if
146+
the configuration had just been applied.
147+
148+
## edit last-applied
149+
150+
1. Open the last-applied-config in an editor
151+
152+
```sh
153+
kubectl apply edit-last-applied -f deployment_nginx.yaml
154+
```
155+
156+
Since the last-applied-configuration annotation exists only
157+
on the live object, this command can alternatively take the
158+
kind/name.
159+
160+
```sh
161+
kubectl apply edit-last-applied deployment/nginx
162+
```
163+
164+
Sends a Patch request to set the last-applied-config to
165+
the value saved in the editor.
166+
167+
## Example workflow to stop managing a field with apply - using get/set
168+
169+
As a user, I want to have the replicas on a Deployment managed by an autoscaler
170+
instead of by the configuration.
171+
172+
1. Check to make sure the live object is up-to-date
173+
- `kubectl apply diff-last-applied -f deployment_nginx.yaml`
174+
- Expect no changes
175+
2. Update the deployment_nginx.yaml by removing the replicas field
176+
3. Diff the last-applied-config to make sure the only change is the removal of the replicas field
177+
4. Remove the replicas field from the last-applied-config so it doesn't get deleted next apply
178+
- `kubectl apply set-last-applied -f deployment_nginx.yaml`
179+
5. Verify the last-applied-config has been updated
180+
- `kubectl apply view-last-applied -f deployment_nginx.yaml`
181+
182+
## Example workflow to stop managing a field with apply - using edit
183+
184+
1. Check to make sure the live object is up-to-date
185+
- `kubectl apply diff-last-applied -f deployment_nginx.yaml`
186+
- Expect no changes
187+
2. Update the deployment_nginx.yaml by removing the replicas field
188+
3. Edit the last-applied-config and remove the replicas field
189+
- `kubectl apply edit-last-applied deployment/nginx`
190+
4. Verify the last-applied-config has been updated
191+
- `kubectl apply view-last-applied -f deployment_nginx.yaml`
192+
193+
194+
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
195+
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/design/configmap.md?pixel)]()
196+
<!-- END MUNGE: GENERATED_ANALYTICS -->

0 commit comments

Comments
 (0)