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

Merge pull request #1922 from bzub/cmd_config_docs

Browse Source 
cmd/config: Documentation nits + updates.
This commit is contained in:
Jeff Regan
2019-12-11 12:59:41 -08:00
committed by GitHub
parent 54b1549586 3803541bfd
commit 4ba69b27f8
17 changed files with 182 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
cmd/config/cmddocs/api/docs.go
View File

@@ -9,9 +9,9 @@ var ConfigFnLong = `# Configuration Functions API Semantics
Configuration Functions are functions packaged as executables in containers which enable Configuration Functions are functions packaged as executables in containers which enable
**shift-left practices**. They configure applications and infrastructure through **shift-left practices**. They configure applications and infrastructure through
Kubernetes style Resource Configuration, but run locally pre-commit. Kubernetes style Resource Configuration, but run locally pre-commit.
Configuration functions enable shift-left practices (client-side) through: Configuration functions enable shift-left practices (client-side) through:
- Pre-commit / delivery validation and linting of configuration - Pre-commit / delivery validation and linting of configuration
- e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits - e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits
- Implementation of abstractions as client actuated APIs (e.g. templating) - Implementation of abstractions as client actuated APIs (e.g. templating)
@@ -23,7 +23,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
Type, annotations, etc. Type, annotations, etc.
Performing these on the client rather than the server enables: Performing these on the client rather than the server enables:
- Configuration to be reviewed prior to being sent to the API server - Configuration to be reviewed prior to being sent to the API server
- Configuration to be validated as part of the CD pipeline - Configuration to be validated as part of the CD pipeline
- Configuration for Resources to validated holistically rather than individually - Configuration for Resources to validated holistically rather than individually
@@ -36,14 +36,14 @@ var ConfigFnLong = `# Configuration Functions API Semantics
- Compose generation, injection, validation together - Compose generation, injection, validation together
Configuration Functions are implemented as executable programs published in containers which: Configuration Functions are implemented as executable programs published in containers which:
- Accept as input (stdin): - Accept as input (stdin):
- A list of Resource Configuration - A list of Resource Configuration
- A Function Configuration (to configure the function itself) - A Function Configuration (to configure the function itself)
- Emit as output (stdout + exit): - Emit as output (stdout + exit):
- A list of Resource Configuration - A list of Resource Configuration
- An exit code for success / failure - An exit code for success / failure
### Function Specification ### Function Specification
- Functions **SHOULD** be published as container images containing a ` + "`" + `CMD` + "`" + ` invoking an executable. - Functions **SHOULD** be published as container images containing a ` + "`" + `CMD` + "`" + ` invoking an executable.
@@ -71,7 +71,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
- contains ` + "`" + `functionConfig` + "`" + ` field -- a single item with the configuration for the function itself - contains ` + "`" + `functionConfig` + "`" + ` field -- a single item with the configuration for the function itself
Example ` + "`" + `ResourceList` + "`" + ` Input: Example ` + "`" + `ResourceList` + "`" + ` Input:
apiVersion: config.kubernetes.io/v1alpha1 apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList kind: ResourceList
functionConfig: functionConfig:
@@ -106,7 +106,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
- contains ` + "`" + `items` + "`" + ` field, same as ` + "`" + `List.items` + "`" + ` - contains ` + "`" + `items` + "`" + ` field, same as ` + "`" + `List.items` + "`" + `
Example ` + "`" + `ResourceList` + "`" + ` Output: Example ` + "`" + `ResourceList` + "`" + ` Output:
apiVersion: config.kubernetes.io/v1alpha1 apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList kind: ResourceList
items: items:
@@ -206,7 +206,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
#### ` + "`" + `Dockerfile` + "`" + ` #### ` + "`" + `Dockerfile` + "`" + `
` + "`" + `Dockerfile` + "`" + ` installs ` + "`" + `kustomize config` + "`" + ` and copies the script into the container image. ` + "`" + `Dockerfile` + "`" + ` installs ` + "`" + `kustomize config` + "`" + ` and copies the script into the container image.
FROM golang:1.13-stretch FROM golang:1.13-stretch
RUN go get sigs.k8s.io/kustomize/cmd/config RUN go get sigs.k8s.io/kustomize/cmd/config
@@ -238,11 +238,11 @@ Following is an example of running the ` + "`" + `kustomize config run` + "`" +
- ` + "`" + `configFn.container.image` + "`" + `: the image to use for this API - ` + "`" + `configFn.container.image` + "`" + `: the image to use for this API
- ` + "`" + `annotations[config.kubernetes.io/local-config]` + "`" + `: mark this as not a Resource that should - ` + "`" + `annotations[config.kubernetes.io/local-config]` + "`" + `: mark this as not a Resource that should
be applied be applied
#### ` + "`" + `kustomize config run dir/` + "`" + ` (Output) #### ` + "`" + `kustomize config run dir/` + "`" + ` (Output)
` + "`" + `dir/my-instance_deployment.yaml` + "`" + ` contains the Deployment: ` + "`" + `dir/my-instance_deployment.yaml` + "`" + ` contains the Deployment:
apiVersion: apps/v1 apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
@@ -284,8 +284,7 @@ Following is an example of running the ` + "`" + `kustomize config run` + "`" +
name: http name: http
selector: selector:
app: nginx app: nginx
instance: my-instance instance: my-instance`
`
var ConfigIoLong = `# Configuration IO API Semantics var ConfigIoLong = `# Configuration IO API Semantics
@@ -330,9 +329,9 @@ var ConfigIoLong = `# Configuration IO API Semantics
rather than a remote Resource. e.g. The ` + "`" + `Kustomization` + "`" + ` config in a ` + "`" + `kustomization.yaml` + "`" + ` rather than a remote Resource. e.g. The ` + "`" + `Kustomization` + "`" + ` config in a ` + "`" + `kustomization.yaml` + "`" + `
**SHOULD** contain this annotation so that tools know it is not intended to be sent to **SHOULD** contain this annotation so that tools know it is not intended to be sent to
the Kubernetes api server. the Kubernetes api server.
Example: Example:
metadata: metadata:
annotations: annotations:
config.kubernetes.io/local-config: "true"` config.kubernetes.io/local-config: "true"`
@@ -362,7 +361,7 @@ var Merge2Long = `# Merge (2-way)
- if the field is present in both the src and dest, and the src value is - if the field is present in both the src and dest, and the src value is
` + "`" + `null` + "`" + `, the field is removed from the dest ` + "`" + `null` + "`" + `, the field is removed from the dest
- if the field is present in both the src and dest, the value is recursively merged - if the field is present in both the src and dest, the value is recursively merged
- example src: ` + "`" + `{'key1': 'value1', 'key2': 'value2'}` + "`" + `, - example src: ` + "`" + `{'key1': 'value1', 'key2': 'value2'}` + "`" + `,
dest: ` + "`" + `{'key2': 'value0', 'key3': 'value3'}` + "`" + ` dest: ` + "`" + `{'key2': 'value0', 'key3': 'value3'}` + "`" + `
=> result: ` + "`" + `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}` + "`" + ` => result: ` + "`" + `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}` + "`" + `

