kustomize Documentation

File: README.md Copy Chapter

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
• General documentation
• Examples

kubectl integration Copy Chapter

To find the kustomize version embedded in recent versions of kubectl, run kubectl version:

> 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. The kustomize
flow in kubectl remained frozen at v2.0.3 until kubectl v1.21,
which updated it to v4.0.5. It will
be updated on a regular basis going forward, and such updates
will be reflected in the Kubernetes release notes.

For examples and guides for using the kubectl integration please
see the kubernetes documentation.

Usage Copy Chapter

1) Make a [kustomization] file Copy Section

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:

text Copy

~/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:

text Copy

kustomize build ~/someApp | kubectl apply -f -

2) Create [variants] using [overlays] Copy Section

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:

text Copy

~/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

kustomize build ~/someApp/overlays/production

The YAML can be directly applied to a cluster:

sh Copy

kustomize build ~/someApp/overlays/production | kubectl apply -f -

Community Copy Chapter

• file a bug
• contribute a feature
• propose a larger enhancement

Code of conduct Copy Section

Participation in the Kubernetes community
is governed by the Kubernetes Code of Conduct.

File: cmd/gorepomod/README.md Copy Chapter

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 Copy Chapter

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 Copy Chapter

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/[email protected]

and any other package that imports kube-openapi (e.g. kyaml)
may see a build error like

~/go/pkg/mod/sigs.k8s.io/[email protected]+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? Copy Chapter

As it happens,

k8s.io/[email protected]

depends on

sigs.k8s.io/[email protected]+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/[email protected] predates Go modules.

To pin its dependencies, it has a Gopkg.lock file and
a vendor directory. Per the lock file:

sigs.k8s.io/[email protected]
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/[email protected]
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 Copy Chapter

Configuration Basics Copy Chapter

Synopsis Copy Section

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 Copy Section

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 Copy Section

$ 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) Copy Chapter

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 Copy Section

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 Copy Section

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` Copy Section

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` Copy Section

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: <YOUR-CONTAINER>
...

File: cmd/config/docs/tutorials/function-basics.md Copy Chapter

Function Basics Copy Chapter

Synopsis Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Chapter

annotate Copy Chapter

[Alpha] Set an annotation on Resources.

Synopsis Copy Section

[Alpha] Set an annotation on Resources.

DIR:
Path to local directory.

Examples Copy Section

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 Copy Chapter

cat Copy Chapter

[Alpha] Print Resource Config from a local directory.

Synopsis Copy Section

[Alpha] Print Resource Config from a local directory.

DIR:
Path to local directory.

Examples Copy Section

# 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 Copy Chapter

completion Copy Chapter

Generate shell completion.

Synopsis Copy Section

Generate shell completion for kustomize -- supports bash, zsh, fish and powershell.

Examples Copy Section

# 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 Copy Chapter

count Copy Chapter

[Alpha] Count Resources Config from a local directory.

Synopsis Copy Section

[Alpha] Count Resources Config from a local directory.

DIR:
Path to local directory.

Examples Copy Section

# print Resource counts from a directory
kustomize cfg count my-dir/

File: cmd/config/docs/commands/create-setter.md Copy Chapter

create-setter Copy Chapter

[Alpha] Create a custom setter for a Resource field

Synopsis Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

# 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"