Refactor kustomize config command structure

- Create cfg, fn, live parent commands
This commit is contained in:
Phillip Wittrock
2020-06-03 13:17:30 -07:00
committed by Phillip Wittrock
parent 73157c7141
commit 701c217791
68 changed files with 669 additions and 3846 deletions

View File

@@ -12,11 +12,11 @@ var AnnotateLong = `
Path to local directory.
`
var AnnotateExamples = `
kustomize config annotate my-dir/ --kv foo=bar
kustomize cfg annotate my-dir/ --kv foo=bar
kustomize config annotate my-dir/ --kv foo=bar --kv a=b
kustomize cfg annotate my-dir/ --kv foo=bar --kv a=b
kustomize config annotate my-dir/ --kv foo=bar --kind Deployment --name foo`
kustomize cfg annotate my-dir/ --kv foo=bar --kind Deployment --name foo`
var CatShort = `[Alpha] Print Resource Config from a local directory.`
var CatLong = `
@@ -27,13 +27,13 @@ var CatLong = `
`
var CatExamples = `
# print Resource config from a directory
kustomize config cat my-dir/
kustomize cfg 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
kustomize cfg 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`
... | kustomize cfg cat`
var CompletionShort = `Install shell completion.`
var CompletionLong = `
@@ -61,7 +61,7 @@ var CountLong = `
`
var CountExamples = `
# print Resource counts from a directory
kustomize config count my-dir/`
kustomize cfg count my-dir/`
var CreateSetterShort = `[Alpha] Create a custom setter for a Resource field`
var CreateSetterLong = `
@@ -81,12 +81,12 @@ Create a custom setter for a Resource field by inlining OpenAPI as comments.
`
var CreateSetterExamples = `
# create a setter for port fields matching "8080"
kustomize config create-setter DIR/ port 8080 --type "integer" --field port \
kustomize cfg create-setter DIR/ port 8080 --type "integer" --field port \
--description "default port used by the app"
# create a setter for a substring of a field rather than the full field -- e.g. only the
# image tag, not the full image
kustomize config create-setter DIR/ image-tag v1.0.1 --type "string" \
kustomize cfg create-setter DIR/ image-tag v1.0.1 --type "string" \
--field image --description "current stable release"`
var FmtShort = `[Alpha] Format yaml configuration files.`
@@ -118,16 +118,16 @@ field paths.
`
var FmtExamples = `
# format file1.yaml and file2.yml
kustomize config fmt file1.yaml file2.yml
kustomize cfg fmt file1.yaml file2.yml
# format all *.yaml and *.yml recursively traversing directories
kustomize config fmt my-dir/
kustomize cfg fmt my-dir/
# format kubectl output
kubectl get -o yaml deployments | kustomize config fmt
kubectl get -o yaml deployments | kustomize cfg fmt
# format kustomize output
kustomize build | kustomize config fmt`
kustomize build | kustomize cfg fmt`
var GrepShort = `[Alpha] Search for matching Resources in a directory or from stdin`
var GrepLong = `
@@ -145,16 +145,16 @@ var GrepLong = `
`
var GrepExamples = `
# find Deployment Resources
kustomize config grep "kind=Deployment" my-dir/
kustomize cfg grep "kind=Deployment" my-dir/
# find Resources named nginx
kustomize config grep "metadata.name=nginx" my-dir/
kustomize cfg grep "metadata.name=nginx" my-dir/
# use tree to display matching Resources
kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree
kustomize cfg grep "metadata.name=nginx" my-dir/ | kustomize cfg 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 cfg grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize cfg tree`
var InitShort = `[Alpha] Initialize a directory with a Krmfile.`
var InitLong = `
@@ -165,10 +165,10 @@ var InitLong = `
`
var InitExamples = `
# create a Krmfile in the local directory
kustomize config init
kustomize cfg init
# create a Krmfile in my-dir/
kustomize config init my-dir/`
kustomize cfg init my-dir/`
var ListSettersShort = `[Alpha] List setters for Resources.`
var ListSettersLong = `
@@ -185,7 +185,7 @@ List setters for Resources.
var ListSettersExamples = `
Show setters:
$ config list-setters DIR/
$ kustomize cfg list-setters DIR/
NAME DESCRIPTION VALUE TYPE COUNT SETBY
name-prefix '' PREFIX string 2`
@@ -204,10 +204,10 @@ earlier are lower-precedence (the destination).
For information on merge rules, run:
kustomize config docs merge
kustomize cfg docs merge
`
var MergeExamples = `
cat resources_and_patches.yaml | kustomize config merge > merged_resources.yaml`
cat resources_and_patches.yaml | kustomize cfg merge > merged_resources.yaml`
var Merge3Short = `[Alpha] Merge diff of Resource configuration files into a destination (3-way)`
var Merge3Long = `
@@ -223,10 +223,10 @@ to the Resource in the DEST_DIR.
For information on merge rules, run:
kustomize config docs-merge3
kustomize cfg docs-merge3
`
var Merge3Examples = `
kustomize config merge3 --ancestor a/ --from b/ --to c/`
kustomize cfg merge3 --ancestor a/ --from b/ --to c/`
var RunFnsShort = `[Alpha] Reoncile config functions to Resources.`
var RunFnsLong = `
@@ -266,16 +266,16 @@ order they appear in the file).
spec:
configField: configValue
In the preceding example, 'kustomize config run example/' would identify the function by
In the preceding example, 'kustomize fn run example/' would identify the function by
the metadata.annotations.[config.kubernetes.io/function] field. It would then write all Resources in the directory to
a container stdin (running the gcr.io/example/examplefunction:v1.0.1 image). It
would then write the container stdout back to example/, replacing the directory
file contents.
See ` + "`" + `kustomize help config docs-fn` + "`" + ` for more details on writing functions.
See ` + "`" + `kustomize help cfg docs-fn` + "`" + ` for more details on writing functions.
`
var RunFnsExamples = `
kustomize config run example/`
kustomize fn run example/`
var SetShort = `[Alpha] Set values on Resources fields values.`
var SetLong = `
@@ -304,7 +304,7 @@ the configuration as comments.
To print the possible setters for the Resources in a directory, run
` + "`" + `list-setters` + "`" + ` on a directory -- e.g. ` + "`" + `kustomize config list-setters DIR/` + "`" + `.
` + "`" + `list-setters` + "`" + ` on a directory -- e.g. ` + "`" + `kustomize cfg list-setters DIR/` + "`" + `.
#### Tips
@@ -314,7 +314,7 @@ To print the possible setters for the Resources in a directory, run
The description and setBy fields are left unmodified unless specified with flags.
To create a custom setter for a field see: ` + "`" + `kustomize help config create-setter` + "`" + `
To create a custom setter for a field see: ` + "`" + `kustomize help cfg create-setter` + "`" + `
`
var SetExamples = `
Resource YAML: Name Prefix Setter
@@ -322,12 +322,12 @@ var SetExamples = `
# DIR/resources.yaml
...
metadata:
name: PREFIX-app1 # {"type":"string","x-kustomize":{"partialFieldSetters":[{"name":"name-prefix","value":"PREFIX"}]}}
name: PREFIX-app1 # {"type":"string","x-kustomize":{"setter":[{"name":"name-prefix","value":"PREFIX"}]}}
...
---
...
metadata:
name: PREFIX-app2 # {"type":"string","x-kustomize":{"partialFieldSetters":[{"name":"name-prefix","value":"PREFIX"}]}}
name: PREFIX-app2 # {"type":"string","x-kustomize":{"setter":[{"name":"name-prefix","value":"PREFIX"}]}}
...
List setters: Show the possible setters
@@ -338,7 +338,7 @@ var SetExamples = `
Perform set: set a new value, owner and description
$ kustomize config set DIR/ name-prefix "test" --description "test environment" --set-by "dev"
$ kustomize cfg set DIR/ name-prefix "test" --description "test environment" --set-by "dev"
set 2 values
List setters: Show the new values
@@ -352,19 +352,19 @@ var SetExamples = `
# DIR/resources.yaml
...
metadata:
name: test-app1 # {"description":"test environment","type":"string","x-kustomize":{"setBy":"dev","partialFieldSetters":[{"name":"name-prefix","value":"test"}]}}
name: test-app1 # {"description":"test environment","type":"string","x-kustomize":{"setBy":"dev","setter":[{"name":"name-prefix","value":"test"}]}}
...
---
...
metadata:
name: test-app2 # {"description":"test environment","type":"string","x-kustomize":{"setBy":"dev","partialFieldSetters":[{"name":"name-prefix","value":"test"}]}}
name: test-app2 # {"description":"test environment","type":"string","x-kustomize":{"setBy":"dev","setter":[{"name":"name-prefix","value":"test"}]}}
...`
var SinkShort = `[Alpha] Implement a Sink by writing input to a local directory.`
var SinkLong = `
[Alpha] Implement a Sink by writing input to a local directory.
kustomize config sink [DIR]
kustomize fn sink [DIR]
DIR:
Path to local directory. If unspecified, sink will write to stdout as if it were a single file.
@@ -372,13 +372,13 @@ var SinkLong = `
` + "`" + `sink` + "`" + ` writes its input to a directory
`
var SinkExamples = `
kustomize config source DIR/ | your-function | kustomize config sink DIR/`
kustomize fn source DIR/ | your-function | kustomize fn sink DIR/`
var SourceShort = `[Alpha] Implement a Source by reading a local directory.`
var SourceLong = `
[Alpha] Implement a Source by reading a local directory.
kustomize config source DIR...
kustomize fn source DIR...
DIR:
One or more paths to local directories. Contents from directories will be concatenated.
@@ -388,15 +388,15 @@ var SourceLong = `
`
var SourceExamples = `
# emity configuration directory as input source to a function
kustomize config source DIR/
kustomize fn source DIR/
kustomize config source DIR/ | your-function | kustomize config sink DIR/`
kustomize fn source DIR/ | your-function | kustomize fn sink DIR/`
var TreeShort = `[Alpha] Display Resource structure from a directory or stdin.`
var TreeLong = `
[Alpha] Display Resource structure from a directory or stdin.
kustomize config tree may be used to print Resources in a directory or cluster, preserving structure
kustomize cfg tree may be used to print Resources in a directory or cluster, preserving structure
Args:
@@ -405,37 +405,37 @@ Args:
Resource fields may be printed as part of the Resources by specifying the fields as flags.
kustomize config tree has build-in support for printing common fields, such as replicas, container images,
kustomize cfg tree has build-in support for printing common fields, such as replicas, container images,
container names, etc.
kustomize config tree supports printing arbitrary fields using the '--field' flag.
kustomize cfg tree supports printing arbitrary fields using the '--field' flag.
By default, kustomize config tree uses Resource graph structure if any relationships between resources (ownerReferences)
By default, kustomize cfg tree uses Resource graph structure if any relationships between resources (ownerReferences)
are detected, as is typically the case when printing from a cluster. Otherwise, directory graph structure is used. The
graph structure can also be selected explicitly using the '--graph-structure' flag.
`
var TreeExamples = `
# print Resources using directory structure
kustomize config tree my-dir/
kustomize cfg tree my-dir/
# print replicas, container name, and container image and fields for Resources
kustomize config tree my-dir --replicas --image --name
kustomize cfg tree my-dir --replicas --image --name
# print all common Resource fields
kustomize config tree my-dir/ --all
kustomize cfg tree my-dir/ --all
# print the "foo"" annotation
kustomize config tree my-dir/ --field "metadata.annotations.foo"
kustomize cfg tree my-dir/ --field "metadata.annotations.foo"
# print the "foo"" annotation
kubectl get all -o yaml | kustomize config tree \
kubectl get all -o yaml | kustomize cfg tree \
--field="status.conditions[type=Completed].status"
# print live Resources from a cluster using owners for graph structure
kubectl get all -o yaml | kustomize config tree --replicas --name --image
kubectl get all -o yaml | kustomize cfg tree --replicas --name --image
# print live Resources with status condition fields
kubectl get all -o yaml | kustomize config tree \
kubectl get all -o yaml | kustomize cfg tree \
--name --image --replicas \
--field="status.conditions[type=Completed].status" \
--field="status.conditions[type=Complete].status" \

View File

@@ -6,7 +6,7 @@ package tutorials
var ConfigurationBasicsShort = `### Synopsis`
var ConfigurationBasicsLong = `
` + "`" + `kustomize config` + "`" + ` provides tools for working with local configuration directories.
` + "`" + `kustomize cfg` + "`" + ` provides tools for working with local configuration directories.
First fetch a bundle of configuration to your local file system from the
Kubernetes examples repository.
@@ -18,7 +18,7 @@ var ConfigurationBasicsLong = `
` + "`" + `tree` + "`" + ` can be used to summarize the collection of Resources in a directory:
$ kustomize config tree mysql-wordpress-pd/
$ kustomize cfg tree mysql-wordpress-pd/
mysql-wordpress-pd
├── [gce-volumes.yaml] v1.PersistentVolume wordpress-pv-1
├── [gce-volumes.yaml] v1.PersistentVolume wordpress-pv-2
@@ -35,7 +35,7 @@ var ConfigurationBasicsLong = `
supported fields, and may also print arbitrary values using the ` + "`" + `--field` + "`" + ` flag to specify a field
path.
$ kustomize config tree mysql-wordpress-pd/ --name --image --replicas --ports
$ kustomize cfg tree mysql-wordpress-pd/ --name --image --replicas --ports
mysql-wordpress-pd
├── [gce-volumes.yaml] PersistentVolume wordpress-pv-1
├── [gce-volumes.yaml] PersistentVolume wordpress-pv-2
@@ -64,7 +64,7 @@ var ConfigurationBasicsLong = `
to build the tree structure.
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 cfg tree --graph-structure owners --name --image --replicas
.
├── [Resource] Deployment wp/wordpress
│   ├── spec.replicas: 1
@@ -88,7 +88,7 @@ var ConfigurationBasicsLong = `
### ` + "`" + `cat` + "`" + ` -- view the full collection of Resources
$ kustomize config cat mysql-wordpress-pd/
$ kustomize cfg cat mysql-wordpress-pd/
apiVersion: v1
kind: PersistentVolume
metadata:
@@ -115,7 +115,7 @@ var ConfigurationBasicsLong = `
` + "`" + `fmt` + "`" + ` formats the Resource Configuration by applying a consistent style, including
ordering of fields and indentation.
$ kustomize config fmt mysql-wordpress-pd/
$ kustomize cfg fmt mysql-wordpress-pd/
Run ` + "`" + `git diff` + "`" + ` and see the changes that have been applied.
@@ -124,7 +124,7 @@ var ConfigurationBasicsLong = `
` + "`" + `grep` + "`" + ` prints Resources matching some field value. The Resources are annotated with their
file source so they can be piped to other commands without losing this information.
$ kustomize config grep "metadata.name=wordpress" wordpress/
$ kustomize cfg grep "metadata.name=wordpress" wordpress/
apiVersion: v1
kind: Service
metadata:
@@ -146,7 +146,7 @@ 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/
$ kustomize cfg 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
kind: Deployment
metadata:
@@ -167,7 +167,7 @@ var ConfigurationBasicsLong = `
` + "`" + `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 cfg grep "spec.replicas>0" | kustomize cfg tree --replicas
.
└──
├── [.] Deployment wp/wordpress
@@ -183,7 +183,7 @@ var ConfigurationBasicsLong = `
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 cfg grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ | kustomize cfg tree --name --resources
Error: staging/persistent-volume-provisioning/quobyte/quobyte-admin-secret.yaml: [0]: yaml: unmarshal errors:
line 13: mapping key "type" already defined at line 9
@@ -196,7 +196,7 @@ var ConfigurationBasicsLong = `
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
$ kustomize cfg 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)
go/src/sigs.k8s.io/kustomize/kyaml/kio/byteio_reader.go:130 (0x4d3e099)
@@ -210,7 +210,7 @@ var ConfigurationBasicsLong = `
Query for ` + "`" + `replicas` + "`" + `:
$ kustomize config grep "spec.replicas>5" ./ | kustomize config tree --replicas
$ kustomize cfg grep "spec.replicas>5" ./ | kustomize cfg tree --replicas
.
├── staging/sysdig-cloud
│   └── [sysdig-rc.yaml] ReplicationController sysdig-agent
@@ -221,7 +221,7 @@ var ConfigurationBasicsLong = `
Query for ` + "`" + `resource.limits` + "`" + `
$ kustomize config grep "spec.template.spec.containers[name=\.*].resources.limits.memory>0" ./ | kustomize config tree --resources
$ kustomize cfg grep "spec.template.spec.containers[name=\.*].resources.limits.memory>0" ./ | kustomize cfg tree --resources
.
├── cassandra
│   └── [cassandra-statefulset.yaml] StatefulSet cassandra
@@ -250,7 +250,7 @@ var ConfigurationBasicsLong = `
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 cfg grep "spec.template.spec.containers[name=\.*].name=\.*" ./ | kustomize cfg grep "spec.template.spec.containers[name=\.*].image=\.*:\.*" -v | kustomize cfg tree --image --name
.
├── staging/newrelic
│   ├── [newrelic-daemonset.yaml] DaemonSet newrelic-agent
@@ -302,13 +302,13 @@ var FunctionBasicsLong = `
cd template-heredoc-cockroachdb/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
kustomize cfg tree local-resource/ --name --image --replicas
# run the function
kustomize config run local-resource/
kustomize fn run local-resource/
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
kustomize cfg tree local-resource/ --name --image --replicas
` + "`" + `run` + "`" + ` generated the directory ` + "`" + ` local-resource/config` + "`" + ` containing the generated
Resources.
@@ -322,7 +322,7 @@ var FunctionBasicsLong = `
but keep the fields that you manually added to the generated Resource configuration.
# run the function
kustomize config run local-resource/
kustomize fn 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
@@ -347,13 +347,13 @@ var FunctionBasicsLong = `
cd template-go-nginx/
# view the Resources
kustomize config tree local-resource/ --name --image --replicas
kustomize cfg tree local-resource/ --name --image --replicas
# run the function
kustomize config run local-resource/
kustomize fn run local-resource/
# view the generated Resources
kustomize config tree local-resource/ --name --image --replicas
kustomize cfg 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
@@ -369,7 +369,7 @@ var FunctionBasicsLong = `
but keep the fields that you manually added to the generated Resource configuration.
# run the function
kustomize config run local-resource/
kustomize fn 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.
@@ -389,7 +389,7 @@ var FunctionBasicsLong = `
directory, and invoke ` + "`" + `run` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
# run the function
kustomize config run local-resource/
kustomize fn run local-resource/
cpu-requests missing for a container in Deployment nginx (example-use.yaml [1])
Error: exit status 1
Usage:
@@ -401,7 +401,7 @@ var FunctionBasicsLong = `
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/
kustomize fn run local-resource/
The validation now passes.
@@ -416,7 +416,7 @@ var FunctionBasicsLong = `
directory, and invoke ` + "`" + `run` + "`" + ` on the ` + "`" + `local-resource/` + "`" + ` directory.
# print the resources
kustomize config tree local-resource --resources --name
kustomize cfg tree local-resource --resources --name
local-resource
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
@@ -425,10 +425,10 @@ var FunctionBasicsLong = `
└── name: nginx
# run the functions
kustomize config run local-resource/
kustomize fn run local-resource/
# print the new resources
kustomize config tree local-resource --resources --name
kustomize cfg tree local-resource --resources --name
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx
└── spec.template.spec.containers
@@ -440,8 +440,8 @@ var FunctionBasicsLong = `
Change the ` + "`" + `tshirt-size` + "`" + ` annotation from ` + "`" + `medium` + "`" + ` to ` + "`" + `small` + "`" + ` and re-run the functions.
kustomize config run local-resource/
kustomize config tree local-resource/
kustomize fn run local-resource/
kustomize cfg tree local-resource/
local-resource
├── [example-use.yaml] Validator
└── [example-use.yaml] Deployment nginx