From b9700f00458b226070e7214f8d2f141de68a93e3 Mon Sep 17 00:00:00 2001 From: Katrina Verey Date: Fri, 17 Mar 2023 16:20:07 -0400 Subject: [PATCH 1/3] Add annotations reserved by the KRM Functions Specification --- .../labels-annotations-taints/_index.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md index 03397f462f5..529e9638c6a 100644 --- a/content/en/docs/reference/labels-annotations-taints/_index.md +++ b/content/en/docs/reference/labels-annotations-taints/_index.md @@ -104,6 +104,50 @@ The cluster autoscaler never evicts Pods that have this annotation explicitly se `"false"`; you could set that on an important Pod that you want to keep running. If this annotation is not set then the cluster autoscaler follows its Pod-level behavior. +### config.kubernetes.io/local-config + +Example: `config.kubernetes.io/local-config: "true"` + +Used on: All resources + +This annotation is used to mark a resource as a local configuration file that should not be applied to the API server. It is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by tools such as Kustomize and Kpt. For example, Kustomize removes objects with this annotation from its final build output. + +A value of "true" for this annotation declares that the resource is only consumed by client-side tooling and should not be applied to the API server. + +A value of "false" can be used to declare that a resource should be applied to the API server even when it would otherwise be assumed to be local. + +### internal.config.kubernetes.io/* (reserved prefix) + +Used on: All resources + +This prefix is reserved for internal use by tools that act as orchestrators in accordance with the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md). Annotations with this prefix are internal to the orchestration process and are not persisted to resource manifests on the filesystem. In other words, the orchestrator should set these annotations when reading files from the local filesystem and remove them when writing the output of functions back to the filesystem. + +A KRM function **must not** modify annotations with this prefix, unless otherwise specified for a given annotation. This enables orchestrators to add additional internal annotations, without requiring changes to existing functions. + +### internal.config.kubernetes.io/path + +Example: `internal.config.kubernetes.io/path: "relative/file/path.yaml"` + +Used on: All resources + +Records the slash-delimited, OS-agnostic, relative file path to a resource. The path is relative to a fixed location on the filesystem, determined by the orchestrator. + +This annotation is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by function orchestrator tools such as Kustomize and Kpt. + +A KRM Function **should not** modify this annotation on input resources unless it is modifying the referenced files. A KRM Function **may** include this annotation on resources it generates. + +### internal.config.kubernetes.io/index + +Example: `internal.config.kubernetes.io/index: "2"` + +Used on: All resources + +Records the index of a resource in file. In a multi-object YAML file, resources are separated by three dashes (---), and the index represents the position of the resource starting from zero. When this annotation is not specified, it implies a value of 0. + +This annotation is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by function orchestrator tools such as Kustomize and Kpt. + +A KRM Function **should not** modify this annotation on input resources unless it is modifying the referenced files. A KRM Function **may** include this annotation on resources it generates. + ### kubernetes.io/arch Example: `kubernetes.io/arch: "amd64"` From 61b721d04838df7ccfb5b431711a0da76eff5900 Mon Sep 17 00:00:00 2001 From: Katrina Verey Date: Mon, 20 Mar 2023 15:12:11 -0400 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Tim Bannister --- .../en/docs/reference/labels-annotations-taints/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md index 529e9638c6a..0b6a54bdc3e 100644 --- a/content/en/docs/reference/labels-annotations-taints/_index.md +++ b/content/en/docs/reference/labels-annotations-taints/_index.md @@ -108,7 +108,7 @@ If this annotation is not set then the cluster autoscaler follows its Pod-level Example: `config.kubernetes.io/local-config: "true"` -Used on: All resources +Used on: All objects This annotation is used to mark a resource as a local configuration file that should not be applied to the API server. It is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by tools such as Kustomize and Kpt. For example, Kustomize removes objects with this annotation from its final build output. @@ -116,7 +116,7 @@ A value of "true" for this annotation declares that the resource is only consume A value of "false" can be used to declare that a resource should be applied to the API server even when it would otherwise be assumed to be local. -### internal.config.kubernetes.io/* (reserved prefix) +### internal.config.kubernetes.io/* (reserved prefix) {#internal.config.kubernetes.io-reserved-wildcard} Used on: All resources @@ -130,7 +130,7 @@ Example: `internal.config.kubernetes.io/path: "relative/file/path.yaml"` Used on: All resources -Records the slash-delimited, OS-agnostic, relative file path to a resource. The path is relative to a fixed location on the filesystem, determined by the orchestrator. +Records the slash-delimited, OS-agnostic, relative file path to a manifest representing a resource. The path is relative to a fixed location on the filesystem, determined by the orchestrator tool. This annotation is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by function orchestrator tools such as Kustomize and Kpt. From dc203c13e653e26a5d2df027b69b7f5f25dce020 Mon Sep 17 00:00:00 2001 From: Katrina Verey Date: Mon, 20 Mar 2023 15:47:25 -0400 Subject: [PATCH 3/3] Apply feedback --- .../labels-annotations-taints/_index.md | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md index 0b6a54bdc3e..504d8700c26 100644 --- a/content/en/docs/reference/labels-annotations-taints/_index.md +++ b/content/en/docs/reference/labels-annotations-taints/_index.md @@ -110,43 +110,46 @@ Example: `config.kubernetes.io/local-config: "true"` Used on: All objects -This annotation is used to mark a resource as a local configuration file that should not be applied to the API server. It is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by tools such as Kustomize and Kpt. For example, Kustomize removes objects with this annotation from its final build output. +This annotation is used in manifests to mark an object as local configuration that should not be submitted to the Kubernetes API. -A value of "true" for this annotation declares that the resource is only consumed by client-side tooling and should not be applied to the API server. +A value of "true" for this annotation declares that the object is only consumed by client-side tooling and should not be submitted to the API server. + +A value of "false" can be used to declare that the object should be submitted to the API server even when it would otherwise be assumed to be local. + +This annotation is part of the Kubernetes Resource Model (KRM) Functions Specification, which is used by Kustomize and similar third-party tools. For example, Kustomize removes objects with this annotation from its final build output. -A value of "false" can be used to declare that a resource should be applied to the API server even when it would otherwise be assumed to be local. ### internal.config.kubernetes.io/* (reserved prefix) {#internal.config.kubernetes.io-reserved-wildcard} -Used on: All resources +Used on: All objects -This prefix is reserved for internal use by tools that act as orchestrators in accordance with the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md). Annotations with this prefix are internal to the orchestration process and are not persisted to resource manifests on the filesystem. In other words, the orchestrator should set these annotations when reading files from the local filesystem and remove them when writing the output of functions back to the filesystem. +This prefix is reserved for internal use by tools that act as orchestrators in accordance with the Kubernetes Resource Model (KRM) Functions Specification. Annotations with this prefix are internal to the orchestration process and are not persisted to the manifests on the filesystem. In other words, the orchestrator tool should set these annotations when reading files from the local filesystem and remove them when writing the output of functions back to the filesystem. -A KRM function **must not** modify annotations with this prefix, unless otherwise specified for a given annotation. This enables orchestrators to add additional internal annotations, without requiring changes to existing functions. +A KRM function **must not** modify annotations with this prefix, unless otherwise specified for a given annotation. This enables orchestrator tools to add additional internal annotations, without requiring changes to existing functions. ### internal.config.kubernetes.io/path Example: `internal.config.kubernetes.io/path: "relative/file/path.yaml"` -Used on: All resources +Used on: All objects -Records the slash-delimited, OS-agnostic, relative file path to a manifest representing a resource. The path is relative to a fixed location on the filesystem, determined by the orchestrator tool. +This annotation records the slash-delimited, OS-agnostic, relative path to the manifest file the object was loaded from. The path is relative to a fixed location on the filesystem, determined by the orchestrator tool. -This annotation is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by function orchestrator tools such as Kustomize and Kpt. +This annotation is part of the Kubernetes Resource Model (KRM) Functions Specification, which is used by Kustomize and similar third-party tools. -A KRM Function **should not** modify this annotation on input resources unless it is modifying the referenced files. A KRM Function **may** include this annotation on resources it generates. +A KRM Function **should not** modify this annotation on input objects unless it is modifying the referenced files. A KRM Function **may** include this annotation on objects it generates. ### internal.config.kubernetes.io/index Example: `internal.config.kubernetes.io/index: "2"` -Used on: All resources +Used on: All objects -Records the index of a resource in file. In a multi-object YAML file, resources are separated by three dashes (---), and the index represents the position of the resource starting from zero. When this annotation is not specified, it implies a value of 0. +This annotation records the zero-indexed position of the YAML document that contains the object within the manifest file the object was loaded from. Note that YAML documents are separated by three dashes (`---`) and can each contain one object. When this annotation is not specified, a value of 0 is implied. -This annotation is part of the [Kubernetes Resource Model (KRM) Functions Specification](https://github.com/kubernetes-sigs/kustomize/blob/ce3e394a414387ce09679523902e981414b09a1a/cmd/config/docs/api-conventions/functions-spec.md) that is used by function orchestrator tools such as Kustomize and Kpt. +This annotation is part of the Kubernetes Resource Model (KRM) Functions Specification, which is used by Kustomize and similar third-party tools. -A KRM Function **should not** modify this annotation on input resources unless it is modifying the referenced files. A KRM Function **may** include this annotation on resources it generates. +A KRM Function **should not** modify this annotation on input objects unless it is modifying the referenced files. A KRM Function **may** include this annotation on objects it generates. ### kubernetes.io/arch