Add generator kustomization references (#5447)

* Initial configMapGenerator ref * Draft configMapGenerator options * ConfigMapArgs * Add sources * Begin to restructure generator spec * Add ObjectMeta * Draft kustomization.md * Draft kustomization file links * Move bases weight * Update generatorArgs link to commmon generatorOptions * Remove api/generators for now * Update generatorOptions * Add generatorArgs header * Add secretGenerator * Remove ObjectMeta for now * Draft generators * Fix secretGenerator * Cleanup * Add include shortcode, cleanup generators * Use common includes * Update object metadata description * spelling * Improve args description
kubernetes-sigs · Jan 10, 2024 · f3fedac · f3fedac
1 parent f72db33
commit f3fedac
Show file tree

Hide file tree

Showing 13 changed files with 354 additions and 102 deletions.
diff --git a/site/content/en/docs/Reference/API/Generators/ConfigMapGenerator.md 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
+---