diff --git a/site/content/en/docs/Reference/API/Generators/ConfigMapGenerator.md b/site/content/en/docs/Reference/API/Generators/ConfigMapGenerator.md new file mode 100644 index 0000000000..463cd0be50 --- /dev/null +++ b/site/content/en/docs/Reference/API/Generators/ConfigMapGenerator.md @@ -0,0 +1,23 @@ +--- +title: "ConfigMapGenerator" +linkTitle: "ConfigMapGenerator" +weight: 1 +date: 2023-11-16 +description: > + Generate ConfigMap objects. +--- + +## ConfigMapGenerator +ConfigMapGenerator generates [ConfigMap] objects. + +--- + +* **apiVersion**: builtin +* **kind**: ConfigMapGenerator +* **metadata** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta)) + + Kubernetes API object metadata. + +{{< include "../included/generatorargs.md" >}} + +[ConfigMap]: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1/ diff --git a/site/content/en/docs/Reference/API/Generators/SecretGenerator.md b/site/content/en/docs/Reference/API/Generators/SecretGenerator.md new file mode 100644 index 0000000000..8fd05cf211 --- /dev/null +++ b/site/content/en/docs/Reference/API/Generators/SecretGenerator.md @@ -0,0 +1,23 @@ +--- +title: "SecretGenerator" +linkTitle: "SecretGenerator" +weight: 2 +date: 2023-11-16 +description: > + Generate Secret objects. +--- + +## SecretGenerator +SecretGenerator generates [Secret] objects. + +--- + +* **apiVersion**: builtin +* **kind**: SecretGenerator +* **metadata** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta)) + + Kubernetes API object metadata. + +{{< include "../included/secretargs.md" >}} + +[Secret]: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/ diff --git a/site/content/en/docs/Reference/API/Generators/_index.md b/site/content/en/docs/Reference/API/Generators/_index.md new file mode 100644 index 0000000000..507c1539fc --- /dev/null +++ b/site/content/en/docs/Reference/API/Generators/_index.md @@ -0,0 +1,8 @@ +--- +title: "Generators" +linkTitle: "Generators" +weight: 2 +date: 2023-11-16 +description: > + Generators create Kubernetes API resources from metadata. +--- diff --git a/site/content/en/docs/Reference/API/Kustomization File/bases.md b/site/content/en/docs/Reference/API/Kustomization File/bases.md index 2d7bed3d3d..ff5d4bf6a7 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/bases.md +++ b/site/content/en/docs/Reference/API/Kustomization File/bases.md @@ -2,7 +2,7 @@ title: "bases" linkTitle: "bases" type: docs -weight: 1 +weight: 2 description: > Add resources from a kustomization dir. --- diff --git a/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md b/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md index 03d4df2108..ae8049e882 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md +++ b/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md @@ -4,7 +4,25 @@ linkTitle: "configMapGenerator" type: docs weight: 6 description: > - Generate ConfigMap resources. + Generate ConfigMap objects. --- +`apiVersion: kustomize.config.k8s.io/v1beta1` -The Tasks section contains examples of how to use [`configMapGenerator`](/docs/tasks/configmap_generator/). +See the [Tasks section] for examples of how to use `configMapGenerator`. + +### configMapGenerator +ConfigMapGenerator generates [ConfigMap] objects. + +--- + +* **configMapGenerator** ([]ConfigMapArgs) + + List of metadata to generate ConfigMaps. + + _ConfigMapArgs represents metadata and options for ConfigMap generation._ + + {{< include "../included/generatorargs.md" >}} + + +[Tasks section]: /docs/tasks/configmap_generator/ +[ConfigMap]: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1/ diff --git a/site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md b/site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md index 75c40d0d16..d928d02bf2 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md +++ b/site/content/en/docs/Reference/API/Kustomization File/generatorOptions.md @@ -4,112 +4,28 @@ linkTitle: "generatorOptions" type: docs weight: 8 description: > - Control behavior of [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) and - [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) generators. + Modify behavior of generators. --- -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/kustomization-file/configmapgenerator/) and see [secretGenerator](/docs/reference/api/kustomization-file/secretgenerator/). +`apiVersion: kustomize.config.k8s.io/v1beta1` -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization +### generatorOptions +GeneratorOptions modifies resource generation behavior. -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 +* **labels** (map[string]string), optional -```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 -``` + Labels to add to all generated resources. -## Example II +* **annotations** (map[string]string), optional -Using Secrets + Annotations to add to all generated resources. -### Input Files +* **disableNameSuffixHash** (bool), optional -```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 -``` + DisableNameSuffixHash if true disables the default behavior of adding a suffix to the names of generated resources that is a hash of the resource contents. -### Output File +* **immutable** (bool), optional -```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 -``` + Immutable if true add to all generated resources. diff --git a/site/content/en/docs/Reference/API/Kustomization File/kustomization.md b/site/content/en/docs/Reference/API/Kustomization File/kustomization.md new file mode 100644 index 0000000000..7bac4a6ce0 --- /dev/null +++ b/site/content/en/docs/Reference/API/Kustomization File/kustomization.md @@ -0,0 +1,140 @@ +--- +title: "kustomization" +linkTitle: "kustomization" +type: docs +weight: 1 +description: > + Kustomization contains information to generate customized resources. +--- + +`apiVersion: kustomize.config.k8s.io/v1beta1` + +### Kustomization + +--- + +* **apiVersion**: kustomize.config.k8s.io/v1beta1 +* **kind**: Kustomization +* **openAPI** (map[string]string) + + [OpenAPI]({{< ref "openapi.md" >}}) contains information about what kubernetes schema to use. + +* **namePrefix** (string) + + [NamePrefix]({{< ref "namePrefix.md" >}}) will prefix the names of all resources mentioned in the kustomization file including generated configmaps and secrets. + +* **nameSuffix** (string) + + [NameSuffix]({{< ref "nameSuffix.md" >}}) will suffix the names of all resources mentioned in the kustomization file including generated configmaps and secrets. + +* **namespace** (string) + + [Namespace]({{< ref "namespace.md" >}}) to add to all objects. + +* **commonLabels** (map[string]string) + + [CommonLabels]({{< ref "commonLabels.md" >}}) to add to all objects and selectors. + +* **labels** ([][Label]({{< ref "labels.md" >}})) + + Labels to add to all objects but not selectors. + +* **commonAnnotations** (map[string]string) + + [CommonAnnotations]({{< ref "commonAnnotations.md" >}}) to add to all objects. + +* **patchesStrategicMerge** ([][PatchStrategicMerge]({{< ref "patchesStrategicMerge.md" >}})) + + Deprecated: Use the Patches field instead, which provides a superset of the functionality of PatchesStrategicMerge. + +* **patchesJson6902** ([][Patch]({{< ref "patches.md" >}})) + + Deprecated: Use the Patches field instead, which provides a superset of the functionality of JSONPatches. [JSONPatches]({{< ref "patchesjson6902.md" >}}) is a list of JSONPatch for applying JSON patch. + +* **patches** ([][Patch]({{< ref "patches.md" >}})) + + Patches is a list of patches, where each one can be either a Strategic Merge Patch or a JSON patch. Each patch can be applied to multiple target objects. + +* **images** ([][Image]({{< ref "images.md" >}})) + + Images is a list of (image name, new name, new tag or digest) for changing image names, tags or digests. This can also be achieved with a patch, but this operator is simpler to specify. + +* **imageTags** ([][Image]({{< ref "images.md" >}})) + + Deprecated: Use the Images field instead. + +* **replacements** ([][ReplacementField]({{< ref "replacements.md" >}})) + + Replacements is a list of replacements, which will copy nodes from a specified source to N specified targets. + +* **replicas** ([][Replica]({{< ref "replicas.md" >}})) + + Replicas is a list of {resourcename, count} that allows for simpler replica specification. This can also be done with a patch. + +* **vars** ([][Var]({{< ref "vars.md" >}})) + + Deprecated: Vars will be removed in future release. Migrate to Replacements instead. Vars allow things modified by kustomize to be injected into a kubernetes object specification. + +* **sortOptions** ([sortOptions]({{< ref "sortOptions.md" >}})) + + SortOptions change the order that kustomize outputs resources. + +* **resources** ([]string) + + [Resources]({{< ref "resources.md" >}}) specifies relative paths to files holding YAML representations of kubernetes API objects, or specifications of other kustomizations via relative paths, absolute paths, or URLs. + +* **components** ([]string) + + [Components]({{< ref "components.md" >}}) specifies relative paths to specifications of other Components via relative paths, absolute paths, or URLs. + +* **crds** ([]string) + + [Crds]({{< ref "crds.md" >}}) specifies relative paths to Custom Resource Definition files. This allows custom resources to be recognized as operands, making it possible to add them to the Resources list. CRDs themselves are not modified. + +* **bases** ([]string) + + Deprecated: Anything that would have been specified here should be specified in the Resources field instead. [Bases]({{< ref "bases.md" >}}) specifies relative paths to files holding YAML representations of Kubernetes API objects. + +* **configMapGenerator** ([][ConfigMapArgs]({{< ref "configMapGenerator.md#configmapargs" >}})) + + [ConfigMapGenerator]({{< ref "configMapGenerator.md" >}}) is a list of configmaps to generate from local data (one configMap per list item). The resulting resource is a normal operand, subject to name prefixing, patching, etc. By default, the name of the map will have a suffix hash generated from its contents. + +* **secretGenerator** ([][SecretArgs]({{< ref "secretGenerator.md#secretargs" >}})) + + [SecretGenerator]({{< ref "secretGenerator.md" >}}) is a list of secrets to generate from local data (one secret per list item). The resulting resource is a normal operand, subject to name prefixing, patching, etc. By default, the name of the map will have a suffix hash generated from its contents. + +* **helmGlobals** (HelmGlobals) + + HelmGlobals contains helm configuration that isn't chart specific. + +* **helmCharts** ([][HelmChart]({{< ref "helmCharts.md" >}})) + + HelmCharts is a list of helm chart configuration instances. + +* **helmChartInflationGenerator** ([]HelmChartArgs) + + Deprecated: Auto-converted to HelmGlobals and [HelmCharts]({{< ref "helmCharts.md" >}}). HelmChartInflationGenerator is a list of helm chart configurations. + +* **generatorOptions** ([GeneratorOptions]({{< ref "generatorOptions.md" >}})) + + GeneratorOptions modify behavior of all ConfigMap and Secret generators. + +* **configurations** ([]string) + + Configurations is a list of transformer configuration files + +* **generators** ([]string) + + Generators is a list of files containing custom generators + +* **transformers** ([]string) + + Transformers is a list of files containing transformers + +* **validators** ([]string) + + Validators is a list of files containing validators + +* **buildMetadata** ([]string) + + [BuildMetadata]({{< ref "buildMetadata.md" >}}) is a list of strings used to toggle different build options diff --git a/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md b/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md index 315a4a2a75..9ef3fce230 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md +++ b/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md @@ -4,7 +4,25 @@ linkTitle: "secretGenerator" type: docs weight: 21 description: > - Generate Secret resources. + Generate Secret objects. --- -The Tasks section contains examples of how to use [`secretGenerator`](/docs/tasks/secret_generator/). +`apiVersion: kustomize.config.k8s.io/v1beta1` + +See the [Tasks section] for examples of how to use `secretGenerator`. + +### secretGenerator +SecretGenerator generates [Secret] objects. + +--- + +* **secretGenerator** ([]SecretArgs) + + List of metadata to generate Secrets. + + _SecretArgs represents metadata and options for Secret generation._ + + {{< include "../included/secretargs.md" >}} + +[Tasks section]: /docs/tasks/secret_generator/ +[Secret]: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/ diff --git a/site/content/en/docs/Reference/API/included/_index.md b/site/content/en/docs/Reference/API/included/_index.md new file mode 100644 index 0000000000..d295492cc0 --- /dev/null +++ b/site/content/en/docs/Reference/API/included/_index.md @@ -0,0 +1,10 @@ +--- +title: "api included" +description: "Snippets to be included in api pages." +headless: true +toc_hide: true +_build: + list: never + render: never + publishResources: false +--- diff --git a/site/content/en/docs/Reference/API/included/generatorargs.md b/site/content/en/docs/Reference/API/included/generatorargs.md new file mode 100644 index 0000000000..4dff01bc75 --- /dev/null +++ b/site/content/en/docs/Reference/API/included/generatorargs.md @@ -0,0 +1,48 @@ +--- +title: "GeneratorArgs" +weight: 2 +date: 2023-11-15 +description: > + GeneratorArgs contains arguments common to generators. +headless: true +_build: + list: never + render: never + publishResources: false +--- + +* **name** (string), optional + + Name of the generated resource. A hash suffix will be added to the Name by default. + +* **namespace** (string), optional + + Namespace of the generated resource. + +* **behavior** (string), optional + + Behavior of generated resource, must be one of: + + * **create**: Create new resource + * **replace**: Replace existing resource + * **merge**: Merge with existing resource + +* **literals** ([]string), optional + + List of string literal pair sources. Each literal source should be a key and literal value, e.g. `key=value`. + +* **files** ([]string), optional + + List of files paths to use in creating a list of key value pairs. A source should be in the form [{key}=]{path}. If the `key=` argument is not provided, the key is the path's basename. If the `key=` argument is provided, it becomes the key. The value is the file contents. Specifying a directory will iterate each named file in the directory whose basename is a valid resource key. + +* **envs** ([]string), optional + + List of file paths. The contents of each file should be one key=value pair per line. Additionally, npm `.env` and `.ini` files are supported. + +* **env** (string), optional + + Env is the singular form of `envs`. This is merged with `env` on edits with `kustomize fix` for consistency with `literals` and `files`. + +* **options** ([GeneratorOptions]({{< ref "../kustomization%20file/generatorOptions.md" >}})) + + Options override global [generatorOptions]({{< ref "../kustomization%20file/generatorOptions.md" >}}) field. diff --git a/site/content/en/docs/Reference/API/included/secretargs.md b/site/content/en/docs/Reference/API/included/secretargs.md new file mode 100644 index 0000000000..70119b4f93 --- /dev/null +++ b/site/content/en/docs/Reference/API/included/secretargs.md @@ -0,0 +1,18 @@ +--- +title: "secretargs" +weight: 2 +date: 2023-11-17 +description: > + SecretArgs contains arguments to generate Secrets. +headless: true +_build: + list: never + render: never + publishResources: false +--- + +{{< include "generatorargs.md" >}} + +* **type** (string), optional + + Type of the secret. Must be `Opaque` or `kubernetes.io/tls`. Defaults to `Opaque`. diff --git a/site/content/en/includes/index.md b/site/content/en/includes/index.md new file mode 100644 index 0000000000..ca03031f1e --- /dev/null +++ b/site/content/en/includes/index.md @@ -0,0 +1,3 @@ +--- +headless: true +--- diff --git a/site/layouts/shortcodes/include.html b/site/layouts/shortcodes/include.html new file mode 100644 index 0000000000..042e17ed8c --- /dev/null +++ b/site/layouts/shortcodes/include.html @@ -0,0 +1,27 @@ +{{/* This will try to find a resource in the "includes" bundle */}} +{{- $name := .Get 0 -}} +{{- if $name -}} + {{- $bundle := site.GetPage "page" "includes" -}} + {{- with $bundle -}} + {{- $pattern := printf "%s*" $name -}} + {{- range $bundle.Resources -}} + {{- end -}} + {{- $resource := $bundle.Resources.GetMatch $pattern -}} + {{- with $resource -}} + {{- .Content | safeHTML -}} + {{- else -}} + {{/* It is not a resource in the includes bundle. Try to find the page relative to the current. */}} + {{- $path := path.Join $.Page.File.Dir $name -}} + {{- $page := site.GetPage "page" $path -}} + {{- with $page }} + {{ .Content }} + {{- else -}} + {{ errorf "[%s] no Resource or Page matching %q." $.Page.Lang ($pattern | safeHTML ) }} + {{- end -}} + {{- end -}} + {{- else -}} + {{ errorf "[%s] the 'includes' bundle was not found." $.Page.Lang }} + {{- end -}} +{{- else -}} + {{- errorf "[%s] missing resource name in include for page %q" $.Page.Lang $.Page.Path -}} +{{- end -}}