Skip to content

Commit

Permalink
Clean up search-replace and apply-setters docs
Browse files Browse the repository at this point in the history
  • Loading branch information
phanimarupaka committed Apr 1, 2021
1 parent fa5b3cc commit 7842481
Show file tree
Hide file tree
Showing 8 changed files with 219 additions and 218 deletions.
20 changes: 10 additions & 10 deletions examples/mutators/apply-setters/simple/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# apply-setters: Simple Example

Setters provide a solution for template-free setting of field values. The
Setters provide a solution for template-free setting of field values. The
`apply-setters` KRM config function applies setter values to resource fields
with setter references.

Expand All @@ -19,8 +19,8 @@ kind: MyKind
metadata:
name: ns
environments: # kpt-set: ${env}
- dev
- stage
- dev
- stage
```
We use ConfigMap to configure the `apply-setters` function. The desired
Expand All @@ -32,15 +32,15 @@ desired value for the tagged field.
apiVersion: v1
kind: ConfigMap
metadata:
...
name: apply-setters-fn-config
data:
name: my-new-map
env: |
- prod
- stage
```

Invoking `apply-setters` function would apply the changes to resource configs
Invoking `apply-setters` function would apply the changes to resource configs

```yaml
apiVersion: v1
Expand All @@ -55,17 +55,17 @@ kind: MyKind
metadata:
name: ns
environments: # kpt-set: ${env}
- prod
- stage
- prod
- stage
```

## Function invocation

Get the config example and try it out by running the following commands:

```sh
kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-catalog.git/examples/mutators/apply-setters/simple .
kpt fn run simple
kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-catalog.git/examples/mutators/apply-setters/simple
kpt fn eval simple/ --image gcr.io/kpt-fn/apply-setters:unstable --fn-config simple/fn-config.yaml
```

## Expected result
Expand All @@ -74,5 +74,5 @@ Check the value of setter `name` is set to `my-new-map`.
Check the value of setter `env` is set to array value `[prod, stage]`.

```sh
kpt cfg cat simple
kpt pkg cat simple/
```
3 changes: 2 additions & 1 deletion examples/mutators/apply-setters/simple/fn-config.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
apiVersion: v1
kind: ConfigMap
metadata:
name: my-func-config
name: apply-setters-fn-config
# TODO:(pmarupaka) remove annotations when e2e tests switch to kpt v1 binary
annotations:
config.k8s.io/function: |
container:
Expand Down
6 changes: 3 additions & 3 deletions examples/mutators/search-replace/simple/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,14 @@ metadata:
Get the config example and try it out by running the following commands:

```sh
kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-catalog.git/examples/mutators/search/simple .
kpt fn run simple
kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-catalog.git/examples/mutators/search/simple
kpt fn eval simple/ --image gcr.io/kpt-fn/apply-setters:unstable --fn-config simple/fn-config.yaml
```

## Expected result

Check the value of deployment `the-deloyment` is changed to `my-deloyment`.

```sh
kpt cfg cat simple
kpt pkg cat simple/
```
3 changes: 2 additions & 1 deletion examples/mutators/search-replace/simple/fn-config.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
apiVersion: v1
kind: ConfigMap
metadata:
name: my-func-config
name: search-replace-fn-config
# TODO:(pmarupaka) remove annotations when e2e tests switch to kpt v1 binary
annotations:
config.k8s.io/function: |
container:
Expand Down
90 changes: 30 additions & 60 deletions functions/go/apply-setters/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,44 +9,26 @@ setting of field values.

<!--mdtogo-->

Setters are a safer alternative to other substitution techniques which do not have the context
of the structured data. Setters may be invoked to modify the package resources
using `apply-setters` function to set values.

### Synopsis

<!--mdtogo:Long-->

Package publishers declare setters in the package, consumers can set their values
either declaratively or imperatively.
Setters are a safer alternative to other substitution techniques which do not
have the context of the structured data. Setters may be invoked to modify the
package resources using `apply-setters` function to set desired values.

Setter names can be discovered in the pipeline section of Kptfile, and the values
can be declared next to setter names.
We use ConfigMap to configure the `apply-setters` function. The desired setter
values are provided as key-value pairs using `data` field where key is the name of the
setter and value is the new desired value for the setter.

```yaml
apiVersion: v1alpha2
kind: Kptfile
apiVersion: v1
kind: ConfigMap
metadata:
name: my-pkg
pipeline:
mutators:
- image: gcr.io/kpt-fn/apply-setters:unstable
configMap:
setter_name1: setter-value1
setter_name2: setter-value2
```
The declared values for setters are rendered by invoking the following command:
```
kpt fn render [PKG_PATH]
```

Alternatively, this function can be invoked imperatively on the package by passing the
inputs as key-value pairs.

```
kpt fn eval --image gcr.io/kpt-fn/apply-setters:VERSION [PKG_PATH] -- [setter_name=setter_value]
name: my-func-config
data:
setter_name1: setter_value1
setter_name2: setter_value2
```
<!--mdtogo-->
Expand All @@ -68,31 +50,28 @@ spec:
replicas: 1 # kpt-set: ${replicas}
```
Discover the names of setters in the Kptfile and declare desired values.
Discover the names of setters in the function config file and declare desired values.
```yaml
apiVersion: v1alpha2
kind: Kptfile
apiVersion: v1
kind: ConfigMap
metadata:
name: my-pkg
pipeline:
mutators:
- image: gcr.io/kpt-fn/apply-setters:unstable
configMap:
image: ubuntu
replicas: 3
name: apply-setters-fn-config
data:
image: ubuntu
replicas: "3"
```
Render the declared values by invoking:
```
kpt fn render
kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable --fn-config ./apply-setters-fn-config
```

Alternatively, values can be rendered imperatively
Alternatively, setter values can be passed as key-value pairs in the CLI

```
kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable -- 'replicas=3'
kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable -- 'image=ubuntu' 'replicas=3'
```

Rendered resource looks like the following:
Expand Down Expand Up @@ -127,29 +106,20 @@ environments: # kpt-set: ${env}
Declare the desired array values, wrapped into string.
```yaml
apiVersion: v1alpha2
kind: Kptfile
apiVersion: v1
kind: ConfigMap
metadata:
name: my-pkg
pipeline:
mutators:
- image: gcr.io/kpt-fn/apply-setters:unstable
configMap:
env: |
- prod
- dev
name: apply-setters-fn-config
data:
env: |
- prod
- dev
```
Render the declared values by invoking:
```
kpt fn render
```

Alternatively, values can be rendered imperatively

```
kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable -- 'env=[prod, dev]'
kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable --fn-config ./apply-setters-fn-config
```

Rendered resource looks like the following:
Expand Down
80 changes: 30 additions & 50 deletions functions/go/apply-setters/generated/docs.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 7842481

Please sign in to comment.