kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-13 01:50:55 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Merge pull request #4236 from Goodwine/docs-fn

Browse Source 
Update documents from 'kustomize configuration' to 'kustomize fn'
This commit is contained in:
Kubernetes Prow Robot
2021-10-13 18:35:28 -07:00
committed by GitHub
parent 4769751943 548f5ffca9
commit 5765ab4dbc
19 changed files with 60 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
cmd/config/docs/api-conventions/functions-impl.md
View File

@@ -5,7 +5,7 @@ container workflow orchestrator including Tekton, Cloud Build, or run directly u
Run `config help docs-fn-spec` to see the Configuration Functions Specification. Run `config help docs-fn-spec` to see the Configuration Functions Specification.
`kustomize config run` is an example orchestrator for invoking Configuration Functions. This `kustomize fn run` is an example orchestrator for invoking Configuration Functions. This
document describes how to implement and invoke an example function. document describes how to implement and invoke an example function.
## Example Function Implementation ## Example Function Implementation
@@ -28,7 +28,7 @@ The script wraps itself using `config run wrap -- $0` which will:
```bash ```bash
#!/bin/bash #!/bin/bash
# script must run wrapped by "kustomize config run wrap" # script must run wrapped by "kustomize fn run wrap"
# for parsing input the functionConfig into env vars # for parsing input the functionConfig into env vars
if [ -z ${WRAPPED} ]; then if [ -z ${WRAPPED} ]; then
export WRAPPED=true export WRAPPED=true
@@ -82,7 +82,7 @@ End-of-message
### Dockerfile ### Dockerfile
`Dockerfile` installs `kustomize config` and copies the script into the container image. `Dockerfile` installs `kustomize fn` and copies the script into the container image.
``` ```
FROM golang:1.13-stretch FROM golang:1.13-stretch
@@ -94,9 +94,9 @@ CMD ["nginx-template.sh]
## Example Function Usage ## Example Function Usage
Following is an example of running the `kustomize config run` using the preceding API. Following is an example of running the `kustomize fn run` using the preceding API.
When run by `kustomize config run`, functions are run in containers with the When run by `kustomize fn run`, functions are run in containers with the
following environment: following environment:
- Network: `none` - Network: `none`
@@ -129,7 +129,7 @@ spec:
### Output ### Output
The function is invoked using byrunning `kustomize config run dir/`. The function is invoked using byrunning `kustomize fn run dir/`.
`dir/my-instance_deployment.yaml` contains the Deployment: `dir/my-instance_deployment.yaml` contains the Deployment:

4
cmd/config/docs/tutorials/function-basics.md
View File

@@ -2,7 +2,7 @@
### Synopsis ### Synopsis
`kustomize config` enables encapsulating function for manipulating Resource `kustomize fn` enables encapsulating function for manipulating Resource
configuration inside containers, which are run using `run`. configuration inside containers, which are run using `run`.
First fetch the kustomize repository, which contains a collection of example First fetch the kustomize repository, which contains a collection of example
@@ -14,7 +14,7 @@
### Templating -- CockroachDB ### Templating -- CockroachDB
This section demonstrates how to leverage templating based solutions from This section demonstrates how to leverage templating based solutions from
`kustomize config`. The templating function is implemented as a `bash` script `kustomize fn`. The templating function is implemented as a `bash` script
using a `heredoc`. using a `heredoc`.
#### 1: Generate the Resources #### 1: Generate the Resources

24
cmd/config/internal/generateddocs/api/docs.go
View File

@@ -61,15 +61,16 @@ Example:
annotations: annotations:
config.kubernetes.io/local-config: "true"` config.kubernetes.io/local-config: "true"`
var FunctionsImplShort = `Following is an example for implementing an nginx abstraction using a configuration` var (
var FunctionsImplLong = `# Running Configuration Functions using kustomize CLI FunctionsImplShort = `Following is an example for implementing an nginx abstraction using a configuration`
FunctionsImplLong = `# Running Configuration Functions using kustomize CLI
Configuration functions can be implemented using any toolchain and invoked using any Configuration functions can be implemented using any toolchain and invoked using any
container workflow orchestrator including Tekton, Cloud Build, or run directly using ` + "`" + `docker run` + "`" + `. container workflow orchestrator including Tekton, Cloud Build, or run directly using ` + "`" + `docker run` + "`" + `.
Run ` + "`" + `config help docs-fn-spec` + "`" + ` to see the Configuration Functions Specification. Run ` + "`" + `config help docs-fn-spec` + "`" + ` to see the Configuration Functions Specification.
` + "`" + `kustomize config run` + "`" + ` is an example orchestrator for invoking Configuration Functions. This ` + "`" + `kustomize fn run` + "`" + ` is an example orchestrator for invoking Configuration Functions. This
document describes how to implement and invoke an example function. document describes how to implement and invoke an example function.
function. function.
@@ -88,7 +89,7 @@ The script wraps itself using ` + "`" + `config run wrap -- $0` + "`" + ` which
4. Format the output 4. Format the output
#!/bin/bash #!/bin/bash
# script must run wrapped by "kustomize config run wrap" # script must run wrapped by "kustomize fn run wrap"
# for parsing input the functionConfig into env vars # for parsing input the functionConfig into env vars
if [ -z ${WRAPPED} ]; then if [ -z ${WRAPPED} ]; then
export WRAPPED=true export WRAPPED=true
@@ -141,7 +142,7 @@ The script wraps itself using ` + "`" + `config run wrap -- $0` + "`" + ` which
### Dockerfile ### Dockerfile
` + "`" + `Dockerfile` + "`" + ` installs ` + "`" + `kustomize config` + "`" + ` and copies the script into the container image. ` + "`" + `Dockerfile` + "`" + ` installs ` + "`" + `kustomize fn` + "`" + ` and copies the script into the container image.
FROM golang:1.13-stretch FROM golang:1.13-stretch
RUN go get sigs.k8s.io/kustomize/cmd/config RUN go get sigs.k8s.io/kustomize/cmd/config
@@ -151,9 +152,9 @@ The script wraps itself using ` + "`" + `config run wrap -- $0` + "`" + ` which
## Example Function Usage ## Example Function Usage
Following is an example of running the ` + "`" + `kustomize config run` + "`" + ` using the preceding API. Following is an example of running the ` + "`" + `kustomize fn run` + "`" + ` using the preceding API.
When run by ` + "`" + `kustomize config run` + "`" + `, functions are run in containers with the When run by ` + "`" + `kustomize fn run` + "`" + `, functions are run in containers with the
following environment: following environment:
- Network: ` + "`" + `none` + "`" + ` - Network: ` + "`" + `none` + "`" + `
@@ -184,7 +185,7 @@ are passed to the Function through the ` + "`" + `ResourceList.functionConfig` +
### Output ### Output
The function is invoked using byrunning ` + "`" + `kustomize config run dir/` + "`" + `. The function is invoked using byrunning ` + "`" + `kustomize fn run dir/` + "`" + `.
` + "`" + `dir/my-instance_deployment.yaml` + "`" + ` contains the Deployment: ` + "`" + `dir/my-instance_deployment.yaml` + "`" + ` contains the Deployment:
@@ -230,9 +231,11 @@ The function is invoked using byrunning ` + "`" + `kustomize config run dir/` +
selector: selector:
app: nginx app: nginx
instance: my-instance` instance: my-instance`
)
var FunctionsSpecShort = `_Configuration functions_ enable shift-left practices (client-side) through:` var (
var FunctionsSpecLong = `# Configuration Functions Specification FunctionsSpecShort = `_Configuration functions_ enable shift-left practices (client-side) through:`
FunctionsSpecLong = `# Configuration Functions Specification
This document specifies a standard for client-side functions that operate on This document specifies a standard for client-side functions that operate on
Kubernetes declarative configurations. This standard enables creating Kubernetes declarative configurations. This standard enables creating
@@ -408,6 +411,7 @@ A non-zero exit code indicates a failure.
[1]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md [1]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
[2]: https://tools.ietf.org/html/rfc2119 [2]: https://tools.ietf.org/html/rfc2119
[3]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds` [3]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds`
)
var Merge2Long = `# Merge (2-way) var Merge2Long = `# Merge (2-way)

11
cmd/config/internal/generateddocs/tutorials/docs.go
View File

@@ -2,6 +2,7 @@
package tutorials package tutorials
var ConfigurationBasicsShort = `### Synopsis` var ConfigurationBasicsShort = `### Synopsis`
var ConfigurationBasicsLong = ` var ConfigurationBasicsLong = `
` + "`" + `kustomize cfg` + "`" + ` provides tools for working with local configuration directories. ` + "`" + `kustomize cfg` + "`" + ` provides tools for working with local configuration directories.
@@ -274,9 +275,10 @@ var ConfigurationBasicsLong = `
│   └── image: <YOUR-CONTAINER> │   └── image: <YOUR-CONTAINER>
...` ...`
var FunctionBasicsShort = `### Synopsis` var (
var FunctionBasicsLong = ` FunctionBasicsShort = `### Synopsis`
` + "`" + `kustomize config` + "`" + ` enables encapsulating function for manipulating Resource FunctionBasicsLong = `
` + "`" + `kustomize fn` + "`" + ` enables encapsulating function for manipulating Resource
configuration inside containers, which are run using ` + "`" + `run` + "`" + `. configuration inside containers, which are run using ` + "`" + `run` + "`" + `.
First fetch the kustomize repository, which contains a collection of example First fetch the kustomize repository, which contains a collection of example
@@ -288,7 +290,7 @@ var FunctionBasicsLong = `
### Templating -- CockroachDB ### Templating -- CockroachDB
This section demonstrates how to leverage templating based solutions from This section demonstrates how to leverage templating based solutions from
` + "`" + `kustomize config` + "`" + `. The templating function is implemented as a ` + "`" + `bash` + "`" + ` script ` + "`" + `kustomize fn` + "`" + `. The templating function is implemented as a ` + "`" + `bash` + "`" + ` script
using a ` + "`" + `heredoc` + "`" + `. using a ` + "`" + `heredoc` + "`" + `.
#### 1: Generate the Resources #### 1: Generate the Resources
@@ -455,3 +457,4 @@ Functions may be composed together. Try putting the Injection (tshirt-size) and
Validation functions together in the same .yaml file (separated by ` + "`" + `---` + "`" + `). Run 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, ` + "`" + `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.` and then the second function in the file is applied.`
)

