kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-10 08:20: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
**shift-left practices**. They configure applications and infrastructure through
Kubernetes style Resource Configuration, but run locally pre-commit.
Configuration functions enable shift-left practices (client-side) through:
- Pre-commit / delivery validation and linting of configuration
- e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits
- Implementation of abstractions as client actuated APIs (e.g. templating)
@@ -23,7 +23,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
Type, annotations, etc.
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 validated as part of the CD pipeline
- Configuration for Resources to validated holistically rather than individually
@@ -36,14 +36,14 @@ var ConfigFnLong = `# Configuration Functions API Semantics
- Compose generation, injection, validation together
Configuration Functions are implemented as executable programs published in containers which:
- Accept as input (stdin):
- A list of Resource Configuration
- A Function Configuration (to configure the function itself)
- Emit as output (stdout + exit):
- A list of Resource Configuration
- An exit code for success / failure
### Function Specification
- 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
Example ` + "`" + `ResourceList` + "`" + ` Input:
apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList
functionConfig:
@@ -106,7 +106,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
- contains ` + "`" + `items` + "`" + ` field, same as ` + "`" + `List.items` + "`" + `
Example ` + "`" + `ResourceList` + "`" + ` Output:
apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList
items:
@@ -206,7 +206,7 @@ var ConfigFnLong = `# Configuration Functions API Semantics
#### ` + "`" + `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
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
- ` + "`" + `annotations[config.kubernetes.io/local-config]` + "`" + `: mark this as not a Resource that should
be applied
#### ` + "`" + `kustomize config run dir/` + "`" + ` (Output)
` + "`" + `dir/my-instance_deployment.yaml` + "`" + ` contains the Deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
@@ -284,8 +284,7 @@ Following is an example of running the ` + "`" + `kustomize config run` + "`" +
name: http
selector:
app: nginx
instance: my-instance
`
instance: my-instance`
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` + "`" + `
**SHOULD** contain this annotation so that tools know it is not intended to be sent to
the Kubernetes api server.
Example:
metadata:
annotations:
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
` + "`" + `null` + "`" + `, the field is removed from the dest
- 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'}` + "`" + `
=> result: ` + "`" + `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}` + "`" + `

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

@@ -14,10 +14,10 @@ var CatLong = `
var CatExamples = `
# print Resource config from a directory
kustomize config cat my-dir/
# 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
# unwrap Resource config from a directory in an ResourceList
... | kustomize config cat`
@@ -106,13 +106,13 @@ var GrepLong = `
var GrepExamples = `
# find Deployment Resources
kustomize config grep "kind=Deployment" my-dir/
# find Resources named nginx
kustomize config grep "metadata.name=nginx" my-dir/
# use tree to display matching Resources
kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree
# 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`
@@ -180,7 +180,7 @@ order they appear in the file).
would then write the container stdout back to example/, replacing the directory
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 = `
kustomize config run example/`
@@ -209,26 +209,26 @@ from the cluster, the Resource graph structure may be used instead.
var TreeExamples = `
# print Resources using directory structure
kustomize config tree my-dir/
# print replicas, container name, and container image and fields for Resources
kustomize config tree my-dir --replicas --image --name
# print all common Resource fields
kustomize config tree my-dir/ --all
# 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
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"
# print live Resources from a cluster using graph for structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image --structure=graph
# print live Resources using graph for structure
kubectl get all,applications,releasetracks -o yaml | kustomize config tree --structure=graph \
# print live Resources from a cluster using owners for graph structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image \
--graph-structure=owners
# print live Resources with status condition fields
kubectl get all -o yaml | kustomize config tree \
--name --image --replicas \
--field="status.conditions[type=Completed].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
to build the tree structure.
kubectl apply -R -f cockroachdb/
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.
$ kustomize config fmt mysql-wordpress-pd/
Run ` + "`" + `git diff` + "`" + ` and see the changes that have been applied.
### ` + "`" + `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]
- '.' 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/
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
...
` + "`" + `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
.
└──
└──
├── [.] Deployment wp/wordpress
│   └── spec.replicas: 1
├── [.] ReplicaSet wp/wordpress-76b5d9f5c8
@@ -182,7 +180,7 @@ var ConfigurationBasicsLong = `
└── spec.replicas: 1
### Error handling
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
@@ -191,13 +189,13 @@ var ConfigurationBasicsLong = `
Here the ` + "`" + `staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml` + "`" + ` has a malformed
Resource. Remove the malformed Resources:
rm staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml
rm staging/storage/vitess/etcd-service-template.yaml
When developing -- to get a stack trace for where an error was encountered,
use the ` + "`" + `--stack-trace` + "`" + ` flag:
$ 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)
(*RNode).GetMeta: return m, errors.Wrap(err)
@@ -209,9 +207,9 @@ var ConfigurationBasicsLong = `
### Combine ` + "`" + `grep` + "`" + ` and ` + "`" + `tree` + "`" + `
` + "`" + `grep` + "`" + ` and ` + "`" + `tree` + "`" + ` may be combined to perform queries against configuration.
Query for ` + "`" + `replicas` + "`" + `:
$ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas
.
├── 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
match a query.
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
.
├── staging/newrelic
@@ -302,31 +300,30 @@ var FunctionBasicsLong = `
directory, and invoke ` + "`" + `run` + "`" + ` 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 local-resource/
# view the generated Resources
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
` + "`" + `run` + "`" + ` 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
- modify the ` + "`" + `local-resources/example-use.yaml` + "`" + ` by changing the replicas
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.
# run the function
kustomize config run local-resource/
` + "`" + `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
composition with other functions which may appy validation or injection of values.
@@ -339,7 +336,7 @@ var FunctionBasicsLong = `
### 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` + "`" + `
but the function implementation is very different, and implemented as a ` + "`" + `go` + "`" + `
program rather than a ` + "`" + `bash` + "`" + ` script.
#### 1: Generate the Resources
@@ -348,32 +345,32 @@ var FunctionBasicsLong = `
directory, and invoke ` + "`" + `run` + "`" + ` 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 local-resource/
# view the generated Resources
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
` + "`" + `run` + "`" + ` 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` + "`" + `. 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 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.
@@ -385,7 +382,7 @@ var FunctionBasicsLong = `
### Validation -- resource reservations
This section uses ` + "`" + `run` + "`" + ` to perform validation rather than generate Resources.
#### 1: Run the Validator
` + "`" + `cd` + "`" + ` into the ` + "`" + `kustomize/functions/examples/validator-resource-requests` + "`" + `
@@ -397,13 +394,13 @@ var FunctionBasicsLong = `
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 local-resource/
The validation now passes.
@@ -412,7 +409,7 @@ var FunctionBasicsLong = `
This section uses ` + "`" + `run` + "`" + ` 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` + "`" + `
@@ -421,7 +418,7 @@ var FunctionBasicsLong = `
# print the resources
kustomize config tree local-resource --resources --name
local-resource
├── [example-use.yaml] Validator
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
@@ -429,10 +426,10 @@ var FunctionBasicsLong = `
# run the functions
kustomize config run local-resource/
# print the new resources
kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator
kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
@@ -440,24 +437,24 @@ var FunctionBasicsLong = `
└── 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 local-resource/
kustomize config tree local-resource/
local-resource
├── [example-use.yaml] Validator
├── [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
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
Functions may be composed together. Try putting the Injection (tshirt-size) and
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,
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'
$ kustomize help config tutorials-basics
$ kustomize help config tutorials-command-basics
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
**shift-left practices**. They configure applications and infrastructure through
Kubernetes style Resource Configuration, but run locally pre-commit.
Configuration functions enable shift-left practices (client-side) through:
- Pre-commit / delivery validation and linting of configuration
- e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits
- Implementation of abstractions as client actuated APIs (e.g. templating)
@@ -17,7 +17,7 @@
Type, annotations, etc.
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 validated as part of the CD pipeline
- Configuration for Resources to validated holistically rather than individually
@@ -30,14 +30,14 @@
- Compose generation, injection, validation together
Configuration Functions are implemented as executable programs published in containers which:
- Accept as input (stdin):
- A list of Resource Configuration
- A Function Configuration (to configure the function itself)
- Emit as output (stdout + exit):
- A list of Resource Configuration
- An exit code for success / failure
### Function Specification
- 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
Example `ResourceList` Input:
apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList
functionConfig:
@@ -100,7 +100,7 @@
- contains `items` field, same as `List.items`
Example `ResourceList` Output:
apiVersion: config.kubernetes.io/v1alpha1
kind: ResourceList
items:
@@ -200,7 +200,7 @@
#### `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
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
- `annotations[config.kubernetes.io/local-config]`: mark this as not a Resource that should
be applied
#### `kustomize config run dir/` (Output)
`dir/my-instance_deployment.yaml` contains the Deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
@@ -279,4 +279,3 @@ Following is an example of running the `kustomize config run` using the precedin
selector:
app: nginx
instance: my-instance

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

