From e19ca5405a3002a5e9fe1d3f895ddb4a86f7e31d Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Mon, 4 Sep 2023 23:17:02 +0900 Subject: [PATCH 1/8] docs: setup API section with cli-experimental site --- go.work.sum | 2 +- site/content/en/docs/Reference/API/bases.md | 24 ++ .../en/docs/Reference/API/buildMetadata.md | 316 ++++++++++++++ .../docs/Reference/API/commonAnnotations.md | 58 +++ .../en/docs/Reference/API/commonLabels.md | 107 +++++ .../en/docs/Reference/API/components.md | 11 + .../docs/Reference/API/configMapGenerator.md | 359 ++++++++++++++++ site/content/en/docs/Reference/API/crds.md | 41 ++ .../en/docs/Reference/API/generatorOptions.md | 117 ++++++ .../en/docs/Reference/API/helmCharts.md | 46 +++ site/content/en/docs/Reference/API/images.md | 169 ++++++++ site/content/en/docs/Reference/API/labels.md | 237 +++++++++++ .../en/docs/Reference/API/namePrefix.md | 64 +++ .../en/docs/Reference/API/nameSuffix.md | 57 +++ .../en/docs/Reference/API/namespace.md | 58 +++ site/content/en/docs/Reference/API/openapi.md | 217 ++++++++++ site/content/en/docs/Reference/API/patches.md | 280 +++++++++++++ .../Reference/API/patchesStrategicMerge.md | 80 ++++ .../en/docs/Reference/API/patchesjson6902.md | 111 +++++ .../en/docs/Reference/API/replacements.md | 387 ++++++++++++++++++ .../content/en/docs/Reference/API/replicas.md | 90 ++++ .../en/docs/Reference/API/resources.md | 35 ++ .../en/docs/Reference/API/secretGenerator.md | 95 +++++ .../en/docs/Reference/API/sortOptions.md | 118 ++++++ site/content/en/docs/Reference/API/vars.md | 335 +++++++++++++++ 25 files changed, 3413 insertions(+), 1 deletion(-) create mode 100644 site/content/en/docs/Reference/API/bases.md create mode 100644 site/content/en/docs/Reference/API/buildMetadata.md create mode 100644 site/content/en/docs/Reference/API/commonAnnotations.md create mode 100644 site/content/en/docs/Reference/API/commonLabels.md create mode 100644 site/content/en/docs/Reference/API/components.md create mode 100644 site/content/en/docs/Reference/API/configMapGenerator.md create mode 100644 site/content/en/docs/Reference/API/crds.md create mode 100644 site/content/en/docs/Reference/API/generatorOptions.md create mode 100644 site/content/en/docs/Reference/API/helmCharts.md create mode 100644 site/content/en/docs/Reference/API/images.md create mode 100644 site/content/en/docs/Reference/API/labels.md create mode 100644 site/content/en/docs/Reference/API/namePrefix.md create mode 100644 site/content/en/docs/Reference/API/nameSuffix.md create mode 100644 site/content/en/docs/Reference/API/namespace.md create mode 100644 site/content/en/docs/Reference/API/openapi.md create mode 100644 site/content/en/docs/Reference/API/patches.md create mode 100644 site/content/en/docs/Reference/API/patchesStrategicMerge.md create mode 100644 site/content/en/docs/Reference/API/patchesjson6902.md create mode 100644 site/content/en/docs/Reference/API/replacements.md create mode 100644 site/content/en/docs/Reference/API/replicas.md create mode 100644 site/content/en/docs/Reference/API/resources.md create mode 100644 site/content/en/docs/Reference/API/secretGenerator.md create mode 100644 site/content/en/docs/Reference/API/sortOptions.md create mode 100644 site/content/en/docs/Reference/API/vars.md diff --git a/go.work.sum b/go.work.sum index a917eea926..905151d34e 100644 --- a/go.work.sum +++ b/go.work.sum @@ -7,6 +7,7 @@ github.com/evanphx/json-patch v5.6.0+incompatible h1:jBYDEEiFBPxA0v50tFdvOzQQTCv github.com/evanphx/json-patch v5.6.0+incompatible/go.mod h1:50XU6AFN0ol/bzJsmQLiYLvXMP4fmwYFNcr97nuDLSk= github.com/fsnotify/fsnotify v1.4.9 h1:hsms1Qyu0jgnwNXIxa+/V/PDsU6CfLf6CNO8H7IWoS4= github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE= +github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da h1:oI5xCqsCo564l8iNU+DwB5epxmsaqB+rhGL0m5jtYqE= github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc= github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= github.com/google/pprof v0.0.0-20210720184732-4bb14d4b1be1/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= @@ -45,7 +46,6 @@ golang.org/x/tools v0.4.0/go.mod h1:UE5sM2OK9E/d67R0ANs2xJizIymRP5gJU295PvKXxjQ= golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= golang.org/x/tools v0.7.0/go.mod h1:4pg6aUX35JBAogB10C9AtvVL+qowtN4pT3CGSQex14s= golang.org/x/xerrors v0.0.0-20220907171357-04be3eba64a2/go.mod h1:K8+ghG5WaK9qNqU5K3HdILfMLy1f3aNYFI/wnl100a8= -golang.org/x/xerrors v0.0.0-20220907171357-04be3eba64a2/go.mod h1:K8+ghG5WaK9qNqU5K3HdILfMLy1f3aNYFI/wnl100a8= google.golang.org/protobuf v1.28.1/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I= gopkg.in/ini.v1 v1.51.0 h1:AQvPpx3LzTDM0AjnIRlVFwFFGC+npRopjZxLJj6gdno= k8s.io/klog v1.0.0 h1:Pt+yjF5aB1xDSVbau4VsWe+dQNzA0qv1LlXdC2dF6Q8= diff --git a/site/content/en/docs/Reference/API/bases.md b/site/content/en/docs/Reference/API/bases.md new file mode 100644 index 0000000000..519e29469a --- /dev/null +++ b/site/content/en/docs/Reference/API/bases.md @@ -0,0 +1,24 @@ +--- +title: "bases" +linkTitle: "bases" +type: docs +weight: 1 +description: > + Add resources from a kustomization dir. +--- + +{{% pageinfo color="warning" %}} +The `bases` field was deprecated in v2.1.0. This field will never be removed from the +kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included +in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available, +we will announce the deprecation of the v1beta1 version. There will be at least +two releases between deprecation and removal of Kustomization v1beta1 support from the +kustomize CLI, and removal itself will happen in a future major version bump. + +You can run `kustomize edit fix` to automatically convert `bases` to `resources`. +{{% /pageinfo %}} + +Move entries into the [resources](/references/kustomize/kustomization/resource) +field. This allows bases - which are still a +[central concept](/references/kustomize/glossary#base) - to be +ordered relative to other input resources. diff --git a/site/content/en/docs/Reference/API/buildMetadata.md b/site/content/en/docs/Reference/API/buildMetadata.md new file mode 100644 index 0000000000..4383c4336a --- /dev/null +++ b/site/content/en/docs/Reference/API/buildMetadata.md @@ -0,0 +1,316 @@ +--- +title: "buildMetadata" +linkTitle: "buildMetadata" +type: docs +weight: 2 +description: > + Specify options for including information about the build in annotations or labels. +--- + +The `buildMetadata` field is a list of strings. The strings can be one of three builtin +options that add some metadata to each resource about how the resource was built. + +These options are: + +- `managedByLabel` +- `originAnnotations` +- `transformerAnnotations` + +It is possible to set one or all of these options in the kustomization file: + +```yaml +buildMetadata: [managedByLabel, originAnnotations, transformerAnnotations] +``` + +### Managed By Label +To mark the resource as having been managed by kustomize, you can specify the `managedByLabel` +option in the `buildMetadata` field of the kustomization: + +```yaml +buildMetadata: [managedByLabel] +``` + +This will add the label `app.kubernetes.io/managed-by` to each resource with the version of kustomize +that has built it. For example, given the following input: + +kustomization.yaml +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +resources: +- service.yaml +buildMetadata: [managedByLabel] +``` + +service.yaml +```yaml +apiVersion: v1 +kind: Service +metadata: + name: myService +spec: + ports: + - port: 7002 +``` + +`kustomize build` will produce a resource with an output like the following: + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/managed-by: kustomize-v4.4.1 + name: myService +spec: + ports: + - port: 7002 +``` + + +### Origin Annotation +To annotate resources with information about their origin, you can specify the `originAnnotations`: + +```yaml +buildMetadata: [originAnnotations] +``` + +When this option is set, generated resources will receive an annotation with key `config.kubernetes.io/origin`, +containing data about the generator that produced it. If the resource is from the `resources` field, this annotation +contains data about the file it originated from. + +The possible fields of these annotations are: + +- `path`: The path to a resource file itself +- `ref`: If from a remote file or generator, the ref of the repo URL. +- `repo`: If from a remote file or generator, the repo source +- `configuredIn`: If a generated resource, the path to the generator config. If a generator is invoked via a field +in the kustomization file, this would point to the kustomization file itself. +- `configuredBy`: If a generated resource, the ObjectReference of the generator config. + + +All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon +which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths +in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the +remote repository. Any fields that are not applicable would be omitted from the final output. + +Here is an example of what this would look like: +```yaml +config.kubernetes.io/origin: | + path: path.yaml + ref: v0.0.0 + repo: http://github.com/examplerepo + configuredIn: path/to/generatorconfig + configuredBy: + kind: Generator + apiVersion: builtin + name: foo + namespace: default +``` + +#### Examples + +##### Resource declared from `resources` +A kustomization such as the following: + +```yaml +resources: +- deployment.yaml + +buildMetadata: [originAnnotations] +``` + +would produce a resource with an annotation like the following: + +```yaml +config.kubernetes.io/origin: | + path: deployment.yaml +``` + +##### Local custom generator +A kustomization such as the following: + +```yaml +generators: +- generator.yaml + +buildMetadata: [originAnnotations] +``` + +would produce a resource with an annotation like the following: + +```yaml +config.kubernetes.io/origin: | + configuredIn: generator.yaml + configuredBy: + kind: MyGenerator + apiVersion: v1 + name: generator +``` + +##### Remote builtin generator +We have a top-level kustomization such as the following: + +```yaml +resources: +- github.com/examplerepo/?ref=v1.0.6 + +buildMetadata: [originAnnotations] +``` + +which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization +defined in `github.com/examplerepo/kustomization.yaml`: + +```yaml +configMapGenerator: +- name: my-java-server-env-vars + literals: + - JAVA_HOME=/opt/java/jdk + - JAVA_TOOL_OPTIONS=-agentlib:hprof +``` + +Running `kustomize build` on the top-level kustomization would produce the following output: + +```yaml +apiVersion: v1 +data: + JAVA_HOME: /opt/java/jdk + JAVA_TOOL_OPTIONS: -agentlib:hprof +kind: ConfigMap +metadata: + name: my-java-server-env-vars-44k658k8gk + annotations: + config.kubernetes.io/origin: | + ref: v1.0.6 + repo: github.com/examplerepo + configuredIn: kustomization.yaml + configuredBy: + kind: ConfigMapGenerator + apiVersion: builtin +``` + +### Transformer Annotations [Alpha] + +To annotate resources with information about the transformers that have acted on them, you can add the +`transformerAnnotations` option to the `buildMetadata` field of the kustomization: + +```yaml +buildMetadata: [transformerAnnotations] +``` + +When the `transformerAnnotations` option is set, kustomize will add annotations with information about what transformers +have acted on each resource. Transformers can be invoked either through various fields in the kustomization file +(e.g. the `replacements` field will invoke the ReplacementTransformer), or through the `transformers` field. + +The annotation key for transformer annotations will be `config.kubernetes.io/transformations`, which will contain a list of +transformer data. The possible fields in each item in this list is identical to the possible fields in `config.kubernetes.io/origin`, +except that the transformer annotation does not have a `path` field: + +The possible fields of these annotations are: + +- `path`: The path to a resource file itself +- `ref`: If from a remote file or generator, the ref of the repo URL. +- `repo`: If from a remote file or generator, the repo source +- `configuredIn`: The path to the transformer config. If a transformer is invoked via a field +in the kustomization file, this would point to the kustomization file itself. +- `configuredBy`: The ObjectReference of the transformer config. + +All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon +which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths +in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the +remote repository. Any fields that are not applicable would be omitted from the final output. + +Here is an example of what this would look like: +```yaml +config.kubernetes.io/transformations: | + - ref: v0.0.0 + repo: http://github.com/examplerepo + configuredIn: path/to/transformerconfig + configuredBy: + kind: Transformer + apiVersion: builtin + name: foo + namespace: default +``` + + +While this field is in alpha, it will receive the `alpha` prefix, so you will see the annotation key +`alpha.config.kubernetes.io/transformations` instead. We are not guaranteeing that the annotation content will be stable during +alpha, and reserve the right to make changes as we evolve the feature. + + +#### Examples + +#### Local custom transformer +A kustomization such as the following: + +```yaml +transformers: +- transformer.yaml + +buildMetadata: [transformerAnnotations] + +``` + +would produce a resource with an annotation like the following: + +```yaml +config.kubernetes.io/transformations: | +- configuredIn: transformer.yaml + configuredBy: + kind: MyTransformer + apiVersion: v1 + name: transformer +``` + +##### Remote builtin transformer + local builtin transformer +We have a top-level kustomization such as the following: + +```yaml +resources: +- github.com/examplerepo/?ref=v1.0.6 + +buildMetadata: [transformerAnnotations] + +namespace: my-ns +``` + +which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization +defined in `github.com/examplerepo/kustomization.yaml`: + +```yaml +resources: +- deployment.yaml + +namePrefix: pre- +``` + +`deployment.yaml` contains the following: + +```yaml +apiVersion: v1 +kind: Deployment +metadata: + name: deploy +``` + +Running `kustomize build` on the top-level kustomization would produce the following output: + +```yaml +apiVersion: v1 +kind: Deployment +metadata: + name: pre-deploy + annotations: + config.kubernetes.io/transformations: | + - ref: v1.0.6 + repo: github.com/examplerepo + configuredIn: kustomization.yaml + configuredBy: + kind: PrefixSuffixTransformer + apiVersion: builtin + - configuredIn: kustomization.yaml + configuredBy: + kind: NamespaceTransformer + apiVersion: builtin +``` diff --git a/site/content/en/docs/Reference/API/commonAnnotations.md b/site/content/en/docs/Reference/API/commonAnnotations.md new file mode 100644 index 0000000000..db4230e9d3 --- /dev/null +++ b/site/content/en/docs/Reference/API/commonAnnotations.md @@ -0,0 +1,58 @@ +--- +title: "commonAnnotations" +linkTitle: "commonAnnotations" +type: docs +weight: 3 +description: > + Add annotations to add all resources. +--- + +Add annotations to all resources. If the annotation key already is present on the resource, +the value will be overridden. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +commonAnnotations: + oncallPager: 800-555-1212 +``` + +## Example + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +commonAnnotations: + oncallPager: 800-555-1212 + +resources: +- deploy.yaml +``` + +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + ... +``` + +### Build Output + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example + annotations: + oncallPager: 800-555-1212 +spec: + ... +``` diff --git a/site/content/en/docs/Reference/API/commonLabels.md b/site/content/en/docs/Reference/API/commonLabels.md new file mode 100644 index 0000000000..3c57b95809 --- /dev/null +++ b/site/content/en/docs/Reference/API/commonLabels.md @@ -0,0 +1,107 @@ +--- +title: "commonLabels" +linkTitle: "commonLabels" +type: docs +weight: 4 +description: > + Add labels and selectors to add all resources. +--- + +[labels]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/labels/ + +Add labels and selectors to all resources. If the label key already is present on the resource, +the value will be overridden. + +An alternative to this field is the [labels] field, which allows adding labels without also automatically +injecting corresponding selectors. + +{{% pageinfo color="warning" %}} +Selectors for resources such as Deployments and Services shouldn't be changed once the +resource has been applied to a cluster. + +Changing commonLabels to live resources could result in failures. +{{% /pageinfo %}} + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +commonLabels: + someName: someValue + owner: alice + app: bingo +``` + +## Example + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +commonLabels: + someName: someValue + owner: alice + app: bingo + +resources: +- deploy.yaml +- service.yaml +``` + +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +### Build Output + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +spec: + selector: + app: bingo + owner: alice + someName: someValue +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +spec: + selector: + matchLabels: + app: bingo + owner: alice + someName: someValue + template: + metadata: + labels: + app: bingo + owner: alice + someName: someValue +``` diff --git a/site/content/en/docs/Reference/API/components.md b/site/content/en/docs/Reference/API/components.md new file mode 100644 index 0000000000..b682b670a3 --- /dev/null +++ b/site/content/en/docs/Reference/API/components.md @@ -0,0 +1,11 @@ +--- +title: "components" +linkTitle: "components" +type: docs +weight: 5 +description: > + Compose kustomizations. +--- + +Please check out the existing [components guide](/guides/config_management/components/) for explanation with examples. +More examples are in progress diff --git a/site/content/en/docs/Reference/API/configMapGenerator.md b/site/content/en/docs/Reference/API/configMapGenerator.md new file mode 100644 index 0000000000..02b04804ff --- /dev/null +++ b/site/content/en/docs/Reference/API/configMapGenerator.md @@ -0,0 +1,359 @@ +--- +title: "configMapGenerator" +linkTitle: "configMapGenerator" +type: docs +weight: 6 +description: > + Generate ConfigMap resources. +--- + +Each entry in this list results in the creation of +one ConfigMap resource (it's a generator of n maps). + +The example below creates four ConfigMaps: + +- first, with the names and contents of the given files +- second, with key/value as data using key/value pairs from files +- third, also with key/value as data, directly specified using `literals` +- and a fourth, which sets an annotation and label via `options` for that single ConfigMap + +Each configMapGenerator item accepts a parameter of +`behavior: [create|replace|merge]`. +This allows an overlay to modify or +replace an existing configMap from the parent. + +Also, each entry has an `options` field, that has the +same subfields as the kustomization file's `generatorOptions` field. + +This `options` field allows one to add labels and/or +annotations to the generated instance, or to individually +disable the name suffix hash for that instance. +Labels and annotations added here will not be overwritten +by the global options associated with the kustomization +file `generatorOptions` field. However, due to how +booleans behave, if the global `generatorOptions` field +specifies `disableNameSuffixHash: true`, this will +trump any attempt to locally override it. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +# These labels are added to all configmaps and secrets. +generatorOptions: + labels: + fruit: apple + +configMapGenerator: +- name: my-java-server-props + behavior: merge + files: + - application.properties + - more.properties +- name: my-java-server-env-file-vars + envs: + - my-server-env.properties + - more-server-props.env +- name: my-java-server-env-vars + literals: + - JAVA_HOME=/opt/java/jdk + - JAVA_TOOL_OPTIONS=-agentlib:hprof + options: + disableNameSuffixHash: true + labels: + pet: dog +- name: dashboards + files: + - mydashboard.json + options: + annotations: + dashboard: "1" + labels: + app.kubernetes.io/name: "app1" +``` + +It is also possible to +[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) +to set a name different than the filename. + +The example below creates a ConfigMap +with the name of file as `myFileName.ini` +while the _actual_ filename from which the +configmap is created is `whatever.ini`. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +configMapGenerator: +- name: app-whatever + files: + - myFileName.ini=whatever.ini +``` + +## ConfigMap `from File` + +ConfigMap Resources may be generated from files - such as a java `.properties` file. To generate a ConfigMap +Resource for a file, add an entry to `configMapGenerator` with the filename. + +**Example:** Generate a ConfigMap with a data item containing the contents of a file. + +The ConfigMaps will have data values populated from the file contents. The contents of each file will +appear as a single data item in the ConfigMap keyed by the filename. + +The example illustrates how you can create ConfigMaps from File using Generators. + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +configMapGenerator: +- name: my-application-properties + files: + - application.properties + +``` + +```yaml +# application.properties +FOO=Bar +``` + +### Build Output + +```yaml +apiVersion: v1 +data: + application.properties: |- + FOO=Bar +kind: ConfigMap +metadata: + name: my-application-properties-f7mm6mhf59 +``` + +## ConfigMap `from Literals` + +ConfigMap Resources may be generated from literal key-value pairs - such as `JAVA_HOME=/opt/java/jdk`. +To generate a ConfigMap Resource from literal key-value pairs, add an entry to `configMapGenerator` with a +list of `literals`. + +{{< alert color="success" title="Literal Syntax" >}} +- The key/value are separated by a `=` sign (left side is the key) +- The value of each literal will appear as a data item in the ConfigMap keyed by its key. +{{< /alert >}} + +**Example:** Create a ConfigMap with 2 data items generated from literals. + +The example illustrates how you can create ConfigMaps from Literals using Generators. + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +configMapGenerator: +- name: my-java-server-env-vars + literals: + - JAVA_HOME=/opt/java/jdk + - JAVA_TOOL_OPTIONS=-agentlib:hprof + +``` + +### Build Output + +```yaml +apiVersion: v1 +data: + JAVA_HOME: /opt/java/jdk + JAVA_TOOL_OPTIONS: -agentlib:hprof +kind: ConfigMap +metadata: + name: my-java-server-env-vars-44k658k8gk +``` + +## ConfigMap `from env file` + +ConfigMap Resources may be generated from key-value pairs much the same as using the literals option +but taking the key-value pairs from an environment file. These generally end in `.env`. +To generate a ConfigMap Resource from an environment file, add an entry to `configMapGenerator` with a +single `envs` entry, e.g. `envs: [ 'config.env' ]`. + +{{< alert color="success" title="Environment File Syntax" >}} +- The key/value pairs inside of the environment file are separated by a `=` sign (left side is the key) +- The value of each line will appear as a data item in the ConfigMap keyed by its key. +- Pairs may span a single line only. +{{< /alert >}} + +**Example:** Create a ConfigMap with 3 data items generated from an environment file. + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +configMapGenerator: +- name: tracing-options + envs: + - tracing.env +``` + +```bash +# tracing.env +ENABLE_TRACING=true +SAMPLER_TYPE=probabilistic +SAMPLER_PARAMETERS=0.1 +``` + +### Build Output + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + # The name has had a suffix applied + name: tracing-options-6bh8gkdf7k +# The data has been populated from each literal pair +data: + ENABLE_TRACING: "true" + SAMPLER_TYPE: "probabilistic" + SAMPLER_PARAMETERS: "0.1" +``` + +## Overriding Base ConfigMap Values + +ConfigMap values from bases may be overridden by adding another generator for the ConfigMap +in the overlay and specifying the `behavior` field. `behavior` may be +one of: +* `create` (default value): used to create a new ConfigMap. A name conflict error will be thrown if a ConfigMap with the same name and namespace already exists. +* `replace`: replace an existing ConfigMap from the base. +* `merge`: add or update the values in an existing ConfigMap from the base. + +When updating an existing ConfigMap with the `merge` or `replace` strategies, you must ensure that both the name and namespace match the ConfigMap you're targeting. For example, if the namespace is unspecified in the base, you should not specify it in the overlay. Conversely, if it is specified in the base, you must specify it in the overlay as well. This is true even if the overlay Kustomization includes a namespace, because configMapGenerator runs before the namespace transformer. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +namespace: my-new-namespace + +resources: +- ../base + +configMapGenerator: + - name: existing-name + namespace: existing-ns # needs to match target ConfigMap from base + behavior: replace + literals: + - ENV=dev +``` + +{{< alert color="warning" title="Name suffixing with overlay configMapGenerator" >}} +When using configMapGenerator to override values of an existing ConfigMap, the overlay configMapGenerator does not cause suffixing of the existing ConfigMap's name to occur. To take advantage of name suffixing, use configMapGenerator in the base, and the overlay generator will correctly update the suffix based on the new content. +{{< /alert >}} + +## Propagating the Name Suffix + +Workloads that reference the ConfigMap or Secret will need to know the name of the generated Resource, +including the suffix. Kustomize takes care of this automatically by identifying +references to generated ConfigMaps and Secrets, and updating them. + +In the following example, the generated ConfigMap name will be `my-java-server-env-vars` with a suffix unique to its contents. +Changes to the contents will change the name suffix, resulting in the creation of a new ConfigMap, +which Kustomize will transform Workloads to point to. + +The PodTemplate volume references the ConfigMap by the name specified in the generator (excluding the suffix). +Kustomize will update the name to include the suffix applied to the ConfigMap name. + +**Input:** The kustomization.yaml and deployment.yaml files + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +configMapGenerator: +- name: my-java-server-env-vars + literals: + - JAVA_HOME=/opt/java/jdk + - JAVA_TOOL_OPTIONS=-agentlib:hprof +resources: +- deployment.yaml +``` + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: test-deployment + labels: + app: test +spec: + selector: + matchLabels: + app: test + template: + metadata: + labels: + app: test + spec: + containers: + - name: container + image: registry.k8s.io/busybox + command: [ "/bin/sh", "-c", "ls /etc/config/" ] + volumeMounts: + - name: config-volume + mountPath: /etc/config + volumes: + - name: config-volume + configMap: + name: my-java-server-env-vars +``` + +**Result:** The output of the Kustomize build. + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + # The name has been updated to include the suffix + name: my-java-server-env-vars-k44mhd6h5f +data: + JAVA_HOME: /opt/java/jdk + JAVA_TOOL_OPTIONS: -agentlib:hprof +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: test + name: test-deployment +spec: + selector: + matchLabels: + app: test + template: + metadata: + labels: + app: test + spec: + containers: + - command: + - /bin/sh + - -c + - ls /etc/config/ + image: registry.k8s.io/busybox + name: container + volumeMounts: + - mountPath: /etc/config + name: config-volume + volumes: + - configMap: + # The name has been updated to include the + # suffix matching the ConfigMap + name: my-java-server-env-vars-k44mhd6h5f + name: config-volume +``` diff --git a/site/content/en/docs/Reference/API/crds.md b/site/content/en/docs/Reference/API/crds.md new file mode 100644 index 0000000000..7eda7ffddf --- /dev/null +++ b/site/content/en/docs/Reference/API/crds.md @@ -0,0 +1,41 @@ +--- +title: "crds" +linkTitle: "crds" +type: docs +weight: 7 +description: > + Adding CRD support +--- + +Each entry in this list should be a relative path to +a file for custom resource definition (CRD). + +The presence of this field is to allow kustomize be +aware of CRDs and apply proper +transformation for any objects in those types. + +Typical use case: A CRD object refers to a +ConfigMap object. In a kustomization, the ConfigMap +object name may change by adding namePrefix, +nameSuffix, or hashing. The name reference for this +ConfigMap object in CRD object need to be updated +with namePrefix, nameSuffix, or hashing in the +same way. + +The annotations can be put into openAPI definitions are: + +- "x-kubernetes-annotation": "" +- "x-kubernetes-label-selector": "" +- "x-kubernetes-identity": "" +- "x-kubernetes-object-ref-api-version": "v1", +- "x-kubernetes-object-ref-kind": "Secret", +- "x-kubernetes-object-ref-name-key": "name", + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +crds: +- crds/typeA.yaml +- crds/typeB.yaml +``` diff --git a/site/content/en/docs/Reference/API/generatorOptions.md b/site/content/en/docs/Reference/API/generatorOptions.md new file mode 100644 index 0000000000..58479d05ec --- /dev/null +++ b/site/content/en/docs/Reference/API/generatorOptions.md @@ -0,0 +1,117 @@ +--- +title: "generatorOptions" +linkTitle: "generatorOptions" +type: docs +weight: 8 +description: > + Control behavior of [ConfigMap]() and + [Secret]() generators. +--- + + + +Additionally, generatorOptions can be set on a per resource level within each +generator. For details on per-resource generatorOptions usage see +[field-name-configMapGenerator]() and See [field-name-secretGenerator](). + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +generatorOptions: + # labels to add to all generated resources + labels: + kustomize.generated.resources: somevalue + # annotations to add to all generated resources + annotations: + kustomize.generated.resource: somevalue + # disableNameSuffixHash is true disables the default behavior of adding a + # suffix to the names of generated resources that is a hash of + # the resource contents. + disableNameSuffixHash: true + # if set to true, the immutable property is added to generated resources + immutable: true +``` + +## Example I + +Using ConfigMap + +### Input Files + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +configMapGenerator: +- name: my-application-properties + files: + - application.properties +generatorOptions: + labels: + kustomize.generated.resources: config-label + annotations: + kustomize.generated.resource: config-annotation +``` + +```yaml +# application.properties +FOO=Bar +``` + +### Output File + +```yaml +apiVersion: v1 +data: + application.properties: |- + # application.properties + FOO=Bar +kind: ConfigMap +metadata: + annotations: + kustomize.generated.resource: config-annotation + labels: + kustomize.generated.resources: config-label + name: my-application-properties-f7mm6mhf59 +``` + +## Example II + +Using Secrets + +### Input Files + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +secretGenerator: +- name: app-tls + files: + - "tls.cert" + - "tls.key" + type: "kubernetes.io/tls" +generatorOptions: + labels: + kustomize.generated.resources: secret-label + annotations: + kustomize.generated.resource: secret-annotation + disableNameSuffixHash: true +``` + +### Output File + +```yaml +apiVersion: v1 +data: + tls.cert: TFMwdExTMUNSVWQuLi50Q2c9PQ== + tls.key: TFMwdExTMUNSVWQuLi4wdExRbz0= +kind: Secret +metadata: + annotations: + kustomize.generated.resource: secret-annotation + labels: + kustomize.generated.resources: secret-label + name: app-tls +type: kubernetes.io/tls +``` diff --git a/site/content/en/docs/Reference/API/helmCharts.md b/site/content/en/docs/Reference/API/helmCharts.md new file mode 100644 index 0000000000..2ed8522b68 --- /dev/null +++ b/site/content/en/docs/Reference/API/helmCharts.md @@ -0,0 +1,46 @@ +--- +title: "helmCharts" +linkTitle: "helmCharts" +type: docs +weight: 8 +description: > + Helm chart inflation generator. +--- + +[kustomize builtins]: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_helmchartinflationgenerator_ +[Helm support long term plan]: https://github.com/kubernetes-sigs/kustomize/issues/4401 + +## Helm Chart Inflation Generator + +Kustomize has limited support for helm chart inflation through the `helmCharts` field. +You can read a detailed description of this field in the docs about [kustomize builtins]. + +To enable the helm chart inflation generator, you have to specify the `enable-helm` flag as follows: + +```sh +kustomize build --enable-helm +``` + +## Long term support + +The helm chart inflation generator in kustomize is intended to be a limited subset of helm features to help with +getting started with kustomize, and we cannot support the entire helm feature set. + +### The current builtin +For enhancements to the helm chart inflation generator feature, we will only support the following changes: + +- bug fixes +- critical security issues +- additional fields that are analogous to flags passed to `helm template`, except for flags such as `post-renderer` + that allow arbitrary commands to be executed + +We will not add support for: + +- private repository or registry authentication +- OCI registries +- other large features that increase the complexity of the feature and/or have significant security implications + +### Future support +The next iteration of the helm inflation generator will take the form of a KRM function, which will have +no such restrictions on what types of features we can add and support. You can see more details in +the [Helm support long term plan]. diff --git a/site/content/en/docs/Reference/API/images.md b/site/content/en/docs/Reference/API/images.md new file mode 100644 index 0000000000..d2955bfa46 --- /dev/null +++ b/site/content/en/docs/Reference/API/images.md @@ -0,0 +1,169 @@ +--- +title: "images" +linkTitle: "images" +type: docs +weight: 9 +description: > + Modify the name, tags and/or digest for images. +--- + +Images modify the name, tags and/or digest for images without creating patches. + +One can change the `image` in the following ways (Refer the following example to know exactly how this is done): + +- `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 + +It is possible to set image tags for container images through +the `kustomization.yaml` using the `images` field. When `images` are +specified, Apply will override the images whose image name matches `name` with a new +tag. + + +| Field | Description | Example Field | Example Result | +|-----------|--------------------------------------------------------------------------|----------| --- | +| `name` | Match images with this image name| `name: nginx`| | +| `newTag` | Override the image **tag** or **digest** for images whose image name matches `name` | `newTag: new` | `nginx:old` -> `nginx:new` | +| `newName` | Override the image **name** for images whose image name matches `name` | `newName: nginx-special` | `nginx:old` -> `nginx-special:old` | + + +## Example + +### File Input + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + template: + spec: + containers: + - name: mypostgresdb + image: postgres:8 + - name: nginxapp + image: nginx:1.7.9 + - name: myapp + image: my-demo-app:latest + - name: alpine-app + image: alpine:3.7 + +``` + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +images: +- name: postgres + newName: my-registry/my-postgres + newTag: v1 +- name: nginx + newTag: 1.8.0 +- name: my-demo-app + newName: my-app +- name: alpine + digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 + +resources: +- deployment.yaml + +``` + +### Build Output + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + template: + spec: + containers: + - image: my-registry/my-postgres:v1 + name: mypostgresdb + - image: nginx:1.8.0 + name: nginxapp + - image: my-app:latest + name: myapp + - image: alpine@sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 + name: alpine-app +``` + +## Setting a Name + +The name for an image may be set by specifying `newName` and the name of the old container image. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +images: + - name: mycontainerregistry/myimage + newName: differentregistry/myimage +``` + +## Setting a Tag + +The tag for an image may be set by specifying `newTag` and the name of the container image. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +images: + - name: mycontainerregistry/myimage + newTag: v1 +``` + +## Setting a Digest + +The digest for an image may be set by specifying `digest` and the name of the container image. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +images: + - name: alpine + digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 +``` + + +## Setting a Tag from the latest commit SHA + +A common CI/CD pattern is to tag container images with the git commit SHA of source code. e.g. if +the image name is `foo` and an image was built for the source code at commit `1bb359ccce344ca5d263cd257958ea035c978fd3` +then the container image would be `foo:1bb359ccce344ca5d263cd257958ea035c978fd3`. + +A simple way to push an image that was just built without manually updating the image tags is to +download the [kustomize standalone](https://github.com/kubernetes-sigs/kustomize/) tool and run +`kustomize edit set image` command to update the tags for you. + +**Example:** Set the latest git commit SHA as the image tag for `foo` images. + +```bash +kustomize edit set image foo:$(git log -n 1 --pretty=format:"%H") +kubectl apply -f . +``` + +## Setting a Tag from an Environment Variable + +It is also possible to set a Tag from an environment variable using the same technique for setting from a commit SHA. + +**Example:** Set the tag for the `foo` image to the value in the environment variable `FOO_IMAGE_TAG`. + +```bash +kustomize edit set image foo:$FOO_IMAGE_TAG +kubectl apply -f . +``` + +{{< alert color="success" title="Committing Image Tag Updates" >}} +The `kustomization.yaml` changes *may* be committed back to git so that they +can be audited. When committing the image tag updates that have already +been pushed by a CI/CD system, be careful not to trigger new builds + +deployments for these changes. +{{< /alert >}} \ No newline at end of file diff --git a/site/content/en/docs/Reference/API/labels.md b/site/content/en/docs/Reference/API/labels.md new file mode 100644 index 0000000000..750fcaa905 --- /dev/null +++ b/site/content/en/docs/Reference/API/labels.md @@ -0,0 +1,237 @@ +--- +title: "labels" +linkTitle: "labels" +type: docs +weight: 10 +description: > + Add labels and optionally selectors to all resources. +--- + +A field that allows adding labels without also automatically injecting corresponding selectors. +This can be used instead of the `commonLabels` field, which always adds selectors. + +{{% pageinfo color="warning" %}} +Selectors for resources such as Deployments and Services shouldn't be changed once the +resource has been applied to a cluster. + +Changing `includeSelectors` to `true` or changing labels when `includeSelectors` is `true` in live resources +is equivalent to changing `commonLabels` and could result in failures. +{{% /pageinfo %}} + +The following flags are available: +* `includeTemplates`: When set will also apply labels to metadata/labels and spec/template/metadata/labels. This can be used to add labels to Pods from owner resources, such as Deployments and StatefulSets, without modifying selectors. False by default. +* `includeSelectors`: When set will apply labels to metadata/labels, selectors, and spec/template/metadata/labels. False by default. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +labels: + - pairs: + someName: someValue + owner: alice + app: bingo + includeSelectors: true # <-- false by default + includeTemplates: true # <-- false by default +``` + +## Example 1 - selectors and templates NOT modified + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +labels: + - pairs: + someName: someValue + owner: alice + app: bingo + +resources: +- deploy.yaml +- service.yaml +``` + +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +### Build Output + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +``` + + +## Example 2 - selectors modified + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +labels: + - pairs: + someName: someValue + owner: alice + app: bingo + includeSelectors: true + +resources: +- deploy.yaml +- service.yaml +``` + +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +### Build Output + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +spec: + selector: + app: bingo + owner: alice + someName: someValue +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +spec: + selector: + matchLabels: + app: bingo + owner: alice + someName: someValue + template: + metadata: + labels: + app: bingo + owner: alice + someName: someValue +``` + +## Example 3 - templates modified + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +labels: + - pairs: + someName: someValue + owner: alice + app: bingo + includeTemplates: true + +resources: +- deploy.yaml +- service.yaml +``` + +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +### Build Output + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: bingo + owner: alice + someName: someValue + name: example +spec: + template: + metadata: + labels: + app: bingo + owner: alice + someName: someValue +``` diff --git a/site/content/en/docs/Reference/API/namePrefix.md b/site/content/en/docs/Reference/API/namePrefix.md new file mode 100644 index 0000000000..256e55ef99 --- /dev/null +++ b/site/content/en/docs/Reference/API/namePrefix.md @@ -0,0 +1,64 @@ +--- +title: "namePrefix" +linkTitle: "namePrefix" +type: docs +weight: 11 +description: > + Prepends the value to the names of all resources and references. +--- + +As `namePrefix` is self explanatory, it helps adding prefix to names in the defined yaml files. + +## Example + +### File Input + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + replicas: 5 + template: + containers: + - name: the-container + image: registry/container:latest +``` + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +namePrefix: custom-prefix- + +resources: +- deployment.yaml + +``` + +### Build Output + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: custom-prefix-the-deployment +spec: + replicas: 5 + template: + containers: + - image: registry/container:latest + name: the-container +``` + +{{< alert color="success" title="References" >}} +Apply will propagate the `namePrefix` to any place Resources within the project are referenced by other Resources +including: + +- Service references from StatefulSets +- ConfigMap references from PodSpecs +- Secret references from PodSpecs +{{< /alert >}} diff --git a/site/content/en/docs/Reference/API/nameSuffix.md b/site/content/en/docs/Reference/API/nameSuffix.md new file mode 100644 index 0000000000..be5d7da11b --- /dev/null +++ b/site/content/en/docs/Reference/API/nameSuffix.md @@ -0,0 +1,57 @@ +--- +title: "nameSuffix" +linkTitle: "nameSuffix" +type: docs +weight: 13 +description: > + Appends the value to the names of all resources and references. +--- + +As `nameSuffix` is self explanatory, it helps adding suffix to names in the defined yaml files. + +**Note:** The suffix is appended before the content hash if the resource type is ConfigMap or Secret. + +## Example + +### File Input + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + replicas: 5 + template: + containers: + - name: the-container + image: registry/container:latest +``` + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +nameSuffix: -custom-suffix + +resources: +- deployment.yaml + +``` + +### Build Output + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment-custom-suffix +spec: + replicas: 5 + template: + containers: + - image: registry/container:latest + name: the-container +``` diff --git a/site/content/en/docs/Reference/API/namespace.md b/site/content/en/docs/Reference/API/namespace.md new file mode 100644 index 0000000000..1685c45d4d --- /dev/null +++ b/site/content/en/docs/Reference/API/namespace.md @@ -0,0 +1,58 @@ +--- +title: "namespace" +linkTitle: "namespace" +type: docs +weight: 12 +description: > + Adds namespace to all resources. +--- + +Will override the existing namespace if it is set on a resource, or add it +if it is not set on a resource. + +## Example + +### File Input + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment + namespace: the-namespace +spec: + replicas: 5 + template: + containers: + - name: the-container + image: registry/container:latest +``` + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +namespace: kustomize-namespace + +resources: +- deployment.yaml + +``` + +### Build Output + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment + namespace: kustomize-namespace +spec: + replicas: 5 + template: + containers: + - image: registry/container:latest + name: the-container +``` diff --git a/site/content/en/docs/Reference/API/openapi.md b/site/content/en/docs/Reference/API/openapi.md new file mode 100644 index 0000000000..d7f19c4cfe --- /dev/null +++ b/site/content/en/docs/Reference/API/openapi.md @@ -0,0 +1,217 @@ +--- +title: "openapi" +linkTitle: "openapi" +type: docs +weight: 14 +description: > + Specify where kustomize gets its OpenAPI schema. +--- + +Kustomize uses kubernetes OpenAPI data to get merge key and patch strategy +information about resource types. Kustomize has an OpenAPI schema builtin, +but this schema only has information about builtin kubernetes types. If +you need to provide merge key and patch strategy information about custom +resource types, you will have to provide your own OpenAPI schema to do so. + +In your kustomization file, you can specify where kustomize should get +its OpenAPI schema via an `openapi` field. For example: + +```yaml +resources: +- my_resource.yaml + +openapi: + path: my_schema.json +``` + +The `openapi` field of a kustomization file can either a path to a custom schema +file, as in the example above. It can also be used to explicitly tell kustomize to +use a builtin kubernetes OpenAPI schema: + +```yaml +resources: +- my_resource.yaml + +openapi: + version: v1.20.4 +``` + +You can see what builtin kubernetes OpenAPI schemas are available with the command +`kustomize openapi info`. + +Here is an example of a custom resource we might want to edit with a custom OpenAPI schema +file. It looks like this: + +```yaml +apiVersion: example.com/v1alpha1 +kind: MyResource +metadata: + name: service +spec: + template: + spec: + containers: + - name: server + image: server + command: example + ports: + - name: grpc + protocol: TCP + containerPort: 8080 +``` + +This resource has an image field. Let's change its value from `server` +to `nginx` with a patch. You can get an OpenAPI document like this from +your locally favored cluster with the command `kustomize openapi fetch`. +Kustomize will use the OpenAPI extensions `x-kubernetes-patch-merge-key` and +`x-kubernetes-patch-strategy` to perform a strategic merge. +`x-kubernetes-patch-strategy` should be set to "merge", and you can set your +merge key to whatever you like. + +Below, our custom resource inherits merge keys from PodTemplateSpec. In the +definition of "io.k8s.api.core.v1.Container", the `ports` field has its merge +key set to "containerPort": + +```json +{ + "definitions": { + "v1alpha1.MyResource": { + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "type": "object" + }, + "spec": { + "properties": { + "template": { + "\$ref": "#/definitions/io.k8s.api.core.v1.PodTemplateSpec" + } + }, + "type": "object" + }, + "status": { + "properties": { + "success": { + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object", + "x-kubernetes-group-version-kind": [ + { + "group": "example.com", + "kind": "MyResource", + "version": "v1alpha1" + } + ] + }, + "io.k8s.api.core.v1.PodTemplateSpec": { + "properties": { + "metadata": { + "\$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta" + }, + "spec": { + "\$ref": "#/definitions/io.k8s.api.core.v1.PodSpec" + } + }, + "type": "object" + }, + "io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta": { + "properties": { + "name": { + "type": "string" + } + }, + "type": "object" + }, + "io.k8s.api.core.v1.PodSpec": { + "properties": { + "containers": { + "items": { + "\$ref": "#/definitions/io.k8s.api.core.v1.Container" + }, + "type": "array", + "x-kubernetes-patch-merge-key": "name", + "x-kubernetes-patch-strategy": "merge" + } + }, + "type": "object" + }, + "io.k8s.api.core.v1.Container": { + "properties": { + "command": { + "items": { + "type": "string" + }, + "type": "array" + }, + "image": { + "type": "string" + }, + "name": { + "type": "string" + }, + "ports": { + "items": { + "\$ref": "#/definitions/io.k8s.api.core.v1.ContainerPort" + }, + "type": "array", + "x-kubernetes-list-map-keys": [ + "containerPort", + "protocol" + ], + "x-kubernetes-list-type": "map", + "x-kubernetes-patch-merge-key": "containerPort", + "x-kubernetes-patch-strategy": "merge" + } + }, + "type": "object" + }, + "io.k8s.api.core.v1.ContainerPort": { + "properties": { + "containerPort": { + "format": "int32", + "type": "integer" + }, + "name": { + "type": "string" + }, + "protocol": { + "type": "string" + } + }, + "type": "object" + } + } +} +``` + +Then, our kustomization file to do the patch can be as follows: +```yaml +resources: +- my_resource.yaml + +openapi: + path: my_schema.json + +patchesStrategicMerge: +- |- + apiVersion: example.com/v1alpha1 + kind: MyResource + metadata: + name: service + spec: + template: + spec: + containers: + - name: server + image: nginx +``` + diff --git a/site/content/en/docs/Reference/API/patches.md b/site/content/en/docs/Reference/API/patches.md new file mode 100644 index 0000000000..e7d57e15cd --- /dev/null +++ b/site/content/en/docs/Reference/API/patches.md @@ -0,0 +1,280 @@ +--- +title: "patches" +linkTitle: "patches" +type: docs +weight: 15 +description: > + Patch resources +--- + +[strategic merge]: /references/kustomize/glossary#patchstrategicmerge +[JSON6902]: /references/kustomize/glossary#patchjson6902 + +Patches (also called overlays) add or override fields on resources. They are provided using the +`patches` Kustomization field. + +The `patches` field contains a list of patches to be applied in the order they are specified. + +Each patch may: + +- be either a [strategic merge] patch, or a [JSON6902] patch +- be either a file, or an inline string +- target a single resource or multiple resources + +The patch target selects resources by `group`, `version`, `kind`, `name`, `namespace`, `labelSelector` and +`annotationSelector`. Any resource which matches all the **specified** fields has the patch applied +to it (regular expressions). + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +patches: +- path: patch.yaml + target: + group: apps + version: v1 + kind: Deployment + name: deploy.* + labelSelector: "env=dev" + annotationSelector: "zone=west" +- patch: |- + - op: replace + path: /some/existing/path + value: new value + target: + kind: MyKind + 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$`. + +## Name and kind changes + +With `patches` it is possible to override the kind or name of the resource it is +editing with the options `allowNameChange` and `allowKindChange`. For example: +```yaml +resources: +- deployment.yaml +patches: +- path: patch.yaml + target: + kind: Deployment + options: + allowNameChange: true + allowKindChange: true +``` +By default, these fields are false and the patch will leave the kind and name of the resource untouched. + +## Name references + +A patch can refer to a resource by any of its previous names or kinds. +For example, if a resource has gone through name-prefix transformations, it can refer to the +resource by its current name, original name, or any intermediate name that it had. + +## Patching custom resources + +[Strategic merge] patches may require additional configuration via [openapi](../openapi) field to work as expected with custom resources. For example, if a resource uses a merge key other than `name` or needs a list to be merged rather than replaced, Kustomize needs openapi information informing it about this. + +[JSON6902] patch usage is the same for built-in and custom resources. + +## Examples + +Consider the following `deployment.yaml` common for all examples: +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dummy-app + labels: + app.kubernetes.io/name: nginx +spec: + selector: + matchLabels: + app.kubernetes.io/name: nginx + template: + metadata: + labels: + app.kubernetes.io/name: nginx + spec: + containers: + - name: nginx + image: nginx:stable + ports: + - name: http + containerPort: 80 +``` + +### Intents + +- Make the container image point to a specific version and not to the latest container in the registry. +- Adding a standard label containing the deployed version. + +There are multiple possible strategies that all achieve the same results. + +### Patch using Inline Strategic Merge + +```yaml +# kustomization.yaml +resources: +- deployment.yaml +patches: + - patch: |- + apiVersion: apps/v1 + kind: Deployment + metadata: + name: dummy-app + labels: + app.kubernetes.io/version: 1.21.0 + - patch: |- + apiVersion: apps/v1 + kind: Deployment + metadata: + name: not-used + spec: + template: + spec: + containers: + - name: nginx + image: nginx:1.21.0 + target: + labelSelector: "app.kubernetes.io/name=nginx" +``` + +If a `target` is specified, the `name` contained in the metadata is required but not used. + +### Patch using Inline JSON6902 + +```yaml +# kustomization.yaml +resources: +- deployment.yaml +patches: + - patch: |- + - op: add + path: /metadata/labels/app.kubernetes.io~1version + value: 1.21.0 + target: + group: apps + version: v1 + kind: Deployment + - patch: |- + - op: replace + path: /spec/template/spec/containers/0/image + value: nginx:1.21.0 + target: + labelSelector: "app.kubernetes.io/name=nginx" +``` + +The `target` field is always required for JSON6902 patches. +A special replacement character `~1` is used to replace `/` in label name. + +### Patch using Path Strategic Merge + +```yaml +# kustomization.yaml +resources: +- deployment.yaml +patches: + - path: add-label.patch.yaml + - path: fix-version.patch.yaml + target: + labelSelector: "app.kubernetes.io/name=nginx" +``` + +As with the Inline Strategic Merge, the `target` field can be omitted. +In that case, the target resource is matched using +the `apiVersion`, `kind` and `name` from the patch. + +```yaml +# add-label.patch.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: dummy-app + labels: + app.kubernetes.io/version: 1.21.0 +``` + +```yaml +# fix-version.patch.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: not-used +spec: + template: + spec: + containers: + - name: nginx + image: nginx:1.21.0 +``` + +As with the Inline Strategic Merge, the `name` field in the patch is not used when a `target` is specified. + +### Patch using Path JSON6902 + +```yaml +# kustomization.yaml +resources: +- deployment.yaml +patches: + - path: add-label.patch.json + target: + group: apps + version: v1 + kind: Deployment + - path: fix-version.patch.yaml + target: + labelSelector: "app.kubernetes.io/name=nginx" +``` + +As with Inline JSON6902, the `target` field is mandatory. + +```yaml +# add-label.patch.json +[ + {"op": "add", "path": "/metadata/labels/app.kubernetes.io~1version", "value": "1.21.0"} +] +``` + +```yaml +# fix-version.patch.yaml +- op: replace + path: /spec/template/spec/containers/0/image + value: nginx:1.21.0 +``` + +External patch file can be written both as YAML or JSON. +The content must follow the JSON6902 standard. + +### Build Output + +All four patches strategies lead to the exact same output: +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app.kubernetes.io/name: nginx + app.kubernetes.io/version: 1.21.0 + name: dummy-app +spec: + selector: + matchLabels: + app.kubernetes.io/name: nginx + template: + metadata: + labels: + app.kubernetes.io/name: nginx + spec: + containers: + - image: nginx:1.21.0 + name: nginx + ports: + - containerPort: 80 + name: http +``` diff --git a/site/content/en/docs/Reference/API/patchesStrategicMerge.md b/site/content/en/docs/Reference/API/patchesStrategicMerge.md new file mode 100644 index 0000000000..d76d30456c --- /dev/null +++ b/site/content/en/docs/Reference/API/patchesStrategicMerge.md @@ -0,0 +1,80 @@ +--- +title: "patchesStrategicMerge" +linkTitle: "patchesStrategicMerge" +type: docs +weight: 17 +description: > + Patch resources using the strategic merge patch standard. +--- + +{{% pageinfo color="warning" %}} +The `patchesStrategicMerge` field was deprecated in v5.0.0. This field will never be removed from the +kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included +in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available, +we will announce the deprecation of the v1beta1 version. There will be at least +two releases between deprecation and removal of Kustomization v1beta1 support from the +kustomize CLI, and removal itself will happen in a future major version bump. + +Please move your `patchesStrategicMerge` into +the [patches](/references/kustomize/kustomization/patches) field. This field supports patchesStrategicMerge, +but with slightly different syntax. You can run `kustomize edit fix` to automatically convert +`patchesStrategicMerge` to `patches`. +{{% /pageinfo %}} + +Each entry in this list should be either a relative +file path or an inline content +resolving to a partial or complete resource +definition. + +The names in these (possibly partial) resource +files must match names already loaded via the +`resources` field. These entries are used to +_patch_ (modify) the known resources. + +Small patches that do one thing are best, e.g. modify +a memory request/limit, change an env var in a +ConfigMap, etc. Small patches are easy to review and +easy to mix together in overlays. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +patchesStrategicMerge: +- service_port_8888.yaml +- deployment_increase_replicas.yaml +- deployment_increase_memory.yaml +``` + +The patch content can be a inline string as well. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +patchesStrategicMerge: +- |- + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx + spec: + template: + spec: + containers: + - name: nginx + image: nignx:latest +``` + +Note that kustomize does not support more than one patch +for the same object that contain a _delete_ directive. To remove +several fields / slice elements from an object create a single +patch that performs all the needed deletions. + +A patch can refer to a resource by any of its previous names or kinds. +For example, if a resource has gone through name-prefix transformations, it can refer to the +resource by its current name, original name, or any intermediate name that it had. + +## Patching custom resources + +Strategic merge patches may require additional configuration via [openapi](../openapi) field to work as expected with custom resources. For example, if a resource uses a merge key other than `name` or needs a list to be merged rather than replaced, Kustomize needs openapi information informing it about this. diff --git a/site/content/en/docs/Reference/API/patchesjson6902.md b/site/content/en/docs/Reference/API/patchesjson6902.md new file mode 100644 index 0000000000..21e61074b3 --- /dev/null +++ b/site/content/en/docs/Reference/API/patchesjson6902.md @@ -0,0 +1,111 @@ +--- +title: "patchesJson6902" +linkTitle: "patchesJson6902" +type: docs +weight: 16 +description: > + Patch resources using the [json 6902 standard](https://tools.ietf.org/html/rfc6902) +--- + +{{% pageinfo color="warning" %}} +The `patchesJson6902` field was deprecated in v5.0.0. This field will never be removed from the +kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included +in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available, +we will announce the deprecation of the v1beta1 version. There will be at least +two releases between deprecation and removal of Kustomization v1beta1 support from the +kustomize CLI, and removal itself will happen in a future major version bump. + +Please move your `patchesJson6902` into +the [patches](/references/kustomize/kustomization/patches) field. This field supports patchesJson6902, +but with slightly different syntax. You can run `kustomize edit fix` to automatically convert +`patchesJson6902` to `patches`. +{{% /pageinfo %}} + +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 + +target field points to a kubernetes object within the same kustomization +by the object's group, version, kind, name and namespace. +path field is a relative file path of a JSON patch file. +The content in this patch file can be either in JSON format as + +```json + [ + {"op": "add", "path": "/some/new/path", "value": "value"}, + {"op": "replace", "path": "/some/existing/path", "value": "new value"}, + {"op": "copy", "from": "/some/existing/path", "path": "/some/path"}, + {"op": "move", "from": "/some/existing/path", "path": "/some/existing/destination/path"}, + {"op": "remove", "path": "/some/existing/path"}, + {"op": "test", "path": "/some/path", "value": "my-node-value"} + ] + ``` + +or in YAML format as + +```yaml +# add: creates a new entry with a given value +- op: add + path: /some/new/path + value: value +# replace: replaces the value of the node with the new specified value +- op: replace + path: /some/existing/path + value: new value +# copy: copies the value specified in from to the destination path +- op: copy + from: /some/existing/path + path: /some/path +# move: moves the node specified in from to the destination path +- op: move + from: /some/existing/path + path: /some/existing/destination/path +# remove: delete's the node('s subtree) +- op: remove + path: /some/path +# test: check if the specified node has the specified value, if the value differs it will throw an error +- op: test + path: /some/path + value: "my-node-value" +``` + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +patchesJson6902: +- target: + version: v1 + kind: Deployment + name: my-deployment + path: add_init_container.yaml +- target: + version: v1 + kind: Service + name: my-service + path: add_service_annotation.yaml +``` + +The patch content can be an inline string as well: + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +patchesJson6902: +- target: + version: v1 + kind: Deployment + name: my-deployment + patch: |- + - op: add + path: /some/new/path + value: value + - op: replace + path: /some/existing/path + value: "new value" +``` + +A patch can refer to a resource by any of its previous names or kinds. +For example, if a resource has gone through name-prefix transformations, it can refer to the +resource by its current name, original name, or any intermediate name that it had. \ No newline at end of file diff --git a/site/content/en/docs/Reference/API/replacements.md b/site/content/en/docs/Reference/API/replacements.md new file mode 100644 index 0000000000..bd748d2fa7 --- /dev/null +++ b/site/content/en/docs/Reference/API/replacements.md @@ -0,0 +1,387 @@ +--- +title: "replacements" +linkTitle: "replacements" +type: docs +weight: 18 +description: > + Substitute field(s) in N target(s) with a field from a source. +--- + +Replacements are used to copy fields from one source into any +number of specified targets. + +\ +The `replacements` field can support a path to a replacement: + +`kustomization.yaml` +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +replacements: + - path: replacement.yaml +``` +`replacement.yaml` +```yaml +source: + kind: Deployment + fieldPath: metadata.name +targets: + - select: + name: my-resource +``` +\ +Alternatively, `replacements` supports inline replacements: + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +replacements: +- source: + kind: Deployment + fieldPath: metadata.name + targets: + - select: + name: my-resource +``` + +### Syntax + +The full schema of `replacements` is as follows: + +```yaml +replacements: +- source: + group: string + version: string + kind: string + name: string + namespace: string + fieldPath: string + options: + delimiter: string + index: int + create: bool + targets: + - select: + group: string + version: string + kind: string + name: string + namespace: string + reject: + - group: string + version: string + kind: string + name: string + namespace: string + fieldPaths: + - string + options: + delimiter: string + index: int + create: bool +``` + +### Field Descriptions + +| Field | Required| Description | Default | +| -----------: | :----:| ----------- | ---- | +| `source`| :heavy_check_mark: | The source of the value | +| `target`|:heavy_check_mark: | The N fields to write the value to | +| `group` | | The group of the referent | +| `version`| | The version of the referent +|`kind` | |The kind of the referent +|`name` | |The name of the referent +|`namespace`| |The namespace of the referent +|`select` |:heavy_check_mark: |Include objects that match this +|`reject`| |Exclude objects that match this +|`fieldPath`| |The structured path to the source value | `metadata.name` +|`fieldPaths`| |The structured path(s) to the target nodes | `metadata.name` +|`options`| |Options used to refine interpretation of the field +|`delimiter`| |Used to split/join the field +|`index`| |Which position in the split to consider | `0` +|`create`| |If target field is missing, add it | `false` + +#### Source +The source field is a selector that determines the source of the value by finding a +match to the specified GVKNN. All the subfields of `source` are optional, +but the source selection must resolve to a single resource. + +#### Targets +Replacements will be applied to all targets that are matched by the `select` field and +are NOT matched by the `reject` field, and will be applied to all listed `fieldPaths`. + +##### Select +You can use any of the following fields to select the targets to replace: +`group`, `version`, `kind`, `name`, `namespace` + +For example, the following will select all the Deployments as targets of replacement. + +```yaml +select: + kind: Deployment +``` + +Also, you can use multiple fields together to select only the resources that match all the conditions. +For example, the following will select only the Deployments that are named my-deploy: + +```yaml +select: +- kind: Deployment + name: my-deploy +``` + +Moreover, when the selected target is going to be transformed during the kustomization process, +you can use either the original or the transformed resource id to select it. + +For example, the name of the target could be changed because of the `namePrefix` field, as below: + +```yaml +namePrefix: my- +``` + +In this case, below will be enough if we wanted to select all the targets that were originally named deploy: + +```yaml +select: +- name: deploy +``` + +Alternatively, using the transformed name with the prefix will produce the same behaviour. +So the following case will select all the resources that *will be* named my-deploy, +along with all the resources that *were* originally named my-deploy. + +```yaml +select: +- name: my-deploy +``` + +##### Reject +The reject field is a selector that drops targets selected by select, overruling their selection. + +For example, if we wanted to reject all Deployments named my-deploy: + +```yaml +reject: +- kind: Deployment + name: my-deploy +``` + +This is distinct from the following: + +```yaml +reject: +- kind: Deployment +- name: my-deploy +``` + +The first case would only reject resources that are both of kind Deployment and named my-deploy. The second case would reject all Deployments, and all resources named my-deploy. + +We can also reject more than one kind, name, etc. For example: + +```yaml +reject: +- kind: Deployment +- kind: StatefulSet +``` + +Moreover, when the selected target is going to be transformed during the kustomization process, +you can use either the original or the transformed resource id to reject it. + +For example, the name of the target could be changed because of the `nameSuffix` field, as below: + +```yaml +nameSuffix: -dev +``` + +You can use the original target name to prevent it from going through any replacement. + +```yaml +reject: +- name: my-deploy +``` + +Alternatively, using the transformed name with the suffix will produce the same behaviour. + +```yaml +reject: +- name: my-deploy-dev +``` + +#### Delimiter + +This field is intended to be used in conjunction with the `index` field for partial string replacement. +For example, say we have a value: + +`path: my/path/VALUE` + +In our replacement target, we can specify something like: + +```yaml +options: + delimiter: '/' + index: 2 +``` + +and it would replace VALUE, e.g. `path: my/path/NEW_VALUE`. + +#### Index + +This field is intended to be used in conjunction with the `delimiter` field described above for partial string +replacement. The default value is 0. + +If the index is out of bounds, behavior depends on whether it is in a source or target. In a source, an index out of bounds +will throw an error. For a target, a value less than 0 will cause the target to be prefixed, and a value beyond +the length of the split will cause the target to be suffixed. + +If the fields `index` and `delimiter` are specified on sources or targets that are not scalar values (e.g. mapping or list values), +kustomize will throw an error. + +#### Field Path format +The fieldPath and fieldPaths fields support a format of a '.'-separated path to a value. For example, the default: + +`metadata.name` + +You can escape the '.' one of two ways. For example, say we have the following resource: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + annotations: + config.kubernetes.io/local-config: true # this is what we want to target +``` + +We can express our path: + +1. With a '\\': `metadata.annotations.config\.kubernetes\.io/local-config` + +2. With '[]': `metadata.annotations.[config.kubernetes.io/local-config]` + +Strings are used for mapping nodes. For sequence nodes, we support three options: + +1. Index by number: `spec.template.spec.containers.1.image` + +2. Index by key-value pair: `spec.template.spec.containers.[name=nginx].image`. If the key-value pair matches multiple elements in the sequence node, all matching elements will be targetted. + +3. Index with a wildcard match: `spec.template.spec.containers.*.env.[name=TARGET_ENV].value`. This will target every element in the list. + + +### Example + +For example, suppose one specifies the name of a k8s Secret object in a container's +environment variable as follows: + +`job.yaml` +```yaml +apiVersion: batch/v1 +kind: Job +metadata: + name: hello +spec: + template: + spec: + containers: + - image: myimage + name: hello + env: + - name: SECRET_TOKEN + value: SOME_SECRET_NAME +``` + +Suppose you have the following resources: + +`resources.yaml` +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: my-pod +spec: + containers: + - image: busybox + name: myapp-container + restartPolicy: OnFailure +--- +apiVersion: v1 +kind: Secret +metadata: + name: my-secret +``` + +To (1) replace the value of SOME_SECRET_NAME with the name of my-secret, and (2) to add +a restartPolicy copied from my-pod, you can do the following: + +`kustomization.yaml` +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: +- resources.yaml +- job.yaml + +replacements: +- path: my-replacement.yaml +- source: + kind: Secret + name: my-secret + targets: + - select: + name: hello + kind: Job + fieldPaths: + - spec.template.spec.containers.[name=hello].env.[name=SECRET_TOKEN].value +``` + +`my-replacement.yaml` +```yaml +source: + kind: Pod + name: my-pod + fieldPath: spec.restartPolicy +targets: +- select: + name: hello + kind: Job + fieldPaths: + - spec.template.spec.restartPolicy + options: + create: true +``` + +The output of `kustomize build` will be: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-secret +--- +apiVersion: batch/v1 +kind: Job +metadata: + name: hello +spec: + template: + spec: + containers: + - env: + - name: SECRET_TOKEN + value: my-secret # this value is copied from my-secret + image: myimage + name: hello + restartPolicy: OnFailure # this value is copied from my-pod +--- +apiVersion: v1 +kind: Pod +metadata: + name: my-pod +spec: + containers: + - image: busybox + name: myapp-container + restartPolicy: OnFailure +``` diff --git a/site/content/en/docs/Reference/API/replicas.md b/site/content/en/docs/Reference/API/replicas.md new file mode 100644 index 0000000000..c4d50fb19f --- /dev/null +++ b/site/content/en/docs/Reference/API/replicas.md @@ -0,0 +1,90 @@ +--- +title: "replicas" +linkTitle: "replicas" +type: docs +weight: 19 +description: > + Change the number of replicas for a resource. +--- + +Given this kubernetes Deployment fragment: + +```yaml +kind: Deployment +metadata: + name: deployment-name +spec: + replicas: 3 +``` + +one can change the number of replicas to 5 +by adding the following to your kustomization: + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +replicas: +- name: deployment-name + count: 5 +``` + +This field accepts a list, so many resources can +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` +- `StatefulSet` + +For more complex use cases, revert to using a patch. + +## Example + +### Input File + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + replicas: 5 + template: + containers: + - name: the-container + image: registry/container:latest +``` + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +replicas: +- name: the-deployment + count: 10 + +resources: +- deployment.yaml +``` + +### Output +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: the-deployment +spec: + replicas: 10 + template: + containers: + - name: the-container + image: registry/container:latest +``` diff --git a/site/content/en/docs/Reference/API/resources.md b/site/content/en/docs/Reference/API/resources.md new file mode 100644 index 0000000000..c51bc503a9 --- /dev/null +++ b/site/content/en/docs/Reference/API/resources.md @@ -0,0 +1,35 @@ +--- +title: "resources" +linkTitle: "resources" +type: docs +weight: 20 +description: > + Resources to include. +--- + +Each entry in this list must be a path to a _file_, or a path (or URL) referring to another +kustomization _directory_, e.g. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: +- myNamespace.yaml +- sub-dir/some-deployment.yaml +- ../../commonbase +- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6 +- deployment.yaml +- github.com/kubernets-sigs/kustomize/examples/helloWorld?ref=test-branch +``` + +Resources will be read and processed in depth-first order. + +Files should contain k8s resources in YAML form. A file may contain multiple resources separated by +the document marker `---`. File paths should be specified _relative_ to the directory holding the +kustomization file containing the `resources` field. + +Directory specification can be relative, absolute, or part of a URL. URL specifications should +follow the [hashicorp URL] format. The directory must contain a `kustomization.yaml` file. + +[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format diff --git a/site/content/en/docs/Reference/API/secretGenerator.md b/site/content/en/docs/Reference/API/secretGenerator.md new file mode 100644 index 0000000000..8b0256fe8e --- /dev/null +++ b/site/content/en/docs/Reference/API/secretGenerator.md @@ -0,0 +1,95 @@ +--- +title: "secretGenerator" +linkTitle: "secretGenerator" +type: docs +weight: 21 +description: > + Generate Secret resources. +--- + +Each entry in the argument list results in the creation of one Secret resource (it's a generator of N secrets). + +This works like the [configMapGenerator](/references/kustomize/kustomization/configmapgenerator). + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +secretGenerator: +- name: app-tls + files: + - secret/tls.crt + - secret/tls.key + type: "kubernetes.io/tls" +- name: app-tls-namespaced + # you can define a namespace to generate + # a secret in, defaults to: "default" + namespace: apps + files: + - tls.crt=catsecret/tls.crt + - tls.key=secret/tls.key + type: "kubernetes.io/tls" +- name: env_file_secret + envs: + - env.txt + type: Opaque +- name: secret-with-annotation + files: + - app-config.yaml + type: Opaque + options: + annotations: + app_config: "true" + labels: + app.kubernetes.io/name: "app2" +``` + +Secret Resources may be generated much like ConfigMaps can. This includes generating them +from literals, files or environment files. + +{{< alert color="success" title="Secret Syntax" >}} +Secret type is set using the `type` field. +{{< /alert >}} + +## Example + +### File Input + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +secretGenerator: +- name: app-tls + files: + - "tls.crt" + - "tls.key" + type: "kubernetes.io/tls" +``` + +```yaml +# tls.crt +LS0tLS1CRUd...tCg== +``` + +```yaml +# tls.key +LS0tLS1CRUd...0tLQo= +``` + +### Build Output + +```yaml +apiVersion: v1 +data: + tls.crt: TFMwdExTMUNSVWQuLi50Q2c9PQ== + tls.key: TFMwdExTMUNSVWQuLi4wdExRbz0= +kind: Secret +metadata: + name: app-tls-c888dfbhf8 +type: kubernetes.io/tls +``` + +{{< alert color="warning" title="Important" >}} +It is important to note that the secrets are `base64` encoded +{{< /alert >}} \ No newline at end of file diff --git a/site/content/en/docs/Reference/API/sortOptions.md b/site/content/en/docs/Reference/API/sortOptions.md new file mode 100644 index 0000000000..a330ccaa05 --- /dev/null +++ b/site/content/en/docs/Reference/API/sortOptions.md @@ -0,0 +1,118 @@ +--- +title: "sortOptions" +linkTitle: "sortOptions" +type: docs +weight: 22 +description: > + Change the strategy used to sort resources at the end of the Kustomize build. +--- + +The `sortOptions` field is used to sort the resources kustomize outputs. It is +available in kustomize v5.0.0+. + +IMPORTANT: +- Currently, this field is respected only in the top-level Kustomization (that + is, the immediate target of `kustomize build`). Any instances of the field in + Kustomizations further down the build chain (for example, in bases included + through the `resources` field) will be ignored. +- This field is the endorsed way to sort resources. It should be used instead of + the `--reorder` CLI flag, which is deprecated. + +Currently, we support the following sort options: +- `legacy` +- `fifo` + +```yaml +kind: Kustomization +sortOptions: + order: legacy | fifo # "legacy" is the default +``` + +## FIFO Sorting + +In `fifo` order, kustomize does not change the order of resources. They appear +in the order they are loaded in `resources`. + +### Example 1: FIFO Sorting + +```yaml +kind: Kustomization +sortOptions: + order: fifo +``` + +## Legacy Sorting + +The `legacy` sort is the default order, and is used when the sortOrder field is +unspecified. + +In `legacy` order, kustomize sorts resources by using two priority lists: +- An `orderFirst` list for resources which should be first in the output. +- An `orderLast` list for resources which should be last in the output. +- Resources not on the lists will appear in between, sorted using their apiVersion and kind fields. + +### Example 2: Legacy Sorting with orderFirst / orderLast lists + +In this example, we use the `legacy` sort order to output `Namespace` objects +first and `Deployment` objects last. + +```yaml +kind: Kustomization +sortOptions: + order: legacy + legacySortOptions: + orderFirst: + - Namespace + orderLast: + - Deployment +``` + +### Example 3: Default Legacy Sorting + +If you specify `legacy` sort order without any arguments for the lists, +kustomize will fall back to the lists we were using before introducing this +feature. Since legacy sort is the default, this is also equivalent to not +specifying the field at all. + +These two configs are equivalent: + +```yaml +kind: Kustomization +sortOptions: + order: legacy +``` + +is equivalent to: + +```yaml +kind: Kustomization +sortOptions: + order: legacy + legacySortOptions: + orderFirst: + - Namespace + - ResourceQuota + - StorageClass + - CustomResourceDefinition + - ServiceAccount + - PodSecurityPolicy + - Role + - ClusterRole + - RoleBinding + - ClusterRoleBinding + - ConfigMap + - Secret + - Endpoints + - Service + - LimitRange + - PriorityClass + - PersistentVolume + - PersistentVolumeClaim + - Deployment + - StatefulSet + - CronJob + - PodDisruptionBudget + orderLast: + - MutatingWebhookConfiguration + - ValidatingWebhookConfiguration +``` diff --git a/site/content/en/docs/Reference/API/vars.md b/site/content/en/docs/Reference/API/vars.md new file mode 100644 index 0000000000..20760727e1 --- /dev/null +++ b/site/content/en/docs/Reference/API/vars.md @@ -0,0 +1,335 @@ +--- +title: "vars" +linkTitle: "vars" +type: docs +weight: 23 +description: > + Substitute name references. +--- + +[replacements]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/ + +{{% pageinfo color="warning" %}} +The `vars` field was deprecated in v5.0.0. This field will never be removed from the +kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included +in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available, +we will announce the deprecation of the v1beta1 version. There will be at least +two releases between deprecation and removal of Kustomization v1beta1 support from the +kustomize CLI, and removal itself will happen in a future major version bump. + +Please try to migrate to the +the [replacements](/references/kustomize/kustomization/replacements) field. If you are +unable to restructure your configuration to use replacements instead of vars, please +ask for help in slack or file an issue for guidance. + +We are experimentally attempting to +automatically convert `vars` to `replacements` with `kustomize edit fix --vars`. However, +converting vars to replacements in this way will potentially overwrite many resource files +and the resulting files may not produce the same output when `kustomize build` is run. +We recommend doing this in a clean git repository where the change is easy to undo. +{{% /pageinfo %}} + +Vars are used to capture text from one resource's field +and insert that text elsewhere - a reflection feature. + +For example, suppose one specifies the name of a k8s Service +object in a container's command line, and the name of a +k8s Secret object in a container's environment variable, +so that the following would work: + +```yaml +containers: + - image: myimage + command: ["start", "--host", "$(MY_SERVICE_NAME)"] + env: + - name: SECRET_TOKEN + value: $(SOME_SECRET_NAME) +``` + +To do so, add an entry to `vars:` as follows: + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +vars: +- name: SOME_SECRET_NAME + objref: + kind: Secret + name: my-secret + apiVersion: v1 +- name: MY_SERVICE_NAME + objref: + kind: Service + name: my-service + apiVersion: v1 + fieldref: + fieldpath: metadata.name +- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY + objref: + kind: Deployment + name: my-deployment + apiVersion: apps/v1 + fieldref: + fieldpath: spec.template.spec.restartPolicy +``` + +A var is a tuple of variable name, object +reference and field reference within that object. +That's where the text is found. + +The field reference is optional; it defaults to +`metadata.name`, a normal default, since kustomize +is used to generate or modify the names of +resources. + +At time of writing, only string type fields are +supported. No ints, bools, arrays etc. It's not +possible to, say, extract the name of the image in +container number 2 of some pod template. + +A variable reference, i.e. the string '$(FOO)', +can only be placed in particular fields of +particular objects as specified by kustomize's +configuration data. + +The default config data for vars is at [/api/konfig/builtinpluginconsts/varreference.go](https://github.com/kubernetes-sigs/kustomize/blob/master/api/konfig/builtinpluginconsts/varreference.go) +Long story short, the default targets are all +container command args and env value fields. + +Vars should _not_ be used for inserting names in +places where kustomize is already handling that +job. E.g., a Deployment may reference a ConfigMap +by name, and if kustomize changes the name of a +ConfigMap, it knows to change the name reference +in the Deployment. + +### Convert vars to replacements + +There are plans to deprecate vars, so we recommend migration to [replacements] as early as possible. + +#### Simple migration example +Let's first take a simple example of how to manually do this conversion. Suppose we have a container +referencing secret (similar to the above example): + +`pod.yaml` +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: my-pod +spec: + containers: + - image: myimage + name: hello + env: + - name: SECRET_TOKEN + value: $(SOME_SECRET_NAME) +``` + +and we are using vars as follows: + +`kustomization.yaml` +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: +- pod.yaml +- secret.yaml + +vars: +- name: SOME_SECRET_NAME + objref: + kind: Secret + name: my-secret + apiVersion: v1 +``` + +In order to convert `vars` to `replacements`, we have to: + 1. Replace every instance of $(SOME_SECRET_NAME) with any arbitrary placeholder value. + 2. Convert the vars `objref` field to a [replacements] `source` field. + 3. Replace the vars `name` fied with a [replacements] `targets` field that points to +every instance of the placeholder value in step 1. + +In our simple example here, this would look like the following: + +`pod.yaml` +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: my-pod +spec: + containers: + - image: myimage + name: hello + env: + - name: SECRET_TOKEN + value: SOME_PLACEHOLDER_VALUE +``` + +`kustomization.yaml` +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: +- pod.yaml +- secret.yaml + +replacements: +- source: + kind: Secret + name: my-secret + version: v1 + targets: + - select: + kind: Pod + name: my-pod + fieldPaths: + - spec.containers.[name=hello].env.[name=SECRET_TOKEN].value +``` + +#### More complex migration example + +Let's take a more complex usage of vars and convert it to [replacements]. We are going +to convert the vars in the [wordpress example](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/wordpress) +to replacements. + +The wordpress example has the following directory structure: + +``` +. +├── README.md +├── kustomization.yaml +├── mysql +│   ├── deployment.yaml +│   ├── kustomization.yaml +│   ├── secret.yaml +│   └── service.yaml +├── patch.yaml +└── wordpress + ├── deployment.yaml + ├── kustomization.yaml + └── service.yaml +``` + +where `patch.yaml` has the following contents: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: wordpress +spec: + template: + spec: + initContainers: + - name: init-command + image: debian + command: ["/bin/sh"] + args: ["-c", "echo $(WORDPRESS_SERVICE); echo $(MYSQL_SERVICE)"] + containers: + - name: wordpress + env: + - name: WORDPRESS_DB_HOST + value: $(MYSQL_SERVICE) + - name: WORDPRESS_DB_PASSWORD + valueFrom: + secretKeyRef: + name: mysql-pass + key: password + ``` + +and the top level `kustomization.yaml` has the following contents: + + ``` + resources: + - wordpress + - mysql + patchesStrategicMerge: + - patch.yaml + namePrefix: demo- + + vars: + - name: WORDPRESS_SERVICE + objref: + kind: Service + name: wordpress + apiVersion: v1 + - name: MYSQL_SERVICE + objref: + kind: Service + name: mysql + apiVersion: v1 + ``` + +In this example, the patch is used to: +- Add an initial container to show the mysql service name +- Add environment variable that allow wordpress to find the mysql database + +We can convert vars to replacements in this more complex case too, by taking the same steps as +the previous example. To do this, we can change the contents of `patch.yaml` to: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: wordpress +spec: + template: + spec: + initContainers: + - name: init-command + image: debian + command: ["/bin/sh"] + args: ["-c", "echo", "WORDPRESS_SERVICE", ";", "echo", "MYSQL_SERVICE"] + containers: + - name: wordpress + env: + - name: WORDPRESS_DB_HOST + value: MYSQL_SERVICE + - name: WORDPRESS_DB_PASSWORD + valueFrom: + secretKeyRef: + name: mysql-pass + key: password + + ``` + +Then, in our kustomization, we can have our replacements: + +`kustomization.yaml` + +```yaml +resources: +- wordpress +- mysql +patchesStrategicMerge: +- patch.yaml +namePrefix: demo- + +replacements: +- source: + name: demo-wordpress + kind: Service + version: v1 + targets: + - select: + kind: Deployment + name: demo-wordpress + fieldPaths: + - spec.template.spec.initContainers.[name=init-command].args.2 +- source: + name: demo-mysql + kind: Service + version: v1 + targets: + - select: + kind: Deployment + name: demo-wordpress + fieldPaths: + - spec.template.spec.initContainers.[name=init-command].args.5 + - spec.template.spec.containers.[name=wordpress].env.[name=WORDPRESS_DB_HOST].value +``` From 5c1a022a3c73676fb14ab6cec3c4e7df8673b249 Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Mon, 4 Sep 2023 23:51:24 +0900 Subject: [PATCH 2/8] docs(api): fix broken hyperlinks --- site/content/en/docs/Reference/API/bases.md | 2 +- site/content/en/docs/Reference/API/commonLabels.md | 2 +- site/content/en/docs/Reference/API/patchesStrategicMerge.md | 2 +- site/content/en/docs/Reference/API/patchesjson6902.md | 2 +- site/content/en/docs/Reference/API/secretGenerator.md | 2 +- site/content/en/docs/Reference/API/vars.md | 4 ++-- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/site/content/en/docs/Reference/API/bases.md b/site/content/en/docs/Reference/API/bases.md index 519e29469a..aecb477c24 100644 --- a/site/content/en/docs/Reference/API/bases.md +++ b/site/content/en/docs/Reference/API/bases.md @@ -18,7 +18,7 @@ kustomize CLI, and removal itself will happen in a future major version bump. You can run `kustomize edit fix` to automatically convert `bases` to `resources`. {{% /pageinfo %}} -Move entries into the [resources](/references/kustomize/kustomization/resource) +Move entries into the [resources](/docs/reference/api/resources) field. This allows bases - which are still a [central concept](/references/kustomize/glossary#base) - to be ordered relative to other input resources. diff --git a/site/content/en/docs/Reference/API/commonLabels.md b/site/content/en/docs/Reference/API/commonLabels.md index 3c57b95809..20a907eb19 100644 --- a/site/content/en/docs/Reference/API/commonLabels.md +++ b/site/content/en/docs/Reference/API/commonLabels.md @@ -7,7 +7,7 @@ description: > Add labels and selectors to add all resources. --- -[labels]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/labels/ +[labels]: /docs/reference/api/labels/ Add labels and selectors to all resources. If the label key already is present on the resource, the value will be overridden. diff --git a/site/content/en/docs/Reference/API/patchesStrategicMerge.md b/site/content/en/docs/Reference/API/patchesStrategicMerge.md index d76d30456c..51ab157e90 100644 --- a/site/content/en/docs/Reference/API/patchesStrategicMerge.md +++ b/site/content/en/docs/Reference/API/patchesStrategicMerge.md @@ -16,7 +16,7 @@ two releases between deprecation and removal of Kustomization v1beta1 support fr kustomize CLI, and removal itself will happen in a future major version bump. Please move your `patchesStrategicMerge` into -the [patches](/references/kustomize/kustomization/patches) field. This field supports patchesStrategicMerge, +the [patches](/docs/reference/api/patches) field. This field supports patchesStrategicMerge, but with slightly different syntax. You can run `kustomize edit fix` to automatically convert `patchesStrategicMerge` to `patches`. {{% /pageinfo %}} diff --git a/site/content/en/docs/Reference/API/patchesjson6902.md b/site/content/en/docs/Reference/API/patchesjson6902.md index 21e61074b3..7c4682ef43 100644 --- a/site/content/en/docs/Reference/API/patchesjson6902.md +++ b/site/content/en/docs/Reference/API/patchesjson6902.md @@ -16,7 +16,7 @@ two releases between deprecation and removal of Kustomization v1beta1 support fr kustomize CLI, and removal itself will happen in a future major version bump. Please move your `patchesJson6902` into -the [patches](/references/kustomize/kustomization/patches) field. This field supports patchesJson6902, +the [patches](/docs/reference/api/patches) field. This field supports patchesJson6902, but with slightly different syntax. You can run `kustomize edit fix` to automatically convert `patchesJson6902` to `patches`. {{% /pageinfo %}} diff --git a/site/content/en/docs/Reference/API/secretGenerator.md b/site/content/en/docs/Reference/API/secretGenerator.md index 8b0256fe8e..8155776e1c 100644 --- a/site/content/en/docs/Reference/API/secretGenerator.md +++ b/site/content/en/docs/Reference/API/secretGenerator.md @@ -9,7 +9,7 @@ description: > Each entry in the argument list results in the creation of one Secret resource (it's a generator of N secrets). -This works like the [configMapGenerator](/references/kustomize/kustomization/configmapgenerator). +This works like the [configMapGenerator](/docs/reference/api/configmapgenerator). ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 diff --git a/site/content/en/docs/Reference/API/vars.md b/site/content/en/docs/Reference/API/vars.md index 20760727e1..3c8edc4289 100644 --- a/site/content/en/docs/Reference/API/vars.md +++ b/site/content/en/docs/Reference/API/vars.md @@ -7,7 +7,7 @@ description: > Substitute name references. --- -[replacements]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/ +[replacements]: /docs/reference/api/replacements/ {{% pageinfo color="warning" %}} The `vars` field was deprecated in v5.0.0. This field will never be removed from the @@ -18,7 +18,7 @@ two releases between deprecation and removal of Kustomization v1beta1 support fr kustomize CLI, and removal itself will happen in a future major version bump. Please try to migrate to the -the [replacements](/references/kustomize/kustomization/replacements) field. If you are +the [replacements](/docs/reference/api/replacements) field. If you are unable to restructure your configuration to use replacements instead of vars, please ask for help in slack or file an issue for guidance. From bd8045b64874eb8aaccfe4aef639a0d375b6e428 Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Wed, 13 Sep 2023 12:58:02 +0900 Subject: [PATCH 3/8] docs(api/replacements): fix heavy check mark issue --- .../en/docs/Reference/API/replacements.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/site/content/en/docs/Reference/API/replacements.md b/site/content/en/docs/Reference/API/replacements.md index bd748d2fa7..bd51f2fcf0 100644 --- a/site/content/en/docs/Reference/API/replacements.md +++ b/site/content/en/docs/Reference/API/replacements.md @@ -87,22 +87,22 @@ replacements: ### Field Descriptions | Field | Required| Description | Default | -| -----------: | :----:| ----------- | ---- | -| `source`| :heavy_check_mark: | The source of the value | -| `target`|:heavy_check_mark: | The N fields to write the value to | +| -----------: | :----: | ----------- | ---- | +| `source`| ✔️ | The source of the value | +| `target`| ✔️ | The N fields to write the value to | | `group` | | The group of the referent | | `version`| | The version of the referent -|`kind` | |The kind of the referent -|`name` | |The name of the referent -|`namespace`| |The namespace of the referent -|`select` |:heavy_check_mark: |Include objects that match this +|`kind` | | The kind of the referent +|`name` | | The name of the referent +|`namespace`| | The namespace of the referent +|`select` | ✔️ |Include objects that match this |`reject`| |Exclude objects that match this -|`fieldPath`| |The structured path to the source value | `metadata.name` -|`fieldPaths`| |The structured path(s) to the target nodes | `metadata.name` -|`options`| |Options used to refine interpretation of the field -|`delimiter`| |Used to split/join the field -|`index`| |Which position in the split to consider | `0` -|`create`| |If target field is missing, add it | `false` +|`fieldPath`| | The structured path to the source value | `metadata.name` +|`fieldPaths`| | The structured path(s) to the target nodes | `metadata.name` +|`options`| | Options used to refine interpretation of the field +|`delimiter`| | Used to split/join the field +|`index`| | Which position in the split to consider | `0` +|`create`| | If target field is missing, add it | `false` #### Source The source field is a selector that determines the source of the value by finding a From 9d126f6dd8be627fc16fd19890e02632e9d528ce Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Thu, 14 Sep 2023 12:55:50 +0900 Subject: [PATCH 4/8] docs(api/components): add Components guide from cli-experimental - add reference to Concept page --- .../en/docs/Reference/API/components.md | 382 +++++++++++++++++- 1 file changed, 378 insertions(+), 4 deletions(-) diff --git a/site/content/en/docs/Reference/API/components.md b/site/content/en/docs/Reference/API/components.md index b682b670a3..4f3f3d3493 100644 --- a/site/content/en/docs/Reference/API/components.md +++ b/site/content/en/docs/Reference/API/components.md @@ -1,11 +1,385 @@ --- -title: "components" -linkTitle: "components" +title: "Components" +linkTitle: "Components" type: docs weight: 5 description: > Compose kustomizations. --- -Please check out the existing [components guide](/guides/config_management/components/) for explanation with examples. -More examples are in progress +As of ``v3.7.0`` Kustomize supports a special type of kustomization that allows +one to define reusable pieces of configuration logic that can be included from +multiple overlays. + +Components come in handy when dealing with applications that support multiple +optional features and you wish to enable only a subset of them in different +overlays, i.e., different features for different environments or audiences. + +For more details regarding this feature you can read the +[Kustomize Components KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/1802-kustomize-components) +and the [components concept](/docs/concepts/components/) page. + +## Use case + +Suppose you've written a very simple Web application: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + template: + spec: + containers: + - name: example + image: example:1.0 +``` + +You want to deploy a **community** edition of this application as SaaS, so you +add support for persistence (e.g. an external database), and bot detection +(e.g. Google reCAPTCHA). + +You've now attracted **enterprise** customers who want to deploy it +on-premises, so you add LDAP support, and disable Google reCAPTCHA. At the same +time, the **devs** need to be able to test parts of the application, so they +want to deploy it with some features enabled and others not. + +Here's a matrix with the deployments of this application and the features +enabled for each one: + +| | External DB | LDAP | reCAPTCHA | +|------------|:------------------:|:------------------:|:------------------:| +| Community | ✔️ | | ✔️ | +| Enterprise | ✔️ | ✔️ | | +| Dev | ✅ | ✅ | ✅ | + +(✔️ enabled, ✅: optional) + +So, you want to make it easy to deploy your application in any of the above +three environments. Here's how you can do this with Kustomize components: each +opt-in feature gets packaged as a component, so that it can be referred to from +multiple higher-level overlays. + +First, define a place to work: + +```shell +DEMO_HOME=$(mktemp -d) +``` + +Define a common **base** that has a `Deployment` and a simple `ConfigMap`, that +is mounted on the application's container. + +```bash +BASE=$DEMO_HOME/base +mkdir $BASE +``` + +```bash +# $BASE/kustomization.yaml +resources: +- deployment.yaml + +configMapGenerator: +- name: conf + literals: + - main.conf=| + color=cornflower_blue + log_level=info +``` + +```bash +# $BASE/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + template: + spec: + containers: + - name: example + image: example:1.0 + volumeMounts: + - name: conf + mountPath: /etc/config + volumes: + - name: conf + configMap: + name: conf +``` + +Define an `external_db` component, using `kind: Component`, that creates a +`Secret` for the DB password and a new entry in the `ConfigMap`: + +```shell +EXT_DB=$DEMO_HOME/components/external_db +mkdir -p $EXT_DB +``` + +```bash +# $EXT_DB/kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1alpha1 # <-- Component notation +kind: Component + +secretGenerator: +- name: dbpass + files: + - dbpass.txt + +patchesStrategicMerge: + - configmap.yaml + +patchesJson6902: +- target: + group: apps + version: v1 + kind: Deployment + name: example + path: deployment.yaml +``` + +```bash +# $EXT_DB/deployment.yaml +- op: add + path: /spec/template/spec/volumes/0 + value: + name: dbpass + secret: + secretName: dbpass +- op: add + path: /spec/template/spec/containers/0/volumeMounts/0 + value: + mountPath: /var/run/secrets/db/ + name: dbpass +``` + +```bash +# $EXT_DB/configmap.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: conf +data: + db.conf: | + endpoint=127.0.0.1:1234 + name=app + user=admin + pass=/var/run/secrets/db/dbpass.txt +``` + +Define an `ldap` component, that creates a `Secret` for the LDAP password +and a new entry in the `ConfigMap`: + +```shell +LDAP=$DEMO_HOME/components/ldap +mkdir -p $LDAP +``` + +```bash +# $LDAP/kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +secretGenerator: +- name: ldappass + files: + - ldappass.txt + +patchesStrategicMerge: + - configmap.yaml + +patchesJson6902: +- target: + group: apps + version: v1 + kind: Deployment + name: example + path: deployment.yaml +``` + +```bash +# $LDAP/deployment.yaml +- op: add + path: /spec/template/spec/volumes/0 + value: + name: ldappass + secret: + secretName: ldappass +- op: add + path: /spec/template/spec/containers/0/volumeMounts/0 + value: + mountPath: /var/run/secrets/ldap/ + name: ldappass +``` + +```bash +# $LDAP/configmap.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: conf +data: + ldap.conf: | + endpoint=ldap://ldap.example.com + bindDN=cn=admin,dc=example,dc=com + pass=/var/run/secrets/ldap/ldappass.txt +``` + +Define a `recaptcha` component, that creates a `Secret` for the reCAPTCHA +site/secret keys and a new entry in the `ConfigMap`: + +```shell +RECAPTCHA=$DEMO_HOME/components/recaptcha +mkdir -p $RECAPTCHA +``` + +```bash +# $RECAPTCHA/kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +secretGenerator: +- name: recaptcha + files: + - site_key.txt + - secret_key.txt + +# Updating the ConfigMap works with generators as well. +configMapGenerator: +- name: conf + behavior: merge + literals: + - recaptcha.conf=| + enabled=true + site_key=/var/run/secrets/recaptcha/site_key.txt + secret_key=/var/run/secrets/recaptcha/secret_key.txt + +patchesJson6902: +- target: + group: apps + version: v1 + kind: Deployment + name: example + path: deployment.yaml +``` + +```bash +# $RECAPTCHA/deployment.yaml +- op: add + path: /spec/template/spec/volumes/0 + value: + name: recaptcha + secret: + secretName: recaptcha +- op: add + path: /spec/template/spec/containers/0/volumeMounts/0 + value: + mountPath: /var/run/secrets/recaptcha/ + name: recaptcha +``` + +Define a `community` variant, that bundles the external DB and reCAPTCHA +components: + +```shell +COMMUNITY=$DEMO_HOME/overlays/community +mkdir -p $COMMUNITY +``` + +```bash + +# $COMMUNITY/kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: + - ../../base + +components: + - ../../components/external_db + - ../../components/recaptcha +``` + +Define an `enterprise` overlay, that bundles the external DB and LDAP +components: + +```shell +ENTERPRISE=$DEMO_HOME/overlays/enterprise +mkdir -p $ENTERPRISE +``` + +```bash +# $ENTERPRISE/kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: + - ../../base + +components: + - ../../components/external_db + - ../../components/ldap +``` + +Define a `dev` overlay, that points to all the components and has LDAP +disabled: + +```shell +DEV=$DEMO_HOME/overlays/dev +mkdir -p $DEV +``` + +```bash +# $DEV/kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +resources: + - ../../base + +components: + - ../../components/external_db + #- ../../components/ldap + - ../../components/recaptcha +``` + +Now, the workspace has the following directories: + +```shell +├── base +│ ├── deployment.yaml +│ └── kustomization.yaml +├── components +│ ├── external_db +│ │ ├── configmap.yaml +│ │ ├── dbpass.txt +│ │ ├── deployment.yaml +│ │ └── kustomization.yaml +│ ├── ldap +│ │ ├── configmap.yaml +│ │ ├── deployment.yaml +│ │ ├── kustomization.yaml +│ │ └── ldappass.txt +│ └── recaptcha +│ ├── deployment.yaml +│ ├── kustomization.yaml +│ ├── secret_key.txt +│ └── site_key.txt +└── overlays + ├── community + │ └── kustomization.yaml + ├── dev + │ └── kustomization.yaml + └── enterprise + └── kustomization.yaml +``` + +With this structure, you can generate the YAML manifests for each deployment +using `kustomize build`: + +```shell +kustomize build overlays/community +kustomize build overlays/enterprise +kustomize build overlays/dev +``` From a2b60e4bcb498a8e69b48fdb24561b9d09b5df18 Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Thu, 14 Sep 2023 20:52:11 +0900 Subject: [PATCH 5/8] docs(api): fix broken links --- site/content/en/docs/Reference/API/bases.md | 2 +- site/content/en/docs/Reference/API/images.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/en/docs/Reference/API/bases.md b/site/content/en/docs/Reference/API/bases.md index aecb477c24..9b4fdb7111 100644 --- a/site/content/en/docs/Reference/API/bases.md +++ b/site/content/en/docs/Reference/API/bases.md @@ -20,5 +20,5 @@ You can run `kustomize edit fix` to automatically convert `bases` to `resources` Move entries into the [resources](/docs/reference/api/resources) field. This allows bases - which are still a -[central concept](/references/kustomize/glossary#base) - to be +[central concept](/docs/concepts/bases) - to be ordered relative to other input resources. diff --git a/site/content/en/docs/Reference/API/images.md b/site/content/en/docs/Reference/API/images.md index d2955bfa46..5f7fefe27c 100644 --- a/site/content/en/docs/Reference/API/images.md +++ b/site/content/en/docs/Reference/API/images.md @@ -140,7 +140,7 @@ the image name is `foo` and an image was built for the source code at commit `1b then the container image would be `foo:1bb359ccce344ca5d263cd257958ea035c978fd3`. A simple way to push an image that was just built without manually updating the image tags is to -download the [kustomize standalone](https://github.com/kubernetes-sigs/kustomize/) tool and run +[download the kustomize standalone](/docs/getting-started/installation/) tool and run `kustomize edit set image` command to update the tags for you. **Example:** Set the latest git commit SHA as the image tag for `foo` images. From ae041b5c54832ed26117bec8f29b38aab31b35fb Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Thu, 14 Sep 2023 20:54:06 +0900 Subject: [PATCH 6/8] docs(api/generatorOptions): fill up empty links --- site/content/en/docs/Reference/API/generatorOptions.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/site/content/en/docs/Reference/API/generatorOptions.md b/site/content/en/docs/Reference/API/generatorOptions.md index 58479d05ec..731a5cd855 100644 --- a/site/content/en/docs/Reference/API/generatorOptions.md +++ b/site/content/en/docs/Reference/API/generatorOptions.md @@ -4,15 +4,13 @@ linkTitle: "generatorOptions" type: docs weight: 8 description: > - Control behavior of [ConfigMap]() and - [Secret]() generators. + Control behavior of [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) and + [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) generators. --- - - Additionally, generatorOptions can be set on a per resource level within each generator. For details on per-resource generatorOptions usage see -[field-name-configMapGenerator]() and See [field-name-secretGenerator](). +[configMapGenerator](/docs/reference/api/configmapgenerator/) and see [secretGenerator](/docs/reference/api/secretgenerator/). ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 From d30e4570311d80cbf8533a235211f543e49343da Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Thu, 14 Sep 2023 21:01:25 +0900 Subject: [PATCH 7/8] docs(api/patches): fix broken links --- site/content/en/docs/Reference/API/patches.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/en/docs/Reference/API/patches.md b/site/content/en/docs/Reference/API/patches.md index e7d57e15cd..24e04831b0 100644 --- a/site/content/en/docs/Reference/API/patches.md +++ b/site/content/en/docs/Reference/API/patches.md @@ -7,8 +7,8 @@ description: > Patch resources --- -[strategic merge]: /references/kustomize/glossary#patchstrategicmerge -[JSON6902]: /references/kustomize/glossary#patchjson6902 +[strategic merge]: /docs/reference/api/patchesstrategicmerge/ +[JSON6902]: /docs/reference/api/patchesjson6902/ Patches (also called overlays) add or override fields on resources. They are provided using the `patches` Kustomization field. From 2c444d6bf4a2466f41c9e9f6243bf899280d179a Mon Sep 17 00:00:00 2001 From: Jeong Jinwoo Date: Sun, 17 Sep 2023 16:05:32 +0900 Subject: [PATCH 8/8] docs(api/kustomizaion-file): migrate field sections --- .../{kustomization_file.md => Kustomization File/_index.md} | 4 ++-- .../en/docs/Reference/API/{ => Kustomization File}/bases.md | 2 +- .../Reference/API/{ => Kustomization File}/buildMetadata.md | 0 .../API/{ => Kustomization File}/commonAnnotations.md | 0 .../Reference/API/{ => Kustomization File}/commonLabels.md | 2 +- .../docs/Reference/API/{ => Kustomization File}/components.md | 0 .../API/{ => Kustomization File}/configMapGenerator.md | 0 .../en/docs/Reference/API/{ => Kustomization File}/crds.md | 0 .../API/{ => Kustomization File}/generatorOptions.md | 2 +- .../docs/Reference/API/{ => Kustomization File}/helmCharts.md | 0 .../en/docs/Reference/API/{ => Kustomization File}/images.md | 0 .../en/docs/Reference/API/{ => Kustomization File}/labels.md | 0 .../docs/Reference/API/{ => Kustomization File}/namePrefix.md | 0 .../docs/Reference/API/{ => Kustomization File}/nameSuffix.md | 0 .../docs/Reference/API/{ => Kustomization File}/namespace.md | 0 .../en/docs/Reference/API/{ => Kustomization File}/openapi.md | 0 .../en/docs/Reference/API/{ => Kustomization File}/patches.md | 4 ++-- .../API/{ => Kustomization File}/patchesStrategicMerge.md | 2 +- .../Reference/API/{ => Kustomization File}/patchesjson6902.md | 2 +- .../Reference/API/{ => Kustomization File}/replacements.md | 0 .../docs/Reference/API/{ => Kustomization File}/replicas.md | 0 .../docs/Reference/API/{ => Kustomization File}/resources.md | 0 .../Reference/API/{ => Kustomization File}/secretGenerator.md | 2 +- .../Reference/API/{ => Kustomization File}/sortOptions.md | 0 .../en/docs/Reference/API/{ => Kustomization File}/vars.md | 4 ++-- 25 files changed, 12 insertions(+), 12 deletions(-) rename site/content/en/docs/Reference/API/{kustomization_file.md => Kustomization File/_index.md} (88%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/bases.md (91%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/buildMetadata.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/commonAnnotations.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/commonLabels.md (96%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/components.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/configMapGenerator.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/crds.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/generatorOptions.md (93%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/helmCharts.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/images.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/labels.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/namePrefix.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/nameSuffix.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/namespace.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/openapi.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/patches.md (97%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/patchesStrategicMerge.md (96%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/patchesjson6902.md (97%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/replacements.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/replicas.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/resources.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/secretGenerator.md (94%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/sortOptions.md (100%) rename site/content/en/docs/Reference/API/{ => Kustomization File}/vars.md (98%) diff --git a/site/content/en/docs/Reference/API/kustomization_file.md b/site/content/en/docs/Reference/API/Kustomization File/_index.md similarity index 88% rename from site/content/en/docs/Reference/API/kustomization_file.md rename to site/content/en/docs/Reference/API/Kustomization File/_index.md index 0bea5c073a..feefe31b9d 100644 --- a/site/content/en/docs/Reference/API/kustomization_file.md +++ b/site/content/en/docs/Reference/API/Kustomization File/_index.md @@ -2,7 +2,7 @@ title: "Kustomization File" linkTitle: "Kustomization File" weight: 1 -date: 2023-07-28 +date: 2023-09-17 description: > The Kustomization file is the entry point for Kustomize execution. ---- \ No newline at end of file +--- diff --git a/site/content/en/docs/Reference/API/bases.md b/site/content/en/docs/Reference/API/Kustomization File/bases.md similarity index 91% rename from site/content/en/docs/Reference/API/bases.md rename to site/content/en/docs/Reference/API/Kustomization File/bases.md index 9b4fdb7111..2d7bed3d3d 100644 --- a/site/content/en/docs/Reference/API/bases.md +++ b/site/content/en/docs/Reference/API/Kustomization File/bases.md @@ -18,7 +18,7 @@ kustomize CLI, and removal itself will happen in a future major version bump. You can run `kustomize edit fix` to automatically convert `bases` to `resources`. {{% /pageinfo %}} -Move entries into the [resources](/docs/reference/api/resources) +Move entries into the [resources](/docs/reference/api/kustomization-file/resources) field. This allows bases - which are still a [central concept](/docs/concepts/bases) - to be ordered relative to other input resources. diff --git a/site/content/en/docs/Reference/API/buildMetadata.md b/site/content/en/docs/Reference/API/Kustomization File/buildMetadata.md similarity index 100% rename from site/content/en/docs/Reference/API/buildMetadata.md rename to site/content/en/docs/Reference/API/Kustomization File/buildMetadata.md diff --git a/site/content/en/docs/Reference/API/commonAnnotations.md b/site/content/en/docs/Reference/API/Kustomization File/commonAnnotations.md similarity index 100% rename from site/content/en/docs/Reference/API/commonAnnotations.md rename to site/content/en/docs/Reference/API/Kustomization File/commonAnnotations.md diff --git a/site/content/en/docs/Reference/API/commonLabels.md b/site/content/en/docs/Reference/API/Kustomization File/commonLabels.md similarity index 96% rename from site/content/en/docs/Reference/API/commonLabels.md rename to site/content/en/docs/Reference/API/Kustomization File/commonLabels.md index 20a907eb19..379a35a95d 100644 --- a/site/content/en/docs/Reference/API/commonLabels.md +++ b/site/content/en/docs/Reference/API/Kustomization File/commonLabels.md @@ -7,7 +7,7 @@ description: > Add labels and selectors to add all resources. --- -[labels]: /docs/reference/api/labels/ +[labels]: /docs/reference/api/kustomization-file/labels/ Add labels and selectors to all resources. If the label key already is present on the resource, the value will be overridden. diff --git a/site/content/en/docs/Reference/API/components.md b/site/content/en/docs/Reference/API/Kustomization File/components.md similarity index 100% rename from site/content/en/docs/Reference/API/components.md rename to site/content/en/docs/Reference/API/Kustomization File/components.md diff --git a/site/content/en/docs/Reference/API/configMapGenerator.md b/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md similarity index 100% rename from site/content/en/docs/Reference/API/configMapGenerator.md rename to site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md diff --git a/site/content/en/docs/Reference/API/crds.md b/site/content/en/docs/Reference/API/Kustomization File/crds.md similarity index 100% rename from site/content/en/docs/Reference/API/crds.md rename to site/content/en/docs/Reference/API/Kustomization File/crds.md diff --git a/site/content/en/docs/Reference/API/generatorOptions.md b/site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md similarity index 93% rename from site/content/en/docs/Reference/API/generatorOptions.md rename to site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md index 731a5cd855..75c40d0d16 100644 --- a/site/content/en/docs/Reference/API/generatorOptions.md +++ b/site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md @@ -10,7 +10,7 @@ description: > Additionally, generatorOptions can be set on a per resource level within each generator. For details on per-resource generatorOptions usage see -[configMapGenerator](/docs/reference/api/configmapgenerator/) and see [secretGenerator](/docs/reference/api/secretgenerator/). +[configMapGenerator](/docs/reference/api/kustomization-file/configmapgenerator/) and see [secretGenerator](/docs/reference/api/kustomization-file/secretgenerator/). ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 diff --git a/site/content/en/docs/Reference/API/helmCharts.md b/site/content/en/docs/Reference/API/Kustomization File/helmCharts.md similarity index 100% rename from site/content/en/docs/Reference/API/helmCharts.md rename to site/content/en/docs/Reference/API/Kustomization File/helmCharts.md diff --git a/site/content/en/docs/Reference/API/images.md b/site/content/en/docs/Reference/API/Kustomization File/images.md similarity index 100% rename from site/content/en/docs/Reference/API/images.md rename to site/content/en/docs/Reference/API/Kustomization File/images.md diff --git a/site/content/en/docs/Reference/API/labels.md b/site/content/en/docs/Reference/API/Kustomization File/labels.md similarity index 100% rename from site/content/en/docs/Reference/API/labels.md rename to site/content/en/docs/Reference/API/Kustomization File/labels.md diff --git a/site/content/en/docs/Reference/API/namePrefix.md b/site/content/en/docs/Reference/API/Kustomization File/namePrefix.md similarity index 100% rename from site/content/en/docs/Reference/API/namePrefix.md rename to site/content/en/docs/Reference/API/Kustomization File/namePrefix.md diff --git a/site/content/en/docs/Reference/API/nameSuffix.md b/site/content/en/docs/Reference/API/Kustomization File/nameSuffix.md similarity index 100% rename from site/content/en/docs/Reference/API/nameSuffix.md rename to site/content/en/docs/Reference/API/Kustomization File/nameSuffix.md diff --git a/site/content/en/docs/Reference/API/namespace.md b/site/content/en/docs/Reference/API/Kustomization File/namespace.md similarity index 100% rename from site/content/en/docs/Reference/API/namespace.md rename to site/content/en/docs/Reference/API/Kustomization File/namespace.md diff --git a/site/content/en/docs/Reference/API/openapi.md b/site/content/en/docs/Reference/API/Kustomization File/openapi.md similarity index 100% rename from site/content/en/docs/Reference/API/openapi.md rename to site/content/en/docs/Reference/API/Kustomization File/openapi.md diff --git a/site/content/en/docs/Reference/API/patches.md b/site/content/en/docs/Reference/API/Kustomization File/patches.md similarity index 97% rename from site/content/en/docs/Reference/API/patches.md rename to site/content/en/docs/Reference/API/Kustomization File/patches.md index 24e04831b0..19805b0d0e 100644 --- a/site/content/en/docs/Reference/API/patches.md +++ b/site/content/en/docs/Reference/API/Kustomization File/patches.md @@ -7,8 +7,8 @@ description: > Patch resources --- -[strategic merge]: /docs/reference/api/patchesstrategicmerge/ -[JSON6902]: /docs/reference/api/patchesjson6902/ +[strategic merge]: /docs/reference/api/kustomization-file/patchesstrategicmerge/ +[JSON6902]: /docs/reference/api/kustomization-file/patchesjson6902/ Patches (also called overlays) add or override fields on resources. They are provided using the `patches` Kustomization field. diff --git a/site/content/en/docs/Reference/API/patchesStrategicMerge.md b/site/content/en/docs/Reference/API/Kustomization File/patchesStrategicMerge.md similarity index 96% rename from site/content/en/docs/Reference/API/patchesStrategicMerge.md rename to site/content/en/docs/Reference/API/Kustomization File/patchesStrategicMerge.md index 51ab157e90..d8f32add40 100644 --- a/site/content/en/docs/Reference/API/patchesStrategicMerge.md +++ b/site/content/en/docs/Reference/API/Kustomization File/patchesStrategicMerge.md @@ -16,7 +16,7 @@ two releases between deprecation and removal of Kustomization v1beta1 support fr kustomize CLI, and removal itself will happen in a future major version bump. Please move your `patchesStrategicMerge` into -the [patches](/docs/reference/api/patches) field. This field supports patchesStrategicMerge, +the [patches](/docs/reference/api/kustomization-file/patches) field. This field supports patchesStrategicMerge, but with slightly different syntax. You can run `kustomize edit fix` to automatically convert `patchesStrategicMerge` to `patches`. {{% /pageinfo %}} diff --git a/site/content/en/docs/Reference/API/patchesjson6902.md b/site/content/en/docs/Reference/API/Kustomization File/patchesjson6902.md similarity index 97% rename from site/content/en/docs/Reference/API/patchesjson6902.md rename to site/content/en/docs/Reference/API/Kustomization File/patchesjson6902.md index 7c4682ef43..66771533ec 100644 --- a/site/content/en/docs/Reference/API/patchesjson6902.md +++ b/site/content/en/docs/Reference/API/Kustomization File/patchesjson6902.md @@ -16,7 +16,7 @@ two releases between deprecation and removal of Kustomization v1beta1 support fr kustomize CLI, and removal itself will happen in a future major version bump. Please move your `patchesJson6902` into -the [patches](/docs/reference/api/patches) field. This field supports patchesJson6902, +the [patches](/docs/reference/api/kustomization-file/patches) field. This field supports patchesJson6902, but with slightly different syntax. You can run `kustomize edit fix` to automatically convert `patchesJson6902` to `patches`. {{% /pageinfo %}} diff --git a/site/content/en/docs/Reference/API/replacements.md b/site/content/en/docs/Reference/API/Kustomization File/replacements.md similarity index 100% rename from site/content/en/docs/Reference/API/replacements.md rename to site/content/en/docs/Reference/API/Kustomization File/replacements.md diff --git a/site/content/en/docs/Reference/API/replicas.md b/site/content/en/docs/Reference/API/Kustomization File/replicas.md similarity index 100% rename from site/content/en/docs/Reference/API/replicas.md rename to site/content/en/docs/Reference/API/Kustomization File/replicas.md diff --git a/site/content/en/docs/Reference/API/resources.md b/site/content/en/docs/Reference/API/Kustomization File/resources.md similarity index 100% rename from site/content/en/docs/Reference/API/resources.md rename to site/content/en/docs/Reference/API/Kustomization File/resources.md diff --git a/site/content/en/docs/Reference/API/secretGenerator.md b/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md similarity index 94% rename from site/content/en/docs/Reference/API/secretGenerator.md rename to site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md index 8155776e1c..e06c8e2758 100644 --- a/site/content/en/docs/Reference/API/secretGenerator.md +++ b/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md @@ -9,7 +9,7 @@ description: > Each entry in the argument list results in the creation of one Secret resource (it's a generator of N secrets). -This works like the [configMapGenerator](/docs/reference/api/configmapgenerator). +This works like the [configMapGenerator](/docs/reference/api/kustomization-file/configmapgenerator). ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 diff --git a/site/content/en/docs/Reference/API/sortOptions.md b/site/content/en/docs/Reference/API/Kustomization File/sortOptions.md similarity index 100% rename from site/content/en/docs/Reference/API/sortOptions.md rename to site/content/en/docs/Reference/API/Kustomization File/sortOptions.md diff --git a/site/content/en/docs/Reference/API/vars.md b/site/content/en/docs/Reference/API/Kustomization File/vars.md similarity index 98% rename from site/content/en/docs/Reference/API/vars.md rename to site/content/en/docs/Reference/API/Kustomization File/vars.md index 3c8edc4289..db93bd4597 100644 --- a/site/content/en/docs/Reference/API/vars.md +++ b/site/content/en/docs/Reference/API/Kustomization File/vars.md @@ -7,7 +7,7 @@ description: > Substitute name references. --- -[replacements]: /docs/reference/api/replacements/ +[replacements]: /docs/reference/api/kustomization-file/replacements/ {{% pageinfo color="warning" %}} The `vars` field was deprecated in v5.0.0. This field will never be removed from the @@ -18,7 +18,7 @@ two releases between deprecation and removal of Kustomization v1beta1 support fr kustomize CLI, and removal itself will happen in a future major version bump. Please try to migrate to the -the [replacements](/docs/reference/api/replacements) field. If you are +the [replacements](/docs/reference/api/kustomization-file/replacements) field. If you are unable to restructure your configuration to use replacements instead of vars, please ask for help in slack or file an issue for guidance.