kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-11 17:12:51 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Merge pull request #2728 from prachirp/markdownlint

Browse Source 
Docs: Auto-fix markdownlint issues
This commit is contained in:
Jeff Regan
2020-07-21 16:56:45 -07:00
committed by GitHub
parent 0f7aae38e3 f9ee578aed
commit 95fb639fa8
76 changed files with 308 additions and 304 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
site/content/en/guides/plugins/_index.md
View File

@@ -18,14 +18,14 @@ or [transformer configs] doesn't meet your needs.
[12-factor]: https://12factor.net
* A _generator_ plugin could be a helm chart
* A _generator_ plugin could be a helm chart
inflator, or a plugin that emits all the
components (deployment, service, scaler,
ingress, etc.) needed by someone's [12-factor]
application, based on a smaller number of free
variables.
* A _transformer_ plugin might perform special
* A _transformer_ plugin might perform special
container command line edits, or any other
transformation beyond those provided by the
builtin (`namePrefix`, `commonLabels`, etc.)
@@ -63,7 +63,6 @@ in-process kustomization run. Each of the
resulting objects is now further interpreted by
kustomize as a _plugin configuration_ object.
## Configuration
A kustomization file could have the following lines:
@@ -112,7 +111,6 @@ browse the unit tests below the [plugins] root,
e.g. the tests for [ChartInflator] or
[NameTransformer].
## Placement
Each plugin gets its own dedicated directory named
@@ -228,11 +226,11 @@ provided in the kustomization file).
#### Examples
* [helm chart inflator] - A generator that inflates a helm chart.
* [bashed config map] - Super simple configMap generation from bash.
* [sed transformer] - Define your unstructured edits using a
* [helm chart inflator] - A generator that inflates a helm chart.
* [bashed config map] - Super simple configMap generation from bash.
* [sed transformer] - Define your unstructured edits using a
plugin like this one.
* [hashicorp go-getter] - Download kustomize layes and build it to generate resources
* [hashicorp go-getter] - Download kustomize layes and build it to generate resources
A generator plugin accepts nothing on `stdin`, but emits
generated resources to `stdout`.
@@ -247,7 +245,7 @@ marshalled resources on `stdin` and capture
#### Generator Options
A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations.
A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations.
> NOTE: These annotations are local to kustomize and will not be included in the final output.
@@ -258,6 +256,7 @@ Resources can be marked as needing to be processed by the internal hash transfor
If this annotation is set on a resource not supported by the hash transformer the build will fail.
Example:
```yaml
apiVersion: v1
kind: ConfigMap
@@ -266,14 +265,15 @@ metadata:
annotations:
kustomize.config.k8s.io/needs-hash: "true"
data:
foo: bar
foo: bar
```
**`kustomize.config.k8s.io/behavior`**
The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default.
The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default.
Example:
```yaml
apiVersion: v1
kind: ConfigMap
@@ -282,7 +282,7 @@ metadata:
annotations:
kustomize.config.k8s.io/behavior: "merge"
data:
foo: bar
foo: bar
```
### Go plugins
@@ -306,7 +306,7 @@ A Go plugin for kustomize looks like this:
> package main
>
> import (
> "sigs.k8s.io/kustomize/api/resmap"
> "sigs.k8s.io/kustomize/api/resmap"
> ...
> )
>
@@ -342,17 +342,17 @@ Do one or the other or both as desired.
#### Examples
* [service generator] - generate a service from a name and port argument.
* [string prefixer] - uses the value in `metadata/name` as the prefix.
* [service generator] - generate a service from a name and port argument.
* [string prefixer] - uses the value in `metadata/name` as the prefix.
This particular example exists to show how a plugin can
transform the behavior of a plugin. See the
`TestTransformedTransformers` test in the `target` package.
* [date prefixer] - prefix the current date to resource names, a simple
* [date prefixer] - prefix the current date to resource names, a simple
example used to modify the string prefixer plugin just mentioned.
* [secret generator] - generate secrets from a toy database.
* [sops encoded secrets] - a more complex secret generator that converts SOPS files into Kubernetes Secrets
* [SOPSGenerator] - another generator that decrypts SOPS files into Secrets
* [All the builtin plugins](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin).
* [secret generator] - generate secrets from a toy database.
* [sops encoded secrets] - a more complex secret generator that converts SOPS files into Kubernetes Secrets
* [SOPSGenerator] - another generator that decrypts SOPS files into Secrets
* [All the builtin plugins](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin).
User authored plugins are
on the same footing as builtin operations.
@@ -372,4 +372,3 @@ d=$XDG_CONFIG_HOME/kustomize/plugin\
go build -buildmode plugin \
-o $d/${kind}.so $d/${kind}.go
```

85
site/content/en/guides/plugins/builtins.md
View File

@@ -16,7 +16,7 @@ For each plugin, an example is given for
* implicitly triggering
the plugin via a dedicated kustomization
file field (e.g. the `AnnotationsTransformer` is
file field (e.g. the `AnnotationsTransformer` is
triggered by the `commonAnnotations` field).
* explicitly triggering the plugin
@@ -24,12 +24,11 @@ via the `generators` or `transformers` field
(by providing a config file specifying the
plugin).
The former method is convenient but limited in
The former method is convenient but limited in
power as most of the plugins arguments must
be defaulted. The latter method allows for
complete plugin argument specification.
[types.GeneratorOptions]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/generatoroptions.go
[types.SecretArgs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/secretargs.go
[types.ConfigMapArgs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/configmapargs.go
@@ -42,6 +41,7 @@ complete plugin argument specification.
[image.Image]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/image.go
## _AnnotationTransformer_
### Usage via `kustomization.yaml`
#### field name: `commonAnnotations`
@@ -56,6 +56,7 @@ commonAnnotations:
```
### Usage via plugin
#### Arguments
> Annotations map\[string\]string
@@ -63,6 +64,7 @@ commonAnnotations:
> FieldSpecs \[\][config.FieldSpec]
#### Example
>
> ```
> apiVersion: builtin
> kind: AnnotationsTransformer
@@ -76,8 +78,6 @@ commonAnnotations:
> create: true
> ```
## _ConfigMapGenerator_
### Usage via `kustomization.yaml`
@@ -122,7 +122,7 @@ configMapGenerator:
- application.properties
- more.properties
- name: my-java-server-env-vars
literals:
literals:
- JAVA_HOME=/opt/java/jdk
- JAVA_TOOL_OPTIONS=-agentlib:hprof
options:
@@ -156,11 +156,13 @@ configMapGenerator:
```
### Usage via plugin
#### Arguments
> [types.ConfigMapArgs]
#### Example
>
> ```
> apiVersion: builtin
> kind: ConfigMapGenerator
@@ -174,8 +176,8 @@ configMapGenerator:
> - VEGETABLE=carrot
> ```
## _ImageTagTransformer_
### Usage via `kustomization.yaml`
#### field name: `images`
@@ -197,11 +199,11 @@ containers:
```
one can change the `image` in the following ways:
- `postgres:8` to `my-registry/my-postgres:v1`,
- nginx tag `1.7.9` to `1.8.0`,
- image name `my-demo-app` to `my-app`,
- alpine's tag `3.7` to a digest value
- `postgres:8` to `my-registry/my-postgres:v1`,
- nginx tag `1.7.9` to `1.8.0`,
- image name `my-demo-app` to `my-app`,
- alpine's tag `3.7` to a digest value
all with the following *kustomization*:
@@ -219,6 +221,7 @@ images:
```
### Usage via plugin
#### Arguments
> ImageTag [image.Image]
@@ -226,6 +229,7 @@ images:
> FieldSpecs \[\][config.FieldSpec]
#### Example
>
> ```
> apiVersion: builtin
> kind: ImageTagTransformer
@@ -236,9 +240,8 @@ images:
> newTag: v2
> ```
## _LabelTransformer_
### Usage via `kustomization.yaml`
#### field name: `commonLabels`
@@ -253,6 +256,7 @@ commonLabels:
```
### Usage via plugin
#### Arguments
> Labels map\[string\]string
@@ -260,6 +264,7 @@ commonLabels:
> FieldSpecs \[\][config.FieldSpec]
#### Example
>
> ```
> apiVersion: builtin
> kind: LabelTransformer
@@ -273,14 +278,8 @@ commonLabels:
> create: true
> ```
## _NamespaceTransformer_
### Usage via `kustomization.yaml`
#### field name: `namespace`
@@ -292,6 +291,7 @@ namespace: my-namespace
```
### Usage via plugin
#### Arguments
> [types.ObjectMeta]
@@ -299,6 +299,7 @@ namespace: my-namespace
> FieldSpecs \[\][config.FieldSpec]
#### Example
>
> ```
> apiVersion: builtin
> kind: NamespaceTransformer
@@ -316,11 +317,8 @@ namespace: my-namespace
> group: rbac.authorization.k8s.io
> ```
## _PatchesJson6902_
### Usage via `kustomization.yaml`
#### field name: `patchesJson6902`
@@ -328,7 +326,7 @@ namespace: my-namespace
Each entry in this list should resolve to
a kubernetes object and a JSON patch that will be applied
to the object.
The JSON patch is documented at https://tools.ietf.org/html/rfc6902
The JSON patch is documented at <https://tools.ietf.org/html/rfc6902>
target field points to a kubernetes object within the same kustomization
by the object's group, version, kind, name and namespace.
@@ -385,7 +383,9 @@ patchesJson6902:
```
### Usage via plugin
#### Arguments
> Target [types.PatchTarget]
>
> Path string
@@ -393,6 +393,7 @@ patchesJson6902:
> JsonOp string
#### Example
>
> ```
> apiVersion: builtin
> kind: PatchJson6902Transformer
@@ -406,8 +407,8 @@ patchesJson6902:
> path: jsonpatch.json
> ```
## _PatchesStrategicMerge_
### Usage via `kustomization.yaml`
#### field name: `patchesStrategicMerge`
@@ -435,6 +436,7 @@ patchesStrategicMerge:
```
The patch content can be a inline string as well.
```
patchesStrategicMerge:
- |-
@@ -463,8 +465,8 @@ patch that performs all the needed deletions.
>
> Patches string
#### Example
>
> ```
> apiVersion: builtin
> kind: PatchStrategicMergeTransformer
@@ -474,14 +476,14 @@ patch that performs all the needed deletions.
> - patch.yaml
> ```
## _PatchTransformer_
### Usage via `kustomization.yaml`
#### field name: `patches`
Each entry in this list should resolve to an Patch
object, which includes a patch and a target selector.
object, which includes a patch and a target selector.
The patch can be either a strategic merge patch or a
JSON patch. it can be either a patch file or an inline
string. The target selects
@@ -506,23 +508,25 @@ patches:
value: new value
target:
kind: MyKind
labelSelector: "env=dev"
labelSelector: "env=dev"
```
The `name` and `namespace` fields of the patch target selector are
automatically anchored regular expressions. This means that the value `myapp`
is equivalent to `^myapp$`.
is equivalent to `^myapp$`.
### Usage via plugin
#### Arguments
> Path string
>
> Patch string
>
> Target \*[types.Selector]
> Target \*[types.Selector]
#### Example
>
> ```
> apiVersion: builtin
> kind: PatchTransformer
@@ -534,10 +538,8 @@ is equivalent to `^myapp$`.
> kind: Deployment
> ```
## _PrefixSuffixTransformer_
### Usage via `kustomization.yaml`
#### field names: `namePrefix`, `nameSuffix`
@@ -547,7 +549,7 @@ of all resources.
E.g. a deployment named `wordpress` could
become `alices-wordpress` or `wordpress-v2`
or `alices-wordpress-v2`.
or `alices-wordpress-v2`.
```
namePrefix: alices-
@@ -558,6 +560,7 @@ The suffix is appended before the content hash if
the resource type is ConfigMap or Secret.
### Usage via plugin
#### Arguments
> Prefix string
@@ -567,6 +570,7 @@ the resource type is ConfigMap or Secret.
> FieldSpecs \[\][config.FieldSpec]
#### Example
>
> ```
> apiVersion: builtin
> kind: PrefixSuffixTransformer
@@ -578,9 +582,8 @@ the resource type is ConfigMap or Secret.
> - path: metadata/name
> ```
## _ReplicaCountTransformer_
### Usage via `kustomization.yaml`
#### field name: `replicas`
@@ -612,6 +615,7 @@ be modified at the same time.
As this declaration does not take in a `kind:` nor a `group:`
it will match any `group` and `kind` that has a matching name and
that is one of:
- `Deployment`
- `ReplicationController`
- `ReplicaSet`
@@ -628,6 +632,7 @@ For more complex use cases, revert to using a patch.
> FieldSpecs \[\][config.FieldSpec]
#### Example
>
> ```
> apiVersion: builtin
> kind: ReplicaCountTransformer
@@ -645,8 +650,6 @@ For more complex use cases, revert to using a patch.
> kind: ReplicationController
> ```
## _SecretGenerator_
### Usage via `kustomization.yaml`

