mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-11 09:02:53 +00:00
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
This commit is contained in:
Nick
@@ -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/
|
||||
|
||||
@@ -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/
|
||||
|
||||
Reference in New Issue
Block a user