Skip to content

Commit c334705

Browse files
hhiroshellhhiroshell
committed
Documentation (#2)
update README.md and help messages
1 parent 998b608 commit c334705

File tree

2 files changed

+120
-25
lines changed

2 files changed

+120
-25
lines changed

‎README.md

Lines changed: 109 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,118 @@
11
# Kubectl Real Name Diff
22

3+
![CI](https://github.com/hhiroshell/kubectl-realname-diff/actions/workflows/ci.yaml/badge.svg)
4+
5+
A kubectl plugin that diffs live and local resources ignoring Kustomize hash-suffixes.
6+
37
## What's this ?
4-
If realname is specified in the label, diff between resources with the same label.
5-
Other than that, it works just like normal kubectl diff.
8+
Normally, `kubectl realname-diff` works the same as `kubectl diff`, but if you set
9+
"real name" as a label, local and live resources with the same label will be compared.
10+
11+
This is especially beneficial if you use the Kustomize and enable the hash suffixed
12+
ConfigMap/Secret name. In case of `kubectl diff`, local and live resources with hash
13+
suffixed name are considered as irrelevant. So you will not be able to get any results
14+
comparing them.
15+
16+
However, with realname-diff, you can compare the resources with hash suffixed name by
17+
specifying the comparison target with "real name" labels.
18+
19+
## Usage
20+
First, you have set the label `realname-diff/realname: [real name]` to the resources
21+
you want to diff ignoring difference of `{.metadata.name}`.
22+
23+
In Kustomize, you can set the label in ConfigMap/Secret Generator fields.
24+
25+
```yaml
26+
resources:
27+
# resources that have references to the ConfigMap "nginx-conf"
28+
- deployment.yaml
29+
30+
configMapGenerator:
31+
- name: nginx-conf
32+
files:
33+
- conf/nginx.conf
34+
options:
35+
labels:
36+
realname-diff/realname: nginx-conf
37+
# hash suffix is enabled by default
38+
```
39+
40+
Then, apply the manifests to your kubernetes cluster.
41+
42+
```bash
43+
# assume you have placed the kustomization.yaml in "./example" directory
44+
$ kustomize build -f ./example | kubectl apply -f -
45+
46+
# you can get the ConfigMap with hash suffixed name.
47+
$ kubectl get configmap --show-labels
48+
NAME DATA AGE LABELS
49+
nginx-conf-m5d2cggb7k 1 18s realname-diff/realname=nginx-conf
50+
```
651

7-
This kubectl plugin assumes that you want to create ConfigMap, Secret with hash
8-
suffix in Kustomize.
9-
By specifying the real name without the hash suffix as a label, you can compare
10-
the old and new resources regardless of the hash value.`)
52+
Next, edit the content you want to pack into ConfigMap and use `kubectl realname-diff`
53+
to diff the local ConfigMap and the live one.
1154

12-
## Example
55+
```bash
56+
$ echo "# test" >> ./example/conf/nginx.conf
1357

58+
$ kustomize build -f ./example | kubectl realname-diff -f -
1459
```
15-
# Diff resources included in the result of kustomize build
16-
$ kustomize build ./example | kubectl realname-diff -f -
1760

18-
# Also you can use kubectl's built-in kustomize
19-
$ kubectl realname-diff -k ./example`)
61+
You can see the diff result comparing contents in the ConfigMap. The local ConfigMap
62+
is not treated as new one.
63+
64+
```diff
65+
diff -u -N /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/LIVE-116798495/apps.v1.Deployment.default.nginx /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/MERGED-2431241138/apps.v1.Deployment.default.nginx
66+
--- /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/LIVE-116798495/apps.v1.Deployment.default.nginx 2021-12-24 00:04:23.000000000 +0900
67+
+++ /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/MERGED-2431241138/apps.v1.Deployment.default.nginx 2021-12-24 00:04:23.000000000 +0900
68+
@@ -6,7 +6,7 @@
69+
kubectl.kubernetes.io/last-applied-configuration: |
70+
{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"annotations":{},"labels":{"app":"nginx","prunable":"true"},"name":"nginx","namespace":"default"},"spec":{"replicas":2,"selector":{"matchLabels":{"app":"nginx","prunable":"true"}},"template":{"metadata":{"labels":{"app":"nginx","prunable":"true"}},"spec":{"containers":[{"image":"nginx:latest","name":"nginx","ports":[{"containerPort":80}],"volumeMounts":[{"mountPath":"/etc/nginx/htpasswd","name":"htpasswd","readOnly":true},{"mountPath":"/etc/nginx","name":"nginx-conf","readOnly":true}]}],"volumes":[{"name":"htpasswd","secret":{"secretName":"htpasswd-k7mbh9mm68"}},{"configMap":{"name":"nginx-conf-m5d2cggb7k"},"name":"nginx-conf"}]}}}}
71+
creationTimestamp: "2021-12-23T15:00:12Z"
72+
- generation: 1
73+
+ generation: 2
74+
labels:
75+
app: nginx
76+
prunable: "true"
77+
@@ -177,7 +177,7 @@
78+
secretName: htpasswd-k7mbh9mm68
79+
- configMap:
80+
defaultMode: 420
81+
- name: nginx-conf-m5d2cggb7k
82+
+ name: nginx-conf-b6gmtkgcd5
83+
name: nginx-conf
84+
status:
85+
availableReplicas: 2
86+
diff -u -N /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/LIVE-116798495/v1.ConfigMap.default.nginx-conf-m5d2cggb7k /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/MERGED-2431241138/v1.ConfigMap.default.nginx-conf-m5d2cggb7k
87+
--- /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/LIVE-116798495/v1.ConfigMap.default.nginx-conf-m5d2cggb7k 2021-12-24 00:04:23.000000000 +0900
88+
+++ /var/folders/2n/lgqgy6f151l5mw1x4dj_7ztw0000gn/T/MERGED-2431241138/v1.ConfigMap.default.nginx-conf-m5d2cggb7k 2021-12-24 00:04:23.000000000 +0900
89+
@@ -16,12 +16,10 @@
90+
}
91+
}
92+
}
93+
+ # test
94+
kind: ConfigMap
95+
metadata:
96+
...(snip last-applied-configuration label)..
97+
labels:
98+
prunable: "true"
99+
realname-diff/realname: nginx-conf
100+
@@ -33,17 +31,13 @@
101+
...(snip managed fields)...
102+
manager: kubectl-client-side-apply
103+
operation: Update
104+
- time: "2021-12-23T15:00:12Z"
105+
- name: nginx-conf-m5d2cggb7k
106+
+ time: "2021-12-23T15:04:23Z"
107+
+ name: nginx-conf-b6gmtkgcd5
108+
namespace: default
109+
- resourceVersion: "82594"
110+
- uid: 6a5d347c-d936-49c6-825b-70e2e39eb676
111+
+ uid: 0d69cf40-d201-47fe-bad2-8c3333ef0d07
20112
```
113+
114+
For a complete example, see the [example directory](./example).
115+
116+
## License
117+
Kubectl Real Name Diff is licensed under the Apache License 2.0, and includes works
118+
distributed under same one.

‎pkg/cmd/realname-diff.go

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -18,28 +18,25 @@ import (
1818
cmdutil "k8s.io/kubectl/pkg/cmd/util"
1919
"k8s.io/kubectl/pkg/scheme"
2020
"k8s.io/kubectl/pkg/util/openapi"
21-
"k8s.io/kubectl/pkg/util/templates"
2221
"k8s.io/utils/exec"
2322

2423
_ "k8s.io/client-go/plugin/pkg/client/auth"
2524
)
2625

2726
var (
28-
diffLong = templates.LongDesc(`
29-
If realname is specified in the label, diff between resources with the same label.
30-
Other than that, it works just like normal kubectl diff.
27+
diffLong = `Diffs live and local resources ignoring Kustomize hash-suffixes.
3128
32-
This kubectl plugin assumes that you want to create ConfigMap, Secret with hash
33-
suffix in Kustomize.
34-
By specifying the real name without the hash suffix as a label, you can compare
35-
the old and new resources regardless of the hash value.`)
29+
Normally, "kubectl realname-diff" works the same as "kubectl diff", but if you set
30+
"real name" as a label, local and live resources with the same label will be compared.`
3631

37-
diffExample = templates.Examples(`
38-
# Diff resources included in the result of kustomize build
39-
kustomize build ./example | kubectl realname-diff -f -
32+
diffExample = ` # Make sure you have already labeled the resources with "realname-diff/realname: [real name]"
33+
# For a complete example, see https://github.com/hhiroshell/kubectl-realname-diff/tree/main/example
4034
41-
# Also you can use kubectl's built-in kustomize
42-
kubectl realname-diff -k ./example`)
35+
# Diff resources included in the result of kustomize build
36+
kustomize build ./example | kubectl realname-diff -f -
37+
38+
# Also you can use kubectl's built-in kustomize
39+
kubectl realname-diff -k ./example`
4340
)
4441

4542
const (
@@ -56,7 +53,7 @@ func NewCmdRealnameDiff(streams genericclioptions.IOStreams) *cobra.Command {
5653
cmd := &cobra.Command{
5754
Use: "kubectl realname-diff -f FILENAME",
5855
DisableFlagsInUseLine: true,
59-
Short: "Diff between resources with the same realname label",
56+
Short: "Diff live and local resources ignoring Kustomize hash-suffixes.",
6057
Long: diffLong,
6158
Example: diffExample,
6259
Run: func(cmd *cobra.Command, args []string) {

0 commit comments

Comments
 (0)