8
site/content/en/guides/plugins/execPluginGuidedExample.md
View File

@@ -18,8 +18,7 @@ current setup.
#### requirements
* linux, git, curl, Go 1.13
* linux, git, curl, Go 1.13
## Make a place to work
@@ -128,11 +127,11 @@ EOF
```
Review the files
```
ls -C1 $MYAPP
```
## Make a home for plugins
Plugins must live in a particular place for
@@ -205,6 +204,7 @@ chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator
## Install kustomize
Per the [instructions](/kustomize/installation):
```
curl -s "https://raw.githubusercontent.com/\
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
@@ -218,7 +218,7 @@ mv kustomize $DEMO/bin
tree $DEMO
```
## Build your app, using the plugin:
## Build your app, using the plugin
```
XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP

8
site/content/en/guides/plugins/goPluginCaveats.md
View File

@@ -57,6 +57,7 @@ accepting a shared plugin _must compile both
kustomize and the plugin_.
This means a one-time run of
```
# Or whatever is appropriate at time of reading
GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api
@@ -68,16 +69,17 @@ and then a normal development cycle using
go build -buildmode plugin \
-o ${wherever}/${kind}.so ${wherever}/${kind}.go
```
with paths and the release version tag (e.g. `v3.0.0`)
adjusted as needed.
For comparison, consider what one
must do to write a [tensorflow plugin].
## Why support Go plugins?
## Why support Go plugins
### Safety
The Go plugin developer sees the same API offered
to native kustomize operations, assuring certain
semantics, invariants, checks, etc. An exec
@@ -104,7 +106,7 @@ a developer can write an `.go` program that functions
as an _exec plugin_, but can be processed by `go generate`
to emit a _Go plugin_ (or vice versa).
### Unit of contribution
### Unit of contribution
All the builtin generators and transformers
are themselves Go plugins. This means that

8
site/content/en/guides/plugins/goPluginGuidedExample.md
View File

@@ -102,7 +102,7 @@ PLUGIN_ROOT=$DEMO/kustomize/plugin
and ephemerally set `XDG_CONFIG_HOME` on a command
line below.
### What apiVersion and kind?
### What apiVersion and kind
At this stage in the development of kustomize
plugins, plugin code doesn't know or care what
@@ -180,12 +180,12 @@ dependency [skew].
On load failure
* be sure to build the plugin with the same
* be sure to build the plugin with the same
version of Go (_go1.13_) on the same `$GOOS`
(_linux_) and `$GOARCH` (_amd64_) used to build
the kustomize being [used in this demo].
* change the plugin's dependencies in its `go.mod`
* change the plugin's dependencies in its `go.mod`
to match the versions used by kustomize (check
kustomize's `go.mod` used in its tagged commit).
@@ -356,7 +356,7 @@ This should look something like:
> └── secGenerator.yaml
> ```
## Build your app, using the plugin:
## Build your app, using the plugin
```shell
XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP