Skip to content

Commit fa347d3

Browse files
monopolemonopole
authored
Merge branch 'master' into patch-1
2 parents e252614 + 07badb8 commit fa347d3

File tree

4 files changed

+174
-10
lines changed

4 files changed

+174
-10
lines changed

‎README.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,22 @@
1010
[overlay]: docs/glossary.md#overlay
1111
[resources]: docs/glossary.md#resource
1212
[workflows]: docs/workflows.md
13+
[kubernetes style]: docs/glossary.md#kubernetes-style-object
1314

1415
`kustomize` is a command line tool supporting
15-
template-free customization of declarative
16-
configuration targetted to kubernetes.
16+
template-free customization of YAML (or JSON)
17+
objects that conform to the [kubernetes style].
18+
19+
If your objects have a `kind` and a `metadata` field,
20+
kustomize can patch them to help you manage
21+
configuration sharing and re-use.
22+
23+
For more details, try a [demo].
1724

1825
## Installation
1926

20-
Assumes [Go](https://golang.org/) is installed
21-
and your `PATH` contains `$GOPATH/bin`:
27+
This assumes [Go](https://golang.org/) (v1.10.1 or higher)
28+
is installed and your `PATH` contains `$GOPATH/bin`:
2229

2330
<!-- @installkustomize @test -->
2431
```
@@ -48,5 +55,3 @@ _development, staging and production_.
4855
Run kustomize on your overlay. The result
4956
is printed to `stdout` as a set of complete
5057
resources, ready to be [applied] to a cluster.
51-
52-
For more details, try a [demo].

‎demos/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,5 @@ These demos are covered by presubmit tests.
1111

1212
* [springboot](springboot.md) - Create a Spring Boot application production
1313
configuration from scratch.
14+
15+
* [breakfast](breakfast.md) - Customize breakfast for Alice and Bob.

‎demos/breakfast.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
[kubernetes API object style]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
2+
3+
# Demo: configure breakfast
4+
5+
6+
Define a place to work:
7+
8+
<!-- @makeWorkplace @test -->
9+
```
10+
DEMO_HOME=$(mktemp -d)
11+
```
12+
13+
Make a place to put the base breakfast configuration:
14+
15+
<!-- @baseDir @test -->
16+
```
17+
mkdir -p $DEMO_HOME/breakfast/base
18+
```
19+
20+
Make a `kustomization` to define what goes into
21+
breakfast. This breakfast has coffee and pancakes:
22+
23+
<!-- @baseKustomization @test -->
24+
```
25+
cat <<EOF >$DEMO_HOME/breakfast/base/kustomization.yaml
26+
resources:
27+
- coffee.yaml
28+
- pancakes.yaml
29+
EOF
30+
```
31+
32+
Here's a _coffee_ type. Give it a `kind` and `metdata/name` field
33+
to conform to [kubernetes API object style]; no other
34+
file or definition is needed:
35+
36+
<!-- @coffee @test -->
37+
```
38+
cat <<EOF >$DEMO_HOME/breakfast/base/coffee.yaml
39+
kind: Coffee
40+
metadata:
41+
name: morningCup
42+
temperature: lukewarm
43+
data:
44+
greeting: "Good Morning!"
45+
EOF
46+
```
47+
48+
The `name` field merely distinguishes this instance of coffee from others (if
49+
there were any).
50+
51+
Likewise, define _pancakes_:
52+
<!-- @pancakes @test -->
53+
```
54+
cat <<EOF >$DEMO_HOME/breakfast/base/pancakes.yaml
55+
kind: Pancakes
56+
metadata:
57+
name: comfort
58+
stacksize: 3
59+
topping: none
60+
EOF
61+
```
62+
63+
Make a custom version of breakfast for Alice, who
64+
likes her coffee hot:
65+
66+
<!-- @aliceOverlay @test -->
67+
```
68+
mkdir -p $DEMO_HOME/breakfast/overlays/alice
69+
70+
cat <<EOF >$DEMO_HOME/breakfast/overlays/alice/kustomization.yaml
71+
commonLabels:
72+
who: alice
73+
bases:
74+
- ../../base
75+
patches:
76+
- temperature.yaml
77+
EOF
78+
79+
cat <<EOF >$DEMO_HOME/breakfast/overlays/alice/temperature.yaml
80+
kind: Coffee
81+
metadata:
82+
name: morningCup
83+
temperature: hot!
84+
EOF
85+
```
86+
87+
And likewise for Bob, who wants _five_ pancakes, with strawberries:
88+
89+
<!-- @bobOverlay @test -->
90+
```
91+
mkdir -p $DEMO_HOME/breakfast/overlays/bob
92+
93+
cat <<EOF >$DEMO_HOME/breakfast/overlays/bob/kustomization.yaml
94+
commonLabels:
95+
who: bob
96+
bases:
97+
- ../../base
98+
patches:
99+
- topping.yaml
100+
EOF
101+
102+
cat <<EOF >$DEMO_HOME/breakfast/overlays/bob/topping.yaml
103+
kind: Pancakes
104+
metadata:
105+
name: comfort
106+
stacksize: 5
107+
topping: strawberries
108+
EOF
109+
```
110+
111+
One can now generate the configs for Alice’s breakfast:
112+
113+
<!-- @generateAlice @test -->
114+
```
115+
kustomize build $DEMO_HOME/breakfast/overlays/alice
116+
```
117+
118+
Likewise for Bob:
119+
120+
<!-- @generateBob @test -->
121+
```
122+
kustomize build $DEMO_HOME/breakfast/overlays/bob
123+
```

‎docs/glossary.md

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
[base]: #base
1111
[bases]: #base
1212
[bespoke]: #bespoke-configuration
13+
[k8s]: #kubernetes
14+
[kubernetes]: #kubernetes
1315
[kustomize]: #kustomize
1416
[kustomization]: #kustomization
1517
[off-the-shelf]: #off-the-shelf
@@ -143,11 +145,30 @@ A kustomization contains fields falling into these categories:
143145
a [kustomization] (only meaningful in an [overlay]).
144146
* (_TBD_) Standard k8s API kind-version fields.
145147

148+
## kubernetes
149+
150+
[Kubernetes](https://kubernetes.io) is an open-source
151+
system for automating deployment, scaling, and
152+
management of containerized applications.
153+
154+
It's often abbreviated as _k8s_.
155+
156+
## kubernetes-style object
157+
158+
[fields required]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
159+
160+
An object, expressed in a YAML or JSON file, with the
161+
[fields required] by kubernetes. Basically just a
162+
`kind` field to identify the type, a `metadata/name`
163+
field to identify the instance, and an `apiVersion`
164+
field to identify the version (if there's more than one
165+
version).
166+
146167
## kustomize
147168

148169
_kustomize_ is a command line tool supporting template-free
149170
customization of declarative configuration targetted to
150-
k8s.
171+
k8s-style objects.
151172

152173
_Targetted to k8s means_ that kustomize may need some
153174
limited understanding of API resources, k8s concepts
@@ -229,15 +250,28 @@ traversal rules built into [kustomize].
229250
_Patch_ is a field in the kustomization, distinct from
230251
resources, because a patch file looks like a resource
231252
file, but has different semantics. A patch depends on
232-
(modifies) a resource, whereas a resourse has no
253+
(modifies) a resource, whereas a resource has no
233254
dependencies. Since any resource file can be used as a
234255
patch, one cannot reliably distinguish a resource from
235256
a patch just by looking at the file's [YAML].
236257
237258
## resource
238259
239-
A _resource_ is a path to a [YAML] or [JSON] file that
240-
completely defines a functional k8s API object.
260+
A _resource_, in the context of kustomize, is a path to
261+
a [YAML] or [JSON] file that completely defines a
262+
functional k8s API object, like a deployment or a
263+
configmap.
264+
265+
More generally, a resource can be any correct YAML file
266+
that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields)
267+
with a `kind` and a `metadata/name` field.
268+
269+
270+
A _resource_ in the content of a REST-ful API is the
271+
target of an HTTP operation like _GET_, _PUT_ or
272+
_POST_. k8s offers a RESTful API surface to interact
273+
with clients.
274+
241275
242276
## sub-target / sub-application / sub-package
243277

0 commit comments

Comments
 (0)