38
cmd/config/cmddocs/commands/docs.go
View File

@@ -14,10 +14,10 @@ var CatLong = `
var CatExamples = ` var CatExamples = `
# print Resource config from a directory # print Resource config from a directory
kustomize config cat my-dir/ kustomize config cat my-dir/
# wrap Resource config from a directory in an ResourceList # wrap Resource config from a directory in an ResourceList
kustomize config cat my-dir/ --wrap-kind ResourceList --wrap-version config.kubernetes.io/v1alpha1 --function-config fn.yaml kustomize config cat my-dir/ --wrap-kind ResourceList --wrap-version config.kubernetes.io/v1alpha1 --function-config fn.yaml
# unwrap Resource config from a directory in an ResourceList # unwrap Resource config from a directory in an ResourceList
... | kustomize config cat` ... | kustomize config cat`
@@ -106,13 +106,13 @@ var GrepLong = `
var GrepExamples = ` var GrepExamples = `
# find Deployment Resources # find Deployment Resources
kustomize config grep "kind=Deployment" my-dir/ kustomize config grep "kind=Deployment" my-dir/
# find Resources named nginx # find Resources named nginx
kustomize config grep "metadata.name=nginx" my-dir/ kustomize config grep "metadata.name=nginx" my-dir/
# use tree to display matching Resources # use tree to display matching Resources
kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree
# look for Resources matching a specific container image # look for Resources matching a specific container image
kustomize config grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize config tree` kustomize config grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize config tree`
@@ -180,7 +180,7 @@ order they appear in the file).
would then write the container stdout back to example/, replacing the directory would then write the container stdout back to example/, replacing the directory
file contents. file contents.
See ` + "`" + `kustomize config help docs-fn` + "`" + ` for more details on writing functions. See ` + "`" + `kustomize help config docs-fn` + "`" + ` for more details on writing functions.
` `
var RunFnsExamples = ` var RunFnsExamples = `
kustomize config run example/` kustomize config run example/`
@@ -209,26 +209,26 @@ from the cluster, the Resource graph structure may be used instead.
var TreeExamples = ` var TreeExamples = `
# print Resources using directory structure # print Resources using directory structure
kustomize config tree my-dir/ kustomize config tree my-dir/
# print replicas, container name, and container image and fields for Resources # print replicas, container name, and container image and fields for Resources
kustomize config tree my-dir --replicas --image --name kustomize config tree my-dir --replicas --image --name
# print all common Resource fields # print all common Resource fields
kustomize config tree my-dir/ --all kustomize config tree my-dir/ --all
# print the "foo"" annotation # print the "foo"" annotation
kustomize config tree my-dir/ --field "metadata.annotations.foo" kustomize config tree my-dir/ --field "metadata.annotations.foo"
# print the "foo"" annotation # print the "foo"" annotation
kubectl get all -o yaml | kustomize config tree my-dir/ --structure=graph \ kubectl get all -o yaml | kustomize config tree \
--field="status.conditions[type=Completed].status" --field="status.conditions[type=Completed].status"
# print live Resources from a cluster using graph for structure # print live Resources from a cluster using owners for graph structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image --structure=graph kubectl get all -o yaml | kustomize config tree --replicas --name --image \
--graph-structure=owners
# print live Resources using graph for structure # print live Resources with status condition fields
kubectl get all,applications,releasetracks -o yaml | kustomize config tree --structure=graph \ kubectl get all -o yaml | kustomize config tree \
--name --image --replicas \ --name --image --replicas \
--field="status.conditions[type=Completed].status" \ --field="status.conditions[type=Completed].status" \
--field="status.conditions[type=Complete].status" \ --field="status.conditions[type=Complete].status" \

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

