kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-14 10:30:59 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

cmd/config: Add examples and tutorials for config functions

Browse Source 
- Add examples under `functions`
- Add built-in tutorial for functions
This commit is contained in:
Phillip Wittrock
2019-11-26 20:08:23 -08:00
parent 5876a8cce0
commit dc66de6bf3
34 changed files with 1524 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
cmd/config/cmd/run-fns.go
View File

@@ -14,6 +14,7 @@ func GetRunFnRunner(name string) *RunFnRunner {
r := &RunFnRunner{}
c := &cobra.Command{
Use: "run-fns DIR",
Aliases: []string{"run"},
Short: commands.RunFnsShort,
Long: commands.RunFnsLong,
Example: commands.RunFnsExamples,

183
cmd/config/cmddocs/tutorials/docs.go
View File

@@ -278,3 +278,186 @@ var ConfigurationBasicsLong = `
│   ├── name: web
│   └── image: <YOUR-CONTAINER>
...`
var FunctionBasicsShort = `### Synopsis`
var FunctionBasicsLong = `
` + "`" + `kustomize config` + "`" + ` enables encapsulating function for manipulating Resource
configuration inside containers, which are run using ` + "`" + `run-fns` + "`" + `.
First fetch the kustomize repository, which contains a collection of example
functions
git clone https://github.com/kubernetes-sigs/kustomize
cd kustomize/functions/examples/
### Templating -- CockroachDB
This section demonstrates how to leverage templating based solutions from
` + "`" + `kustomize config` + "`" + `. The templating function is implemented as a ` + "`" + `bash` + "`" + ` script
using a ` + "`" + `heredoc` + "`" + `.
#### 1: Generate the Resources
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/template-heredoc-cockroachdb/` + "`" + `
directory, and invoke ` + "`" + `run-fns` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
cd template-heredoc-cockroachdb/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
# run the function
kustomize config run-fns local-resource/
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
` + "`" + `run-fns` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated
Resources.
#### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas
re-run ` + "`" + `run-fns` + "`" + `. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration.
# run the function
kustomize config run-fns local-resource/
` + "`" + `run-fns` + "`" + ` facilitates a non-destructive *smart templating* approach that allows templating
to be composed with manual modifications directly to the template output, as well as
composition with other functions which may appy validation or injection of values.
#### 3. Function Implementation
the function implementation is located under the ` + "`" + `image/` + "`" + ` directory as a ` + "`" + `Dockerfile` + "`" + `
and a ` + "`" + `bash` + "`" + ` script.
### Templating -- Nginx
The steps in this section are identical to the CockroachDB templating example,
but the function implementation is very different, and implemented as a ` + "`" + `go` + "`" + `
program rather than a ` + "`" + `bash` + "`" + ` script.
#### 1: Generate the Resources
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/template-go-nginx/` + "`" + `
directory, and invoke ` + "`" + `run-fns` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
cd template-go-nginx/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
# run the function
kustomize config run-fns local-resource/
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
` + "`" + `run-fns` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated
Resources. this time it put the configuration in a single file rather than multiple
files. The mapping of Resources to files is controlled by the function itself through
annotations on the generated Resources.
#### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas
re-run ` + "`" + `run-fns` + "`" + `. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration.
# run the function
kustomize config run-fns local-resource/
Just like in the preceding section, the function is implemented using a non-destructive
approach which merges the generated Resources into previously generated instances.
#### 3. Function Implementation
the function implementation is located under the ` + "`" + `image/` + "`" + ` directory as a ` + "`" + `Dockerfile` + "`" + `
and a ` + "`" + `go` + "`" + ` program.
### Validation -- resource reservations
This section uses ` + "`" + `run-fns` + "`" + ` to perform validation rather than generate Resources.
#### 1: Run the Validator
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/validator-resource-requests` + "`" + `
directory, and invoke ` + "`" + `run-fns` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
# run the function
kustomize config run-fns local-resource/
cpu-requests missing for a container in Deployment nginx (example-use.yaml [1])
Error: exit status 1
Usage:
...
#### 2: Fix the validation issue
The command will fail complaining that the nginx Deployment is missing ` + "`" + `cpu-requests` + "`" + `,
and print the name of the file + Resource index. Edit the file and uncomment the resources,
then re-run the functions.
kustomize config run-fns local-resource/
The validation now passes.
### Injection -- resource reservations
This section uses ` + "`" + `run-fns` + "`" + ` to perform injection of field values based off annotations
on the Resource.
#### 1: Run the Injector
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/inject-tshirt-sizes` + "`" + `
directory, and invoke ` + "`" + `run-fns` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
# print the resources
kustomize config tree local-resource --resources --name
local-resource
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
└── name: nginx
# run the functions
kustomize config run-fns local-resource/
# print the new resources
kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
├── name: nginx
└── resources: {requests: {cpu: 4, memory: 1GiB}}
#### 2: Change the tshirt-size
Change the ` + "`" + `tshirt-size` + "`" + ` annotation from ` + "`" + `medium` + "`" + ` to ` + "`" + `small` + "`" + ` and re-run the functions.
kustomize config run-fns local-resource/
kustomize config tree local-resource/
local-resource
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
├── name: nginx
└── resources: {requests: {cpu: 200m, memory: 50MiB}}
The function has applied the reservations for the new tshirt-size
### Function Composition
Functions may be composed together. Try putting the Injection (tshirt-size) and
Validation functions together in the same .yaml file (separated by ` + "`" + `---` + "`" + `). Run
` + "`" + `run-fns` + "`" + ` and observe that the first function in the file is applied to the Resources,
and then the second function in the file is applied.`

10
cmd/config/cmds/cmds.go
View File

@@ -77,7 +77,7 @@ func NewConfigCommand(name string) *cobra.Command {
})
root.AddCommand(&cobra.Command{
Use: "docs-fn",
Short: "[Alpha] Documentation for writing containerized functions run by run-fns.",
Short: "[Alpha] Documentation for writing containerized functions run by run.",
Long: api.ConfigFnLong,
})
root.AddCommand(&cobra.Command{
@@ -87,10 +87,16 @@ func NewConfigCommand(name string) *cobra.Command {
})
root.AddCommand(&cobra.Command{
Use: "tutorials-basics",
Use: "tutorials-command-basics",
Short: "[Alpha] Tutorials for using basic config commands.",
Long: tutorials.ConfigurationBasicsLong,
})
root.AddCommand(&cobra.Command{
Use: "tutorials-function-basics",
Short: "[Alpha] Tutorials for using functions.",
Long: tutorials.FunctionBasicsLong,
})
return root
}

184
cmd/config/docs/tutorials/function-basics.md Normal file
View File

@@ -0,0 +1,184 @@
## Function Basics
### Synopsis
`kustomize config` enables encapsulating function for manipulating Resource
configuration inside containers, which are run using `run-fns`.
First fetch the kustomize repository, which contains a collection of example
functions
git clone https://github.com/kubernetes-sigs/kustomize
cd kustomize/functions/examples/
### Templating -- CockroachDB
This section demonstrates how to leverage templating based solutions from
`kustomize config`. The templating function is implemented as a `bash` script
using a `heredoc`.
#### 1: Generate the Resources
`cd` into the `kustomize/functions/examples/template-heredoc-cockroachdb/`
directory, and invoke `run-fns` on the `local-resource/` directory.
cd template-heredoc-cockroachdb/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
# run the function
kustomize config run-fns local-resource/
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
`run-fns` generated the directory ` local-resource/config` containing the generated
Resources.
#### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the `local-resources/example-use.yaml` by changing the replicas
re-run `run-fns`. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration.
# run the function
kustomize config run-fns local-resource/
`run-fns` facilitates a non-destructive *smart templating* approach that allows templating
to be composed with manual modifications directly to the template output, as well as
composition with other functions which may appy validation or injection of values.
#### 3. Function Implementation
the function implementation is located under the `image/` directory as a `Dockerfile`
and a `bash` script.
### Templating -- Nginx
The steps in this section are identical to the CockroachDB templating example,
but the function implementation is very different, and implemented as a `go`
program rather than a `bash` script.
#### 1: Generate the Resources
`cd` into the `kustomize/functions/examples/template-go-nginx/`
directory, and invoke `run-fns` on the `local-resource/` directory.
cd template-go-nginx/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
# run the function
kustomize config run-fns local-resource/
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
`run-fns` generated the directory ` local-resource/config` containing the generated
Resources. this time it put the configuration in a single file rather than multiple
files. The mapping of Resources to files is controlled by the function itself through
annotations on the generated Resources.
#### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the `local-resources/example-use.yaml` by changing the replicas
re-run `run-fns`. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration.
# run the function
kustomize config run-fns local-resource/
Just like in the preceding section, the function is implemented using a non-destructive
approach which merges the generated Resources into previously generated instances.
#### 3. Function Implementation
the function implementation is located under the `image/` directory as a `Dockerfile`
and a `go` program.
### Validation -- resource reservations
This section uses `run-fns` to perform validation rather than generate Resources.
#### 1: Run the Validator
`cd` into the `kustomize/functions/examples/validator-resource-requests`
directory, and invoke `run-fns` on the `local-resource/` directory.
# run the function
kustomize config run-fns local-resource/
cpu-requests missing for a container in Deployment nginx (example-use.yaml [1])
Error: exit status 1
Usage:
...
#### 2: Fix the validation issue
The command will fail complaining that the nginx Deployment is missing `cpu-requests`,
and print the name of the file + Resource index. Edit the file and uncomment the resources,
then re-run the functions.
kustomize config run-fns local-resource/
The validation now passes.
### Injection -- resource reservations
This section uses `run-fns` to perform injection of field values based off annotations
on the Resource.
#### 1: Run the Injector
`cd` into the `kustomize/functions/examples/inject-tshirt-sizes`
directory, and invoke `run-fns` on the `local-resource/` directory.
# print the resources
kustomize config tree local-resource --resources --name
local-resource
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
└── name: nginx
# run the functions
kustomize config run-fns local-resource/
# print the new resources
kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
├── name: nginx
└── resources: {requests: {cpu: 4, memory: 1GiB}}
#### 2: Change the tshirt-size
Change the `tshirt-size` annotation from `medium` to `small` and re-run the functions.
kustomize config run-fns local-resource/
kustomize config tree local-resource/
local-resource
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
├── name: nginx
└── resources: {requests: {cpu: 200m, memory: 50MiB}}
The function has applied the reservations for the new tshirt-size
### Function Composition
Functions may be composed together. Try putting the Injection (tshirt-size) and
Validation functions together in the same .yaml file (separated by `---`). Run
`run-fns` and observe that the first function in the file is applied to the Resources,
and then the second function in the file is applied.