mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-30 01:46:23 +00:00
refactor cmd/config to internal
This commit is contained in:
Phillip Wittrock
484
cmd/config/internal/generateddocs/api/docs.go
Normal file
484
cmd/config/internal/generateddocs/api/docs.go
Normal file
@@ -0,0 +1,484 @@
|
||||
// Copyright 2019 The Kubernetes Authors.
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
// Code generated by "mdtogo"; DO NOT EDIT.
|
||||
package api
|
||||
|
||||
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)
|
||||
- e.g. Create a client-side *"CRD"* for generating configuration checked into git
|
||||
- Aspect Orient configuration / Injection of cross-cutting configuration
|
||||
- e.g. T-Shirt size containers by annotating Resources with ` + "`" + `small` + "`" + `, ` + "`" + `medium` + "`" + `, ` + "`" + `large` + "`" + `
|
||||
and inject the cpu and memory resources into containers accordingly.
|
||||
- e.g. Inject ` + "`" + `init` + "`" + ` and ` + "`" + `side-car` + "`" + ` containers into Resources based off of Resource
|
||||
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
|
||||
per-Resource -- e.g. ensure the ` + "`" + `Service.selector` + "`" + ` and ` + "`" + `Deployment.spec.template` + "`" + ` labels
|
||||
match.
|
||||
- MutatingWebHooks are scoped to a single Resource instance at a time.
|
||||
- Low-level tweaks to the output of high-level abstractions -- e.g. add an ` + "`" + `init container` + "`" + `
|
||||
to a client *"CRD"* Resource after it was generated.
|
||||
- Composition and layering of multiple functions together
|
||||
- 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.
|
||||
- Functions **MUST** accept input on STDIN a ` + "`" + `ResourceList` + "`" + ` containing the Resources and
|
||||
` + "`" + `functionConfig` + "`" + `.
|
||||
- Functions **MUST** emit output on STDOUT a ` + "`" + `ResourceList` + "`" + ` containing the modified
|
||||
Resources.
|
||||
- Functions **MUST** exit non-0 on failure, and exit 0 on success.
|
||||
- Functions **MAY** emit output on STDERR with error messaging.
|
||||
- Functions performing validation **SHOULD** exit failure and emit error messaging
|
||||
on a validation failure.
|
||||
- Functions generating Resources **SHOULD** retain non-conflicting changes on the
|
||||
generated Resources -- e.g. 1. the function generates a Deployment, but doesn't
|
||||
specify ` + "`" + `cpu` + "`" + `, 2. the user sets the ` + "`" + `cpu` + "`" + ` on the generated Resource, 3. the
|
||||
function should keep the ` + "`" + `cpu` + "`" + ` when regenerating the Resource a second time.
|
||||
- Functions **SHOULD** be usable outside ` + "`" + `kustomize config run` + "`" + ` -- e.g. though pipeline
|
||||
mechanisms such as Tekton.
|
||||
|
||||
#### Input Format
|
||||
|
||||
Functions must accept on STDIN:
|
||||
|
||||
` + "`" + `ResourceList` + "`" + `:
|
||||
- contains ` + "`" + `items` + "`" + ` field, same as ` + "`" + `List.items` + "`" + `
|
||||
- contains ` + "`" + `functionConfig` + "`" + ` field -- a single item with the configuration for the function itself
|
||||
|
||||
Example ` + "`" + `ResourceList` + "`" + ` Input:
|
||||
|
||||
apiVersion: config.kubernetes.io/v1alpha1
|
||||
kind: ResourceList
|
||||
functionConfig:
|
||||
apiVersion: example.com/v1beta1
|
||||
kind: Nginx
|
||||
metadata:
|
||||
name: my-instance
|
||||
annotations:
|
||||
config.kubernetes.io/local-config: "true"
|
||||
spec:
|
||||
replicas: 5
|
||||
items:
|
||||
- apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: my-instance
|
||||
spec:
|
||||
replicas: 3
|
||||
...
|
||||
- apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: my-instance
|
||||
spec:
|
||||
...
|
||||
|
||||
#### Output Format
|
||||
|
||||
Functions must emit on STDOUT:
|
||||
|
||||
` + "`" + `ResourceList` + "`" + `:
|
||||
- contains ` + "`" + `items` + "`" + ` field, same as ` + "`" + `List.items` + "`" + `
|
||||
|
||||
Example ` + "`" + `ResourceList` + "`" + ` Output:
|
||||
|
||||
apiVersion: config.kubernetes.io/v1alpha1
|
||||
kind: ResourceList
|
||||
items:
|
||||
- apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: my-instance
|
||||
spec:
|
||||
replicas: 5
|
||||
...
|
||||
- apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: my-instance
|
||||
spec:
|
||||
...
|
||||
|
||||
#### Container Environment
|
||||
|
||||
When run by ` + "`" + `kustomize config run` + "`" + `, functions are run in containers with the
|
||||
following environment:
|
||||
|
||||
- Network: ` + "`" + `none` + "`" + `
|
||||
- User: ` + "`" + `nobody` + "`" + `
|
||||
- Security Options: ` + "`" + `no-new-privileges` + "`" + `
|
||||
- Volumes: the volume containing the ` + "`" + `functionConfig` + "`" + ` yaml is mounted under ` + "`" + `/local` + "`" + ` as ` + "`" + `ro` + "`" + `
|
||||
|
||||
### Example Function Implementation
|
||||
|
||||
Following is an example for implementing an nginx abstraction using a config
|
||||
function.
|
||||
|
||||
#### ` + "`" + `nginx-template.sh` + "`" + `
|
||||
|
||||
` + "`" + `nginx-template.sh` + "`" + ` is a simple bash script which uses a *heredoc* as a templating solution
|
||||
for generating Resources from the functionConfig input fields.
|
||||
|
||||
The script wraps itself using ` + "`" + `config run wrap -- $0` + "`" + ` which will:
|
||||
|
||||
1. Parse the ` + "`" + `ResourceList.functionConfig` + "`" + ` (provided to the container stdin) into env vars
|
||||
2. Merge the stdout into the original list of Resources
|
||||
3. Defaults filenames for newly generated Resources (if they are not set as annotations)
|
||||
to ` + "`" + `config/NAME_KIND.yaml` + "`" + `
|
||||
4. Format the output
|
||||
|
||||
#!/bin/bash
|
||||
# script must run wrapped by ` + "`" + `kustomize config run wrap` + "`" + `
|
||||
# for parsing input the functionConfig into env vars
|
||||
if [ -z ${WRAPPED} ]; then
|
||||
export WRAPPED=true
|
||||
config run wrap -- $0
|
||||
exit $?
|
||||
fi
|
||||
|
||||
cat <<End-of-message
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: ${NAME}
|
||||
labels:
|
||||
app: nginx
|
||||
instance: ${NAME}
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
name: http
|
||||
selector:
|
||||
app: nginx
|
||||
instance: ${NAME}
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: ${NAME}
|
||||
labels:
|
||||
app: nginx
|
||||
instance: ${NAME}
|
||||
spec:
|
||||
replicas: ${REPLICAS}
|
||||
selector:
|
||||
matchLabels:
|
||||
app: nginx
|
||||
instance: ${NAME}
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: nginx
|
||||
instance: ${NAME}
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:1.7.9
|
||||
ports:
|
||||
- containerPort: 80
|
||||
End-of-message
|
||||
|
||||
#### ` + "`" + `Dockerfile` + "`" + `
|
||||
|
||||
` + "`" + `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
|
||||
RUN mv /go/bin/config /usr/bin/config
|
||||
COPY nginx-template.sh /usr/bin/nginx-template.sh
|
||||
CMD ["nginx-template.sh]
|
||||
|
||||
### Example Function Usage
|
||||
|
||||
Following is an example of running the ` + "`" + `kustomize config run` + "`" + ` using the preceding API.
|
||||
|
||||
#### ` + "`" + `nginx.yaml` + "`" + ` (Input)
|
||||
|
||||
` + "`" + `dir/nginx.yaml` + "`" + ` contains a reference to the Function. The contents of ` + "`" + `nginx.yaml` + "`" + `
|
||||
are passed to the Function through the ` + "`" + `ResourceList.functionConfig` + "`" + ` field.
|
||||
|
||||
apiVersion: example.com/v1beta1
|
||||
kind: Nginx
|
||||
metadata:
|
||||
name: my-instance
|
||||
annotations:
|
||||
config.kubernetes.io/local-config: "true"
|
||||
configFn:
|
||||
container:
|
||||
image: gcr.io/example-functions/nginx-template:v1.0.0
|
||||
spec:
|
||||
replicas: 5
|
||||
|
||||
- ` + "`" + `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:
|
||||
name: my-instance
|
||||
labels:
|
||||
app: nginx
|
||||
instance: my-instance
|
||||
spec:
|
||||
replicas: 5
|
||||
selector:
|
||||
matchLabels:
|
||||
app: nginx
|
||||
instance: my-instance
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: nginx
|
||||
instance: my-instance
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:1.7.9
|
||||
ports:
|
||||
- containerPort: 80
|
||||
|
||||
` + "`" + `dir/my-instance_service.yaml` + "`" + ` contains the Service:
|
||||
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: my-instance
|
||||
labels:
|
||||
app: nginx
|
||||
instance: my-instance
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
name: http
|
||||
selector:
|
||||
app: nginx
|
||||
instance: my-instance`
|
||||
|
||||
var ConfigIoLong = `# Configuration IO API Semantics
|
||||
|
||||
Resource Configuration may be read / written from / to sources such as directories,
|
||||
stdin|out or network. Tools may be composed using pipes such that the tools writing
|
||||
Resource Configuration may be a different tool from the one that read the configuration.
|
||||
In order for tools to be composed in this way, while preserving origin information --
|
||||
such as the original file, index, etc.
|
||||
|
||||
Tools **SHOULD** write the following annotations when reading from sources,
|
||||
and **SHOULD** respect the annotations when writing to sinks.
|
||||
|
||||
### ` + "`" + `config.kubernetes.io/path` + "`" + `
|
||||
|
||||
Records the slash-delimited, OS-agnostic, relative file path to a Resource.
|
||||
|
||||
This annotation **SHOULD** be set when reading Resources from files.
|
||||
When writing Resources to a directory, the Resource **SHOULD** be written to the corresponding
|
||||
path relative to that directory.
|
||||
|
||||
Example:
|
||||
|
||||
metadata:
|
||||
annotations:
|
||||
config.kubernetes.io/path: "relative/file/path.yaml"
|
||||
|
||||
### ` + "`" + `config.kubernetes.io/index` + "`" + `
|
||||
|
||||
Records the index of a Resource in file. In a multi-object files YAML file, Resources are separated
|
||||
by three dashes (` + "`" + `---` + "`" + `), and the index represents the positon of the Resource starting from zero.
|
||||
|
||||
This annotation **SHOULD** be set when reading Resources from files.
|
||||
When writing multiple Resources to the same file, the Resource **SHOULD** be written in the
|
||||
relative order matching the index.
|
||||
|
||||
When this annotation is not specified, it implies a value of ` + "`" + `0` + "`" + `.
|
||||
|
||||
Example:
|
||||
|
||||
metadata:
|
||||
annotations:
|
||||
config.kubernetes.io/path: "relative/file/path.yaml"
|
||||
config.kubernetes.io/index: 2
|
||||
|
||||
This represents the third Resource in the file.
|
||||
|
||||
### ` + "`" + `config.kubernetes.io/local-config` + "`" + `
|
||||
|
||||
` + "`" + `config.kubernetes.io/local-config` + "`" + ` declares that the configuration is to local tools
|
||||
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"`
|
||||
|
||||
var Merge2Long = `# Merge (2-way)
|
||||
|
||||
2-way merges fields from a source to a destination, overriding the destination fields
|
||||
where they differ.
|
||||
|
||||
### Merge Rules
|
||||
|
||||
Fields are recursively merged using the following rules:
|
||||
|
||||
- scalars
|
||||
- if present only in the dest, it keeps its value
|
||||
- if present in the src and is non-null, take the src value -- if ` + "`" + `null` + "`" + `, clear it
|
||||
- example src: ` + "`" + `5` + "`" + `, dest: ` + "`" + `3` + "`" + ` => result: ` + "`" + `5` + "`" + `
|
||||
|
||||
- non-associative lists -- lists without a merge key
|
||||
- if present only in the dest, it keeps its value
|
||||
- if present in the src and is non-null, take the src value -- if ` + "`" + `null` + "`" + `, clear it
|
||||
- example src: ` + "`" + `[1, 2, 3]` + "`" + `, dest: ` + "`" + `[a, b, c]` + "`" + ` => result: ` + "`" + `[1, 2, 3]` + "`" + `
|
||||
|
||||
- map keys and fields -- paired by the map-key / field-name
|
||||
- if present only in the dest, it keeps its value
|
||||
- if present only in the src, it is added to the dest
|
||||
- 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'}` + "`" + `,
|
||||
dest: ` + "`" + `{'key2': 'value0', 'key3': 'value3'}` + "`" + `
|
||||
=> result: ` + "`" + `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}` + "`" + `
|
||||
|
||||
- associative list elements -- paired by the associative key
|
||||
- if present only in the dest, it keeps its value in the list
|
||||
- if present only in the src, it is added to the dest list
|
||||
- if the field is present in both the src and dest, the value is recursively merged
|
||||
|
||||
### Associative Keys
|
||||
|
||||
Associative keys are used to identify "same" elements within 2 different lists, and merge them.
|
||||
The following fields are recognized as associative keys:
|
||||
|
||||
[` + "`" + `mountPath` + "`" + `, ` + "`" + `devicePath` + "`" + `, ` + "`" + `ip` + "`" + `, ` + "`" + `type` + "`" + `, ` + "`" + `topologyKey` + "`" + `, ` + "`" + `name` + "`" + `, ` + "`" + `containerPort` + "`" + `]
|
||||
|
||||
Any lists where all of the elements contain associative keys will be merged as associative lists.
|
||||
|
||||
### Example
|
||||
|
||||
> Source
|
||||
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
spec:
|
||||
replicas: 3 # scalar
|
||||
template:
|
||||
spec:
|
||||
containers: # associative list -- (name)
|
||||
- name: nginx
|
||||
image: nginx:1.7
|
||||
command: ['new_run.sh', 'arg1'] # non-associative list
|
||||
- name: sidecar2
|
||||
image: sidecar2:v1
|
||||
|
||||
> Destination
|
||||
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:1.6
|
||||
command: ['old_run.sh', 'arg0']
|
||||
- name: sidecar1
|
||||
image: sidecar1:v1
|
||||
|
||||
> Result
|
||||
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
spec:
|
||||
replicas: 3 # scalar
|
||||
template:
|
||||
spec:
|
||||
containers: # associative list -- (name)
|
||||
- name: nginx
|
||||
image: nginx:1.7
|
||||
command: ['new_run.sh', 'arg1'] # non-associative list
|
||||
- name: sidecar1
|
||||
image: sidecar1:v1
|
||||
- name: sidecar2
|
||||
image: sidecar2:v1`
|
||||
|
||||
var Merge3Long = `# Merge (3-way)
|
||||
|
||||
3-way merge identifies changes between an original source + updated source and merges the result
|
||||
into a destination, overriding the destination fields where they have changed between
|
||||
original and updated.
|
||||
|
||||
### Resource MergeRules
|
||||
|
||||
- Resources present in the original and deleted from the update are deleted.
|
||||
- Resources missing from the original and added in the update are added.
|
||||
- Resources present only in the dest are kept without changes.
|
||||
- Resources present in both the update and the dest have their fields merged with the destination.
|
||||
|
||||
### Field Merge Rules
|
||||
|
||||
Fields are recursively merged using the following rules:
|
||||
|
||||
- scalars
|
||||
- if present in either dest or updated and ` + "`" + `null` + "`" + `, clear the value
|
||||
- if unchanged between original and updated, keep dest value
|
||||
- if changed between original and updated (added, deleted, changed), take the updated value
|
||||
|
||||
- non-associative lists -- lists without a merge key
|
||||
- if present in either dest or updated and ` + "`" + `null` + "`" + `, clear the value
|
||||
- if unchanged between original and updated, keep dest value
|
||||
- if changed between original and updated (added, deleted, changed), take the updated value
|
||||
|
||||
- map keys and fields -- paired by the map-key / field-name
|
||||
- if present in either dest or updated and ` + "`" + `null` + "`" + `, clear the value
|
||||
- if present only in the dest, it keeps its value
|
||||
- if not-present in the dest, add the delta between original-updated as a field
|
||||
- otherwise recursively merge the value between original, updated, dest
|
||||
|
||||
- associative list elements -- paired by the associative key
|
||||
- if present only in the dest, it keeps its value
|
||||
- if not-present in the dest, add the delta between original-updated as a field
|
||||
- otherwise recursively merge the value between original, updated, dest
|
||||
|
||||
### Associative Keys
|
||||
|
||||
Associative keys are used to identify "same" elements within 2 different lists, and merge them.
|
||||
The following fields are recognized as associative keys:
|
||||
|
||||
[` + "`" + `mountPath` + "`" + `, ` + "`" + `devicePath` + "`" + `, ` + "`" + `ip` + "`" + `, ` + "`" + `type` + "`" + `, ` + "`" + `topologyKey` + "`" + `, ` + "`" + `name` + "`" + `, ` + "`" + `containerPort` + "`" + `]
|
||||
|
||||
Any lists where all of the elements contain associative keys will be merged as associative lists.`
|
||||
236
cmd/config/internal/generateddocs/commands/docs.go
Normal file
236
cmd/config/internal/generateddocs/commands/docs.go
Normal file
@@ -0,0 +1,236 @@
|
||||
// Copyright 2019 The Kubernetes Authors.
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
// Code generated by "mdtogo"; DO NOT EDIT.
|
||||
package commands
|
||||
|
||||
var CatShort = `[Alpha] Print Resource Config from a local directory.`
|
||||
var CatLong = `
|
||||
[Alpha] Print Resource Config from a local directory.
|
||||
|
||||
DIR:
|
||||
Path to local directory.
|
||||
`
|
||||
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`
|
||||
|
||||
var CompletionShort = `Install shell completion.`
|
||||
var CompletionLong = `
|
||||
Install shell completion for kustomize commands and flags -- supports bash, fish and zsh.
|
||||
|
||||
kustomize install-completion
|
||||
|
||||
Registers the completion command with known shells (e.g. .bashrc, .bash_profile, etc):
|
||||
|
||||
complete -C /Users/USER/go/bin/kustomize kustomize
|
||||
|
||||
Because the completion command is embedded in kustomize directly, there is no need to update
|
||||
it separately from the kustomize binary.
|
||||
|
||||
To uninstall shell completion run:
|
||||
|
||||
COMP_UNINSTALL=1 kustomize install-completion`
|
||||
|
||||
var CountShort = `[Alpha] Count Resources Config from a local directory.`
|
||||
var CountLong = `
|
||||
[Alpha] Count Resources Config from a local directory.
|
||||
|
||||
DIR:
|
||||
Path to local directory.
|
||||
`
|
||||
var CountExamples = `
|
||||
# print Resource counts from a directory
|
||||
kustomize config count my-dir/`
|
||||
|
||||
var FmtShort = `[Alpha] Format yaml configuration files.`
|
||||
var FmtLong = `
|
||||
[Alpha] Format yaml configuration files.
|
||||
|
||||
Fmt will format input by ordering fields and unordered list items in Kubernetes
|
||||
objects. Inputs may be directories, files or stdin, and their contents must
|
||||
include both apiVersion and kind fields.
|
||||
|
||||
- Stdin inputs are formatted and written to stdout
|
||||
- File inputs (args) are formatted and written back to the file
|
||||
- Directory inputs (args) are walked, each encountered .yaml and .yml file
|
||||
acts as an input
|
||||
|
||||
For inputs which contain multiple yaml documents separated by \n---\n,
|
||||
each document will be formatted and written back to the file in the original
|
||||
order.
|
||||
|
||||
Field ordering roughly follows the ordering defined in the source Kubernetes
|
||||
resource definitions (i.e. go structures), falling back on lexicographical
|
||||
sorting for unrecognized fields.
|
||||
|
||||
Unordered list item ordering is defined for specific Resource types and
|
||||
field paths.
|
||||
|
||||
- .spec.template.spec.containers (by element name)
|
||||
- .webhooks.rules.operations (by element value)
|
||||
`
|
||||
var FmtExamples = `
|
||||
# format file1.yaml and file2.yml
|
||||
kustomize config fmt file1.yaml file2.yml
|
||||
|
||||
# format all *.yaml and *.yml recursively traversing directories
|
||||
kustomize config fmt my-dir/
|
||||
|
||||
# format kubectl output
|
||||
kubectl get -o yaml deployments | kustomize config fmt
|
||||
|
||||
# format kustomize output
|
||||
kustomize build | kustomize config fmt`
|
||||
|
||||
var GrepShort = `[Alpha] Search for matching Resources in a directory or from stdin`
|
||||
var GrepLong = `
|
||||
[Alpha] Search for matching Resources in a directory or from stdin.
|
||||
|
||||
QUERY:
|
||||
Query to match expressed as 'path.to.field=value'.
|
||||
Maps and fields are matched as '.field-name' or '.map-key'
|
||||
List elements are matched as '[list-elem-field=field-value]'
|
||||
The value to match is expressed as '=value'
|
||||
'.' as part of a key or value can be escaped as '\.'
|
||||
|
||||
DIR:
|
||||
Path to local directory.
|
||||
`
|
||||
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`
|
||||
|
||||
var MergeShort = `[Alpha] Merge Resource configuration files`
|
||||
var MergeLong = `
|
||||
[Alpha] Merge Resource configuration files
|
||||
|
||||
Merge reads Kubernetes Resource yaml configuration files from stdin or sources packages and write
|
||||
the result to stdout or a destination package.
|
||||
|
||||
Resources are merged using the Resource [apiVersion, kind, name, namespace] as the key. If any of
|
||||
these are missing, merge will default the missing values to empty.
|
||||
|
||||
Resources specified later are high-precedence (the source) and Resources specified
|
||||
earlier are lower-precedence (the destination).
|
||||
|
||||
For information on merge rules, run:
|
||||
|
||||
kustomize config docs merge
|
||||
`
|
||||
var MergeExamples = `
|
||||
cat resources_and_patches.yaml | kustomize config merge > merged_resources.yaml`
|
||||
|
||||
var RunFnsShort = `[Alpha] Reoncile config functions to Resources.`
|
||||
var RunFnsLong = `
|
||||
[Alpha] Reconcile config functions to Resources.
|
||||
|
||||
run sequentially invokes all config functions in the directory, providing Resources
|
||||
in the directory as input to the first function, and writing the output of the last
|
||||
function back to the directory.
|
||||
|
||||
The ordering of functions is determined by the order they are encountered when walking the
|
||||
directory. To clearly specify an ordering of functions, multiple functions may be
|
||||
declared in the same file, separated by '---' (the functions will be invoked in the
|
||||
order they appear in the file).
|
||||
|
||||
#### Arguments:
|
||||
|
||||
DIR:
|
||||
Path to local directory.
|
||||
|
||||
#### Config Functions:
|
||||
|
||||
Config functions are specified as Kubernetes types containing a metadata.configFn.container.image
|
||||
field. This field tells run how to invoke the container.
|
||||
|
||||
Example config function:
|
||||
|
||||
# in file example/fn.yaml
|
||||
apiVersion: fn.example.com/v1beta1
|
||||
kind: ExampleFunctionKind
|
||||
metadata:
|
||||
configFn:
|
||||
container:
|
||||
# function is invoked as a container running this image
|
||||
image: gcr.io/example/examplefunction:v1.0.1
|
||||
annotations:
|
||||
config.kubernetes.io/local-config: "true" # tools should ignore this
|
||||
spec:
|
||||
configField: configValue
|
||||
|
||||
In the preceding example, 'kustomize config run example/' would identify the function by
|
||||
the metadata.configFn 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.
|
||||
`
|
||||
var RunFnsExamples = `
|
||||
kustomize config run example/`
|
||||
|
||||
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
|
||||
|
||||
Args:
|
||||
|
||||
DIR:
|
||||
Path to local directory directory.
|
||||
|
||||
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,
|
||||
container names, etc.
|
||||
|
||||
kustomize config tree supports printing arbitrary fields using the '--field' flag.
|
||||
|
||||
By default, kustomize config tree uses the directory structure for the tree structure, however when printing
|
||||
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"
|
||||
|
||||
# print the "foo"" annotation
|
||||
kubectl get all -o yaml | kustomize config 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 \
|
||||
--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" \
|
||||
--field="status.conditions[type=Ready].status" \
|
||||
--field="status.conditions[type=ContainersReady].status"`
|
||||
460
cmd/config/internal/generateddocs/tutorials/docs.go
Normal file
460
cmd/config/internal/generateddocs/tutorials/docs.go
Normal file
@@ -0,0 +1,460 @@
|
||||
// Copyright 2019 The Kubernetes Authors.
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
// Code generated by "mdtogo"; DO NOT EDIT.
|
||||
package tutorials
|
||||
|
||||
var ConfigurationBasicsShort = `### Synopsis`
|
||||
var ConfigurationBasicsLong = `
|
||||
` + "`" + `kustomize config` + "`" + ` 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 config 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 config 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 config 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 config 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 config 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 config 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 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
|
||||
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 config grep "spec.replicas>0" | kustomize config 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 config grep "spec.template.spec.containers[name=\.*].resources.limits.cpu>1.0" ./staging/ | kustomize config 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 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)
|
||||
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 config grep "spec.replicas>5" ./ | kustomize config 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 config grep "spec.template.spec.containers[name=\.*].resources.limits.memory>0" ./ | kustomize config 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 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
|
||||
│ ├── [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>
|
||||
...`
|
||||
|
||||
var FunctionBasicsShort = `### Synopsis`
|
||||
var FunctionBasicsLong = `
|
||||
` + "`" + `kustomize config` + "`" + ` 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 config` + "`" + `. 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 config tree local-resource/ --name --image --replicas
|
||||
|
||||
# run the function
|
||||
kustomize config run local-resource/
|
||||
|
||||
# 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
|
||||
|
||||
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.
|
||||
|
||||
#### 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 config tree local-resource/ --name --image --replicas
|
||||
|
||||
# run the function
|
||||
kustomize config run local-resource/
|
||||
|
||||
# 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.
|
||||
|
||||
#### 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 config 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 config 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 config 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 config run local-resource/
|
||||
|
||||
# print the new resources
|
||||
kustomize config 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 config run local-resource/
|
||||
kustomize config 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.`
|
||||
Reference in New Issue
Block a user