@@ -62,7 +62,7 @@ var ConfigurationBasicsLong = `
` + "`" + `tree` + "`" + ` can also be used with ` + "`" + `kubectl get` + "`" + ` to print cluster Resources using OwnersReferences ` + "`" + `tree` + "`" + ` can also be used with ` + "`" + `kubectl get` + "`" + ` to print cluster Resources using OwnersReferences
to build the tree structure. to build the tree structure.
kubectl apply -R -f cockroachdb/ kubectl apply -R -f cockroachdb/
kubectl get all -o yaml | kustomize config tree --graph-structure owners --name --image --replicas kubectl get all -o yaml | kustomize config tree --graph-structure owners --name --image --replicas
. .
@@ -116,7 +116,7 @@ var ConfigurationBasicsLong = `
ordering of fields and indentation. ordering of fields and indentation.
$ kustomize config fmt mysql-wordpress-pd/ $ kustomize config fmt mysql-wordpress-pd/
Run ` + "`" + `git diff` + "`" + ` and see the changes that have been applied. Run ` + "`" + `git diff` + "`" + ` and see the changes that have been applied.
### ` + "`" + `grep` + "`" + ` -- search for Resources by field values ### ` + "`" + `grep` + "`" + ` -- search for Resources by field values
@@ -145,7 +145,6 @@ var ConfigurationBasicsLong = `
- list elements may be indexed by a field value using list[field=value] - list elements may be indexed by a field value using list[field=value]
- '.' as part of a key or value may be escaped as '\.' - '.' as part of a key or value may be escaped as '\.'
$ kustomize config grep "spec.status.spec.containers[name=nginx].image=mysql:5\.6" wordpress/ $ kustomize config grep "spec.status.spec.containers[name=nginx].image=mysql:5\.6" wordpress/
apiVersion: apps/v1 # for k8s versions before 1.9.0 use apps/v1beta2 and before 1.8.0 use extensions/v1beta1 apiVersion: apps/v1 # for k8s versions before 1.9.0 use apps/v1beta2 and before 1.8.0 use extensions/v1beta1
@@ -166,12 +165,11 @@ var ConfigurationBasicsLong = `
tier: mysql tier: mysql
... ...
` + "`" + `grep` + "`" + ` may be used with kubectl to search for Resources in a cluster matching a value. ` + "`" + `grep` + "`" + ` may be used with kubectl to search for Resources in a cluster matching a value.
kubectl get all -o yaml | kustomize config grep "spec.replicas>0" | kustomize config tree --replicas kubectl get all -o yaml | kustomize config grep "spec.replicas>0" | kustomize config tree --replicas
. .
└── └──
├── [.] Deployment wp/wordpress ├── [.] Deployment wp/wordpress
│   └── spec.replicas: 1 │   └── spec.replicas: 1
├── [.] ReplicaSet wp/wordpress-76b5d9f5c8 ├── [.] ReplicaSet wp/wordpress-76b5d9f5c8
@@ -182,7 +180,7 @@ var ConfigurationBasicsLong = `
└── spec.replicas: 1 └── spec.replicas: 1
### Error handling ### Error handling
If there is an error parsing the Resource configuration, kustomize will print an error with the file. If there is an error parsing the Resource configuration, kustomize will print an error with the file.
$ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ | kustomize config tree --name --resources $ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ | kustomize config tree --name --resources
@@ -191,13 +189,13 @@ var ConfigurationBasicsLong = `
Here the ` + "`" + `staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml` + "`" + ` has a malformed Here the ` + "`" + `staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml` + "`" + ` has a malformed
Resource. Remove the malformed Resources: Resource. Remove the malformed Resources:
rm staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml rm staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml
rm staging/storage/vitess/etcd-service-template.yaml rm staging/storage/vitess/etcd-service-template.yaml
When developing -- to get a stack trace for where an error was encountered, When developing -- to get a stack trace for where an error was encountered,
use the ` + "`" + `--stack-trace` + "`" + ` flag: use the ` + "`" + `--stack-trace` + "`" + ` flag:
$ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ --stack-trace $ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ --stack-trace
go/src/sigs.k8s.io/kustomize/kyaml/yaml/types.go:260 (0x4d35c86) go/src/sigs.k8s.io/kustomize/kyaml/yaml/types.go:260 (0x4d35c86)
(*RNode).GetMeta: return m, errors.Wrap(err) (*RNode).GetMeta: return m, errors.Wrap(err)
@@ -209,9 +207,9 @@ var ConfigurationBasicsLong = `
### Combine ` + "`" + `grep` + "`" + ` and ` + "`" + `tree` + "`" + ` ### Combine ` + "`" + `grep` + "`" + ` and ` + "`" + `tree` + "`" + `
` + "`" + `grep` + "`" + ` and ` + "`" + `tree` + "`" + ` may be combined to perform queries against configuration. ` + "`" + `grep` + "`" + ` and ` + "`" + `tree` + "`" + ` may be combined to perform queries against configuration.
Query for ` + "`" + `replicas` + "`" + `: Query for ` + "`" + `replicas` + "`" + `:
$ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas $ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas
. .
├── staging/sysdig-cloud ├── staging/sysdig-cloud
@@ -249,9 +247,9 @@ var ConfigurationBasicsLong = `
The ` + "`" + `grep` + "`" + ` results may be inverted with the ` + "`" + `-v` + "`" + ` flag and used to find Resources that don't The ` + "`" + `grep` + "`" + ` results may be inverted with the ` + "`" + `-v` + "`" + ` flag and used to find Resources that don't
match a query. match a query.
Find Resources that have an image specified, but the image doesn't have a tag: Find Resources that have an image specified, but the image doesn't have a tag:
$ kustomize config grep "spec.template.spec.containers[name=\.*].name=\.*" ./ | kustomize config grep "spec.template.spec.containers[name=\.*].image=\.*:\.*" -v | kustomize config tree --image --name $ kustomize config grep "spec.template.spec.containers[name=\.*].name=\.*" ./ | kustomize config grep "spec.template.spec.containers[name=\.*].image=\.*:\.*" -v | kustomize config tree --image --name
. .
├── staging/newrelic ├── staging/newrelic
@@ -302,31 +300,30 @@ var FunctionBasicsLong = `
directory, and invoke ` + "`" + `run` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory. directory, and invoke ` + "`" + `run` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
cd template-heredoc-cockroachdb/ cd template-heredoc-cockroachdb/
# view the Resources # view the Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
# view the generated Resources # view the generated Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
` + "`" + `run` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated ` + "`" + `run` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated
Resources. Resources.
#### 2. Modify the Generated Resources #### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc. - modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas - modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas
re-run ` + "`" + `run` + "`" + `. this will apply the updated replicas to the generated Resources, re-run ` + "`" + `run` + "`" + `. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration. but keep the fields that you manually added to the generated Resource configuration.
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
` + "`" + `run` + "`" + ` facilitates a non-destructive *smart templating* approach that allows templating ` + "`" + `run` + "`" + ` facilitates a non-destructive *smart templating* approach that allows templating
to be composed with manual modifications directly to the template output, as well as 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. composition with other functions which may appy validation or injection of values.
@@ -339,7 +336,7 @@ var FunctionBasicsLong = `
### Templating -- Nginx ### Templating -- Nginx
The steps in this section are identical to the CockroachDB templating example, The steps in this section are identical to the CockroachDB templating example,
but the function implementation is very different, and implemented as a ` + "`" + `go` + "`" + ` but the function implementation is very different, and implemented as a ` + "`" + `go` + "`" + `
program rather than a ` + "`" + `bash` + "`" + ` script. program rather than a ` + "`" + `bash` + "`" + ` script.
#### 1: Generate the Resources #### 1: Generate the Resources
@@ -348,32 +345,32 @@ var FunctionBasicsLong = `
directory, and invoke ` + "`" + `run` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory. directory, and invoke ` + "`" + `run` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
cd template-go-nginx/ cd template-go-nginx/
# view the Resources # view the Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
# view the generated Resources # view the generated Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
` + "`" + `run` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated ` + "`" + `run` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated
Resources. this time it put the configuration in a single file rather than multiple 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 files. The mapping of Resources to files is controlled by the function itself through
annotations on the generated Resources. annotations on the generated Resources.
#### 2. Modify the Generated Resources #### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc. - modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas - modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas
re-run ` + "`" + `run` + "`" + `. this will apply the updated replicas to the generated Resources, re-run ` + "`" + `run` + "`" + `. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration. but keep the fields that you manually added to the generated Resource configuration.
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
Just like in the preceding section, the function is implemented using a non-destructive Just like in the preceding section, the function is implemented using a non-destructive
approach which merges the generated Resources into previously generated instances. approach which merges the generated Resources into previously generated instances.
@@ -385,7 +382,7 @@ var FunctionBasicsLong = `
### Validation -- resource reservations ### Validation -- resource reservations
This section uses ` + "`" + `run` + "`" + ` to perform validation rather than generate Resources. This section uses ` + "`" + `run` + "`" + ` to perform validation rather than generate Resources.
#### 1: Run the Validator #### 1: Run the Validator
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/validator-resource-requests` + "`" + ` ` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/validator-resource-requests` + "`" + `
@@ -397,13 +394,13 @@ var FunctionBasicsLong = `
Error: exit status 1 Error: exit status 1
Usage: Usage:
... ...
#### 2: Fix the validation issue #### 2: Fix the validation issue
The command will fail complaining that the nginx Deployment is missing ` + "`" + `cpu-requests` + "`" + `, 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, and print the name of the file + Resource index. Edit the file and uncomment the resources,
then re-run the functions. then re-run the functions.
kustomize config run local-resource/ kustomize config run local-resource/
The validation now passes. The validation now passes.
@@ -412,7 +409,7 @@ var FunctionBasicsLong = `
This section uses ` + "`" + `run` + "`" + ` to perform injection of field values based off annotations This section uses ` + "`" + `run` + "`" + ` to perform injection of field values based off annotations
on the Resource. on the Resource.
#### 1: Run the Injector #### 1: Run the Injector
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/inject-tshirt-sizes` + "`" + ` ` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/inject-tshirt-sizes` + "`" + `
@@ -421,7 +418,7 @@ var FunctionBasicsLong = `
# print the resources # print the resources
kustomize config tree local-resource --resources --name kustomize config tree local-resource --resources --name
local-resource local-resource
├── [example-use.yaml] Validator ├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx └── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers └── spec.template.spec.containers
└── 0 └── 0
@@ -429,10 +426,10 @@ var FunctionBasicsLong = `
# run the functions # run the functions
kustomize config run local-resource/ kustomize config run local-resource/
# print the new resources # print the new resources
kustomize config tree local-resource --resources --name kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator ├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx └── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers └── spec.template.spec.containers
└── 0 └── 0
@@ -440,24 +437,24 @@ var FunctionBasicsLong = `
└── resources: {requests: {cpu: 4, memory: 1GiB}} └── resources: {requests: {cpu: 4, memory: 1GiB}}
#### 2: Change the tshirt-size #### 2: Change the tshirt-size
Change the ` + "`" + `tshirt-size` + "`" + ` annotation from ` + "`" + `medium` + "`" + ` to ` + "`" + `small` + "`" + ` and re-run the functions. Change the ` + "`" + `tshirt-size` + "`" + ` annotation from ` + "`" + `medium` + "`" + ` to ` + "`" + `small` + "`" + ` and re-run the functions.
kustomize config run local-resource/ kustomize config run local-resource/
kustomize config tree local-resource/ kustomize config tree local-resource/
local-resource local-resource
├── [example-use.yaml] Validator ├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx └── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers └── spec.template.spec.containers
└── 0 └── 0
├── name: nginx ├── name: nginx
└── resources: {requests: {cpu: 200m, memory: 50MiB}} └── resources: {requests: {cpu: 200m, memory: 50MiB}}
The function has applied the reservations for the new tshirt-size The function has applied the reservations for the new tshirt-size
### Function Composition ### Function Composition
Functions may be composed together. Try putting the Injection (tshirt-size) and Functions may be composed together. Try putting the Injection (tshirt-size) and
Validation functions together in the same .yaml file (separated by ` + "`" + `---` + "`" + `). Run Validation functions together in the same .yaml file (separated by ` + "`" + `---` + "`" + `). Run
` + "`" + `run` + "`" + ` and observe that the first function in the file is applied to the Resources, ` + "`" + `run` + "`" + ` and observe that the first function in the file is applied to the Resources,
and then the second function in the file is applied.` and then the second function in the file is applied.`

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

@@ -23,7 +23,7 @@ Tutorials:
Run 'kustomize help config tutorial-TUTORIAL' Run 'kustomize help config tutorial-TUTORIAL'
$ kustomize help config tutorials-basics $ kustomize help config tutorials-command-basics
Command Documentation: Command Documentation:

21
cmd/config/docs/api-conventions/config-fn.md
View File

@@ -3,9 +3,9 @@
Configuration Functions are functions packaged as executables in containers which enable Configuration Functions are functions packaged as executables in containers which enable
**shift-left practices**. They configure applications and infrastructure through **shift-left practices**. They configure applications and infrastructure through
Kubernetes style Resource Configuration, but run locally pre-commit. Kubernetes style Resource Configuration, but run locally pre-commit.
Configuration functions enable shift-left practices (client-side) through: Configuration functions enable shift-left practices (client-side) through:
- Pre-commit / delivery validation and linting of configuration - Pre-commit / delivery validation and linting of configuration
- e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits - e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits
- Implementation of abstractions as client actuated APIs (e.g. templating) - Implementation of abstractions as client actuated APIs (e.g. templating)
@@ -17,7 +17,7 @@
Type, annotations, etc. Type, annotations, etc.
Performing these on the client rather than the server enables: Performing these on the client rather than the server enables:
- Configuration to be reviewed prior to being sent to the API server - Configuration to be reviewed prior to being sent to the API server
- Configuration to be validated as part of the CD pipeline - Configuration to be validated as part of the CD pipeline
- Configuration for Resources to validated holistically rather than individually - Configuration for Resources to validated holistically rather than individually
@@ -30,14 +30,14 @@
- Compose generation, injection, validation together - Compose generation, injection, validation together
Configuration Functions are implemented as executable programs published in containers which: Configuration Functions are implemented as executable programs published in containers which:
- Accept as input (stdin): - Accept as input (stdin):
- A list of Resource Configuration - A list of Resource Configuration
- A Function Configuration (to configure the function itself) - A Function Configuration (to configure the function itself)
- Emit as output (stdout + exit): - Emit as output (stdout + exit):
- A list of Resource Configuration - A list of Resource Configuration
- An exit code for success / failure - An exit code for success / failure
### Function Specification ### Function Specification
- Functions **SHOULD** be published as container images containing a `CMD` invoking an executable. - Functions **SHOULD** be published as container images containing a `CMD` invoking an executable.
@@ -65,7 +65,7 @@
- contains `functionConfig` field -- a single item with the configuration for the function itself - contains `functionConfig` field -- a single item with the configuration for the function itself
Example `ResourceList` Input: Example `ResourceList` Input:
apiVersion: config.kubernetes.io/v1alpha1 apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList kind: ResourceList
functionConfig: functionConfig:
@@ -100,7 +100,7 @@
- contains `items` field, same as `List.items` - contains `items` field, same as `List.items`
Example `ResourceList` Output: Example `ResourceList` Output:
apiVersion: config.kubernetes.io/v1alpha1 apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList kind: ResourceList
items: items:
@@ -200,7 +200,7 @@
#### `Dockerfile` #### `Dockerfile`
`Dockerfile` installs `kustomize config` and copies the script into the container image. `Dockerfile` installs `kustomize config` and copies the script into the container image.
FROM golang:1.13-stretch FROM golang:1.13-stretch
RUN go get sigs.k8s.io/kustomize/cmd/config RUN go get sigs.k8s.io/kustomize/cmd/config
@@ -232,11 +232,11 @@ Following is an example of running the `kustomize config run` using the precedin
- `configFn.container.image`: the image to use for this API - `configFn.container.image`: the image to use for this API
- `annotations[config.kubernetes.io/local-config]`: mark this as not a Resource that should - `annotations[config.kubernetes.io/local-config]`: mark this as not a Resource that should
be applied be applied
#### `kustomize config run dir/` (Output) #### `kustomize config run dir/` (Output)
`dir/my-instance_deployment.yaml` contains the Deployment: `dir/my-instance_deployment.yaml` contains the Deployment:
apiVersion: apps/v1 apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
@@ -279,4 +279,3 @@ Following is an example of running the `kustomize config run` using the precedin
selector: selector:
app: nginx app: nginx
instance: my-instance instance: my-instance

2
cmd/config/docs/api-conventions/config-io.md
View File

@@ -45,7 +45,7 @@ metadata:
config.kubernetes.io/index: 2 config.kubernetes.io/index: 2
``` ```
This represents the thrid Resource in the file. This represents the third Resource in the file.
### `config.kubernetes.io/local-config` ### `config.kubernetes.io/local-config`

4
cmd/config/docs/api-conventions/merge2.md
View File

@@ -23,7 +23,7 @@
- if the field is present in both the src and dest, and the src value is - if the field is present in both the src and dest, and the src value is
`null`, the field is removed from the dest `null`, the field is removed from the dest
- if the field is present in both the src and dest, the value is recursively merged - if the field is present in both the src and dest, the value is recursively merged
- example src: `{'key1': 'value1', 'key2': 'value2'}`, - example src: `{'key1': 'value1', 'key2': 'value2'}`,
dest: `{'key2': 'value0', 'key3': 'value3'}` dest: `{'key2': 'value0', 'key3': 'value3'}`
=> result: `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}` => result: `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}`
@@ -88,4 +88,4 @@
- name: sidecar1 - name: sidecar1
image: sidecar1:v1 image: sidecar1:v1
- name: sidecar2 - name: sidecar2
image: sidecar2:v1 image: sidecar2:v1

4
cmd/config/docs/commands/cat.md
View File

@@ -13,9 +13,9 @@
# print Resource config from a directory # print Resource config from a directory
kustomize config cat my-dir/ kustomize config cat my-dir/
# wrap Resource config from a directory in an ResourceList # wrap Resource config from a directory in an ResourceList
kustomize config cat my-dir/ --wrap-kind ResourceList --wrap-version config.kubernetes.io/v1alpha1 --function-config fn.yaml kustomize config cat my-dir/ --wrap-kind ResourceList --wrap-version config.kubernetes.io/v1alpha1 --function-config fn.yaml
# unwrap Resource config from a directory in an ResourceList # unwrap Resource config from a directory in an ResourceList
... | kustomize config cat ... | kustomize config cat

8
cmd/config/docs/commands/grep.md
View File

@@ -20,12 +20,12 @@
# find Deployment Resources # find Deployment Resources
kustomize config grep "kind=Deployment" my-dir/ kustomize config grep "kind=Deployment" my-dir/
# find Resources named nginx # find Resources named nginx
kustomize config grep "metadata.name=nginx" my-dir/ kustomize config grep "metadata.name=nginx" my-dir/
# use tree to display matching Resources # use tree to display matching Resources
kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree
# look for Resources matching a specific container image # look for Resources matching a specific container image
kustomize config grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize config tree kustomize config grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize config tree

2
cmd/config/docs/commands/run-fns.md
View File

@@ -46,7 +46,7 @@ order they appear in the file).
would then write the container stdout back to example/, replacing the directory would then write the container stdout back to example/, replacing the directory
file contents. file contents.
See `kustomize config help docs-fn` for more details on writing functions. See `kustomize help config docs-fn` for more details on writing functions.
### Examples ### Examples

26
cmd/config/docs/commands/tree.md
View File

@@ -27,26 +27,26 @@ from the cluster, the Resource graph structure may be used instead.
# print Resources using directory structure # print Resources using directory structure
kustomize config tree my-dir/ kustomize config tree my-dir/
# print replicas, container name, and container image and fields for Resources # print replicas, container name, and container image and fields for Resources
kustomize config tree my-dir --replicas --image --name kustomize config tree my-dir --replicas --image --name
# print all common Resource fields # print all common Resource fields
kustomize config tree my-dir/ --all kustomize config tree my-dir/ --all
# print the "foo"" annotation # print the "foo"" annotation
kustomize config tree my-dir/ --field "metadata.annotations.foo" kustomize config tree my-dir/ --field "metadata.annotations.foo"
# print the "foo"" annotation # print the "foo"" annotation
kubectl get all -o yaml | kustomize config tree my-dir/ --structure=graph \ kubectl get all -o yaml | kustomize config tree \
--field="status.conditions[type=Completed].status" --field="status.conditions[type=Completed].status"
# print live Resources from a cluster using graph for structure # print live Resources from a cluster using owners for graph structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image --structure=graph kubectl get all -o yaml | kustomize config tree --replicas --name --image \
--graph-structure=owners
# print live Resources using graph for structure # print live Resources with status condition fields
kubectl get all,applications,releasetracks -o yaml | kustomize config tree --structure=graph \ kubectl get all -o yaml | kustomize config tree \
--name --image --replicas \ --name --image --replicas \
--field="status.conditions[type=Completed].status" \ --field="status.conditions[type=Completed].status" \
--field="status.conditions[type=Complete].status" \ --field="status.conditions[type=Complete].status" \

24
cmd/config/docs/tutorials/configuration-basics.md
View File

@@ -58,7 +58,7 @@
`tree` can also be used with `kubectl get` to print cluster Resources using OwnersReferences `tree` can also be used with `kubectl get` to print cluster Resources using OwnersReferences
to build the tree structure. to build the tree structure.
kubectl apply -R -f cockroachdb/ kubectl apply -R -f cockroachdb/
kubectl get all -o yaml | kustomize config tree --graph-structure owners --name --image --replicas kubectl get all -o yaml | kustomize config tree --graph-structure owners --name --image --replicas
. .
@@ -112,7 +112,7 @@
ordering of fields and indentation. ordering of fields and indentation.
$ kustomize config fmt mysql-wordpress-pd/ $ kustomize config fmt mysql-wordpress-pd/
Run `git diff` and see the changes that have been applied. Run `git diff` and see the changes that have been applied.
### `grep` -- search for Resources by field values ### `grep` -- search for Resources by field values
@@ -141,7 +141,6 @@
- list elements may be indexed by a field value using list[field=value] - list elements may be indexed by a field value using list[field=value]
- '.' as part of a key or value may be escaped as '\.' - '.' as part of a key or value may be escaped as '\.'
$ kustomize config grep "spec.status.spec.containers[name=nginx].image=mysql:5\.6" wordpress/ $ kustomize config grep "spec.status.spec.containers[name=nginx].image=mysql:5\.6" wordpress/
apiVersion: apps/v1 # for k8s versions before 1.9.0 use apps/v1beta2 and before 1.8.0 use extensions/v1beta1 apiVersion: apps/v1 # for k8s versions before 1.9.0 use apps/v1beta2 and before 1.8.0 use extensions/v1beta1
@@ -162,12 +161,11 @@
tier: mysql tier: mysql
... ...
`grep` may be used with kubectl to search for Resources in a cluster matching a value. `grep` may be used with kubectl to search for Resources in a cluster matching a value.
kubectl get all -o yaml | kustomize config grep "spec.replicas>0" | kustomize config tree --replicas kubectl get all -o yaml | kustomize config grep "spec.replicas>0" | kustomize config tree --replicas
. .
└── └──
├── [.] Deployment wp/wordpress ├── [.] Deployment wp/wordpress
│   └── spec.replicas: 1 │   └── spec.replicas: 1
├── [.] ReplicaSet wp/wordpress-76b5d9f5c8 ├── [.] ReplicaSet wp/wordpress-76b5d9f5c8
@@ -178,7 +176,7 @@
└── spec.replicas: 1 └── spec.replicas: 1
### Error handling ### Error handling
If there is an error parsing the Resource configuration, kustomize will print an error with the file. If there is an error parsing the Resource configuration, kustomize will print an error with the file.
$ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ | kustomize config tree --name --resources $ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ | kustomize config tree --name --resources
@@ -187,13 +185,13 @@
Here the `staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml` has a malformed Here the `staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml` has a malformed
Resource. Remove the malformed Resources: Resource. Remove the malformed Resources:
rm staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml rm staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml
rm staging/storage/vitess/etcd-service-template.yaml rm staging/storage/vitess/etcd-service-template.yaml
When developing -- to get a stack trace for where an error was encountered, When developing -- to get a stack trace for where an error was encountered,
use the `--stack-trace` flag: use the `--stack-trace` flag:
$ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ --stack-trace $ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ --stack-trace
go/src/sigs.k8s.io/kustomize/kyaml/yaml/types.go:260 (0x4d35c86) go/src/sigs.k8s.io/kustomize/kyaml/yaml/types.go:260 (0x4d35c86)
(*RNode).GetMeta: return m, errors.Wrap(err) (*RNode).GetMeta: return m, errors.Wrap(err)
@@ -205,9 +203,9 @@
### Combine `grep` and `tree` ### Combine `grep` and `tree`
`grep` and `tree` may be combined to perform queries against configuration. `grep` and `tree` may be combined to perform queries against configuration.
Query for `replicas`: Query for `replicas`:
$ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas $ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas
. .
├── staging/sysdig-cloud ├── staging/sysdig-cloud
@@ -245,9 +243,9 @@
The `grep` results may be inverted with the `-v` flag and used to find Resources that don't The `grep` results may be inverted with the `-v` flag and used to find Resources that don't
match a query. match a query.
Find Resources that have an image specified, but the image doesn't have a tag: Find Resources that have an image specified, but the image doesn't have a tag:
$ kustomize config grep "spec.template.spec.containers[name=\.*].name=\.*" ./ | kustomize config grep "spec.template.spec.containers[name=\.*].image=\.*:\.*" -v | kustomize config tree --image --name $ kustomize config grep "spec.template.spec.containers[name=\.*].name=\.*" ./ | kustomize config grep "spec.template.spec.containers[name=\.*].image=\.*:\.*" -v | kustomize config tree --image --name
. .
├── staging/newrelic ├── staging/newrelic

67
cmd/config/docs/tutorials/function-basics.md
View File

@@ -23,31 +23,30 @@
directory, and invoke `run` on the `local-resource/` directory. directory, and invoke `run` on the `local-resource/` directory.
cd template-heredoc-cockroachdb/ cd template-heredoc-cockroachdb/
# view the Resources # view the Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
# view the generated Resources # view the generated Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
`run` generated the directory ` local-resource/config` containing the generated `run` generated the directory ` local-resource/config` containing the generated
Resources. Resources.
#### 2. Modify the Generated Resources #### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc. - modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the `local-resources/example-use.yaml` by changing the replicas - modify the `local-resources/example-use.yaml` by changing the replicas
re-run `run`. this will apply the updated replicas to the generated Resources, re-run `run`. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration. but keep the fields that you manually added to the generated Resource configuration.
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
`run` facilitates a non-destructive *smart templating* approach that allows templating `run` facilitates a non-destructive *smart templating* approach that allows templating
to be composed with manual modifications directly to the template output, as well as 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. composition with other functions which may appy validation or injection of values.
@@ -60,7 +59,7 @@
### Templating -- Nginx ### Templating -- Nginx
The steps in this section are identical to the CockroachDB templating example, The steps in this section are identical to the CockroachDB templating example,
but the function implementation is very different, and implemented as a `go` but the function implementation is very different, and implemented as a `go`
program rather than a `bash` script. program rather than a `bash` script.
#### 1: Generate the Resources #### 1: Generate the Resources
@@ -69,32 +68,32 @@
directory, and invoke `run` on the `local-resource/` directory. directory, and invoke `run` on the `local-resource/` directory.
cd template-go-nginx/ cd template-go-nginx/
# view the Resources # view the Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
# view the generated Resources # view the generated Resources
kustomize config tree local-resource/ --name --image --replicas kustomize config tree local-resource/ --name --image --replicas
`run` generated the directory ` local-resource/config` containing the generated `run` generated the directory ` local-resource/config` containing the generated
Resources. this time it put the configuration in a single file rather than multiple 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 files. The mapping of Resources to files is controlled by the function itself through
annotations on the generated Resources. annotations on the generated Resources.
#### 2. Modify the Generated Resources #### 2. Modify the Generated Resources
- modify the generated Resources by adding an annotation, sidecar container, etc. - modify the generated Resources by adding an annotation, sidecar container, etc.
- modify the `local-resources/example-use.yaml` by changing the replicas - modify the `local-resources/example-use.yaml` by changing the replicas
re-run `run`. this will apply the updated replicas to the generated Resources, re-run `run`. this will apply the updated replicas to the generated Resources,
but keep the fields that you manually added to the generated Resource configuration. but keep the fields that you manually added to the generated Resource configuration.
# run the function # run the function
kustomize config run local-resource/ kustomize config run local-resource/
Just like in the preceding section, the function is implemented using a non-destructive Just like in the preceding section, the function is implemented using a non-destructive
approach which merges the generated Resources into previously generated instances. approach which merges the generated Resources into previously generated instances.
@@ -106,7 +105,7 @@
### Validation -- resource reservations ### Validation -- resource reservations
This section uses `run` to perform validation rather than generate Resources. This section uses `run` to perform validation rather than generate Resources.
#### 1: Run the Validator #### 1: Run the Validator
`cd` into the `kustomize/functions/examples/validator-resource-requests` `cd` into the `kustomize/functions/examples/validator-resource-requests`
@@ -118,13 +117,13 @@
Error: exit status 1 Error: exit status 1
Usage: Usage:
... ...
#### 2: Fix the validation issue #### 2: Fix the validation issue
The command will fail complaining that the nginx Deployment is missing `cpu-requests`, 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, and print the name of the file + Resource index. Edit the file and uncomment the resources,
then re-run the functions. then re-run the functions.
kustomize config run local-resource/ kustomize config run local-resource/
The validation now passes. The validation now passes.
@@ -133,7 +132,7 @@
This section uses `run` to perform injection of field values based off annotations This section uses `run` to perform injection of field values based off annotations
on the Resource. on the Resource.
#### 1: Run the Injector #### 1: Run the Injector
`cd` into the `kustomize/functions/examples/inject-tshirt-sizes` `cd` into the `kustomize/functions/examples/inject-tshirt-sizes`
@@ -142,7 +141,7 @@
# print the resources # print the resources
kustomize config tree local-resource --resources --name kustomize config tree local-resource --resources --name
local-resource local-resource
├── [example-use.yaml] Validator ├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx └── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers └── spec.template.spec.containers
└── 0 └── 0
@@ -150,10 +149,10 @@
# run the functions # run the functions
kustomize config run local-resource/ kustomize config run local-resource/
# print the new resources # print the new resources
kustomize config tree local-resource --resources --name kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator ├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx └── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers └── spec.template.spec.containers
└── 0 └── 0
@@ -161,24 +160,24 @@
└── resources: {requests: {cpu: 4, memory: 1GiB}} └── resources: {requests: {cpu: 4, memory: 1GiB}}
#### 2: Change the tshirt-size #### 2: Change the tshirt-size
Change the `tshirt-size` annotation from `medium` to `small` and re-run the functions. Change the `tshirt-size` annotation from `medium` to `small` and re-run the functions.
kustomize config run local-resource/ kustomize config run local-resource/
kustomize config tree local-resource/ kustomize config tree local-resource/
local-resource local-resource
├── [example-use.yaml] Validator ├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx └── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers └── spec.template.spec.containers
└── 0 └── 0
├── name: nginx ├── name: nginx
└── resources: {requests: {cpu: 200m, memory: 50MiB}} └── resources: {requests: {cpu: 200m, memory: 50MiB}}
The function has applied the reservations for the new tshirt-size The function has applied the reservations for the new tshirt-size
### Function Composition ### Function Composition
Functions may be composed together. Try putting the Injection (tshirt-size) and Functions may be composed together. Try putting the Injection (tshirt-size) and
Validation functions together in the same .yaml file (separated by `---`). Run Validation functions together in the same .yaml file (separated by `---`). Run
`run` and observe that the first function in the file is applied to the Resources, `run` and observe that the first function in the file is applied to the Resources,
and then the second function in the file is applied. and then the second function in the file is applied.

12
functions/examples/injection-tshirt-sizes/README.md
View File

@@ -8,7 +8,7 @@ input and writing the output. Writing in `go` is not a requirement.
## Function implementation ## Function implementation
The function is implemented as an [image](image), and built using `make image`. The function is implemented as an [image](image), and built using `make image`.
The template is implemented as a go program, which reads a collection of input The template is implemented as a go program, which reads a collection of input
Resource configuration, and looks for invalid configuration. Resource configuration, and looks for invalid configuration.
@@ -17,19 +17,19 @@ Resource configuration, and looks for invalid configuration.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.configFn` and running: with `metadata.configFn` and running:
kustomize config run local-resources/ kustomize config run local-resource/
This exists non-zero if there is an error. This exits non-zero if there is an error.
## Running the Example ## Running the Example
Run the validator with: Run the validator with:
kustomize config run local-resource/ kustomize config run local-resource/
This will add resource reservations to the Deployment. Change the `tshirt-size` This will add resource reservations to the Deployment. Change the `tshirt-size`
annotation from `medium` to `small` and rerun: annotation from `medium` to `small` and rerun:
kustomize config run local-resource/ kustomize config run local-resource/
Observe that the reservations have changed. Observe that the reservations have changed.

