diff --git a/cmd/config/cmddocs/api/docs.go b/cmd/config/cmddocs/api/docs.go index 02f2fe800..45205cfa9 100644 --- a/cmd/config/cmddocs/api/docs.go +++ b/cmd/config/cmddocs/api/docs.go @@ -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'}` + "`" + ` diff --git a/cmd/config/cmddocs/commands/docs.go b/cmd/config/cmddocs/commands/docs.go index 83fa2627e..fef935bfc 100644 --- a/cmd/config/cmddocs/commands/docs.go +++ b/cmd/config/cmddocs/commands/docs.go @@ -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" \ diff --git a/cmd/config/cmddocs/tutorials/docs.go b/cmd/config/cmddocs/tutorials/docs.go index c41a35b22..3f5e81c9e 100644 --- a/cmd/config/cmddocs/tutorials/docs.go +++ b/cmd/config/cmddocs/tutorials/docs.go @@ -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.` diff --git a/cmd/config/cmds/cmds.go b/cmd/config/cmds/cmds.go index 3b010f0ec..c27be0715 100644 --- a/cmd/config/cmds/cmds.go +++ b/cmd/config/cmds/cmds.go @@ -23,7 +23,7 @@ Tutorials: Run 'kustomize help config tutorial-TUTORIAL' - $ kustomize help config tutorials-basics + $ kustomize help config tutorials-command-basics Command Documentation: diff --git a/cmd/config/docs/api-conventions/config-fn.md b/cmd/config/docs/api-conventions/config-fn.md index 5d149df5e..ca159ebae 100644 --- a/cmd/config/docs/api-conventions/config-fn.md +++ b/cmd/config/docs/api-conventions/config-fn.md @@ -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 - diff --git a/cmd/config/docs/api-conventions/config-io.md b/cmd/config/docs/api-conventions/config-io.md index 27efdd0ec..777889a70 100644 --- a/cmd/config/docs/api-conventions/config-io.md +++ b/cmd/config/docs/api-conventions/config-io.md @@ -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` diff --git a/cmd/config/docs/api-conventions/merge2.md b/cmd/config/docs/api-conventions/merge2.md index 06b19c259..91418644a 100644 --- a/cmd/config/docs/api-conventions/merge2.md +++ b/cmd/config/docs/api-conventions/merge2.md @@ -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 \ No newline at end of file + image: sidecar2:v1 diff --git a/cmd/config/docs/commands/cat.md b/cmd/config/docs/commands/cat.md index 0d91bcf95..7e572f044 100644 --- a/cmd/config/docs/commands/cat.md +++ b/cmd/config/docs/commands/cat.md @@ -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 diff --git a/cmd/config/docs/commands/grep.md b/cmd/config/docs/commands/grep.md index 755432c7a..7cc129ce8 100644 --- a/cmd/config/docs/commands/grep.md +++ b/cmd/config/docs/commands/grep.md @@ -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 \ No newline at end of file + kustomize config grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize config tree diff --git a/cmd/config/docs/commands/run-fns.md b/cmd/config/docs/commands/run-fns.md index 89f9885d1..c4b0491c2 100644 --- a/cmd/config/docs/commands/run-fns.md +++ b/cmd/config/docs/commands/run-fns.md @@ -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 diff --git a/cmd/config/docs/commands/tree.md b/cmd/config/docs/commands/tree.md index 44c746252..07cf250e7 100644 --- a/cmd/config/docs/commands/tree.md +++ b/cmd/config/docs/commands/tree.md @@ -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" \ diff --git a/cmd/config/docs/tutorials/configuration-basics.md b/cmd/config/docs/tutorials/configuration-basics.md index f89ecad5a..55e20fb14 100644 --- a/cmd/config/docs/tutorials/configuration-basics.md +++ b/cmd/config/docs/tutorials/configuration-basics.md @@ -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 diff --git a/cmd/config/docs/tutorials/function-basics.md b/cmd/config/docs/tutorials/function-basics.md index 6a9ff6adc..63702e97a 100644 --- a/cmd/config/docs/tutorials/function-basics.md +++ b/cmd/config/docs/tutorials/function-basics.md @@ -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. \ No newline at end of file +and then the second function in the file is applied. diff --git a/functions/examples/injection-tshirt-sizes/README.md b/functions/examples/injection-tshirt-sizes/README.md index b710765c2..97625fab1 100644 --- a/functions/examples/injection-tshirt-sizes/README.md +++ b/functions/examples/injection-tshirt-sizes/README.md @@ -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. \ No newline at end of file +Observe that the reservations have changed. diff --git a/functions/examples/template-go-nginx/README.md b/functions/examples/template-go-nginx/README.md index b6a515d58..ad6bc133d 100644 --- a/functions/examples/template-go-nginx/README.md +++ b/functions/examples/template-go-nginx/README.md @@ -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. \ No newline at end of file + +The replica count should be updated, but your annotation should remain. diff --git a/functions/examples/template-heredoc-cockroachdb/README.md b/functions/examples/template-heredoc-cockroachdb/README.md index ec8c0a1b3..90c39cfc8 100644 --- a/functions/examples/template-heredoc-cockroachdb/README.md +++ b/functions/examples/template-heredoc-cockroachdb/README.md @@ -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. \ No newline at end of file + +The replica count should be updated, but your annotation should remain. diff --git a/functions/examples/validator-resource-requests/README.md b/functions/examples/validator-resource-requests/README.md index 8ba7bdf2c..7f30f21a6 100644 --- a/functions/examples/validator-resource-requests/README.md +++ b/functions/examples/validator-resource-requests/README.md @@ -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 \ No newline at end of file + +This will return success