From bfb00ecb2747dc711abfc27d9cf788ca1d7c637b Mon Sep 17 00:00:00 2001 From: Nick <10539313+ncapps@users.noreply.github.com> Date: Sat, 25 Nov 2023 12:34:10 -0800 Subject: [PATCH] Add common Tasks to documentation (#5383) * Add labels, annotations, namespaces, and names tasks * Remove redundant information from ref/labels ref/annotations * Update labels and annotations example names for consistency * Remove name, prefix and suffix api examples * Add link to tasks in reference * Add link to tasks section for ref/configMapGenerator and ref/secretGenerator * Add Labels/Annotatations headers * Add Labels * Add Template Labels * Cleanup Add Template Labels * Consolidate commonLabels and labels.includeSelectors * Improve commonAnnotations example * Add labels and annotations ref links * Add generated ConfigMap to namespace example * Add name headers * Change header weights so they appear in sidebar * Add namespace/name links * Add generated ConfigMap to namePrefix example * Add name propagation example * Add more description of name propagation * template labels * Address feedback for labels * Address names feedback * Update for consistency * Address feedback * Remove API --- .../Kustomization File/commonAnnotations.md | 50 +-- .../API/Kustomization File/commonLabels.md | 99 +----- .../Kustomization File/configMapGenerator.md | 2 + .../API/Kustomization File/labels.md | 229 +------------- .../API/Kustomization File/namePrefix.md | 56 +--- .../API/Kustomization File/nameSuffix.md | 49 +-- .../API/Kustomization File/namespace.md | 50 +-- .../API/Kustomization File/secretGenerator.md | 4 +- .../en/docs/Tasks/labels_and_annotations.md | 290 +++++++++++++++++- .../en/docs/Tasks/namespaces_and_names.md | 249 +++++++++++++++ 10 files changed, 547 insertions(+), 531 deletions(-) diff --git a/site/content/en/docs/Reference/API/Kustomization File/commonAnnotations.md b/site/content/en/docs/Reference/API/Kustomization File/commonAnnotations.md index db4230e9d3..1c72a082a1 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/commonAnnotations.md +++ b/site/content/en/docs/Reference/API/Kustomization File/commonAnnotations.md @@ -7,52 +7,4 @@ 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: - ... -``` +The Tasks section contains examples of how to use [`commonAnnotations`](/docs/tasks/labels_and_annotations/). diff --git a/site/content/en/docs/Reference/API/Kustomization File/commonLabels.md b/site/content/en/docs/Reference/API/Kustomization File/commonLabels.md index 379a35a95d..b9d73b2bb3 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/commonLabels.md +++ b/site/content/en/docs/Reference/API/Kustomization File/commonLabels.md @@ -7,101 +7,4 @@ description: > Add labels and selectors to add all resources. --- -[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. - -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 -``` +The Tasks section contains examples of how to use [`commonLabels`](/docs/tasks/labels_and_annotations/). 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 e37a98d6d2..03d4df2108 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md +++ b/site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md @@ -6,3 +6,5 @@ weight: 6 description: > Generate ConfigMap resources. --- + +The Tasks section contains examples of how to use [`configMapGenerator`](/docs/tasks/configmap_generator/). diff --git a/site/content/en/docs/Reference/API/Kustomization File/labels.md b/site/content/en/docs/Reference/API/Kustomization File/labels.md index 750fcaa905..7ada7e9c7f 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/labels.md +++ b/site/content/en/docs/Reference/API/Kustomization File/labels.md @@ -7,231 +7,4 @@ 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 -``` +The Tasks section contains examples of how to use [`labels`](/docs/tasks/labels_and_annotations/). diff --git a/site/content/en/docs/Reference/API/Kustomization File/namePrefix.md b/site/content/en/docs/Reference/API/Kustomization File/namePrefix.md index 256e55ef99..d88d617775 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/namePrefix.md +++ b/site/content/en/docs/Reference/API/Kustomization File/namePrefix.md @@ -7,58 +7,4 @@ 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 >}} +The Tasks section contains examples of how to use [`namePrefix`](/docs/tasks/namespaces_and_names/). diff --git a/site/content/en/docs/Reference/API/Kustomization File/nameSuffix.md b/site/content/en/docs/Reference/API/Kustomization File/nameSuffix.md index be5d7da11b..5f8347da56 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/nameSuffix.md +++ b/site/content/en/docs/Reference/API/Kustomization File/nameSuffix.md @@ -7,51 +7,4 @@ 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 -``` +The Tasks section contains examples of how to use [`nameSuffix`](/docs/tasks/namespaces_and_names/). diff --git a/site/content/en/docs/Reference/API/Kustomization File/namespace.md b/site/content/en/docs/Reference/API/Kustomization File/namespace.md index 1685c45d4d..d72134a236 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/namespace.md +++ b/site/content/en/docs/Reference/API/Kustomization File/namespace.md @@ -7,52 +7,4 @@ 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 -``` +The Tasks section contains examples of how to use [`namespace`](/docs/tasks/namespaces_and_names/). 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 a111b8317d..315a4a2a75 100644 --- a/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md +++ b/site/content/en/docs/Reference/API/Kustomization File/secretGenerator.md @@ -7,6 +7,4 @@ 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](/docs/reference/api/kustomization-file/configmapgenerator). +The Tasks section contains examples of how to use [`secretGenerator`](/docs/tasks/secret_generator/). diff --git a/site/content/en/docs/Tasks/labels_and_annotations.md b/site/content/en/docs/Tasks/labels_and_annotations.md index bb90b3e237..4e0f063095 100644 --- a/site/content/en/docs/Tasks/labels_and_annotations.md +++ b/site/content/en/docs/Tasks/labels_and_annotations.md @@ -2,7 +2,295 @@ title: "Labels and Annotations" linkTitle: "Labels and Annotations" weight: 3 -date: 2017-01-05 +date: 2023-10-14 description: > Working with Labels and Annotations --- + +A common set of labels can be applied to all Resources in a project by adding a [`labels`] or [`commonLabels`] entry to the `kustomization.yaml` file. Similarly, a common set of annotations can be applied to Resources with the [`commonAnnotations`] field. + +## Working with Labels +### Add Labels +[`labels`] can be used to add labels to the `metadata` field of all Resources in a project. This will override values for label keys that already exist. + +Here is an example of how to add labels to the `metadata` field. +1. Create a Kustomization file. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +labels: +- pairs: + someName: someValue + owner: alice + app: bingo + +resources: +- deploy.yaml +- service.yaml +``` + +2. Create Deployment and Service manifests. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +3. Add labels with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that the `labels` field is used to add labels to the `metadata` field of the Service and Deployment Resources. +```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 +``` +### Add Template Labels +[`labels.includeTemplates`] can be used to add labels to the template field of all applicable Resources in a project. + +Here is an example of how to add labels to the template field of a Deployment. +1. Create a Kustomization file. +```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 +``` + +2. Create Deployment and Service manifests. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +3. Add labels with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that labels are added to the `metadata` field and the `labels.includeTemplates` field is used to add labels to the template field of the Deployment. However, the [Service] Resource does not have a template field, and Kustomize does not add this field. + +```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 +``` +### Add Selector Labels +[`labels.includeSelectors`] can be used to add labels to the selector field of applicable Resources in a project. Note that this also adds labels to the template field for applicable Resources. + +Labels added to the selector field should not be changed after Workload and Service Resources have been created in a cluster. + +Here is an example of how to add labels to the selector field. +1. Create a Kustomization file. +```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 +``` + +2. Create Deployment and Service manifests. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` +```yaml +# service.yaml +apiVersion: v1 +kind: Service +metadata: + name: example +``` + +3. Add labels with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that labels are added to the `metadata` field and the `labels.includeSelectors` field is used to add labels to the selector and template fields for applicable Resources. However, the [Service] Resource does not have a template field, and Kustomize does not add this field. +```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 +``` + +The following example produces the same result. The [`commonLabels`] field is equivalent to using [`labels.includeSelectors`]. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +commonLabels: + someName: someValue + owner: alice + app: bingo + +resources: +- deploy.yaml +- service.yaml +``` + +## Working with Annotations +### Add Annotations +[`commonAnnotations`] can be used to add annotations to all Resources in a project. This will override values for annotations keys that already exist. Annotations are propagated to the Deployment Pod template. + +Here is an example of how to add annotations to a Deployment. +1. Create a Kustomization file. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +commonAnnotations: + oncallPager: 800-867-5309 + +resources: +- deploy.yaml +``` + +2. Create a Deployment manifest. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +3. Add annotations with `kustomize build`. +```bash +kustomize build . +``` +The output shows that the `commonAnnotations` field is used to add annotations to a Deployment. +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example + annotations: + oncallPager: 800-867-5309 +spec: + template: + metadata: + annotations: + oncallPager: 800-867-5309 +``` + +[`labels`]: /docs/reference/api/kustomization-file/labels/ +[`labels.includeTemplates`]: /docs/reference/api/kustomization-file/labels/ +[`labels.includeSelectors`]: /docs/reference/api/kustomization-file/labels/ +[`commonLabels`]: /docs/reference/api/kustomization-file/commonlabels/ +[`commonAnnotations`]: /docs/reference/api/kustomization-file/commonannotations/ +[Service]: https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/ diff --git a/site/content/en/docs/Tasks/namespaces_and_names.md b/site/content/en/docs/Tasks/namespaces_and_names.md index 572cd6d2b3..6c184d4625 100644 --- a/site/content/en/docs/Tasks/namespaces_and_names.md +++ b/site/content/en/docs/Tasks/namespaces_and_names.md @@ -6,3 +6,252 @@ date: 2023-10-14 description: > Working with Namespaces and Names --- + +The Namespace can be set for all Resources in a project by adding the [`namespace`] entry to the `kustomization.yaml` file. Consistent naming conventions can be applied to Resource Names in a project with the [`namePrefix`] and [`nameSuffix`] fields. + +## Working with Namespaces +[`namespace`] sets the Namespace for all namespaced Resources in a project. This sets the Namespace for both generated Resources (e.g. ConfigMaps and Secrets) and non-generated Resources. This will override Namespace values that already exist. + +### Add Namespace +Here is an example of how to set the Namespace of a Deployment and a generated ConfigMap. The ConfigMap is generated with [`configMapGenerator`]. + +1. Create a Kustomization file. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +namespace: my-namespace + +configMapGenerator: +- name: my-config + literals: + - FOO=BAR + +resources: +- deploy.yaml +``` + +2. Create a Deployment manifest. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +3. Add Namespace with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that the `namespace` field is used to set the Namespace of the Deployment and the generated ConfigMap. +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example + namespace: my-namespace +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-config-m2mg5mb749 + namespace: my-namespace +data: + FOO: BAR +``` + +## Working with Names +A prefix or suffix can be set for all Resources in a project with the [`namePrefix`] and [`nameSuffix`] fields. This sets a name prefix and suffix for both generated Resources (e.g. ConfigMaps and Secrets) and non-generated Resources. + +Resources such as Deployments and StatefulSets may reference other Resources such as ConfigMaps and Secrets in the Pod Spec. The name prefix and suffix will also propagate to Resource references in a project. Typical uses cases include Service reference from a StatefulSet, ConfigMap reference from a Pod Spec, and Secret reference from a Pod Spec. + +### Add Name Prefix +[`namePrefix`] can be used to add a prefix to the name of all Resources in a project. + +Here is an example of how to add a prefix to a Deployment. + +1. Create a Kustomization file. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +namePrefix: foo- + +resources: +- deploy.yaml +``` + +2. Create a Deployment manifest. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +3. Add name prefix with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that the `namePrefix` field is used to add a prefix to the name of the Deployment. +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: foo-example +``` + +### Add Name Suffix +[`nameSuffix`] can be used to add a suffix to the name of all Resources in a project. + +Here is an example of how to add a suffix to the name of a Deployment and a generated ConfigMap. The ConfigMap is generated with [`configMapGenerator`]. + +1. Create a Kustomization file. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +nameSuffix: -bar + +configMapGenerator: +- name: my-config + literals: + - FOO=BAR + +resources: +- deploy.yaml +``` + +2. Create a Deployment manifest. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +``` + +3. Add name suffix with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that the `nameSuffix` field is used to add a suffix to the name of the Deployment and the generated ConfigMap. +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: my-config-bar-m2mg5mb749 +data: + FOO: BAR +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example-bar +``` + +### Propagate Name Prefix to Resource Reference +[`namePrefix`] and [`nameSuffix`] propagate Resources name changes to Resource references in a project. + +Here is an example of how the name prefix of a generated ConfigMap is propagated to the Pod Spec of a Deployment that references the ConfigMap to set a container environment variable. +1. Create a Kustomization file. +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +namePrefix: foo- + +configMapGenerator: +- name: special-config + literals: + - special.how=very + +resources: +- deploy.yaml +``` + +2. Create a Deployment manifest. This Deployment is configured to set an environment variable in the `busybox` container using data from the generated ConfigMap. +```yaml +# deploy.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: example + name: example +spec: + replicas: 1 + selector: + matchLabels: + app: example + template: + metadata: + labels: + app: example + spec: + containers: + - image: registry.k8s.io/busybox + name: busybox + command: [ "/bin/sh", "-c", "env" ] + env: + - name: SPECIAL_LEVEL_KEY + valueFrom: + configMapKeyRef: + name: special-config + key: special.how +``` + +3. Add name prefix with `kustomize build`. +```bash +kustomize build . +``` + +The output shows that the name prefix is propagated to the ConfigMap name reference in the Deployment Pod Spec. +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: foo-special-config-9k6fhm8659 +data: + special.how: very +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: example + name: foo-example +spec: + replicas: 1 + selector: + matchLabels: + app: example + template: + metadata: + labels: + app: example + spec: + containers: + - command: + - /bin/sh + - -c + - env + env: + - name: SPECIAL_LEVEL_KEY + valueFrom: + configMapKeyRef: + key: special.how + name: foo-special-config-9k6fhm8659 + image: registry.k8s.io/busybox + name: busybox +``` + +[`namespace`]: /docs/reference/api/kustomization-file/namespace/ +[`namePrefix`]: /docs/reference/api/kustomization-file/nameprefix/ +[`nameSuffix`]: /docs/reference/api/kustomization-file/namesuffix/ +[`configMapGenerator`]: /docs/reference/api/kustomization-file/configmapgenerator/