2
cmd/config/runner/runner.go
View File

@@ -129,7 +129,7 @@ var ExitOnError bool
// StackOnError if true, will print a stack trace on failure. // StackOnError if true, will print a stack trace on failure.
var StackOnError bool var StackOnError bool
const cmdName = "kustomize config" const cmdName = "kustomize fn"
// FixDocs replaces instances of old with new in the docs for c // FixDocs replaces instances of old with new in the docs for c
func FixDocs(new string, c *cobra.Command) { func FixDocs(new string, c *cobra.Command) {

4
functions/examples/application-cr/README.md
View File

@@ -17,7 +17,7 @@ Resource configuration, and looks for invalid configuration.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.annotations.[config.kubernetes.io/function]` and running: with `metadata.annotations.[config.kubernetes.io/function]` and running:
kustomize config run local-resource/ --fn-path config/ kustomize fn run local-resource/ --fn-path config/
This exits non-zero if there is an error. This exits non-zero if there is an error.
@@ -25,6 +25,6 @@ This exits non-zero if there is an error.
Run the validator with: Run the validator with:
kustomize config run local-resource/ --fn-path config/ kustomize fn run local-resource/ --fn-path config/
This will append an Application CR. This will append an Application CR.

3
functions/examples/application-cr/image/main.go
View File

@@ -2,7 +2,7 @@
// SPDX-License-Identifier: Apache-2.0 // SPDX-License-Identifier: Apache-2.0
// Package main implements adding an Application CR to a group of resources and // Package main implements adding an Application CR to a group of resources and
// is run with `kustomize config run -- DIR/`. // is run with `kustomize fn run -- DIR/`.
package main package main
import ( import (
@@ -82,7 +82,6 @@ func (f appCRFilter) Filter(in []*yaml.RNode) ([]*yaml.RNode, error) {
return append(in, app), nil return append(in, app), nil
} }
return in, nil return in, nil
} }
// parseAPI parses the functionConfig into an API struct. // parseAPI parses the functionConfig into an API struct.

2
functions/examples/application-cr/image/main_test.go
View File

@@ -2,7 +2,7 @@
// SPDX-License-Identifier: Apache-2.0 // SPDX-License-Identifier: Apache-2.0
// Package main implements adding an Application CR to a group of resources and // Package main implements adding an Application CR to a group of resources and
// is run with `kustomize config run -- DIR/`. // is run with `kustomize fn run -- DIR/`.
package main package main
import ( import (

6
functions/examples/injection-tshirt-sizes/README.md
View File

@@ -17,7 +17,7 @@ Resource configuration, and looks for invalid configuration.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.annotations.[config.kubernetes.io/function]` and running: with `metadata.annotations.[config.kubernetes.io/function]` and running:
kustomize config run local-resource/ kustomize fn run local-resource/
This exits non-zero if there is an error. This exits non-zero if there is an error.
@@ -25,11 +25,11 @@ This exits non-zero if there is an error.
Run the validator with: Run the validator with:
kustomize config run local-resource/ kustomize fn run local-resource/
This will add resource reservations to the Deployment. Change the `tshirt-size` This will add resource reservations to the Deployment. Change the `tshirt-size`
annotation from `medium` to `small` and rerun: annotation from `medium` to `small` and rerun:
kustomize config run local-resource/ kustomize fn run local-resource/
Observe that the reservations have changed. Observe that the reservations have changed.

2
functions/examples/injection-tshirt-sizes/image/main.go
View File

@@ -2,7 +2,7 @@
// SPDX-License-Identifier: Apache-2.0 // SPDX-License-Identifier: Apache-2.0
// Package main implements an injection function for resource reservations and // Package main implements an injection function for resource reservations and
// is run with `kustomize config run -- DIR/`. // is run with `kustomize fn run -- DIR/`.
package main package main
import ( import (

6
functions/examples/template-go-nginx/README.md
View File

@@ -27,7 +27,7 @@ function input, and writing the function output.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.annotations.[config.kubernetes.io/function]` and running: with `metadata.annotations.[config.kubernetes.io/function]` and running:
kustomize config run local-resource/ kustomize fn run local-resource/
This generates the `local-resource/config` directory containing the template output. This generates the `local-resource/config` directory containing the template output.
@@ -41,7 +41,7 @@ This generates the `local-resource/config` directory containing the template out
Run the config with: Run the config with:
kustomize config run local-resource/ kustomize fn run local-resource/
This will create the directory This will create the directory
@@ -50,6 +50,6 @@ This will create the directory
Add an annotation to the Deployment Resource and change the replica count of the Add an annotation to the Deployment Resource and change the replica count of the
`kind: Nginx` Resource in `example-use.yaml`. Rerun the template: `kind: Nginx` Resource in `example-use.yaml`. Rerun the template:
kustomize config run local-resource/ kustomize fn run local-resource/
The replica count should be updated, but your annotation should remain. The replica count should be updated, but your annotation should remain.

2
functions/examples/template-go-nginx/local-resource/example-use.yaml
View File

@@ -1,7 +1,7 @@
# Copyright 2019 The Kubernetes Authors. # Copyright 2019 The Kubernetes Authors.
# SPDX-License-Identifier: Apache-2.0 # SPDX-License-Identifier: Apache-2.0
apiVersion: examples.config.kubernetes.io/v1beta1 # call `kustomize config run` on a directory containing this file apiVersion: examples.config.kubernetes.io/v1beta1 # call `kustomize fn run` on a directory containing this file
kind: Nginx kind: Nginx
metadata: metadata:
name: demo name: demo

8
functions/examples/template-heredoc-cockroachdb/README.md
View File

@@ -11,7 +11,7 @@ The function is implemented as an [image](image), and built using `make image`.
The template is implemented as a heredoc, which substitutes environment variables The template is implemented as a heredoc, which substitutes environment variables
into a static string. into a static string.
This simple implementation uses `kustomize config run wrap --` to perform the This simple implementation uses `kustomize fn run wrap --` to perform the
heavy lifting of implementing the function interface. heavy lifting of implementing the function interface.
- parse functionConfig from stdin into environment variables - parse functionConfig from stdin into environment variables
@@ -22,7 +22,7 @@ heavy lifting of implementing the function interface.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.annotations.[config.kubernetes.io/function]` and running: with `metadata.annotations.[config.kubernetes.io/function]` and running:
kustomize config run local-resource/ kustomize fn run local-resource/
This generates the `local-resource/config` directory containing the template output. This generates the `local-resource/config` directory containing the template output.
@@ -36,7 +36,7 @@ This generates the `local-resource/config` directory containing the template out
Run the config with: Run the config with:
kustomize config run local-resource/ kustomize fn run local-resource/
This will create the directory This will create the directory
@@ -45,6 +45,6 @@ This will create the directory
Add an annotation to the StatefulSet Resource and change the replica count of the Add an annotation to the StatefulSet Resource and change the replica count of the
`kind: CockroachDB` Resource in `example-use.yaml`. Rerun the template: `kind: CockroachDB` Resource in `example-use.yaml`. Rerun the template:
kustomize config run local-resource/ kustomize fn run local-resource/
The replica count should be updated, but your annotation should remain. The replica count should be updated, but your annotation should remain.

6
functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh
View File

@@ -3,18 +3,18 @@
# SPDX-License-Identifier: Apache-2.0 # SPDX-License-Identifier: Apache-2.0
# use `kustomize config run wrap` to parse the container stdin into # use `kustomize fn run wrap` to parse the container stdin into
# environment variables, and to merge the template output into the # environment variables, and to merge the template output into the
# input Resources. # input Resources.
if [ -z ${WRAPPED} ]; then if [ -z ${WRAPPED} ]; then
export WRAPPED=true export WRAPPED=true
kustomize config run wrap -- $0 kustomize fn run wrap -- $0
exit $? exit $?
fi fi
# this is the template for a cockroachdb instance # this is the template for a cockroachdb instance
# environment variables are parsed from the input functionConfig by # environment variables are parsed from the input functionConfig by
# `kustomize config run wrap` # `kustomize fn run wrap`
cat <<End-of-message cat <<End-of-message
apiVersion: v1 apiVersion: v1
kind: Service kind: Service

2
functions/examples/template-heredoc-cockroachdb/local-resource/example-use.yaml
View File

@@ -1,7 +1,7 @@
# Copyright 2019 The Kubernetes Authors. # Copyright 2019 The Kubernetes Authors.
# SPDX-License-Identifier: Apache-2.0 # SPDX-License-Identifier: Apache-2.0
# call `kustomize config run` on a directory containing this file # call `kustomize fn run` on a directory containing this file
apiVersion: examples.config.kubernetes.io/v1beta1 apiVersion: examples.config.kubernetes.io/v1beta1
kind: CockroachDB kind: CockroachDB
metadata: metadata:

6
functions/examples/validator-kubeval/README.md
View File

@@ -20,7 +20,7 @@ the `API` struct definition in [main.go](image/main.go) for documentation.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.annotations.[config.kubernetes.io/function]` and running: with `metadata.annotations.[config.kubernetes.io/function]` and running:
kustomize config run local-resource/ kustomize fn run local-resource/
This exists non-zero if kubeval detects an invalid Resource. This exists non-zero if kubeval detects an invalid Resource.
@@ -28,7 +28,7 @@ This exists non-zero if kubeval detects an invalid Resource.
Run the validator with: Run the validator with:
kustomize config run local-resource/ kustomize fn run local-resource/
This will return an error: This will return an error:
@@ -39,6 +39,6 @@ This will return an error:
Now fix the typo in [example-use.yaml](local-resource/example-use.yaml) and Now fix the typo in [example-use.yaml](local-resource/example-use.yaml) and
run: run:
kustomize config run local-resource/ kustomize fn run local-resource/
This will return success (no output). This will return success (no output).

2
functions/examples/validator-kubeval/image/main.go
View File

@@ -1,7 +1,7 @@
// Copyright 2019 The Kubernetes Authors. // Copyright 2019 The Kubernetes Authors.
// SPDX-License-Identifier: Apache-2.0 // SPDX-License-Identifier: Apache-2.0
// Package main implements a validator function run by `kustomize config run` // Package main implements a validator function run by `kustomize fn run`
package main package main
import ( import (

6
functions/examples/validator-resource-requests/README.md
View File

@@ -17,7 +17,7 @@ Resource configuration, and looks for invalid configuration.
The function is invoked by authoring a [local Resource](local-resource) The function is invoked by authoring a [local Resource](local-resource)
with `metadata.annotations.[config.kubernetes.io/function]` and running: with `metadata.annotations.[config.kubernetes.io/function]` and running:
kustomize config run local-resource/ kustomize fn run local-resource/
This exists non-zero if there is an error. This exists non-zero if there is an error.
@@ -25,7 +25,7 @@ This exists non-zero if there is an error.
Run the validator with: Run the validator with:
kustomize config run local-resource/ kustomize fn run local-resource/
This will return an error: This will return an error:
@@ -33,6 +33,6 @@ This will return an error:
Now uncomment the resource reservations and run again: Now uncomment the resource reservations and run again:
kustomize config run local-resource/ kustomize fn run local-resource/
This will return success This will return success

6
functions/examples/validator-resource-requests/image/main.go
View File

@@ -1,7 +1,7 @@
// Copyright 2019 The Kubernetes Authors. // Copyright 2019 The Kubernetes Authors.
// SPDX-License-Identifier: Apache-2.0 // SPDX-License-Identifier: Apache-2.0
// Package main implements a validator function run by `kustomize config run` // Package main implements a validator function run by `kustomize fn run`
package main package main
import ( import (
@@ -18,7 +18,8 @@ func main() {
p := kio.Pipeline{ p := kio.Pipeline{
Inputs: []kio.Reader{rw}, // read the inputs into a slice Inputs: []kio.Reader{rw}, // read the inputs into a slice
Filters: []kio.Filter{filter{}}, // run the filter against the inputs Filters: []kio.Filter{filter{}}, // run the filter against the inputs
Outputs: []kio.Writer{rw}} // copy the inputs to the output Outputs: []kio.Writer{rw}, // copy the inputs to the output
}
if err := p.Execute(); err != nil { if err := p.Execute(); err != nil {
fmt.Fprintf(os.Stderr, "%v\n", err) fmt.Fprintf(os.Stderr, "%v\n", err)
os.Exit(1) os.Exit(1)
@@ -59,7 +60,6 @@ func validate(r *yaml.RNode) error {
// visit each container in the list and validate // visit each container in the list and validate
return containers.VisitElements(func(node *yaml.RNode) error { return containers.VisitElements(func(node *yaml.RNode) error {
// check cpu is non-nil // check cpu is non-nil
f, err := node.Pipe(yaml.Lookup("resources", "requests", "cpu")) f, err := node.Pipe(yaml.Lookup("resources", "requests", "cpu"))
if err != nil { if err != nil {