From 548f5ffca9c5fa1be6a8d95df158b681ac6d4a52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Ortiz=20Garc=C3=ADa?= Date: Mon, 11 Oct 2021 12:03:53 -0500 Subject: [PATCH] Update documents from 'configuration' to 'fn' --- .../docs/api-conventions/functions-impl.md | 12 +++++----- cmd/config/docs/tutorials/function-basics.md | 4 ++-- cmd/config/internal/generateddocs/api/docs.go | 24 +++++++++++-------- .../internal/generateddocs/tutorials/docs.go | 11 +++++---- cmd/config/runner/runner.go | 2 +- functions/examples/application-cr/README.md | 4 ++-- .../examples/application-cr/image/main.go | 3 +-- .../application-cr/image/main_test.go | 2 +- .../examples/injection-tshirt-sizes/README.md | 6 ++--- .../injection-tshirt-sizes/image/main.go | 2 +- .../examples/template-go-nginx/README.md | 6 ++--- .../local-resource/example-use.yaml | 2 +- .../template-heredoc-cockroachdb/README.md | 8 +++---- .../image/cockroachdb-template.sh | 6 ++--- .../local-resource/example-use.yaml | 2 +- .../examples/validator-kubeval/README.md | 6 ++--- .../examples/validator-kubeval/image/main.go | 2 +- .../validator-resource-requests/README.md | 6 ++--- .../validator-resource-requests/image/main.go | 6 ++--- 19 files changed, 60 insertions(+), 54 deletions(-) diff --git a/cmd/config/docs/api-conventions/functions-impl.md b/cmd/config/docs/api-conventions/functions-impl.md index 17891c50a..05c0762b9 100644 --- a/cmd/config/docs/api-conventions/functions-impl.md +++ b/cmd/config/docs/api-conventions/functions-impl.md @@ -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. -`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. ## Example Function Implementation @@ -28,7 +28,7 @@ The script wraps itself using `config run wrap -- $0` which will: ```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 if [ -z ${WRAPPED} ]; then export WRAPPED=true @@ -82,7 +82,7 @@ End-of-message ### 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 @@ -94,9 +94,9 @@ CMD ["nginx-template.sh] ## 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: - Network: `none` @@ -129,7 +129,7 @@ spec: ### 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: diff --git a/cmd/config/docs/tutorials/function-basics.md b/cmd/config/docs/tutorials/function-basics.md index 17a0679e1..c9d4c766d 100644 --- a/cmd/config/docs/tutorials/function-basics.md +++ b/cmd/config/docs/tutorials/function-basics.md @@ -2,7 +2,7 @@ ### 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`. First fetch the kustomize repository, which contains a collection of example @@ -14,7 +14,7 @@ ### Templating -- CockroachDB 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`. #### 1: Generate the Resources diff --git a/cmd/config/internal/generateddocs/api/docs.go b/cmd/config/internal/generateddocs/api/docs.go index d4ffb9672..df884a9f3 100644 --- a/cmd/config/internal/generateddocs/api/docs.go +++ b/cmd/config/internal/generateddocs/api/docs.go @@ -61,15 +61,16 @@ Example: annotations: config.kubernetes.io/local-config: "true"` -var FunctionsImplShort = `Following is an example for implementing an nginx abstraction using a configuration` -var FunctionsImplLong = `# Running Configuration Functions using kustomize CLI +var ( + 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 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. -` + "`" + `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. function. @@ -88,7 +89,7 @@ The script wraps itself using ` + "`" + `config run wrap -- $0` + "`" + ` which 4. Format the output #!/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 if [ -z ${WRAPPED} ]; then export WRAPPED=true @@ -141,7 +142,7 @@ The script wraps itself using ` + "`" + `config run wrap -- $0` + "`" + ` which ### 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 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 -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: - Network: ` + "`" + `none` + "`" + ` @@ -184,7 +185,7 @@ are passed to the Function through the ` + "`" + `ResourceList.functionConfig` + ### 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: @@ -230,9 +231,11 @@ The function is invoked using byrunning ` + "`" + `kustomize config run dir/` + selector: app: nginx instance: my-instance` +) -var FunctionsSpecShort = `_Configuration functions_ enable shift-left practices (client-side) through:` -var FunctionsSpecLong = `# Configuration Functions Specification +var ( + 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 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 [2]: https://tools.ietf.org/html/rfc2119 [3]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds` +) var Merge2Long = `# Merge (2-way) diff --git a/cmd/config/internal/generateddocs/tutorials/docs.go b/cmd/config/internal/generateddocs/tutorials/docs.go index 27f1f0fe6..bf79934be 100644 --- a/cmd/config/internal/generateddocs/tutorials/docs.go +++ b/cmd/config/internal/generateddocs/tutorials/docs.go @@ -2,6 +2,7 @@ package tutorials var ConfigurationBasicsShort = `### Synopsis` + var ConfigurationBasicsLong = ` ` + "`" + `kustomize cfg` + "`" + ` provides tools for working with local configuration directories. @@ -274,9 +275,10 @@ var ConfigurationBasicsLong = ` │   └── image: ...` -var FunctionBasicsShort = `### Synopsis` -var FunctionBasicsLong = ` - ` + "`" + `kustomize config` + "`" + ` enables encapsulating function for manipulating Resource +var ( + FunctionBasicsShort = `### Synopsis` + FunctionBasicsLong = ` + ` + "`" + `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 @@ -288,7 +290,7 @@ var FunctionBasicsLong = ` ### Templating -- CockroachDB 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` + "`" + `. #### 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 ` + "`" + `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.` +) diff --git a/cmd/config/runner/runner.go b/cmd/config/runner/runner.go index 211eb58e4..38fe0ae11 100644 --- a/cmd/config/runner/runner.go +++ b/cmd/config/runner/runner.go @@ -129,7 +129,7 @@ var ExitOnError bool // StackOnError if true, will print a stack trace on failure. var StackOnError bool -const cmdName = "kustomize config" +const cmdName = "kustomize fn" // FixDocs replaces instances of old with new in the docs for c func FixDocs(new string, c *cobra.Command) { diff --git a/functions/examples/application-cr/README.md b/functions/examples/application-cr/README.md index 49b279260..feec0e89c 100644 --- a/functions/examples/application-cr/README.md +++ b/functions/examples/application-cr/README.md @@ -17,7 +17,7 @@ Resource configuration, and looks for invalid configuration. The function is invoked by authoring a [local Resource](local-resource) 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. @@ -25,6 +25,6 @@ This exits non-zero if there is an error. 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. diff --git a/functions/examples/application-cr/image/main.go b/functions/examples/application-cr/image/main.go index ea2e9b886..086120bad 100644 --- a/functions/examples/application-cr/image/main.go +++ b/functions/examples/application-cr/image/main.go @@ -2,7 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // 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 import ( @@ -82,7 +82,6 @@ func (f appCRFilter) Filter(in []*yaml.RNode) ([]*yaml.RNode, error) { return append(in, app), nil } return in, nil - } // parseAPI parses the functionConfig into an API struct. diff --git a/functions/examples/application-cr/image/main_test.go b/functions/examples/application-cr/image/main_test.go index 897caa7c5..fe5fabdc3 100644 --- a/functions/examples/application-cr/image/main_test.go +++ b/functions/examples/application-cr/image/main_test.go @@ -2,7 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // 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 import ( diff --git a/functions/examples/injection-tshirt-sizes/README.md b/functions/examples/injection-tshirt-sizes/README.md index 1da48c642..067c4f3ef 100644 --- a/functions/examples/injection-tshirt-sizes/README.md +++ b/functions/examples/injection-tshirt-sizes/README.md @@ -17,7 +17,7 @@ Resource configuration, and looks for invalid configuration. The function is invoked by authoring a [local Resource](local-resource) 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. @@ -25,11 +25,11 @@ This exits non-zero if there is an error. 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` annotation from `medium` to `small` and rerun: - kustomize config run local-resource/ + kustomize fn run local-resource/ Observe that the reservations have changed. diff --git a/functions/examples/injection-tshirt-sizes/image/main.go b/functions/examples/injection-tshirt-sizes/image/main.go index a153482d2..b3c9bfb3b 100644 --- a/functions/examples/injection-tshirt-sizes/image/main.go +++ b/functions/examples/injection-tshirt-sizes/image/main.go @@ -2,7 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // 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 import ( diff --git a/functions/examples/template-go-nginx/README.md b/functions/examples/template-go-nginx/README.md index 44a677ae2..cbe57c69d 100644 --- a/functions/examples/template-go-nginx/README.md +++ b/functions/examples/template-go-nginx/README.md @@ -27,7 +27,7 @@ function input, and writing the function output. The function is invoked by authoring a [local Resource](local-resource) 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. @@ -41,7 +41,7 @@ This generates the `local-resource/config` directory containing the template out Run the config with: - kustomize config run local-resource/ + kustomize fn run local-resource/ 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 `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. diff --git a/functions/examples/template-go-nginx/local-resource/example-use.yaml b/functions/examples/template-go-nginx/local-resource/example-use.yaml index c323d2dc1..a7378806a 100644 --- a/functions/examples/template-go-nginx/local-resource/example-use.yaml +++ b/functions/examples/template-go-nginx/local-resource/example-use.yaml @@ -1,7 +1,7 @@ # Copyright 2019 The Kubernetes Authors. # 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 metadata: name: demo diff --git a/functions/examples/template-heredoc-cockroachdb/README.md b/functions/examples/template-heredoc-cockroachdb/README.md index 96be73e02..8be4a1c66 100644 --- a/functions/examples/template-heredoc-cockroachdb/README.md +++ b/functions/examples/template-heredoc-cockroachdb/README.md @@ -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 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. - 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) 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. @@ -36,7 +36,7 @@ This generates the `local-resource/config` directory containing the template out Run the config with: - kustomize config run local-resource/ + kustomize fn run local-resource/ 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 `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. diff --git a/functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh b/functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh index 79f78bafd..df727ef3a 100755 --- a/functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh +++ b/functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh @@ -3,18 +3,18 @@ # 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 # input Resources. if [ -z ${WRAPPED} ]; then export WRAPPED=true - kustomize config run wrap -- $0 + kustomize fn run wrap -- $0 exit $? fi # this is the template for a cockroachdb instance # environment variables are parsed from the input functionConfig by -# `kustomize config run wrap` +# `kustomize fn run wrap` cat <