16
functions/examples/template-go-nginx/README.md
View File

@@ -27,12 +27,12 @@ function input, and writing the function output.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.configFn` and running: with `metadata.configFn` and running:
kustomize config run local-resources/ kustomize config run local-resource/
This generates the `local-resources/config` directory containing the template output. This generates the `local-resources/config` directory containing the template output.
- the template output may be modified by adding fields -- such as initContainers, - the template output may be modified by adding fields -- such as initContainers,
sidecarConatiners, cpu resource limits, etc -- and these fields will be retained sidecarConatiners, cpu resource limits, etc -- and these fields will be retained
when re-running `run` when re-running `run`
- the function input `example-use.yaml` may be changed and rerunning `run` will update - the function input `example-use.yaml` may be changed and rerunning `run` will update
only the parts changed in the template output. only the parts changed in the template output.
@@ -42,14 +42,14 @@ This generates the `local-resources/config` directory containing the template ou
Run the config with: Run the config with:
kustomize config run local-resource/ kustomize config run local-resource/
This will create the directory This will create the directory
local-resource/config local-resource/config
Add an annotation to the StatefulSet Resource and change the replica count of the Add an annotation to the Deployment Resource and change the replica count of the
`kind: Nginx` Resource in `example-use.yaml`. Rerun the template: `kind: Nginx` Resource in `example-use.yaml`. Rerun the template:
kustomize config run local-resource/ kustomize config run local-resource/
The replica count should be updated, but your annotation should remain. The replica count should be updated, but your annotation should remain.

16
functions/examples/template-heredoc-cockroachdb/README.md
View File

@@ -7,7 +7,7 @@ This example uses the simplest approach for building abstractions.
## Function implementation ## Function implementation
The function is implemented as an [image](image), and built using `make image`. The function is implemented as an [image](image), and built using `make image`.
The template is implemented as a heredoc, which substitutes environment variables The template is implemented as a heredoc, which substitutes environment variables
into a static string. into a static string.
@@ -22,12 +22,12 @@ heavy lifting of implementing the function interface.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.configFn` and running: with `metadata.configFn` and running:
kustomize config run local-resources/ kustomize config run local-resource/
This generates the `local-resources/config` directory containing the template output. This generates the `local-resources/config` directory containing the template output.
- the template output may be modified by adding fields -- such as initContainers, - the template output may be modified by adding fields -- such as initContainers,
sidecarConatiners, cpu resource limits, etc -- and these fields will be retained sidecarConatiners, cpu resource limits, etc -- and these fields will be retained
when re-running `run` when re-running `run`
- the function input `example-use.yaml` may be changed and rerunning `run` will update - the function input `example-use.yaml` may be changed and rerunning `run` will update
only the parts changed in the template output. only the parts changed in the template output.
@@ -37,14 +37,14 @@ This generates the `local-resources/config` directory containing the template ou
Run the config with: Run the config with:
kustomize config run local-resource/ kustomize config run local-resource/
This will create the directory This will create the directory
local-resource/config local-resource/config
Add an annotation to the StatefulSet Resource and change the replica count of the Add an annotation to the StatefulSet Resource and change the replica count of the
`kind: CockroachDB` Resource in `example-use.yaml`. Rerun the template: `kind: CockroachDB` Resource in `example-use.yaml`. Rerun the template:
kustomize config run local-resource/ kustomize config run local-resource/
The replica count should be updated, but your annotation should remain. The replica count should be updated, but your annotation should remain.