@@ -45,7 +45,7 @@ metadata:
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`

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
`null`, the field is removed from the dest
- 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'}`
=> result: `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}`
@@ -88,4 +88,4 @@
- name: sidecar1
image: sidecar1:v1
- 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
kustomize config cat my-dir/
# 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
# unwrap Resource config from a directory in an ResourceList
... | kustomize config cat

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

@@ -20,12 +20,12 @@
# find Deployment Resources
kustomize config grep "kind=Deployment" my-dir/
# find Resources named nginx
kustomize config grep "metadata.name=nginx" my-dir/
# use tree to display matching Resources
kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree
# 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
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

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
kustomize config tree my-dir/
# print replicas, container name, and container image and fields for Resources
kustomize config tree my-dir --replicas --image --name
# print all common Resource fields
kustomize config tree my-dir/ --all
# 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
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"
# print live Resources from a cluster using graph for structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image --structure=graph
# print live Resources using graph for structure
kubectl get all,applications,releasetracks -o yaml | kustomize config tree --structure=graph \
# print live Resources from a cluster using owners for graph structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image \
--graph-structure=owners
# print live Resources with status condition fields
kubectl get all -o yaml | kustomize config tree \
--name --image --replicas \
--field="status.conditions[type=Completed].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
to build the tree structure.
kubectl apply -R -f cockroachdb/
kubectl get all -o yaml | kustomize config tree --graph-structure owners --name --image --replicas
.
@@ -112,7 +112,7 @@
ordering of fields and indentation.
$ kustomize config fmt mysql-wordpress-pd/
Run `git diff` and see the changes that have been applied.
### `grep` -- search for Resources by field values
@@ -141,7 +141,6 @@
- list elements may be indexed by a field value using list[field=value]
- '.' 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/
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
...
`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
.
└──
└──
├── [.] Deployment wp/wordpress
│   └── spec.replicas: 1
├── [.] ReplicaSet wp/wordpress-76b5d9f5c8
@@ -178,7 +176,7 @@
└── spec.replicas: 1
### Error handling
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
@@ -187,13 +185,13 @@
Here the `staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml` has a malformed
Resource. Remove the malformed Resources:
rm staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml
rm staging/storage/vitess/etcd-service-template.yaml
When developing -- to get a stack trace for where an error was encountered,
use the `--stack-trace` flag:
$ 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)
(*RNode).GetMeta: return m, errors.Wrap(err)
@@ -205,9 +203,9 @@
### Combine `grep` and `tree`
`grep` and `tree` may be combined to perform queries against configuration.
Query for `replicas`:
$ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas
.
├── 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
match a query.
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
.
├── 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.
cd template-heredoc-cockroachdb/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
# run the function
kustomize config run local-resource/
# view the generated Resources
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
`run` 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
- modify the `local-resources/example-use.yaml` by changing the replicas
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.
# run the function
kustomize config run local-resource/
`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
composition with other functions which may appy validation or injection of values.
@@ -60,7 +59,7 @@
### 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`
but the function implementation is very different, and implemented as a `go`
program rather than a `bash` script.
#### 1: Generate the Resources
@@ -69,32 +68,32 @@
directory, and invoke `run` 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 local-resource/
# view the generated Resources
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
`run` 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`. 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 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.
@@ -106,7 +105,7 @@
### Validation -- resource reservations
This section uses `run` to perform validation rather than generate Resources.
#### 1: Run the Validator
`cd` into the `kustomize/functions/examples/validator-resource-requests`
@@ -118,13 +117,13 @@
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 local-resource/
The validation now passes.
@@ -133,7 +132,7 @@
This section uses `run` 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`
@@ -142,7 +141,7 @@
# print the resources
kustomize config tree local-resource --resources --name
local-resource
├── [example-use.yaml] Validator
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
@@ -150,10 +149,10 @@
# run the functions
kustomize config run local-resource/
# print the new resources
kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator
kustomize config tree local-resource --resources --name
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
└── 0
@@ -161,24 +160,24 @@
└── 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 local-resource/
kustomize config tree local-resource/
local-resource
├── [example-use.yaml] Validator
├── [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
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
Functions may be composed together. Try putting the Injection (tshirt-size) and
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,
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
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
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)
with `metadata.configFn` and running:
kustomize config run local-resources/
This exists non-zero if there is an error.
kustomize config run local-resource/
This exits non-zero if there is an error.
## Running the Example
Run the validator with:
kustomize config run local-resource/
This will add resource reservations to the Deployment. Change the `tshirt-size`
annotation from `medium` to `small` and rerun:
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)
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.
- 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`
- the function input `example-use.yaml` may be changed and rerunning `run` will update
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:
kustomize config run local-resource/
This will create the directory
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:
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
The function is implemented as an [image](image), and built using `make image`.
The template is implemented as a heredoc, which substitutes environment variables
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)
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.
- 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`
- the function input `example-use.yaml` may be changed and rerunning `run` will update
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:
kustomize config run local-resource/
This will create the directory
local-resource/config
Add an annotation to the StatefulSet Resource and change the replica count of the
`kind: CockroachDB` Resource in `example-use.yaml`. Rerun the template:
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
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
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)
with `metadata.configFn` and running:
kustomize config run local-resources/
kustomize config run local-resource/
This exists non-zero if there is an error.
## Running the Example
@@ -26,7 +26,7 @@ This exists non-zero if there is an error.
Run the validator with:
kustomize config run local-resource/
This will return an error:
cpu-requests missing for container nginx
@@ -34,5 +34,5 @@ This will return an error:
Now uncomment the resource reservations and run again:
kustomize config run local-resource/
This will return success
This will return success