From 0de5b70e5192896d74599699cb67b79eea6cba71 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Thu, 8 Jun 2023 18:22:07 +0800 Subject: [PATCH] Refactor the label-annotation-taints page The page is currently a mixture of labels, annotations and taints. The line wrappings are terrible. This PR attempts to refactor the page against the style guide. --- .../labels-annotations-taints/_index.md | 945 +++++++++++++----- 1 file changed, 700 insertions(+), 245 deletions(-) diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md index 035db5e547..9f3b08b349 100644 --- a/content/en/docs/reference/labels-annotations-taints/_index.md +++ b/content/en/docs/reference/labels-annotations-taints/_index.md @@ -7,7 +7,7 @@ no_list: true -Kubernetes reserves all labels and annotations in the kubernetes.io and k8s.io namespaces. +Kubernetes reserves all labels and annotations in the `kubernetes.io` and `k8s.io` namespaces. This document serves both as a reference to the values and as a coordination point for assigning values. @@ -17,19 +17,23 @@ This document serves both as a reference to the values and as a coordination poi ### app.kubernetes.io/component +Type: Label + Example: `app.kubernetes.io/component: "database"` Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). -The component within the architecture. +The component within the application architecture. One of the [recommended labels](/docs/concepts/overview/working-with-objects/common-labels/#labels). ### app.kubernetes.io/created-by (deprecated) +Type: Label + Example: `app.kubernetes.io/created-by: "controller-manager"` -Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). +Used on: All Objects (typically used on[workload resources](/docs/reference/kubernetes-api/workload-resources/)). The controller/user who created this resource. @@ -39,19 +43,26 @@ Starting from v1.9, this label is deprecated. ### app.kubernetes.io/instance +Type: Label + Example: `app.kubernetes.io/instance: "mysql-abcxzy"` -Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). +Used on: All Objects (typically used on +[workload resources](/docs/reference/kubernetes-api/workload-resources/)). -A unique name identifying the instance of an application. To assign a non-unique name, use [app.kubernetes.io/name](#app-kubernetes-io-name). +A unique name identifying the instance of an application. +To assign a non-unique name, use [app.kubernetes.io/name](#app-kubernetes-io-name). One of the [recommended labels](/docs/concepts/overview/working-with-objects/common-labels/#labels). ### app.kubernetes.io/managed-by +Type: Label + Example: `app.kubernetes.io/managed-by: "helm"` -Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). +Used on: All Objects (typically used on +[workload resources](/docs/reference/kubernetes-api/workload-resources/)). The tool being used to manage the operation of an application. @@ -59,9 +70,12 @@ One of the [recommended labels](/docs/concepts/overview/working-with-objects/com ### app.kubernetes.io/name +Type: Label + Example: `app.kubernetes.io/name: "mysql"` -Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). +Used on: All Objects (typically used on +[workload resources](/docs/reference/kubernetes-api/workload-resources/)). The name of the application. @@ -69,94 +83,153 @@ One of the [recommended labels](/docs/concepts/overview/working-with-objects/com ### app.kubernetes.io/part-of +Type: Label + Example: `app.kubernetes.io/part-of: "wordpress"` -Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). +Used on: All Objects (typically used on +[workload resources](/docs/reference/kubernetes-api/workload-resources/)). -The name of a higher-level application this one is part of. +The name of a higher-level application this object is part of. One of the [recommended labels](/docs/concepts/overview/working-with-objects/common-labels/#labels). ### app.kubernetes.io/version +Type: Label + Example: `app.kubernetes.io/version: "5.7.21"` -Used on: All Objects (typically used on [workload resources](/docs/reference/kubernetes-api/workload-resources/)). +Used on: All Objects (typically used on +[workload resources](/docs/reference/kubernetes-api/workload-resources/)). The current version of the application. Common forms of values include: - [semantic version](https://semver.org/spec/v1.0.0.html) -- the Git [revision hash](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_single_revisions) for the source code. +- the Git [revision hash](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_single_revisions) + for the source code. One of the [recommended labels](/docs/concepts/overview/working-with-objects/common-labels/#labels). ### applyset.kubernetes.io/additional-namespaces (alpha) {#applyset-kubernetes-io-additional-namespaces} +Type: Annotation + Example: `applyset.kubernetes.io/additional-namespaces: "namespace1,namespace2"` Used on: Objects being used as ApplySet parents. -Use of this annotation is alpha. -For Kubernetes version {{< skew currentVersion >}}, you can use this annotation on Secrets, ConfigMaps, or custom resources if the {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} defining them has the `applyset.kubernetes.io/is-parent-type` label. +Use of this annotation is Alpha. +For Kubernetes version {{< skew currentVersion >}}, you can use this annotation on Secrets, +ConfigMaps, or custom resources if the +{{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} +defining them has the `applyset.kubernetes.io/is-parent-type` label. -Part of the specification used to implement [ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). This annotation is applied to the parent object used to track an ApplySet to extend the scope of the ApplySet beyond the parent object's own namespace (if any). The value is a comma-separated list of the names of namespaces other than the parent's namespace in which objects are found. +Part of the specification used to implement +[ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). +This annotation is applied to the parent object used to track an ApplySet to extend the scope of +the ApplySet beyond the parent object's own namespace (if any). +The value is a comma-separated list of the names of namespaces other than the parent's namespace +in which objects are found. ### applyset.kubernetes.io/contains-group-resources (alpha) {#applyset-kubernetes-io-contains-group-resources} +Type: Annotation + Example: `applyset.kubernetes.io/contains-group-resources: "certificates.cert-manager.io,configmaps,deployments.apps,secrets,services"` Used on: Objects being used as ApplySet parents. -Use of this annotation is alpha. -For Kubernetes version {{< skew currentVersion >}}, you can use this annotation on Secrets, ConfigMaps, or custom resources if the {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} defining them has the `applyset.kubernetes.io/is-parent-type` label. - -Part of the specification used to implement [ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). This annotation is applied to the parent object used to track an ApplySet to optimize listing of ApplySet member objects. It is optional in the ApplySet specification, as tools can perform discovery or use a different optimization. However, as of Kubernetes version {{< skew currentVersion >}}, it is required by kubectl. When present, the value of this annotation must be a comma separated list of the group-kinds, in the fully-qualified name format, i.e. `.`. +Use of this annotation is Alpha. +For Kubernetes version {{< skew currentVersion >}}, you can use this annotation on Secrets, ConfigMaps, +or custom resources if the CustomResourceDefinition +defining them has the `applyset.kubernetes.io/is-parent-type` label. +Part of the specification used to implement +[ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). +This annotation is applied to the parent object used to track an ApplySet to optimize listing of +ApplySet member objects. It is optional in the ApplySet specification, as tools can perform discovery +or use a different optimization. However, as of Kubernetes version {{< skew currentVersion >}}, +it is required by kubectl. When present, the value of this annotation must be a comma separated list +of the group-kinds, in the fully-qualified name format, i.e. `.`. ### applyset.kubernetes.io/id (alpha) {#applyset-kubernetes-io-id} +Type: Label + Example: `applyset.kubernetes.io/id: "applyset-0eFHV8ySqp7XoShsGvyWFQD3s96yqwHmzc4e0HR1dsY-v1"` Used on: Objects being used as ApplySet parents. -Use of this label is alpha. -For Kubernetes version {{< skew currentVersion >}}, you can use this label on Secrets, ConfigMaps, or custom resources if the {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} defining them has the `applyset.kubernetes.io/is-parent-type` label. +Use of this label is Alpha. +For Kubernetes version {{< skew currentVersion >}}, you can use this label on Secrets, ConfigMaps, +or custom resources if the CustomResourceDefinition +defining them has the `applyset.kubernetes.io/is-parent-type` label. -Part of the specification used to implement [ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). This label is what makes an object an ApplySet parent object. Its value is the unique ID of the ApplySet, which is derived from the identity of the parent object itself. This ID **must** be the base64 encoding (using the URL safe encoding of RFC4648) of the hash of the group-kind-name-namespace of the object it is on, in the form: `...))>`. There is no relation between the value of this label and object UIDs. +Part of the specification used to implement +[ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). +This label is what makes an object an ApplySet parent object. +Its value is the unique ID of the ApplySet, which is derived from the identity of the parent +object itself. This ID **must** be the base64 encoding (using the URL safe encoding of RFC4648) of +the hash of the group-kind-name-namespace of the object it is on, in the form: +`...))>`. +There is no relation between the value of this label and object UID. ### applyset.kubernetes.io/is-parent-type (alpha) {#applyset-kubernetes-io-is-parent-type} +Type: Label Example: `applyset.kubernetes.io/is-parent-type: "true"` Used on: Custom Resource Definition (CRD) -Use of this label is alpha. -Part of the specification used to implement [ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). You can set this label on a {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} (CRD) to identify the custom resource type it defines (not the CRD itself) as an allowed parent for an ApplySet. The only permitted value for this label is `"true"`; if you want to mark a CRD as not being a valid parent for ApplySets, omit this label. +Use of this label is Alpha. +Part of the specification used to implement +[ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). +You can set this label on a CustomResourceDefinition (CRD) to identify the custom resource type it +defines (not the CRD itself) as an allowed parent for an ApplySet. +The only permitted value for this label is `"true"`; if you want to mark a CRD as +not being a valid parent for ApplySets, omit this label. ### applyset.kubernetes.io/part-of (alpha) {#applyset-kubernetes-io-part-of} +Type: Label + Example: `applyset.kubernetes.io/part-of: "applyset-0eFHV8ySqp7XoShsGvyWFQD3s96yqwHmzc4e0HR1dsY-v1"` Used on: All objects. -Use of this label is alpha. -Part of the specification used to implement [ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). This label is what makes an object a member of an ApplySet. The value of the label **must** match the value of the `applyset.kubernetes.io/id` label on the parent object. +Use of this label is Alpha. +Part of the specification used to implement +[ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). +This label is what makes an object a member of an ApplySet. +The value of the label **must** match the value of the `applyset.kubernetes.io/id` +label on the parent object. ### applyset.kubernetes.io/tooling (alpha) {#applyset-kubernetes-io-tooling} +Type: Annotation + Example: `applyset.kubernetes.io/tooling: "kubectl/v{{< skew currentVersion >}}"` Used on: Objects being used as ApplySet parents. -Use of this annotation is alpha. -For Kubernetes version {{< skew currentVersion >}}, you can use this annotation on Secrets, ConfigMaps, or custom resources if the {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} defining them has the `applyset.kubernetes.io/is-parent-type` label. +Use of this annotation is Alpha. +For Kubernetes version {{< skew currentVersion >}}, you can use this annotation on Secrets, +ConfigMaps, or custom resources if the CustomResourceDefinitiondefining them has the +`applyset.kubernetes.io/is-parent-type` label. -Part of the specification used to implement [ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). This annotation is applied to the parent object used to track an ApplySet to indicate which tooling manages that ApplySet. Tooling should refuse to mutate ApplySets belonging to other tools. The value must be in the format `/`. +Part of the specification used to implement +[ApplySet-based pruning in kubectl](/docs/tasks/manage-kubernetes-objects/declarative-config/#alternative-kubectl-apply-f-directory-prune). +This annotation is applied to the parent object used to track an ApplySet to indicate which +tooling manages that ApplySet. Tooling should refuse to mutate ApplySets belonging to other tools. +The value must be in the format `/`. ### cluster-autoscaler.kubernetes.io/safe-to-evict +Type: Annotation + Example: `cluster-autoscaler.kubernetes.io/safe-to-evict: "true"` Used on: Pod @@ -169,61 +242,94 @@ If this annotation is not set then the cluster autoscaler follows its Pod-level ### config.kubernetes.io/local-config +Type: Annotation + Example: `config.kubernetes.io/local-config: "true"` Used on: All objects -This annotation is used in manifests to mark an object as local configuration that should not be submitted to the Kubernetes API. +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 object is only consumed by client-side tooling and should not be submitted 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 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. ### internal.config.kubernetes.io/* (reserved prefix) {#internal.config.kubernetes.io-reserved-wildcard} +Type: Annotation + 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. 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. +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 orchestrator tools 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 +Type: Annotation + Example: `internal.config.kubernetes.io/path: "relative/file/path.yaml"` Used on: All objects -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 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, which is used by Kustomize and similar third-party tools. +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 objects unless it is modifying the referenced files. A KRM Function **may** include this annotation on objects 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 +Type: Annotation + Example: `internal.config.kubernetes.io/index: "2"` Used on: All objects -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 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, which is used by Kustomize and similar third-party tools. +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 objects unless it is modifying the referenced files. A KRM Function **may** include this annotation on objects 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 +Type: Label + Example: `kubernetes.io/arch: "amd64"` Used on: Node -The Kubelet populates this with `runtime.GOARCH` as defined by Go. This can be handy if you are mixing arm and x86 nodes. +The Kubelet populates this with `runtime.GOARCH` as defined by Go. +This can be handy if you are mixing ARM and x86 nodes. ### kubernetes.io/os +Type: Label + Example: `kubernetes.io/os: "linux"` Used on: Node, Pod @@ -243,6 +349,8 @@ look for [Pods OS](/docs/concepts/workloads/pods/#pod-os) for more details. ### kubernetes.io/metadata.name +Type: Label + Example: `kubernetes.io/metadata.name: "mynamespace"` Used on: Namespaces @@ -256,20 +364,25 @@ This is useful if you want to target a specific namespace with a label ### kubernetes.io/limit-ranger +Type: Annotation + Example: `kubernetes.io/limit-ranger: "LimitRanger plugin set: cpu, memory request for container nginx; cpu, memory limit for container nginx"` Used on: Pod -Kubernetes by default doesn't provide any resource limit, that means unless you explicitly define limits, -your container can consume unlimited CPU and memory. -You can define a default request or default limit for pods. You do this by creating a LimitRange in the relevant namespace. -Pods deployed after you define a LimitRange will have these limits applied to them. +Kubernetes by default doesn't provide any resource limit, that means unless you explicitly define +limits, your container can consume unlimited CPU and memory. +You can define a default request or default limit for pods. You do this by creating a LimitRange +in the relevant namespace. Pods deployed after you define a LimitRange will have these limits +applied to them. The annotation `kubernetes.io/limit-ranger` records that resource defaults were specified for the Pod, and they were applied successfully. For more details, read about [LimitRanges](/docs/concepts/policy/limit-range). ### addonmanager.kubernetes.io/mode +Type: Label + Example: `addonmanager.kubernetes.io/mode: "Reconcile"` Used on: All objects @@ -277,33 +390,44 @@ Used on: All objects To specify how an add-on should be managed, you can use the `addonmanager.kubernetes.io/mode` label. This label can have one of three values: `Reconcile`, `EnsureExists`, or `Ignore`. -- `Reconcile`: Addon resources will be periodically reconciled with the expected state. If there are any differences, -the add-on manager will recreate, reconfigure or delete the resources as needed. This is the default mode if no label is specified. -- `EnsureExists`: Addon resources will be checked for existence only but will not be modified after creation. -The add-on manager will create or re-create the resources when there is no instance of the resource with that name. -- `Ignore`: Addon resources will be ignored. This mode is useful for add-ons that are not compatible with -the add-on manager or that are managed by another controller. +- `Reconcile`: Addon resources will be periodically reconciled with the expected state. + If there are any differences, the add-on manager will recreate, reconfigure or delete + the resources as needed. This is the default mode if no label is specified. +- `EnsureExists`: Addon resources will be checked for existence only but will not be modified + after creation. The add-on manager will create or re-create the resources when there is + no instance of the resource with that name. +- `Ignore`: Addon resources will be ignored. This mode is useful for add-ons that are not + compatible with the add-on manager or that are managed by another controller. For more details, see [Addon-manager](https://github.com/kubernetes/kubernetes/blob/master/cluster/addons/addon-manager/README.md) ### beta.kubernetes.io/arch (deprecated) +Type: Label + This label has been deprecated. Please use `kubernetes.io/arch` instead. ### beta.kubernetes.io/os (deprecated) +Type: Label + This label has been deprecated. Please use `kubernetes.io/os` instead. ### kube-aggregator.kubernetes.io/automanaged {#kube-aggregator-kubernetesio-automanaged} +Type: Label + Example: `kube-aggregator.kubernetes.io/automanaged: "onstart"` Used on: APIService -The `kube-apiserver` sets this label on any APIService object that the API server has created automatically. The label marks how the control plane should manage that APIService. You should not add, modify, or remove this label by yourself. +The `kube-apiserver` sets this label on any APIService object that the API server +has created automatically. The label marks how the control plane should manage that +APIService. You should not add, modify, or remove this label by yourself. {{< note >}} -Automanaged APIService objects are deleted by kube-apiserver when it has no built-in or custom resource API corresponding to the API group/version of the APIService. +Automanaged APIService objects are deleted by kube-apiserver when it has no built-in +or custom resource API corresponding to the API group/version of the APIService. {{< /note >}} There are two possible values: @@ -313,26 +437,35 @@ There are two possible values: ### service.alpha.kubernetes.io/tolerate-unready-endpoints (deprecated) +Type: Annotation + Used on: StatefulSet -This annotation on a Service denotes if the Endpoints controller should go ahead and create Endpoints for unready Pods. -Endpoints of these Services retain their DNS records and continue receiving -traffic for the Service from the moment the kubelet starts all containers in the pod +This annotation on a Service denotes if the Endpoints controller should go ahead and create +Endpoints for unready Pods. Endpoints of these Services retain their DNS records and continue +receiving traffic for the Service from the moment the kubelet starts all containers in the pod and marks it _Running_, til the kubelet stops all containers and deletes the pod from the API server. ### kubernetes.io/hostname {#kubernetesiohostname} +Type: Label + Example: `kubernetes.io/hostname: "ip-172-20-114-199.ec2.internal"` Used on: Node -The Kubelet populates this label with the hostname. Note that the hostname can be changed from the "actual" hostname by passing the `--hostname-override` flag to the `kubelet`. +The Kubelet populates this label with the hostname of the node. Note that the hostname +can be changed from the "actual" hostname by passing the `--hostname-override` flag to +the `kubelet`. -This label is also used as part of the topology hierarchy. See [topology.kubernetes.io/zone](#topologykubernetesiozone) for more information. +This label is also used as part of the topology hierarchy. +See [topology.kubernetes.io/zone](#topologykubernetesiozone) for more information. ### kubernetes.io/change-cause {#change-cause} +Type: Annotation + Example: `kubernetes.io/change-cause: "kubectl edit --record deployment foo"` Used on: All Objects @@ -343,6 +476,8 @@ It is populated when adding `--record` to a `kubectl` command that may change an ### kubernetes.io/description {#description} +Type: Annotation + Example: `kubernetes.io/description: "Description of K8s object."` Used on: All Objects @@ -351,116 +486,158 @@ This annotation is used for describing specific behaviour of given object. ### kubernetes.io/enforce-mountable-secrets {#enforce-mountable-secrets} +Type: Annotation + Example: `kubernetes.io/enforce-mountable-secrets: "true"` Used on: ServiceAccount -The value for this annotation must be **true** to take effect. This annotation indicates that pods running as this service account may only reference Secret API objects specified in the service account's `secrets` field. +The value for this annotation must be **true** to take effect. +This annotation indicates that Pods running as this ServiceAccount may only reference +Secret API objects specified in the ServiceAccount's `secrets` field. ### node.kubernetes.io/exclude-from-external-load-balancers +Type: Label + Example: `node.kubernetes.io/exclude-from-external-load-balancers` Used on: Node -Kubernetes automatically enables the `ServiceNodeExclusion` feature gate on the clusters it creates. With this feature gate enabled on a cluster, +Kubernetes automatically enables the `ServiceNodeExclusion` feature gate on +the clusters it creates. With this feature gate enabled on a cluster, you can add labels to particular worker nodes to exclude them from the list of backend servers. -The following command can be used to exclude a worker node from the list of backend servers in a backend set- -`kubectl label nodes node.kubernetes.io/exclude-from-external-load-balancers=true` +The following command can be used to exclude a worker node from the list of backend servers in a +backend set: + +```shell +kubectl label nodes node.kubernetes.io/exclude-from-external-load-balancers=true +``` ### controller.kubernetes.io/pod-deletion-cost {#pod-deletion-cost} +Type: Annotation + Example: `controller.kubernetes.io/pod-deletion-cost: "10"` Used on: Pod This annotation is used to set [Pod Deletion Cost](/docs/concepts/workloads/controllers/replicaset/#pod-deletion-cost) -which allows users to influence ReplicaSet downscaling order. The annotation parses into an `int32` type. +which allows users to influence ReplicaSet downscaling order. +The annotation value parses into an `int32` type. ### cluster-autoscaler.kubernetes.io/enable-ds-eviction +Type: Annotation + Example: `cluster-autoscaler.kubernetes.io/enable-ds-eviction: "true"` Used on: Pod This annotation controls whether a DaemonSet pod should be evicted by a ClusterAutoscaler. This annotation needs to be specified on DaemonSet pods in a DaemonSet manifest. -When this annotation is set to `"true"`, the ClusterAutoscaler is allowed to evict a DaemonSet Pod, -even if other rules would normally prevent that. To disallow the ClusterAutoscaler from evicting DaemonSet pods, +When this annotation is set to `"true"`, the ClusterAutoscaler is allowed to evict +a DaemonSet Pod, even if other rules would normally prevent that. +To disallow the ClusterAutoscaler from evicting DaemonSet pods, you can set this annotation to `"false"` for important DaemonSet pods. -If this annotation is not set, then the Cluster Autoscaler follows its overall behaviour (i.e evict the DaemonSets based on its configuration). +If this annotation is not set, then the ClusterAutoscaler follows its overall behavior +(i.e evict the DaemonSets based on its configuration). {{< note >}} -This annotation only impacts DaemonSet pods. +This annotation only impacts DaemonSet Pods. {{< /note >}} ### kubernetes.io/ingress-bandwidth -{{< note >}} -Ingress traffic shaping annotation is an experimental feature. -If you want to enable traffic shaping support, you must add the `bandwidth` plugin to your CNI configuration file (default `/etc/cni/net.d`) and -ensure that the binary is included in your CNI bin dir (default `/opt/cni/bin`). -{{< /note >}} +Type: Annotation Example: `kubernetes.io/ingress-bandwidth: 10M` Used on: Pod -You can apply quality-of-service traffic shaping to a pod and effectively limit its available bandwidth. -Ingress traffic (to the pod) is handled by shaping queued packets to effectively handle data. -To limit the bandwidth on a pod, write an object definition JSON file and specify the data traffic -speed using `kubernetes.io/ingress-bandwidth` annotation. The unit used for specifying ingress -rate is bits per second, as a [Quantity](/docs/reference/kubernetes-api/common-definitions/quantity/). +You can apply quality-of-service traffic shaping to a pod and effectively limit its available +bandwidth. Ingress traffic to a Pod is handled by shaping queued packets to effectively +handle data. To limit the bandwidth on a Pod, write an object definition JSON file and specify +the data traffic speed using `kubernetes.io/ingress-bandwidth` annotation. The unit used for +specifying ingress rate is bits per second, as a +[Quantity](/docs/reference/kubernetes-api/common-definitions/quantity/). For example, `10M` means 10 megabits per second. +{{< note >}} +Ingress traffic shaping annotation is an experimental feature. +If you want to enable traffic shaping support, you must add the `bandwidth` plugin to your CNI +configuration file (default `/etc/cni/net.d`) and ensure that the binary is included in your CNI +bin dir (default `/opt/cni/bin`). +{{< /note >}} + ### kubernetes.io/egress-bandwidth -{{< note >}} -Egress traffic shaping annotation is an experimental feature. -If you want to enable traffic shaping support, you must add the `bandwidth` plugin to your CNI configuration file (default `/etc/cni/net.d`) and -ensure that the binary is included in your CNI bin dir (default `/opt/cni/bin`). -{{< /note >}} +Type: Annotation Example: `kubernetes.io/egress-bandwidth: 10M` Used on: Pod -Egress traffic (from the pod) is handled by policing, which simply drops packets in excess of the configured rate. -The limits you place on a pod do not affect the bandwidth of other pods. -To limit the bandwidth on a pod, write an object definition JSON file and specify the data traffic -speed using `kubernetes.io/egress-bandwidth` annotation. The unit used for specifying egress -rate is bits per second, as a [Quantity](/docs/reference/kubernetes-api/common-definitions/quantity/). +Egress traffic from a Pod is handled by policing, which simply drops packets in excess of the +configured rate. The limits you place on a Pod do not affect the bandwidth of other Pods. +To limit the bandwidth on a Pod, write an object definition JSON file and specify the data traffic +speed using `kubernetes.io/egress-bandwidth` annotation. The unit used for specifying egress rate +is bits per second, as a [Quantity](/docs/reference/kubernetes-api/common-definitions/quantity/). For example, `10M` means 10 megabits per second. +{{< note >}} +Egress traffic shaping annotation is an experimental feature. +If you want to enable traffic shaping support, you must add the `bandwidth` plugin to your CNI +configuration file (default `/etc/cni/net.d`) and ensure that the binary is included in your CNI +bin dir (default `/opt/cni/bin`). +{{< /note >}} + ### beta.kubernetes.io/instance-type (deprecated) -{{< note >}} Starting in v1.17, this label is deprecated in favor of [node.kubernetes.io/instance-type](#nodekubernetesioinstance-type). {{< /note >}} +Type: Label + +{{< note >}} +Starting in v1.17, this label is deprecated in favor of +[node.kubernetes.io/instance-type](#nodekubernetesioinstance-type). +{{< /note >}} ### node.kubernetes.io/instance-type {#nodekubernetesioinstance-type} +Type: Label + Example: `node.kubernetes.io/instance-type: "m3.medium"` Used on: Node -The Kubelet populates this with the instance type as defined by the `cloudprovider`. -This will be set only if you are using a `cloudprovider`. This setting is handy +The Kubelet populates this with the instance type as defined by the cloud provider. +This will be set only if you are using a cloud provider. This setting is handy if you want to target certain workloads to certain instance types, but typically you want -to rely on the Kubernetes scheduler to perform resource-based scheduling. You should aim to schedule based on properties rather than on instance types (for example: require a GPU, instead of requiring a `g2.2xlarge`). +to rely on the Kubernetes scheduler to perform resource-based scheduling. +You should aim to schedule based on properties rather than on instance types +(for example: require a GPU, instead of requiring a `g2.2xlarge`). ### failure-domain.beta.kubernetes.io/region (deprecated) {#failure-domainbetakubernetesioregion} -See [topology.kubernetes.io/region](#topologykubernetesioregion). +Type: Label -{{< note >}} Starting in v1.17, this label is deprecated in favor of [topology.kubernetes.io/region](#topologykubernetesioregion). {{< /note >}} +{{< note >}} +Starting in v1.17, this label is deprecated in favor of +[topology.kubernetes.io/region](#topologykubernetesioregion). +{{< /note >}} ### failure-domain.beta.kubernetes.io/zone (deprecated) {#failure-domainbetakubernetesiozone} -See [topology.kubernetes.io/zone](#topologykubernetesiozone). +Type: Label -{{< note >}} Starting in v1.17, this label is deprecated in favor of [topology.kubernetes.io/zone](#topologykubernetesiozone). {{< /note >}} +{{< note >}} +Starting in v1.17, this label is deprecated in favor of +[topology.kubernetes.io/zone](#topologykubernetesiozone). +{{< /note >}} ### pv.kubernetes.io/bind-completed {#pv-kubernetesiobind-completed} +Type: Annotation + Example: `pv.kubernetes.io/bind-completed: "yes"` Used on: PersistentVolumeClaim @@ -472,163 +649,233 @@ The value of this annotation does not matter to Kubernetes. ### pv.kubernetes.io/bound-by-controller {#pv-kubernetesioboundby-controller} +Type: Annotation + Example: `pv.kubernetes.io/bound-by-controller: "yes"` Used on: PersistentVolume, PersistentVolumeClaim -If this annotation is set on a PersistentVolume or PersistentVolumeClaim, it indicates that a storage binding -(PersistentVolume → PersistentVolumeClaim, or PersistentVolumeClaim → PersistentVolume) was installed -by the {{< glossary_tooltip text="controller" term_id="controller" >}}. -If the annotation isn't set, and there is a storage binding in place, the absence of that annotation means that -the binding was done manually. The value of this annotation does not matter. +If this annotation is set on a PersistentVolume or PersistentVolumeClaim, it indicates that a +storage binding (PersistentVolume → PersistentVolumeClaim, or PersistentVolumeClaim → PersistentVolume) +was installed by the {{< glossary_tooltip text="controller" term_id="controller" >}}. +If the annotation isn't set, and there is a storage binding in place, the absence of that +annotation means that the binding was done manually. +The value of this annotation does not matter. ### pv.kubernetes.io/provisioned-by {#pv-kubernetesiodynamically-provisioned} +Type: Annotation + Example: `pv.kubernetes.io/provisioned-by: "kubernetes.io/rbd"` Used on: PersistentVolume This annotation is added to a PersistentVolume(PV) that has been dynamically provisioned by Kubernetes. -Its value is the name of volume plugin that created the volume. It serves both user (to show where a PV +Its value is the name of volume plugin that created the volume. It serves both users (to show where a PV comes from) and Kubernetes (to recognize dynamically provisioned PVs in its decisions). ### pv.kubernetes.io/migrated-to {#pv-kubernetesio-migratedto} +Type: Annotation + Example: `pv.kubernetes.io/migrated-to: pd.csi.storage.gke.io` Used on: PersistentVolume, PersistentVolumeClaim It is added to a PersistentVolume(PV) and PersistentVolumeClaim(PVC) that is supposed to be dynamically provisioned/deleted by its corresponding CSI driver through the `CSIMigration` feature gate. -When this annotation is set, the Kubernetes components will "stand-down" and the `external-provisioner` -will act on the objects. +When this annotation is set, the Kubernetes components will "stand-down" and the +`external-provisioner` will act on the objects. ### statefulset.kubernetes.io/pod-name {#statefulsetkubernetesiopod-name} -Example: +Type: Annotation -`statefulset.kubernetes.io/pod-name: "mystatefulset-7"` +Example: `statefulset.kubernetes.io/pod-name: "mystatefulset-7"` + +Used on: Pod When a StatefulSet controller creates a Pod for the StatefulSet, the control plane sets this label on that Pod. The value of the label is the name of the Pod being created. -See [Pod Name Label](/docs/concepts/workloads/controllers/statefulset/#pod-name-label) in the -StatefulSet topic for more details. +See [Pod Name Label](/docs/concepts/workloads/controllers/statefulset/#pod-name-label) +in the StatefulSet topic for more details. ### scheduler.alpha.kubernetes.io/node-selector {#schedulerkubernetesnode-selector} +Type: Annotation + Example: `scheduler.alpha.kubernetes.io/node-selector: "name-of-node-selector"` Used on: Namespace -The [PodNodeSelector](/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) uses this annotation key to assign node selectors to pods in namespaces. +The [PodNodeSelector](/docs/reference/access-authn-authz/admission-controllers/#podnodeselector) +uses this annotation key to assign node selectors to pods in namespaces. ### topology.kubernetes.io/region {#topologykubernetesioregion} -Example: +Type: Label -`topology.kubernetes.io/region: "us-east-1"` +Example: `topology.kubernetes.io/region: "us-east-1"` + +Used on: Node, PersistentVolume See [topology.kubernetes.io/zone](#topologykubernetesiozone). ### topology.kubernetes.io/zone {#topologykubernetesiozone} -Example: +Type: Label -`topology.kubernetes.io/zone: "us-east-1c"` +Example: `topology.kubernetes.io/zone: "us-east-1c"` Used on: Node, PersistentVolume -On Node: The `kubelet` or the external `cloud-controller-manager` populates this with the information as provided by the `cloudprovider`. This will be set only if you are using a `cloudprovider`. However, you should consider setting this on nodes if it makes sense in your topology. +**On Node**: The `kubelet` or the external `cloud-controller-manager` populates this +with the information from the cloud provider. This will be set only if you are using +a cloud provider. However, you can consider setting this on nodes if it makes sense +in your topology. -On PersistentVolume: topology-aware volume provisioners will automatically set node affinity constraints on `PersistentVolumes`. +**On PersistentVolume**: topology-aware volume provisioners will automatically set +node affinity constraints on a `PersistentVolume`. -A zone represents a logical failure domain. It is common for Kubernetes clusters to span multiple zones for increased availability. While the exact definition of a zone is left to infrastructure implementations, common properties of a zone include very low network latency within a zone, no-cost network traffic within a zone, and failure independence from other zones. For example, nodes within a zone might share a network switch, but nodes in different zones should not. +A zone represents a logical failure domain. It is common for Kubernetes clusters to +span multiple zones for increased availability. While the exact definition of a zone +is left to infrastructure implementations, common properties of a zone include +very low network latency within a zone, no-cost network traffic within a zone, and +failure independence from other zones. +For example, nodes within a zone might share a network switch, but nodes in different +zones should not. -A region represents a larger domain, made up of one or more zones. It is uncommon for Kubernetes clusters to span multiple regions, While the exact definition of a zone or region is left to infrastructure implementations, common properties of a region include higher network latency between them than within them, non-zero cost for network traffic between them, and failure independence from other zones or regions. For example, nodes within a region might share power infrastructure (e.g. a UPS or generator), but nodes in different regions typically would not. +A region represents a larger domain, made up of one or more zones. +It is uncommon for Kubernetes clusters to span multiple regions, +While the exact definition of a zone or region is left to infrastructure implementations, +common properties of a region include higher network latency between them than within them, +non-zero cost for network traffic between them, and failure independence from other zones or regions. +For example, nodes within a region might share power infrastructure (e.g. a UPS or generator), +but nodes in different regions typically would not. Kubernetes makes a few assumptions about the structure of zones and regions: -1) regions and zones are hierarchical: zones are strict subsets of regions and no zone can be in 2 regions -2) zone names are unique across regions; for example region "africa-east-1" might be comprised of zones "africa-east-1a" and "africa-east-1b" +1. regions and zones are hierarchical: zones are strict subsets of regions and + no zone can be in 2 regions +2) zone names are unique across regions; for example region "africa-east-1" might be comprised + of zones "africa-east-1a" and "africa-east-1b" -It should be safe to assume that topology labels do not change. Even though labels are strictly mutable, consumers of them can assume that a given node is not going to be moved between zones without being destroyed and recreated. +It should be safe to assume that topology labels do not change. +Even though labels are strictly mutable, consumers of them can assume that a given node +is not going to be moved between zones without being destroyed and recreated. -Kubernetes can use this information in various ways. For example, the scheduler automatically tries to spread the Pods in a ReplicaSet across nodes in a single-zone cluster (to reduce the impact of node failures, see [kubernetes.io/hostname](#kubernetesiohostname)). With multiple-zone clusters, this spreading behavior also applies to zones (to reduce the impact of zone failures). This is achieved via _SelectorSpreadPriority_. +Kubernetes can use this information in various ways. +For example, the scheduler automatically tries to spread the Pods in a ReplicaSet across nodes +in a single-zone cluster (to reduce the impact of node failures, see +[kubernetes.io/hostname](#kubernetesiohostname)). +With multiple-zone clusters, this spreading behavior also applies to zones (to reduce the impact of zone failures). +This is achieved via _SelectorSpreadPriority_. -_SelectorSpreadPriority_ is a best effort placement. If the zones in your cluster are heterogeneous (for example: different numbers of nodes, different types of nodes, or different pod resource requirements), this placement might prevent equal spreading of your Pods across zones. If desired, you can use homogenous zones (same number and types of nodes) to reduce the probability of unequal spreading. +_SelectorSpreadPriority_ is a best effort placement. If the zones in your cluster are +heterogeneous (for example: different numbers of nodes, different types of nodes, or different pod +resource requirements), this placement might prevent equal spreading of your Pods across zones. +If desired, you can use homogenous zones (same number and types of nodes) to reduce the probability +of unequal spreading. -The scheduler (through the _VolumeZonePredicate_ predicate) also will ensure that Pods, that claim a given volume, are only placed into the same zone as that volume. Volumes cannot be attached across zones. +The scheduler (through the _VolumeZonePredicate_ predicate) also will ensure that Pods, +that claim a given volume, are only placed into the same zone as that volume. +Volumes cannot be attached across zones. -If `PersistentVolumeLabel` does not support automatic labeling of your PersistentVolumes, you should consider -adding the labels manually (or adding support for `PersistentVolumeLabel`). With `PersistentVolumeLabel`, the scheduler prevents Pods from mounting volumes in a different zone. If your infrastructure doesn't have this constraint, you don't need to add the zone labels to the volumes at all. +If `PersistentVolumeLabel` does not support automatic labeling of your PersistentVolumes, +you should consider adding the labels manually (or adding support for `PersistentVolumeLabel`). +With `PersistentVolumeLabel`, the scheduler prevents Pods from mounting volumes in a different zone. +If your infrastructure doesn't have this constraint, you don't need to add the zone labels to the volumes at all. ### volume.beta.kubernetes.io/storage-provisioner (deprecated) +Type: Annotation + Example: `volume.beta.kubernetes.io/storage-provisioner: "k8s.io/minikube-hostpath"` Used on: PersistentVolumeClaim -This annotation has been deprecated. +This annotation has been deprecated since v1.23. +See [volume.kubernetes.io/storage-provisioner](#volume-kubernetes-io-storage-provisioner) ### volume.beta.kubernetes.io/storage-class (deprecated) +Type: Annotation + Example: `volume.beta.kubernetes.io/storage-class: "example-class"` Used on: PersistentVolume, PersistentVolumeClaim -This annotation can be used for PersistentVolume(PV) or PersistentVolumeClaim(PVC) to specify the name of [StorageClass](/docs/concepts/storage/storage-classes/). When both `storageClassName` attribute and `volume.beta.kubernetes.io/storage-class` annotation are specified, the annotation `volume.beta.kubernetes.io/storage-class` takes precedence over the `storageClassName` attribute. +This annotation can be used for PersistentVolume(PV) or PersistentVolumeClaim(PVC) +to specify the name of [StorageClass](/docs/concepts/storage/storage-classes/). +When both the `storageClassName` attribute and the `volume.beta.kubernetes.io/storage-class` +annotation are specified, the annotation `volume.beta.kubernetes.io/storage-class` +takes precedence over the `storageClassName` attribute. -This annotation has been deprecated. Instead, set the [`storageClassName` field](/docs/concepts/storage/persistent-volumes/#class) +This annotation has been deprecated. Instead, set the +[`storageClassName` field](/docs/concepts/storage/persistent-volumes/#class) for the PersistentVolumeClaim or PersistentVolume. ### volume.beta.kubernetes.io/mount-options (deprecated) {#mount-options} +Type: Annotation + Example : `volume.beta.kubernetes.io/mount-options: "ro,soft"` Used on: PersistentVolume -A Kubernetes administrator can specify additional [mount options](/docs/concepts/storage/persistent-volumes/#mount-options) for when a PersistentVolume is mounted on a node. +A Kubernetes administrator can specify additional +[mount options](/docs/concepts/storage/persistent-volumes/#mount-options) +for when a PersistentVolume is mounted on a node. -This annotation has been deprecated. +### volume.kubernetes.io/storage-provisioner {#volume-kubernetes-io-storage-provisioner} -### volume.kubernetes.io/storage-provisioner +Type: Annotation Used on: PersistentVolumeClaim -This annotation will be added to dynamic provisioning required PVC. +This annotation is added to a PVC that is supposed to be dynamically provisioned. +Its value is the name of a volume plugin that is supposed to provision a volume +for this PVC. ### volume.kubernetes.io/selected-node +Type: Annotation + Used on: PersistentVolumeClaim -This annotation is added to a PVC that is triggered by a scheduler to be dynamically provisioned. Its value is the name of the selected node. +This annotation is added to a PVC that is triggered by a scheduler to be +dynamically provisioned. Its value is the name of the selected node. ### volumes.kubernetes.io/controller-managed-attach-detach +Type: Annotation + Used on: Node -If a node has set the annotation `volumes.kubernetes.io/controller-managed-attach-detach` -on itself, then its storage attach and detach operations are being managed -by the _volume attach/detach_ -{{< glossary_tooltip text="controller" term_id="controller" >}} running within the -{{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}}. +If a node has the annotation `volumes.kubernetes.io/controller-managed-attach-detach`, +its storage attach and detach operations are being managed by the _volume attach/detach_ +{{< glossary_tooltip text="controller" term_id="controller" >}}. -The value of the annotation isn't important; if this annotation exists on a node, -then storage attaches and detaches are controller managed. +The value of the annotation isn't important. ### node.kubernetes.io/windows-build {#nodekubernetesiowindows-build} +Type: Label + Example: `node.kubernetes.io/windows-build: "10.0.17763"` Used on: Node -When the kubelet is running on Microsoft Windows, it automatically labels its node to record the version of Windows Server in use. +When the kubelet is running on Microsoft Windows, it automatically labels its Node +to record the version of Windows Server in use. The label's value is in the format "MajorVersion.MinorVersion.BuildNumber". ### service.kubernetes.io/headless {#servicekubernetesioheadless} +Type: Label + Example: `service.kubernetes.io/headless: ""` Used on: Service @@ -637,6 +884,8 @@ The control plane adds this label to an Endpoints object when the owning Service ### kubernetes.io/service-name {#kubernetesioservice-name} +Type: Label + Example: `kubernetes.io/service-name: "my-website"` Used on: EndpointSlice @@ -650,53 +899,71 @@ the name of their associated Service. ### kubernetes.io/service-account.name +Type: Annotation + Example: `kubernetes.io/service-account.name: "sa-name"` Used on: Secret This annotation records the {{< glossary_tooltip term_id="name" text="name">}} of the -ServiceAccount that the token (stored in the Secret of type `kubernetes.io/service-account-token`) represents. +ServiceAccount that the token (stored in the Secret of type `kubernetes.io/service-account-token`) +represents. ### kubernetes.io/service-account.uid +Type: Annotation + Example: `kubernetes.io/service-account.uid: da68f9c6-9d26-11e7-b84e-002dc52800da` Used on: Secret This annotation records the {{< glossary_tooltip term_id="uid" text="unique ID" >}} of the -ServiceAccount that the token (stored in the Secret of type `kubernetes.io/service-account-token`) represents. +ServiceAccount that the token (stored in the Secret of type `kubernetes.io/service-account-token`) +represents. ### kubernetes.io/legacy-token-last-used +Type: Label + Example: `kubernetes.io/legacy-token-last-used: 2022-10-24` Used on: Secret -The control plane only adds this label for Secrets that have the type `kubernetes.io/service-account-token`. -The value of this label records the date (ISO 8601 format, UTC time zone) when the control plane last saw -a request where the client authenticated using the service account token. +The control plane only adds this label to Secrets that have the type +`kubernetes.io/service-account-token`. +The value of this label records the date (ISO 8601 format, UTC time zone) when the control plane +last saw a request where the client authenticated using the service account token. -If a legacy token was last used before the cluster gained the feature (added in Kubernetes v1.26), then -the label isn't set. +If a legacy token was last used before the cluster gained the feature (added in Kubernetes v1.26), +then the label isn't set. ### endpointslice.kubernetes.io/managed-by {#endpointslicekubernetesiomanaged-by} +Type: Label + Example: `endpointslice.kubernetes.io/managed-by: "controller"` Used on: EndpointSlices -The label is used to indicate the controller or entity that manages an EndpointSlice. This label aims to enable different EndpointSlice objects to be managed by different controllers or entities within the same cluster. +The label is used to indicate the controller or entity that manages the EndpointSlice. This label +aims to enable different EndpointSlice objects to be managed by different controllers or entities +within the same cluster. ### endpointslice.kubernetes.io/skip-mirror {#endpointslicekubernetesioskip-mirror} +Type: Label + Example: `endpointslice.kubernetes.io/skip-mirror: "true"` Used on: Endpoints -The label can be set to `"true"` on an Endpoints resource to indicate that the EndpointSliceMirroring controller should not mirror this resource with EndpointSlices. +The label can be set to `"true"` on an Endpoints resource to indicate that the +EndpointSliceMirroring controller should not mirror this resource with EndpointSlices. ### service.kubernetes.io/service-proxy-name {#servicekubernetesioservice-proxy-name} +Type: Label + Example: `service.kubernetes.io/service-proxy-name: "foo-bar"` Used on: Service @@ -705,33 +972,43 @@ The kube-proxy has this label for custom proxy, which delegates service control ### experimental.windows.kubernetes.io/isolation-type (deprecated) {#experimental-windows-kubernetes-io-isolation-type} +Type: Annotation + Example: `experimental.windows.kubernetes.io/isolation-type: "hyperv"` Used on: Pod -The annotation is used to run Windows containers with Hyper-V isolation. To use Hyper-V isolation feature and create a Hyper-V isolated container, the kubelet should be started with feature gates HyperVContainer=true and the Pod should include the annotation `experimental.windows.kubernetes.io/isolation-type: hyperv`. +The annotation is used to run Windows containers with Hyper-V isolation. {{< note >}} -You can only set this annotation on Pods that have a single container. -Starting from v1.20, this annotation is deprecated. Experimental Hyper-V support was removed in 1.21. +Starting from v1.20, this annotation is deprecated. +Experimental Hyper-V support was removed in 1.21. {{< /note >}} ### ingressclass.kubernetes.io/is-default-class +Type: Annotation + Example: `ingressclass.kubernetes.io/is-default-class: "true"` Used on: IngressClass -When a single IngressClass resource has this annotation set to `"true"`, new Ingress resource without a class specified will be assigned this default class. +When a IngressClass resource has this annotation set to `"true"`, new Ingress resource +without a class specified will be assigned this default class. ### kubernetes.io/ingress.class (deprecated) +Type: Annotation + +Used on: Ingress + {{< note >}} Starting in v1.18, this annotation is deprecated in favor of `spec.ingressClassName`. {{< /note >}} ### storageclass.kubernetes.io/is-default-class +Type: Annotation Example: `storageclass.kubernetes.io/is-default-class: "true"` Used on: StorageClass @@ -741,16 +1018,23 @@ resource without a class specified will be assigned this default class. ### alpha.kubernetes.io/provided-node-ip +Type: Annotation + Example: `alpha.kubernetes.io/provided-node-ip: "10.0.0.1"` Used on: Node The kubelet can set this annotation on a Node to denote its configured IPv4 address. -When kubelet is started with the `--cloud-provider` flag set to any value (includes both external and legacy in-tree cloud providers), it sets this annotation on the Node to denote an IP address set from the command line flag (`--node-ip`). This IP is verified with the cloud provider as valid by the cloud-controller-manager. +When kubelet is started with the `--cloud-provider` flag set to any value (includes both external +and legacy in-tree cloud providers), it sets this annotation on the Node to denote an IP address +set from the command line flag (`--node-ip`). This IP is verified with the cloud provider as valid +by the cloud-controller-manager. ### batch.kubernetes.io/job-completion-index +Type: Annotation + Example: `batch.kubernetes.io/job-completion-index: "3"` Used on: Pod @@ -760,33 +1044,51 @@ created with Indexed [completion mode](/docs/concepts/workloads/controllers/job/ ### kubectl.kubernetes.io/default-container +Type: Annotation + Example: `kubectl.kubernetes.io/default-container: "front-end-app"` -The value of the annotation is the container name that is default for this Pod. For example, `kubectl logs` or `kubectl exec` without `-c` or `--container` flag will use this default container. +The value of the annotation is the container name that is default for this Pod. +For example, `kubectl logs` or `kubectl exec` without `-c` or `--container` flag +will use this default container. ### kubectl.kubernetes.io/default-logs-container (deprecated) +Type: Annotation + Example: `kubectl.kubernetes.io/default-logs-container: "front-end-app"` -The value of the annotation is the container name that is the default logging container for this Pod. For example, `kubectl logs` without `-c` or `--container` flag will use this default container. +The value of the annotation is the container name that is the default logging container for this +Pod. For example, `kubectl logs` without `-c` or `--container` flag will use this default +container. {{< note >}} -This annotation is deprecated. You should use the [`kubectl.kubernetes.io/default-container`](#kubectl-kubernetes-io-default-container) annotation instead. +This annotation is deprecated. You should use the +[`kubectl.kubernetes.io/default-container`](#kubectl-kubernetes-io-default-container) +annotation instead. Kubernetes versions 1.25 and newer ignore this annotation. {{< /note >}} ### endpoints.kubernetes.io/over-capacity +Type: Annotation + Example: `endpoints.kubernetes.io/over-capacity:truncated` Used on: Endpoints -The {{< glossary_tooltip text="control plane" term_id="control-plane" >}} adds this annotation to an [Endpoints](/docs/concepts/services-networking/service/#endpoints) object if the associated {{< glossary_tooltip term_id="service" >}} has more than 1000 backing endpoints. The annotation indicates that the Endpoints object is over capacity and the number of endpoints has been truncated to 1000. +The {{< glossary_tooltip text="control plane" term_id="control-plane" >}} adds this annotation to +an [Endpoints](/docs/concepts/services-networking/service/#endpoints) object if the associated +{{< glossary_tooltip term_id="service" >}} has more than 1000 backing endpoints. +The annotation indicates that the Endpoints object is over capacity and the number of endpoints +has been truncated to 1000. If the number of backend endpoints falls below 1000, the control plane removes this annotation. ### batch.kubernetes.io/job-tracking (deprecated) {#batch-kubernetes-io-job-tracking} +Type: Annotation + Example: `batch.kubernetes.io/job-tracking: ""` Used on: Jobs @@ -805,6 +1107,8 @@ using finalizers. ### job-name (deprecated) {#job-name} +Type: Label + Example: `job-name: "pi"` Used on: Jobs and Pods controlled by Jobs @@ -816,6 +1120,8 @@ Kubernetes 1.27 and newer ignore this label and use the prefixed `job-name` labe ### controller-uid (deprecated) {#controller-uid} +Type: Label + Example: `controller-uid: "$UID"` Used on: Jobs and Pods controlled by Jobs @@ -827,136 +1133,212 @@ Kubernetes 1.27 and newer ignore this label and use the prefixed `controller-uid ### batch.kubernetes.io/job-name {#batchkubernetesio-job-name} +Type: Label + Example: `batch.kubernetes.io/job-name: "pi"` Used on: Jobs and Pods controlled by Jobs This label is used as a user-friendly way to get Pods corresponding to a Job. -The `job-name` comes from the `name` of the Job and allows for an easy way to get Pods corresponding to the Job. +The `job-name` comes from the `name` of the Job and allows for an easy way to +get Pods corresponding to the Job. ### batch.kubernetes.io/controller-uid {#batchkubernetesio-controller-uid} +Type: Label + Example: `batch.kubernetes.io/controller-uid: "$UID"` Used on: Jobs and Pods controlled by Jobs This label is used as a programmatic way to get all Pods corresponding to a Job. -The `controller-uid` is a unique identifer that gets set in the `selector` field so the Job controller -can get all the corresponding Pods. +The `controller-uid` is a unique identifer that gets set in the `selector` field so the Job +controller can get all the corresponding Pods. ### scheduler.alpha.kubernetes.io/defaultTolerations {#scheduleralphakubernetesio-defaulttolerations} +Type: Annotation + Example: `scheduler.alpha.kubernetes.io/defaultTolerations: '[{"operator": "Equal", "value": "value1", "effect": "NoSchedule", "key": "dedicated-node"}]'` Used on: Namespace -This annotation requires the [PodTolerationRestriction](/docs/reference/access-authn-authz/admission-controllers/#podtolerationrestriction) admission controller to be enabled. This annotation key allows assigning tolerations to a namespace and any new pods created in this namespace would get these tolerations added. +This annotation requires the [PodTolerationRestriction](/docs/reference/access-authn-authz/admission-controllers/#podtolerationrestriction) +admission controller to be enabled. This annotation key allows assigning tolerations to a +namespace and any new pods created in this namespace would get these tolerations added. ### scheduler.alpha.kubernetes.io/tolerationsWhitelist {#schedulerkubernetestolerations-whitelist} +Type: Annotation + Example: `scheduler.alpha.kubernetes.io/tolerationsWhitelist: '[{"operator": "Exists", "effect": "NoSchedule", "key": "dedicated-node"}]'` Used on: Namespace -This annotation is only useful when the (alpha) +This annotation is only useful when the (Alpha) [PodTolerationRestriction](/docs/reference/access-authn-authz/admission-controllers/#podtolerationrestriction) -admission controller is enabled. The annotation value is a JSON document that defines a list of allowed tolerations -for the namespace it annotates. When you create a Pod or modify its tolerations, the API server checks the tolerations -to see if they are mentioned in the allow list. The pod is admitted only if the check succeeds. +admission controller is enabled. The annotation value is a JSON document that defines a list of +allowed tolerations for the namespace it annotates. When you create a Pod or modify its +tolerations, the API server checks the tolerations to see if they are mentioned in the allow list. +The pod is admitted only if the check succeeds. ### scheduler.alpha.kubernetes.io/preferAvoidPods (deprecated) {#scheduleralphakubernetesio-preferavoidpods} -Used on: Nodes +Type: Annotation + +Used on: Node This annotation requires the [NodePreferAvoidPods scheduling plugin](/docs/reference/scheduling/config/#scheduling-plugins) to be enabled. The plugin is deprecated since Kubernetes 1.22. Use [Taints and Tolerations](/docs/concepts/scheduling-eviction/taint-and-toleration/) instead. -**The taints listed below are always used on Nodes** - ### node.kubernetes.io/not-ready +Type: Taint + Example: `node.kubernetes.io/not-ready: "NoExecute"` -The node controller detects whether a node is ready by monitoring its health and adds or removes this taint accordingly. +Used on: Node + +The Node controller detects whether a Node is ready by monitoring its health +and adds or removes this taint accordingly. ### node.kubernetes.io/unreachable +Type: Taint + Example: `node.kubernetes.io/unreachable: "NoExecute"` -The node controller adds the taint to a node corresponding to the [NodeCondition](/docs/concepts/architecture/nodes/#condition) `Ready` being `Unknown`. +Used on: Node + +The Node controller adds the taint to a Node corresponding to the +[NodeCondition](/docs/concepts/architecture/nodes/#condition) `Ready` being `Unknown`. ### node.kubernetes.io/unschedulable +Type: Taint + Example: `node.kubernetes.io/unschedulable: "NoSchedule"` +Used on: Node + The taint will be added to a node when initializing the node to avoid race condition. ### node.kubernetes.io/memory-pressure +Type: Taint + Example: `node.kubernetes.io/memory-pressure: "NoSchedule"` -The kubelet detects memory pressure based on `memory.available` and `allocatableMemory.available` observed on a Node. The observed values are then compared to the corresponding thresholds that can be set on the kubelet to determine if the Node condition and taint should be added/removed. +Used on: Node + +The kubelet detects memory pressure based on `memory.available` and `allocatableMemory.available` +observed on a Node. The observed values are then compared to the corresponding thresholds that can +be set on the kubelet to determine if the Node condition and taint should be added/removed. ### node.kubernetes.io/disk-pressure +Type: Taint + Example: `node.kubernetes.io/disk-pressure :"NoSchedule"` -The kubelet detects disk pressure based on `imagefs.available`, `imagefs.inodesFree`, `nodefs.available` and `nodefs.inodesFree`(Linux only) observed on a Node. The observed values are then compared to the corresponding thresholds that can be set on the kubelet to determine if the Node condition and taint should be added/removed. +Used on: Node + +The kubelet detects disk pressure based on `imagefs.available`, `imagefs.inodesFree`, +`nodefs.available` and `nodefs.inodesFree`(Linux only) observed on a Node. +The observed values are then compared to the corresponding thresholds that can be set on the +kubelet to determine if the Node condition and taint should be added/removed. ### node.kubernetes.io/network-unavailable +Type: Taint + Example: `node.kubernetes.io/network-unavailable: "NoSchedule"` -This is initially set by the kubelet when the cloud provider used indicates a requirement for additional network configuration. Only when the route on the cloud is configured properly will the taint be removed by the cloud provider. +Used on: Node + +This is initially set by the kubelet when the cloud provider used indicates a requirement for +additional network configuration. Only when the route on the cloud is configured properly will the +taint be removed by the cloud provider. ### node.kubernetes.io/pid-pressure +Type: Taint + Example: `node.kubernetes.io/pid-pressure: "NoSchedule"` -The kubelet checks D-value of the size of `/proc/sys/kernel/pid_max` and the PIDs consumed by Kubernetes on a node to get the number of available PIDs that referred to as the `pid.available` metric. The metric is then compared to the corresponding threshold that can be set on the kubelet to determine if the node condition and taint should be added/removed. +Used on: Node + +The kubelet checks D-value of the size of `/proc/sys/kernel/pid_max` and the PIDs consumed by +Kubernetes on a node to get the number of available PIDs that referred to as the `pid.available` +metric. The metric is then compared to the corresponding threshold that can be set on the kubelet +to determine if the node condition and taint should be added/removed. ### node.kubernetes.io/out-of-service +Type: Taint + Example: `node.kubernetes.io/out-of-service:NoExecute` -A user can manually add the taint to a Node marking it out-of-service. If the `NodeOutOfServiceVolumeDetach` -[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled on -`kube-controller-manager`, and a Node is marked out-of-service with this taint, the pods on the node will be forcefully deleted if there are no matching tolerations on it and volume detach operations for the pods terminating on the node will happen immediately. This allows the Pods on the out-of-service node to recover quickly on a different node. +Used on: Node + +A user can manually add the taint to a Node marking it out-of-service. +If the `NodeOutOfServiceVolumeDetach` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +is enabled on `kube-controller-manager`, and a Node is marked out-of-service with this taint, +the Pods on the node will be forcefully deleted if there are no matching tolerations on it and +volume detach operations for the Pods terminating on the node will happen immediately. +This allows the Pods on the out-of-service node to recover quickly on a different node. {{< caution >}} -Refer to -[Non-graceful node shutdown](/docs/concepts/architecture/nodes/#non-graceful-node-shutdown) +Refer to [Non-graceful node shutdown](/docs/concepts/architecture/nodes/#non-graceful-node-shutdown) for further details about when and how to use this taint. {{< /caution >}} ### node.cloudprovider.kubernetes.io/uninitialized +Type: Taint + Example: `node.cloudprovider.kubernetes.io/uninitialized: "NoSchedule"` -Sets this taint on a node to mark it as unusable, when kubelet is started with the "external" cloud provider, until a controller from the cloud-controller-manager initializes this node, and then removes the taint. +Used on: Node + +Sets this taint on a Node to mark it as unusable, when kubelet is started with the "external" +cloud provider, until a controller from the cloud-controller-manager initializes this Node, and +then removes the taint. ### node.cloudprovider.kubernetes.io/shutdown +Type: Taint + Example: `node.cloudprovider.kubernetes.io/shutdown: "NoSchedule"` -If a Node is in a cloud provider specified shutdown state, the Node gets tainted accordingly with `node.cloudprovider.kubernetes.io/shutdown` and the taint effect of `NoSchedule`. +Used on: Node + +If a Node is in a cloud provider specified shutdown state, the Node gets tainted accordingly +with `node.cloudprovider.kubernetes.io/shutdown` and the taint effect of `NoSchedule`. ### feature.node.kubernetes.io/* -Used on: Nodes + +Type: Label + Example: `feature.node.kubernetes.io/network-sriov.capable: "true"` -These features are advertised as labels in the Kubernetes Node object on nodes running NFD. -All built-in labels use the feature.node.kubernetes.io label namespace and have the format -`feature.node.kubernetes.io/: `. +Used on: Node + +These labels are used by the Node Feature Discovery (NFD) component to advertise +features on a node. All built-in labels use the `feature.node.kubernetes.io` label +namespace and have the format `feature.node.kubernetes.io/: "true"`. NFD has many extension points for creating vendor and application-specific labels. For details, see the [customization guide](https://kubernetes-sigs.github.io/node-feature-discovery/v0.12/usage/customization-guide). ### nfd.node.kubernetes.io/master.version +Type: Annotation + Example: `nfd.node.kubernetes.io/master.version: "v0.6.0"` -Used on: Nodes +Used on: Node For node(s) where the Node Feature Discovery (NFD) [master](https://kubernetes-sigs.github.io/node-feature-discovery/stable/usage/nfd-master.html) @@ -965,17 +1347,20 @@ It is used for informative use only. ### nfd.node.kubernetes.io/worker.version +Type: Annotation + Example: `nfd.node.kubernetes.io/worker.version: "v0.4.0"` Used on: Nodes This annotation records the version for a Node Feature Discovery's [worker](https://kubernetes-sigs.github.io/node-feature-discovery/stable/usage/nfd-worker.html) -if there is one running on a node. -It's used for informative use only. +if there is one running on a node. It's used for informative use only. ### nfd.node.kubernetes.io/feature-labels +Type: Annotation + Example: `nfd.node.kubernetes.io/feature-labels: "cpu-cpuid.ADX,cpu-cpuid.AESNI,cpu-hardware_multithreading,kernel-version.full"` Used on: Nodes @@ -986,11 +1371,14 @@ NFD uses this for an internal mechanism. You should not edit this annotation you ### nfd.node.kubernetes.io/extended-resources +Type: Annotation + Example: `nfd.node.kubernetes.io/extended-resources: "accelerator.acme.example/q500,example.com/coprocessor-fx5"` Used on: Nodes -This annotation records a comma-separated list of [extended resources](/docs/concepts/configuration/manage-resources-containers/#extended-resources) +This annotation records a comma-separated list of +[extended resources](/docs/concepts/configuration/manage-resources-containers/#extended-resources) managed by [Node Feature Discovery](https://kubernetes-sigs.github.io/node-feature-discovery/) (NFD). NFD uses this for an internal mechanism. You should not edit this annotation yourself. @@ -1002,106 +1390,131 @@ To learn more about NFD and its components go to its official ### pod-security.kubernetes.io/enforce +Type: Label + Example: `pod-security.kubernetes.io/enforce: "baseline"` Used on: Namespace Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to -[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically, -the `enforce` label _prohibits_ the creation of any Pod in the labeled Namespace which does not meet -the requirements outlined in the indicated level. +[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. +Specifically, the `enforce` label _prohibits_ the creation of any Pod in the labeled +Namespace which does not meet the requirements outlined in the indicated level. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) for more information. ### pod-security.kubernetes.io/enforce-version +Type: Label + Example: `pod-security.kubernetes.io/enforce-version: "{{< skew currentVersion >}}"` Used on: Namespace -Value **must** be `latest` or a valid Kubernetes version in the format `v.`. -This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) -policies to apply when validating a submitted Pod. +Value **must** be `latest` or a valid Kubernetes version in the format `v.`. +This determines the version of the +[Pod Security Standard](/docs/concepts/security/pod-security-standards) +policies to apply when validating a Pod. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) for more information. ### pod-security.kubernetes.io/audit +Type: Label + Example: `pod-security.kubernetes.io/audit: "baseline"` Used on: Namespace Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to -[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically, -the `audit` label does not prevent the creation of a Pod in the labeled Namespace which does not meet -the requirements outlined in the indicated level, but adds an audit annotation to that Pod. +[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. +Specifically, the `audit` label does not prevent the creation of a Pod in the labeled +Namespace which does not meet the requirements outlined in the indicated level, +but adds an this annotation to the Pod. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) for more information. ### pod-security.kubernetes.io/audit-version +Type: Label + Example: `pod-security.kubernetes.io/audit-version: "{{< skew currentVersion >}}"` Used on: Namespace -Value **must** be `latest` or a valid Kubernetes version in the format `v.`. -This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) -policies to apply when validating a submitted Pod. +Value **must** be `latest` or a valid Kubernetes version in the format `v.`. +This determines the version of the +[Pod Security Standard](/docs/concepts/security/pod-security-standards) +policies to apply when validating a Pod. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) for more information. ### pod-security.kubernetes.io/warn +Type: Label + Example: `pod-security.kubernetes.io/warn: "baseline"` Used on: Namespace Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to -[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically, -the `warn` label does not prevent the creation of a Pod in the labeled Namespace which does not meet the -requirements outlined in the indicated level, but returns a warning to the user after doing so. -Note that warnings are also displayed when creating or updating objects that contain Pod templates, -such as Deployments, Jobs, StatefulSets, etc. +[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. +Specifically, the `warn` label does not prevent the creation of a Pod in the labeled +Namespace which does not meet the requirements outlined in the indicated level, +but returns a warning to the user after doing so. +Note that warnings are also displayed when creating or updating objects that contain +Pod templates, such as Deployments, Jobs, StatefulSets, etc. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) for more information. ### pod-security.kubernetes.io/warn-version +Type: Label + Example: `pod-security.kubernetes.io/warn-version: "{{< skew currentVersion >}}"` Used on: Namespace -Value **must** be `latest` or a valid Kubernetes version in the format `v.`. +Value **must** be `latest` or a valid Kubernetes version in the format `v.`. This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) -policies to apply when validating a submitted Pod. Note that warnings are also displayed when creating -or updating objects that contain Pod templates, such as Deployments, Jobs, StatefulSets, etc. +policies to apply when validating a submitted Pod. +Note that warnings are also displayed when creating or updating objects that contain +Pod templates, such as Deployments, Jobs, StatefulSets, etc. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) for more information. ### rbac.authorization.kubernetes.io/autoupdate +Type: Annotation + Example: `rbac.authorization.kubernetes.io/autoupdate: "false"` Used on: ClusterRole, ClusterRoleBinding, Role, RoleBinding -When this annotation is set to `"true"` on default RBAC objects created by the kube-apiserver, they are automatically updated at server start to add missing permissions and subjects (extra permissions and subjects are left in place). To prevent autoupdating a particular role or rolebinding, set this annotation to `"false"`. +When this annotation is set to `"true"` on default RBAC objects created by the API server, +they are automatically updated at server start to add missing permissions and subjects +(extra permissions and subjects are left in place). +To prevent autoupdating a particular role or rolebinding, set this annotation to `"false"`. If you create your own RBAC objects and set this annotation to `"false"`, `kubectl auth reconcile` -(which allows reconciling arbitrary RBAC objects in a {{< glossary_tooltip text="manifest" term_id="manifest" >}}) respects this annotation and does not automatically add missing permissions and -subjects. +(which allows reconciling arbitrary RBAC objects in a {{< glossary_tooltip text="manifest" term_id="manifest" >}}) +respects this annotation and does not automatically add missing permissions and subjects. ### kubernetes.io/psp (deprecated) {#kubernetes-io-psp} +Type: Annotation + Example: `kubernetes.io/psp: restricted` Used on: Pod -This annotation was only relevant if you were using [PodSecurityPolicies](/docs/concepts/security/pod-security-policy/). +This annotation was only relevant if you were using +[PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) objects. Kubernetes v{{< skew currentVersion >}} does not support the PodSecurityPolicy API. When the PodSecurityPolicy admission controller admitted a Pod, the admission controller @@ -1110,41 +1523,55 @@ The value of the annotation was the name of the PodSecurityPolicy that was used ### seccomp.security.alpha.kubernetes.io/pod (non-functional) {#seccomp-security-alpha-kubernetes-io-pod} -Older versions of Kubernetes allowed you to configure seccomp -behavior using this {{< glossary_tooltip text="annotation" term_id="annotation" >}}. +Type: Annotation + +Used on: Pod + +Kubernetes before v1.25 allowed you to configure seccomp behavior using this annotation. See [Restrict a Container's Syscalls with seccomp](/docs/tutorials/security/seccomp/) to learn the supported way to specify seccomp restrictions for a Pod. ### container.seccomp.security.alpha.kubernetes.io/[NAME] (non-functional) {#container-seccomp-security-alpha-kubernetes-io} -Older versions of Kubernetes allowed you to configure seccomp -behavior using this {{< glossary_tooltip text="annotation" term_id="annotation" >}}. +Type: Annotation + +Used on: Pod + +Kubernetes before v1.25 allowed you to configure seccomp behavior using this annotation. See [Restrict a Container's Syscalls with seccomp](/docs/tutorials/security/seccomp/) to learn the supported way to specify seccomp restrictions for a Pod. ### snapshot.storage.kubernetes.io/allow-volume-mode-change +Type: Annotation + Example: `snapshot.storage.kubernetes.io/allow-volume-mode-change: "true"` Used on: VolumeSnapshotContent -Value can either be `true` or `false`. -This determines whether a user can modify the mode of the source volume when a -{{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}} is being -created from a VolumeSnapshot. +Value can either be `true` or `false`. This determines whether a user can modify +the mode of the source volume when a PersistentVolumeClaim is being created from +a VolumeSnapshot. Refer to [Converting the volume mode of a Snapshot](/docs/concepts/storage/volume-snapshots/#convert-volume-mode) -and the [Kubernetes CSI Developer Documentation](https://kubernetes-csi.github.io/docs/) for more information. +and the [Kubernetes CSI Developer Documentation](https://kubernetes-csi.github.io/docs/) +for more information. ### scheduler.alpha.kubernetes.io/critical-pod (deprecated) +Type: Annotation + Example: `scheduler.alpha.kubernetes.io/critical-pod: ""` Used on: Pod -This annotation lets Kubernetes control plane know about a pod being a critical pod so that the descheduler will not remove this pod. +This annotation lets Kubernetes control plane know about a Pod being a critical Pod +so that the descheduler will not remove this Pod. -{{< note >}} Starting in v1.16, this annotation was removed in favor of [Pod Priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/). {{< /note >}} +{{< note >}} +Starting in v1.16, this annotation was removed in favor of +[Pod Priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/). +{{< /note >}} ## Annotations used for audit @@ -1157,74 +1584,102 @@ This annotation lets Kubernetes control plane know about a pod being a critical - [`pod-security.kubernetes.io/enforce-policy`](/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-enforce-policy) - [`pod-security.kubernetes.io/exempt`](/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-exempt) -See more details on the [Audit Annotations](/docs/reference/labels-annotations-taints/audit-annotations/) page. +See more details on [Audit Annotations](/docs/reference/labels-annotations-taints/audit-annotations/). ## kubeadm ### kubeadm.alpha.kubernetes.io/cri-socket +Type: Annotation + Example: `kubeadm.alpha.kubernetes.io/cri-socket: unix:///run/containerd/container.sock` Used on: Node -Annotation that kubeadm uses to preserve the CRI socket information given to kubeadm at `init`/`join` time for later use. -kubeadm annotates the Node object with this information. The annotation remains "alpha", since ideally this should -be a field in KubeletConfiguration instead. +Annotation that kubeadm uses to preserve the CRI socket information given to kubeadm at +`init`/`join` time for later use. kubeadm annotates the Node object with this information. +The annotation remains "alpha", since ideally this should be a field in KubeletConfiguration +instead. ### kubeadm.kubernetes.io/etcd.advertise-client-urls +Type: Annotation + Example: `kubeadm.kubernetes.io/etcd.advertise-client-urls: https://172.17.0.18:2379` Used on: Pod -Annotation that kubeadm places on locally managed etcd pods to keep track of a list of URLs where etcd clients -should connect to. This is used mainly for etcd cluster health check purposes. +Annotation that kubeadm places on locally managed etcd Pods to keep track of +a list of URLs where etcd clients should connect to. +This is used mainly for etcd cluster health check purposes. ### kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint +Type: Annotation + Example: `kubeadm.kubernetes.io/kube-apiserver.advertise-address.endpoint: https://172.17.0.18:6443` Used on: Pod -Annotation that kubeadm places on locally managed kube-apiserver pods to keep track of the exposed advertise -address/port endpoint for that API server instance. +Annotation that kubeadm places on locally managed `kube-apiserver` Pods to keep track +of the exposed advertise address/port endpoint for that API server instance. ### kubeadm.kubernetes.io/component-config.hash +Type: Annotation + Used on: ConfigMap Example: `kubeadm.kubernetes.io/component-config.hash: 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae` -Annotation that kubeadm places on ConfigMaps that it manages for configuring components. It contains a hash (SHA-256) -used to determine if the user has applied settings different from the kubeadm defaults for a particular component. +Annotation that kubeadm places on ConfigMaps that it manages for configuring components. +It contains a hash (SHA-256) used to determine if the user has applied settings different +from the kubeadm defaults for a particular component. ### node-role.kubernetes.io/control-plane +Type: Label + Used on: Node -A marker label to indicate that the node is used to run {{< glossary_tooltip text="control plane" term_id="control-plane" >}} components. The kubeadm tool applies this label to the control plane nodes that it manages. Other cluster management tools typically also set this taint. +A marker label to indicate that the node is used to run control plane components. +The kubeadm tool applies this label to the control plane nodes that it manages. +Other cluster management tools typically also set this taint. -You can label control plane nodes with this label to make it easier to schedule Pods only onto these nodes, or to avoid running Pods on the control plane. If this label is set, [EndpointSlice controller](/docs/concepts/services-networking/topology-aware-routing/#implementation-control-plane) ignores that node while calculating Topology Aware Hints. +You can label control plane nodes with this label to make it easier to schedule Pods +only onto these nodes, or to avoid running Pods on the control plane. +If this label is set, the [EndpointSlice controller](/docs/concepts/services-networking/topology-aware-routing/#implementation-control-plane) +ignores that node while calculating Topology Aware Hints. ### node-role.kubernetes.io/control-plane {#node-role-kubernetes-io-control-plane-taint} -Used on: Node - -Taint that kubeadm applies on control plane nodes to restrict placing pods and allow only specific pods to schedule on them. +Type: Taint Example: `node-role.kubernetes.io/control-plane:NoSchedule` -If this Taint is applied, control plane nodes allow only critical workloads to schedule on them. You can manually remove this taint with the following command on a specific node. +Used on: Node + +Taint that kubeadm applies on control plane nodes to restrict placing Pods and +allow only specific pods to schedule on them. + +If this Taint is applied, control plane nodes allow only critical workloads to +be scheduled onto them. You can manually remove this taint with the following +command on a specific node. + ```shell kubectl taint nodes node-role.kubernetes.io/control-plane:NoSchedule- ``` ### node-role.kubernetes.io/master (deprecated) {#node-role-kubernetes-io-master-taint} +Type: Taint + Used on: Node Example: `node-role.kubernetes.io/master:NoSchedule` -Taint that kubeadm previously applied on control plane nodes to allow only critical workloads to schedule on them. -Replaced by [`node-role.kubernetes.io/control-plane`](#node-role-kubernetes-io-control-plane-taint); kubeadm -no longer sets or uses this deprecated taint. +Taint that kubeadm previously applied on control plane nodes to allow only critical +workloads to schedule on them. Replaced by the +[`node-role.kubernetes.io/control-plane`](#node-role-kubernetes-io-control-plane-taint) +taint. kubeadm no longer sets or uses this deprecated taint. +