12
functions/examples/validator-resource-requests/README.md
View File

@@ -8,7 +8,7 @@ input and writing the output. Writing in `go` is not a requirement.
## Function implementation ## Function implementation
The function is implemented as an [image](image), and built using `make image`. The function is implemented as an [image](image), and built using `make image`.
The template is implemented as a go program, which reads a collection of input The template is implemented as a go program, which reads a collection of input
Resource configuration, and looks for invalid configuration. Resource configuration, and looks for invalid configuration.
@@ -17,8 +17,8 @@ Resource configuration, and looks for invalid configuration.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.configFn` and running: with `metadata.configFn` and running:
kustomize config run local-resources/ kustomize config run local-resource/
This exists non-zero if there is an error. This exists non-zero if there is an error.
## Running the Example ## Running the Example
@@ -26,7 +26,7 @@ This exists non-zero if there is an error.
Run the validator with: Run the validator with:
kustomize config run local-resource/ kustomize config run local-resource/
This will return an error: This will return an error:
cpu-requests missing for container nginx cpu-requests missing for container nginx
@@ -34,5 +34,5 @@ This will return an error:
Now uncomment the resource reservations and run again: Now uncomment the resource reservations and run again:
kustomize config run local-resource/ kustomize config run local-resource/
This will return success This will return success