## File: README.md # kustomize `kustomize` lets you customize raw, template-free YAML files for multiple purposes, leaving the original YAML untouched and usable as is. `kustomize` targets kubernetes; it understands and can patch [kubernetes style] API objects. It's like [`make`], in that what it does is declared in a file, and it's like [`sed`], in that it emits edited text. This tool is sponsored by [sig-cli] ([KEP]). - [Installation instructions](https://kubectl.docs.kubernetes.io/installation/kustomize/) - [General documentation](https://kubectl.docs.kubernetes.io/references/kustomize/) - [Examples](examples) [](https://prow.k8s.io/job-history/kubernetes-jenkins/pr-logs/directory/kustomize-presubmit-master) [](https://goreportcard.com/report/github.com/kubernetes-sigs/kustomize) ## kubectl integration To find the kustomize version embedded in recent versions of kubectl, run `kubectl version`: ```sh > kubectl version --client Client Version: v1.31.0 Kustomize Version: v5.4.2 ``` The kustomize build flow at [v2.0.3] was added to [kubectl v1.14][kubectl announcement]. The kustomize flow in kubectl remained frozen at v2.0.3 until kubectl v1.21, which [updated it to v4.0.5][kust-in-kubectl update]. It will be updated on a regular basis going forward, and such updates will be reflected in the Kubernetes release notes. | Kubectl version | Kustomize version | | --------------- | ----------------- | | < v1.14 | n/a | | v1.14-v1.20 | v2.0.3 | | v1.21 | v4.0.5 | | v1.22 | v4.2.0 | | v1.23 | v4.4.1 | | v1.24 | v4.5.4 | | v1.25 | v4.5.7 | | v1.26 | v4.5.7 | | v1.27 | v5.0.1 | [v2.0.3]: https://github.com/kubernetes-sigs/kustomize/releases/tag/v2.0.3 [#2506]: https://github.com/kubernetes-sigs/kustomize/issues/2506 [#1500]: https://github.com/kubernetes-sigs/kustomize/issues/1500 [kust-in-kubectl update]: https://github.com/kubernetes/kubernetes/blob/4d75a6238a6e330337526e0513e67d02b1940b63/CHANGELOG/CHANGELOG-1.21.md#kustomize-updates-in-kubectl For examples and guides for using the kubectl integration please see the [kubernetes documentation]. ## Usage ### 1) Make a [kustomization] file In some directory containing your YAML [resource] files (deployments, services, configmaps, etc.), create a [kustomization] file. This file should declare those resources, and any customization to apply to them, e.g. _add a common label_. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` File structure: > ``` > ~/someApp > ├── deployment.yaml > ├── kustomization.yaml > └── service.yaml > ``` The resources in this directory could be a fork of someone else's configuration. If so, you can easily rebase from the source material to capture improvements, because you don't modify the resources directly. Generate customized YAML with: ``` kustomize build ~/someApp ``` The YAML can be directly [applied] to a cluster: > ``` > kustomize build ~/someApp | kubectl apply -f - > ``` ### 2) Create [variants] using [overlays] Manage traditional [variants] of a configuration - like _development_, _staging_ and _production_ - using [overlays] that modify a common [base]. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` File structure: > ``` > ~/someApp > ├── base > │ ├── deployment.yaml > │ ├── kustomization.yaml > │ └── service.yaml > └── overlays > ├── development > │ ├── cpu_count.yaml > │ ├── kustomization.yaml > │ └── replica_count.yaml > └── production > ├── cpu_count.yaml > ├── kustomization.yaml > └── replica_count.yaml > ``` Take the work from step (1) above, move it into a `someApp` subdirectory called `base`, then place overlays in a sibling directory. An overlay is just another kustomization, referring to the base, and referring to patches to apply to that base. This arrangement makes it easy to manage your configuration with `git`. The base could have files from an upstream repository managed by someone else. The overlays could be in a repository you own. Arranging the repo clones as siblings on disk avoids the need for git submodules (though that works fine, if you are a submodule fan). Generate YAML with ```sh kustomize build ~/someApp/overlays/production ``` The YAML can be directly [applied] to a cluster: > ```sh > kustomize build ~/someApp/overlays/production | kubectl apply -f - > ``` ## Community - [file a bug](https://kubectl.docs.kubernetes.io/contributing/kustomize/bugs/) - [contribute a feature](https://kubectl.docs.kubernetes.io/contributing/kustomize/features/) - [propose a larger enhancement](https://github.com/kubernetes-sigs/kustomize/tree/master/proposals) ### Code of conduct Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct]. [`make`]: https://www.gnu.org/software/make [`sed`]: https://www.gnu.org/software/sed [DAM]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#declarative-application-management [KEP]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/2377-Kustomize/README.md [Kubernetes Code of Conduct]: code-of-conduct.md [applied]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#apply [base]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#base [declarative configuration]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#declarative-application-management [kubectl announcement]: https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement [kubernetes documentation]: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/ [kubernetes style]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#kubernetes-style-object [kustomization]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#kustomization [overlay]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#overlay [overlays]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#overlay [release page]: https://github.com/kubernetes-sigs/kustomize/releases [resource]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#resource [resources]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#resource [sig-cli]: https://github.com/kubernetes/community/blob/master/sig-cli/README.md [variants]: https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#variant --- ## File: cmd/gorepomod/README.md # gorepomod Helps when you have a git repository with multiple Go modules. It handles tasks one might otherwise attempt with ``` find ./ -name "go.mod" | xargs {some hack} ``` Run it from a git repository root. It walks the repository, reads `go.mod` files, builds a model of Go modules and intra-repo module dependencies, then performs some operation. Install: ``` go get sigs.k8s.io/kustomize/cmd/gorepomod ``` ## Usage _Commands that change things (everything but `list`) do nothing but log commands unless you add the `--doIt` flag, allowing the change._ _If you want to run `gorepomod` on your fork or outside of `$GOSRC` directory, add `--local` flag to your command._ #### `gorepomod list` Lists modules and intra-repo dependencies. Use this to get module names for use in other commands. #### `gorepomod tidy` Creates a change with mechanical updates to `go.mod` and `go.sum` files. #### `gorepomod unpin {module} [{conditionalmodule}]` Creates a change to `go.mod` files. For each module _m_ in the repository, if _m_ depends on a _{module}_, then _m_'s dependency on _{module} will be replaced by a relative path to the in-repo version of _{module}_. If _conditionalModule_ is specified, then the replacement of _{module}_ will happen if _m_ depends on _{conditionalModule}_. #### `gorepomod pin {module} [{version}]` Creates a change to `go.mod` files. The opposite of `unpin`. The change removes replacements and pins _m_ to a specific, previously tagged and released version of _{module}_. The argument _{version}_ defaults to recent version of _{module}_. _{version}_ should be in semver form, e.g. `v1.2.3`. #### `gorepomod release {module} [patch|minor|major]` Computes a new version for the module, tags the repo with that version, and pushes the tag to the remote. The value of the 2nd argument, either `patch` (the default), `minor` or `major`, determines the new version. If the existing version is _v1.2.7_, then the new version will be: - `patch` -> _v1.2.8_ - `minor` -> _v1.3.0_ - `major` -> _v2.0.0_ After establishing the version, the command looks for a branch named > _release-{module}/-v{major}.{minor}_ If the branch doesn't exist, the command creates it and pushes it to the remote. The command then creates a new tag in the form > _{module}/v{major}.{minor}.{patch}_ The command pushes this tag to the remote. This typically triggers cloud activity to create release artifacts. #### `gorepomod unrelease {module}` This undoes the work of `release`, by deleting the most recent tag both locally and at the remote. You can then fix whatever, and re-release. This, however, must be done almost immediately. If there's a chance someone (or some cloud robot) already imported the module at the given tag, then don't do this, because it will confuse module caches. Do a new patch release instead. --- ## File: cmd/depprobcheck/README.md # Troubles with dependencies on openapi If you see the error > cannot use api.Schema.SchemaProps.Properties then you have a set of incompatible dependencies. This doc describes the problem and a fix. tl;dr A mix of old and new is bad. Anyone depending on k8s.io `v0.20.x` or _older_ packages must avoid depending on anything that depends on `k8s.io/kube-openapi` newer than v0.0.0-20210323165736-1a6458611d18. > More context in https://github.com/kubernetes/cli-runtime/issues/19 This dir exists to test the problem. Edit the `main.go` and `go.mod` in this dir to see what builds with various combinations of `cli-runtime` and `kube-openapi`. #### A recent in change in kube-openapi https://github.com/kubernetes/kube-openapi/pull/234 means that anyone depending on k8s.io/cli-runtime@v0.20.4 and _any other package that imports kube-openapi_ (e.g. kyaml) may see a build error like > ~/go/pkg/mod/sigs.k8s.io/kustomize@v2.0.3+incompatible/pkg/transformers/config/factorycrd.go:71:47: > cannot use api.Schema.SchemaProps.Properties (type map[string]"k8s.io/kube-openapi/pkg/validation/spec".Schema) > as type myProperties in argument to looksLikeAk8sType ## Why? As it happens, k8s.io/cli-runtime@v0.20.4 depends on sigs.k8s.io/kustomize@v2.0.3+incompatible Line 71 of factorycrd.go in kustomize v2.0.3 is: if !looksLikeAk8sType(api.Schema.SchemaProps.Properties) { The `looksLikeAk8sType` function accepts the argument func looksLikeAk8sType(properties map[string]spec.Schema) bool {...} At the call point in line 71 the argument is common.OpenAPIDefinition.Schema.SchemaProps.Properties The file factorycrd.go depends on "github.com/go-openapi/spec" "k8s.io/kube-openapi/pkg/common" The module sigs.k8s.io/kustomize@v2.0.3 predates Go modules. To pin its dependencies, it has a Gopkg.lock file and a vendor directory. Per the lock file: sigs.k8s.io/kustomize@v2.0.3 depends on "k8s.io/kube-openapi" revision = "b3f03f55328800731ce03a164b80973014ecd455" Checking out this commit in the k8s.io/kube-openapi repo we see this k8s.io/kube-openapi/pkg/common/common.go: import "github.com/go-openapi/spec" ... type OpenAPIDefinition struct { Schema spec.Schema Dependencies []string } But per the imports in this file, `spec.Schema` lives in github.com/go-openapi/spec The aforementioned Gopkg.lock file pins that at sigs.k8s.io/kustomize@v2.0.3 depends on "github.com/go-openapi/spec" revision = "bcff419492eeeb01f76e77d2ebc714dc97b607f5" The struct is github.com/go-openapi/spec: type Schema struct { VendorExtensible SchemaProps SwaggerSchemaProps ExtraProps map[string]interface{} `json:"-"` } type SchemaProps struct { Properties map[string]Schema } This is a recursive type; Schema holds a map[string]Schema. All that is fine. The problem arises when we build a binary that depends on both kustomize v2.0.3 and, say, k8s.io/kube-openapi v0.0.0-20210421082810-95288971da7e This particular version of kube-openapi has a 'go.mod' file. kube-openapi/pkg/common/common.go at tag "95288..." contains: import "k8s.io/kube-openapi/pkg/validation/spec" ... type OpenAPIDefinition struct { Schema spec.Schema Dependencies []string } kube-openapi/pkg/validation/spec/schema.go at this tag contains: type Schema struct { VendorExtensible SchemaProps SwaggerSchemaProps ExtraProps map[string]interface{} `json:"-"` } etc. etc. as above. The same layout as above, but in different files. So adding this new dependency means that factorycrd.go is going to include a version of "k8s.io/kube-openapi/pkg/common". that deals in the type "k8s.io/kube-openapi/pkg/validation/spec".Schema but will then attempt to pass this type to older code (the func looksLikeAk8sType) which is looking to accept a "github.com/go-openapi/spec".Schema It's the same type structure, but a different name so the 'linker' barfs. To avoid this problem, one has to either * roll forward on cli-runtime -- depend on v0.21.0 or higher. * or stick with v0.20.4, which means retaining consistency with kustomize 2.0.3, which means depending on an older version of k8s.io/kube-openapi that still depends on go-openapi/spec. Fortunately you only have to go back to before PR https://github.com/kubernetes/kube-openapi/pull/234 E.g. depend on k8s.io/kube-openapi v0.0.0-20210323165736-1a6458611d18 --- ## File: cmd/config/docs/tutorials/configuration-basics.md ## Configuration Basics ### Synopsis `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. git clone https://github.com/kubernetes/examples/ cd examples/ ### `tree` -- view Resources and directory structure `tree` can be used to summarize the collection of Resources in a directory: $ 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 ├── [local-volumes.yaml] v1.PersistentVolume local-pv-1 ├── [local-volumes.yaml] v1.PersistentVolume local-pv-2 ├── [mysql-deployment.yaml] v1.PersistentVolumeClaim mysql-pv-claim ├── [mysql-deployment.yaml] apps/v1.Deployment wordpress-mysql ├── [mysql-deployment.yaml] v1.Service wordpress-mysql ├── [wordpress-deployment.yaml] apps/v1.Deployment wordpress ├── [wordpress-deployment.yaml] v1.Service wordpress └── [wordpress-deployment.yaml] v1.PersistentVolumeClaim wp-pv-claim `tree` may be provided flags to print the Resource field values. `tree` has a number of built-in supported fields, and may also print arbitrary values using the `--field` flag to specify a field path. $ 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 ├── [local-volumes.yaml] PersistentVolume local-pv-1 ├── [local-volumes.yaml] PersistentVolume local-pv-2 ├── [mysql-deployment.yaml] PersistentVolumeClaim mysql-pv-claim ├── [mysql-deployment.yaml] Deployment wordpress-mysql │   └── spec.template.spec.containers │   └── 0 │   ├── name: mysql │   ├── image: mysql:5.6 │   └── ports: [{name: mysql, containerPort: 3306}] ├── [mysql-deployment.yaml] Service wordpress-mysql │   └── spec.ports: [{port: 3306}] ├── [wordpress-deployment.yaml] Deployment wordpress │   └── spec.template.spec.containers │   └── 0 │   ├── name: wordpress │   ├── image: wordpress:4.8-apache │   └── ports: [{name: wordpress, containerPort: 80}] ├── [wordpress-deployment.yaml] Service wordpress │   └── spec.ports: [{port: 80}] └── [wordpress-deployment.yaml] PersistentVolumeClaim wp-pv-claim `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 cfg tree --graph-structure owners --name --image --replicas . ├── [Resource] Deployment wp/wordpress │   ├── spec.replicas: 1 │   ├── spec.template.spec.containers │   │   └── 0 │   │   ├── name: wordpress │   │   └── image: wordpress:4.8-apache │   └── [Resource] ReplicaSet wp/wordpress-76b5d9f5c8 │   ├── spec.replicas: 1 │   ├── spec.template.spec.containers │   │   └── 0 │   │   ├── name: wordpress │   │   └── image: wordpress:4.8-apache │   └── [Resource] Pod wp/wordpress-76b5d9f5c8-g656w │   └── spec.containers │   └── 0 │   ├── name: wordpress │   └── image: wordpress:4.8-apache ├── [Resource] Service wp/wordpress ... ### `cat` -- view the full collection of Resources $ kustomize cfg cat mysql-wordpress-pd/ apiVersion: v1 kind: PersistentVolume metadata: name: wordpress-pv-1 annotations: config.kubernetes.io/path: gce-volumes.yaml spec: accessModes: - ReadWriteOnce capacity: storage: 20Gi gcePersistentDisk: fsType: ext4 pdName: wordpress-1 --- apiVersion: v1 ... `cat` prints the raw package Resources. This may be used to pipe them to other tools such as `kubectl apply -f -`. ## `fmt` -- format the Resources for a directory (like go fmt for Kubernetes Resources) `fmt` formats the Resource Configuration by applying a consistent style, including ordering of fields and indentation. $ kustomize cfg fmt mysql-wordpress-pd/ Run `git diff` and see the changes that have been applied. ### `grep` -- search for Resources by field values `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 cfg grep "metadata.name=wordpress" wordpress/ apiVersion: v1 kind: Service metadata: name: wordpress labels: app: wordpress annotations: config.kubernetes.io/path: wordpress-deployment.yaml spec: ports: - port: 80 selector: app: wordpress tier: frontend type: LoadBalancer --- ... - 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 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: name: wordpress-mysql labels: app: wordpress spec: selector: matchLabels: app: wordpress tier: mysql template: metadata: labels: app: wordpress tier: mysql ... `grep` may be used with kubectl to search for Resources in a cluster matching a value. kubectl get all -o yaml | kustomize cfg grep "spec.replicas>0" | kustomize cfg tree --replicas . └── ├── [.] Deployment wp/wordpress │   └── spec.replicas: 1 ├── [.] ReplicaSet wp/wordpress-76b5d9f5c8 │   └── spec.replicas: 1 ├── [.] Deployment wp/wordpress-mysql │   └── spec.replicas: 1 └── [.] ReplicaSet wp/wordpress-mysql-f9447f458 └── spec.replicas: 1 ### Error handling If there is an error parsing the Resource configuration, kustomize will print an error with the file. $ 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 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 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) (*ByteReader).Read: meta, err := node.GetMeta() ... ### Combine `grep` and `tree` `grep` and `tree` may be combined to perform queries against configuration. Query for `replicas`: $ kustomize cfg grep "spec.replicas>5" ./ | kustomize cfg tree --replicas . ├── staging/sysdig-cloud │   └── [sysdig-rc.yaml] ReplicationController sysdig-agent │   └── spec.replicas: 100 └── staging/volumes/vsphere └── [simple-statefulset.yaml] StatefulSet web └── spec.replicas: 14 Query for `resource.limits` $ kustomize cfg grep "spec.template.spec.containers[name=\.*].resources.limits.memory>0" ./ | kustomize cfg tree --resources . ├── cassandra │   └── [cassandra-statefulset.yaml] StatefulSet cassandra │   └── spec.template.spec.containers │   └── 0 │   └── resources: {limits: {cpu: "500m", memory: 1Gi}, requests: {cpu: "500m", memory: 1Gi}} ├── staging/selenium │   ├── [selenium-hub-deployment.yaml] Deployment selenium-hub │   │   └── spec.template.spec.containers │   │   └── 0 │   │   └── resources: {limits: {memory: 1000Mi, cpu: ".5"}} │   ├── [selenium-node-chrome-deployment.yaml] Deployment selenium-node-chrome │   │   └── spec.template.spec.containers │   │   └── 0 │   │   └── resources: {limits: {memory: 1000Mi, cpu: ".5"}} │   └── [selenium-node-firefox-deployment.yaml] Deployment selenium-node-firefox │   └── spec.template.spec.containers │   └── 0 │   └── resources: {limits: {memory: 1000Mi, cpu: ".5"}} ... ### Inverting `grep` 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 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 │   │   └── spec.template.spec.containers │   │   └── 0 │   │   ├── name: newrelic │   │   └── image: newrelic/nrsysmond │   └── staging/newrelic-infrastructure │   └── [newrelic-infra-daemonset.yaml] DaemonSet newrelic-infra-agent │   └── spec.template.spec.containers │   └── 0 │   ├── name: newrelic │   └── image: newrelic/infrastructure ├── staging/nodesjs-mongodb │   ├── [mongo-controller.yaml] ReplicationController mongo-controller │   │   └── spec.template.spec.containers │   │   └── 0 │   │   ├── name: mongo │   │   └── image: mongo │   └── [web-controller.yaml] ReplicationController web-controller │   └── spec.template.spec.containers │   └── 0 │   ├── name: web │   └── image: ... --- ## File: cmd/config/docs/tutorials/function-basics.md ## Function Basics ### Synopsis `kustomize fn` enables encapsulating function for manipulating Resource configuration inside containers, which are run using `run`. First fetch the kustomize repository, which contains a collection of example functions git clone https://github.com/kubernetes-sigs/kustomize cd kustomize/functions/examples/ ### Templating -- CockroachDB This section demonstrates how to leverage templating based solutions from `kustomize fn`. The templating function is implemented as a `bash` script using a `heredoc`. #### 1: Generate the Resources `cd` into the `kustomize/functions/examples/template-heredoc-cockroachdb/` directory, and invoke `run` on the `local-resource/` directory. cd template-heredoc-cockroachdb/ # view the Resources kustomize cfg tree local-resource/ --name --image --replicas # run the function kustomize fn run local-resource/ # view the generated Resources kustomize cfg 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-resource/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 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 composition with other functions which may appy validation or injection of values. #### 3. Function Implementation the function implementation is located under the `image/` directory as a `Dockerfile` and a `bash` script. ### Templating -- Nginx The steps in this section are identical to the CockroachDB templating example, but the function implementation is very different, and implemented as a `go` program rather than a `bash` script. #### 1: Generate the Resources `cd` into the `kustomize/functions/examples/template-go-nginx/` directory, and invoke `run` on the `local-resource/` directory. cd template-go-nginx/ # view the Resources kustomize cfg tree local-resource/ --name --image --replicas # run the function kustomize fn run local-resource/ # view the generated Resources 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 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-resource/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 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. #### 3. Function Implementation the function implementation is located under the `image/` directory as a `Dockerfile` and a `go` program. ### Validation -- resource reservations This section uses `run` to perform validation rather than generate Resources. #### 1: Run the Validator `cd` into the `kustomize/functions/examples/validator-resource-requests` directory, and invoke `run` on the `local-resource/` directory. # run the function kustomize fn run local-resource/ cpu-requests missing for a container in Deployment nginx (example-use.yaml [1]) Error: exit status 1 Usage: ... #### 2: Fix the validation issue The command will fail complaining that the nginx Deployment is missing `cpu-requests`, and print the name of the file + Resource index. Edit the file and uncomment the resources, then re-run the functions. kustomize fn run local-resource/ The validation now passes. ### Injection -- resource reservations 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` directory, and invoke `run` on the `local-resource/` directory. # print the resources kustomize cfg tree local-resource --resources --name local-resource ├── [example-use.yaml] Validator └── [example-use.yaml] Deployment nginx └── spec.template.spec.containers └── 0 └── name: nginx # run the functions kustomize fn run local-resource/ # print the new resources kustomize cfg tree local-resource --resources --name ├── [example-use.yaml] Validator └── [example-use.yaml] Deployment nginx └── spec.template.spec.containers └── 0 ├── name: nginx └── resources: {requests: {cpu: 4, memory: 1GiB}} #### 2: Change the tshirt-size Change the `tshirt-size` annotation from `medium` to `small` and re-run the functions. kustomize fn run local-resource/ kustomize cfg tree local-resource/ local-resource ├── [example-use.yaml] Validator └── [example-use.yaml] Deployment nginx └── spec.template.spec.containers └── 0 ├── name: nginx └── resources: {requests: {cpu: 200m, memory: 50MiB}} The function has applied the reservations for the new tshirt-size ### Function Composition Functions may be composed together. Try putting the Injection (tshirt-size) and Validation functions together in the same .yaml file (separated by `---`). Run `run` and observe that the first function in the file is applied to the Resources, and then the second function in the file is applied. --- ## File: cmd/config/docs/commands/annotate.md ## annotate [Alpha] Set an annotation on Resources. ### Synopsis [Alpha] Set an annotation on Resources. DIR: Path to local directory. ### Examples kustomize cfg annotate my-dir/ --kv foo=bar kustomize cfg annotate my-dir/ --kv foo=bar --kv a=b kustomize cfg annotate my-dir/ --kv foo=bar --kind Deployment --name foo --- ## File: cmd/config/docs/commands/cat.md ## cat [Alpha] Print Resource Config from a local directory. ### Synopsis [Alpha] Print Resource Config from a local directory. DIR: Path to local directory. ### Examples # print Resource config from a directory kustomize cfg cat my-dir/ # wrap Resource config from a directory in an ResourceList 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 cfg cat --- ## File: cmd/config/docs/commands/completion.md ## completion Generate shell completion. ### Synopsis Generate shell completion for `kustomize` -- supports bash, zsh, fish and powershell. ### Examples # load completion for Bash source <(kustomize completion bash) # install for Bash in Linux kustomize completion bash > /etc/bash_completion.d/kustomize # install for Bash in MacOS kustomize completion bash > /usr/local/etc/bash_completion.d/kustomize # package for Bash kustomize completion bash > /usr/share/bash-completion/completions/kustomize # package for zsh kustomize completion zsh > /usr/share/zsh/site-functions/_kustomize --- ## File: cmd/config/docs/commands/count.md ## count [Alpha] Count Resources Config from a local directory. ### Synopsis [Alpha] Count Resources Config from a local directory. DIR: Path to local directory. ### Examples # print Resource counts from a directory kustomize cfg count my-dir/ --- ## File: cmd/config/docs/commands/create-setter.md ## create-setter [Alpha] Create a custom setter for a Resource field ### Synopsis Create a custom setter for a Resource field by inlining OpenAPI as comments. DIR A directory containing Resource configuration. NAME The name of the setter to create. VALUE The current value of the field, or a substring within the field. ### Creating a Custom Setter **Given the YAML:** # resource.yaml apiVersion: v1 kind: Service metadata: ... spec: ... ports: ... - name: http port: 8080 ... **Create a new setter:** # create a setter for ports $ kustomize cfg set create DIR/ http-port 8080 --type "integer" --field "port" Resources fields with a field name matching `--field` and field value matching `VALUE` will have a line comment added marking this field as settable. **Newly modified YAML:** # resource.yaml apiVersion: v1 kind: Service metadata: ... spec: ... ports: ... - name: http port: 8080 # {"type":"integer","x-kustomize":{"partialFieldSetters":[{"name":"http-port","value":"8080"}]}} ... Setters may also be defined directly by editing the yaml and adding the comment. Users may not set the field value using the `set` command: # change the http-port value to 8081 $ kustomize cfg set DIR/ http-port 8081 ### Using default values The default values for a setter may be: - valid field values (e.g. `8080` or `008080` for a port) - invalid values that adhere to the schema (e.g. `0000` for a port) - values that do not adhere to the schema (e.g. `[PORT]` for port) A setter may be for a substring of a full field: $ kustomize cfg set create DIR/ image-tag v1.0.01 --type "string" --field "image" image: gcr.io/example/app:v1.0.1 # # {"type":"string","x-kustomize":{"partialFieldSetters":[{"name":"image-tag","value":"v1.0.1"}]}} A single field value may have multiple setters applied to it for different parts of the field. ### Examples # create a setter for port fields matching "8080" 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 cfg create-setter DIR/ image-tag v1.0.1 --type "string" \ --field image --description "current stable release"