diff --git a/cmd/test-manifests/hello/kustomization.yaml b/cmd/test-manifests/hello/kustomization.yaml index ff1cb63a2..c446e234f 100644 --- a/cmd/test-manifests/hello/kustomization.yaml +++ b/cmd/test-manifests/hello/kustomization.yaml @@ -1,4 +1,4 @@ -commonLabels: +labels: app: hello namespace: default diff --git a/site/content/en/faq/kustomize/_index.md b/site/content/en/faq/kustomize/_index.md index e7bd2d5f6..c3279e92f 100644 --- a/site/content/en/faq/kustomize/_index.md +++ b/site/content/en/faq/kustomize/_index.md @@ -74,7 +74,7 @@ The configuration directive allows customization of the following transformers: ```yaml commonAnnotations: [] -commonLabels: [] +labels: [] nameprefix: [] namespace: [] varreference: [] diff --git a/site/content/en/guides/config_management/labels_annotations.md b/site/content/en/guides/config_management/labels_annotations.md index fbe9e5cb3..f380907d8 100755 --- a/site/content/en/guides/config_management/labels_annotations.md +++ b/site/content/en/guides/config_management/labels_annotations.md @@ -9,7 +9,7 @@ description: > {{< alert color="success" title="TL;DR" >}} -- Set Labels for all Resources declared within a Project with `commonLabels` +- Set Labels for all Resources declared within a Project with `labels` - Set Annotations for all Resources declared within a Project with `commonAnnotations` {{< /alert >}} @@ -26,9 +26,9 @@ Users may want to define a common set of labels or annotations for all the Resou ## Setting Labels -**Example:** Add the labels declared in `commonLabels` to all Resources in the project. +**Example:** Add the labels declared in `labels` to all Resources in the project. -**Important:** Once set, commonLabels should not be changed so as not to change the Selectors for Services +**Important:** Once set, labels should not be changed so as not to change the Selectors for Services or Workloads. **Input:** The kustomization.yaml and deployment.yaml files @@ -37,7 +37,7 @@ or Workloads. # kustomization.yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization -commonLabels: +labels: app: foo environment: test resources: @@ -99,22 +99,22 @@ spec: ``` {{% alert color="success" title="Command / Examples" %}} -Check out the [reference](/references/kustomize/kustomization/commonlabels/) for commands and examples for `setting labels` +Check out the [reference](/references/kustomize/kustomization/labels/) for commands and examples for `setting labels` {{% /alert %}} ### Propagating Labels to Selectors In addition to updating the labels for each Resource, any selectors will also be updated to target the -labels. e.g. the selectors for Services in the project will be updated to include the commonLabels +labels. e.g. the selectors for Services in the project will be updated to include the labels *in addition* to the other labels. -**Note:** Once set, commonLabels should not be changed so as not to change the Selectors for Services +**Note:** Once set, labels should not be changed so as not to change the Selectors for Services or Workloads. {{< alert color="success" title="Common Labels" >}} The k8s.io documentation defines a set of [Common Labeling Conventions](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/) that may be applied to Applications. -**Note:** commonLabels should only be set for **immutable** labels, since they will be applied to Selectors. +**Note:** labels should only be set for **immutable** labels, since they will be applied to Selectors. Labeling Workload Resources makes it simpler to query Pods - e.g. for the purpose of getting their logs. {{< /alert >}} diff --git a/site/content/en/guides/extending_kustomize/_index.md b/site/content/en/guides/extending_kustomize/_index.md index ed88329bf..501784ef4 100644 --- a/site/content/en/guides/extending_kustomize/_index.md +++ b/site/content/en/guides/extending_kustomize/_index.md @@ -28,7 +28,7 @@ and _transformers_. * A _transformer_ plugin makes changes to existing Kubernetes objects. For example, it might apply a custom order to the resource list, perform special container command line edits, or any other transformation beyond those provided by the - builtin (`namePrefix`, `commonLabels`, etc.) + builtin (`namePrefix`, `labels`, etc.) transformers. [generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md diff --git a/site/content/en/guides/extending_kustomize/exec_krm_functions.md b/site/content/en/guides/extending_kustomize/exec_krm_functions.md index e950acc61..64604f305 100644 --- a/site/content/en/guides/extending_kustomize/exec_krm_functions.md +++ b/site/content/en/guides/extending_kustomize/exec_krm_functions.md @@ -173,7 +173,7 @@ referencing all of the above: ```yaml # $MYAPP/kustomization.yaml -commonLabels: +labels: app: hello resources: - deployment.yaml diff --git a/site/content/en/guides/extending_kustomize/exec_plugins.md b/site/content/en/guides/extending_kustomize/exec_plugins.md index c4b448a8f..4e11861ae 100644 --- a/site/content/en/guides/extending_kustomize/exec_plugins.md +++ b/site/content/en/guides/extending_kustomize/exec_plugins.md @@ -188,7 +188,7 @@ referencing all of the above: ```bash # $MYAPP/kustomization.yaml -commonLabels: +labels: app: hello resources: - deployment.yaml diff --git a/site/content/en/guides/extending_kustomize/go_plugins.md b/site/content/en/guides/extending_kustomize/go_plugins.md index 2a2273017..cfef3571f 100644 --- a/site/content/en/guides/extending_kustomize/go_plugins.md +++ b/site/content/en/guides/extending_kustomize/go_plugins.md @@ -472,7 +472,7 @@ config: ```shell cat <$MYAPP/kustomization.yaml -commonLabels: +labels: app: hello generators: - secGenerator.yaml diff --git a/site/content/en/references/kubectl/apply/_index.md b/site/content/en/references/kubectl/apply/_index.md index 24066b1f9..3421e40c2 100755 --- a/site/content/en/references/kubectl/apply/_index.md +++ b/site/content/en/references/kubectl/apply/_index.md @@ -56,7 +56,7 @@ resources: namespace: default # labels added to all Resources -commonLabels: +labels: app: example env: test ``` diff --git a/site/content/en/references/kustomize/builtins/_index.md b/site/content/en/references/kustomize/builtins/_index.md index d0b70962b..16f34f5b8 100644 --- a/site/content/en/references/kustomize/builtins/_index.md +++ b/site/content/en/references/kustomize/builtins/_index.md @@ -239,12 +239,12 @@ images: ### Usage via `kustomization.yaml` -#### field name: `commonLabels` +#### field name: `labels` Adds labels to all resources and selectors ```bash -commonLabels: +labels: someName: someValue owner: alice app: bingo diff --git a/site/content/en/references/kustomize/cmd/create/_index.md b/site/content/en/references/kustomize/cmd/create/_index.md index acb41efe8..13c3e1163 100644 --- a/site/content/en/references/kustomize/cmd/create/_index.md +++ b/site/content/en/references/kustomize/cmd/create/_index.md @@ -26,6 +26,6 @@ resources: - deployment.yaml - service.yaml namespace: myapp -commonLabels: +labels: app: myapp ``` diff --git a/site/content/en/references/kustomize/cmd/localize/_index.md b/site/content/en/references/kustomize/cmd/localize/_index.md index 87669e22a..885b98d68 100644 --- a/site/content/en/references/kustomize/cmd/localize/_index.md +++ b/site/content/en/references/kustomize/cmd/localize/_index.md @@ -108,7 +108,7 @@ example ```shell # example/localized-remote-kustomize-v5.0.0/kustomization.yaml apiVersion: kustomize.config.k8s.io/v1beta1 -commonLabels: +labels: purpose: remoteReference kind: Kustomization resources: diff --git a/site/content/en/references/kustomize/glossary/_index.md b/site/content/en/references/kustomize/glossary/_index.md index e9eead795..542ad11dc 100644 --- a/site/content/en/references/kustomize/glossary/_index.md +++ b/site/content/en/references/kustomize/glossary/_index.md @@ -186,7 +186,7 @@ falling into four categories: * _transformers_ - what to _do_ to the aforementioned resources. Example fields: _namePrefix_, _nameSuffix_, _images_, - _commonLabels_, _patchesJson6902_, etc. and the more + _labels_, _patchesJson6902_, etc. and the more general _transformers_ (v2.1) field. * _meta_ - fields which may influence all or some of diff --git a/site/content/en/references/kustomize/kustomization/_index.md b/site/content/en/references/kustomize/kustomization/_index.md index cb316a9c6..0a5607c60 100644 --- a/site/content/en/references/kustomize/kustomization/_index.md +++ b/site/content/en/references/kustomize/kustomization/_index.md @@ -41,7 +41,7 @@ validators: The order in each of these lists is relevant and respected. -> There are other fields too, e.g. `commonLabels`, `namePrefixes`, +> There are other fields too, e.g. `labels`, `namePrefixes`, > `patches`, etc. These fields are _convenience_ fields, shorthand for > longer transformer configuration stanzas, and are discussed later. > They're what's used most often, but it's useful to first cover diff --git a/site/content/en/references/kustomize/kustomization/commonlabels/_index.md b/site/content/en/references/kustomize/kustomization/commonlabels/_index.md index 3c57b9580..d7dc9a1c7 100644 --- a/site/content/en/references/kustomize/kustomization/commonlabels/_index.md +++ b/site/content/en/references/kustomize/kustomization/commonlabels/_index.md @@ -9,19 +9,27 @@ description: > [labels]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/labels/ +{{% pageinfo color="warning" %}} +The `commonLabels` field was deprecated in v5.0.0. Please use the [labels] field instead. + +The `commonLabels` 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 `commonLabels` to `labels`. + +Note: 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 %}} + 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 diff --git a/site/content/en/references/kustomize/kustomization/labels/_index.md b/site/content/en/references/kustomize/kustomization/labels/_index.md index 750fcaa90..ebfd836ae 100644 --- a/site/content/en/references/kustomize/kustomization/labels/_index.md +++ b/site/content/en/references/kustomize/kustomization/labels/_index.md @@ -8,14 +8,14 @@ description: > --- 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. +This can be used instead of the deprecated `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. +is equivalent to changing the deprecated `commonLabels` and could result in failures. {{% /pageinfo %}} The following flags are available: diff --git a/site/content/zh/api-reference/glossary/_index.md b/site/content/zh/api-reference/glossary/_index.md index 8737ee7bd..1ef13971d 100644 --- a/site/content/zh/api-reference/glossary/_index.md +++ b/site/content/zh/api-reference/glossary/_index.md @@ -119,7 +119,7 @@ Kustomize 鼓励对声明式应用程序管理([Declarative Application Manage - `resources`:待定制的现存[资源],示例字段:`resources`、`crds`。 - `generator`:将要创建的**新**资源,示例字段:`configMapGenerator`(传统)、`secretGenerator`(传统)、`generators`(v2.1) -- `transformer`:对前面提到的新旧资源进行**处理**的方式。示例字段:`namePrefix`、`nameSuffix`、`images`、`commonLabels`、`patchesJson6902` 等。在 v2.1 中还有更多的 `transformer`。 +- `transformer`:对前面提到的新旧资源进行**处理**的方式。示例字段:`namePrefix`、`nameSuffix`、`images`、`labels`、`patchesJson6902` 等。在 v2.1 中还有更多的 `transformer`。 - `meta`:会对上面几种字段产生影响。示例字段:`vars`、`namespace`、`apiVersion`、`kind` 等。 ## kustomization root diff --git a/site/content/zh/faq/_index.md b/site/content/zh/faq/_index.md index 25846215e..9ff6402ba 100644 --- a/site/content/zh/faq/_index.md +++ b/site/content/zh/faq/_index.md @@ -53,7 +53,7 @@ The configuration directive allows customization of the following transformers: ```yaml commonAnnotations: [] -commonLabels: [] +labels: [] nameprefix: [] namespace: [] varreference: [] diff --git a/site/content/zh/guides/plugins/_index.md b/site/content/zh/guides/plugins/_index.md index 14291a97b..fd2111af4 100644 --- a/site/content/zh/guides/plugins/_index.md +++ b/site/content/zh/guides/plugins/_index.md @@ -17,7 +17,7 @@ Kustomize 提供一个插件框架,允许用户开发自己的 _生成器_ 和 [12-factor]: https://12factor.net * _generator_ 插件生成 k8s 资源,比如 [helm chart inflator] 是一个 generator 插件,基于少量自由变量生成一个 [12-factor] 应用所包含的全部组件 deployment,service,scaler,ingress 等)也是一个 generator 插件。 -* _transformer_ 插件转化(修改)k8s 资源,比如可能会执行对特殊容器命令行的编辑,或为其他内置转换器(`namePrefix`、`commonLabels` 等)无法转换的内容提供转换。 +* _transformer_ 插件转化(修改)k8s 资源,比如可能会执行对特殊容器命令行的编辑,或为其他内置转换器(`namePrefix`、`labels` 等)无法转换的内容提供转换。 ## `kustomization.yaml` 的格式 diff --git a/site/content/zh/guides/plugins/builtins.md b/site/content/zh/guides/plugins/builtins.md index 86c270135..5f6e8b364 100644 --- a/site/content/zh/guides/plugins/builtins.md +++ b/site/content/zh/guides/plugins/builtins.md @@ -208,12 +208,12 @@ images: ### 使用 `kustomization.yaml` -#### 字段名称:`commonLabels` +#### 字段名称:`labels` 为所有资源和 selectors 增加标签。 ```yaml -commonLabels: +labels: someName: someValue owner: alice app: bingo diff --git a/site/content/zh/guides/plugins/execPluginGuidedExample.md b/site/content/zh/guides/plugins/execPluginGuidedExample.md index c445b82ee..6b7f4a68c 100644 --- a/site/content/zh/guides/plugins/execPluginGuidedExample.md +++ b/site/content/zh/guides/plugins/execPluginGuidedExample.md @@ -104,7 +104,7 @@ EOF ```bash cat <$MYAPP/kustomization.yaml -commonLabels: +labels: app: hello resources: - deployment.yaml diff --git a/site/content/zh/guides/plugins/goPluginGuidedExample.md b/site/content/zh/guides/plugins/goPluginGuidedExample.md index 91a1ba28d..090b7f4c0 100644 --- a/site/content/zh/guides/plugins/goPluginGuidedExample.md +++ b/site/content/zh/guides/plugins/goPluginGuidedExample.md @@ -178,7 +178,7 @@ EOF ```shell cat <$MYAPP/kustomization.yaml -commonLabels: +labels: app: hello generators: - secGenerator.yaml