diff --git a/config.toml b/config.toml index 04329284d8..f4922ef075 100644 --- a/config.toml +++ b/config.toml @@ -138,10 +138,10 @@ time_format_default = "January 02, 2006 at 3:04 PM PST" description = "Production-Grade Container Orchestration" showedit = true -latest = "v1.20" +latest = "v1.21" -fullversion = "v1.20.0" -version = "v1.20" +fullversion = "v1.21.0" +version = "v1.21" githubbranch = "master" docsbranch = "master" deprecated = false @@ -178,40 +178,40 @@ js = [ ] [[params.versions]] -fullversion = "v1.20.0" -version = "v1.20" -githubbranch = "v1.20.0" +fullversion = "v1.21.0" +version = "v1.21" +githubbranch = "v1.21.0" docsbranch = "master" url = "https://kubernetes.io" [[params.versions]] -fullversion = "v1.19.4" +fullversion = "v1.20.5" +version = "v1.20" +githubbranch = "v1.20.5" +docsbranch = "release-1.20" +url = "https://v1-20.kubernetes.io" + +[[params.versions]] +fullversion = "v1.19.9" version = "v1.19" -githubbranch = "v1.19.4" +githubbranch = "v1.19.9" docsbranch = "release-1.19" url = "https://v1-19.docs.kubernetes.io" [[params.versions]] -fullversion = "v1.18.12" +fullversion = "v1.18.17" version = "v1.18" -githubbranch = "v1.18.12" +githubbranch = "v1.18.17" docsbranch = "release-1.18" url = "https://v1-18.docs.kubernetes.io" [[params.versions]] -fullversion = "v1.17.14" +fullversion = "v1.17.17" version = "v1.17" -githubbranch = "v1.17.14" +githubbranch = "v1.17.17" docsbranch = "release-1.17" url = "https://v1-17.docs.kubernetes.io" -[[params.versions]] -fullversion = "v1.16.15" -version = "v1.16" -githubbranch = "v1.16.15" -docsbranch = "release-1.16" -url = "https://v1-16.docs.kubernetes.io" - # User interface configuration [params.ui] diff --git a/content/en/docs/concepts/architecture/cloud-controller.md b/content/en/docs/concepts/architecture/cloud-controller.md index d97fc94a4c..9b64289e82 100644 --- a/content/en/docs/concepts/architecture/cloud-controller.md +++ b/content/en/docs/concepts/architecture/cloud-controller.md @@ -206,6 +206,8 @@ rules: [Cloud Controller Manager Administration](/docs/tasks/administer-cluster/running-cloud-controller/#cloud-controller-manager) has instructions on running and managing the cloud controller manager. +To upgrade a HA control plane to use the cloud controller manager, see [Migrate Replicated Control Plane To Use Cloud Controller Manager](/docs/tasks/administer-cluster/controller-manager-leader-migration/). + Want to know how to implement your own cloud controller manager, or extend an existing project? The cloud controller manager uses Go interfaces to allow implementations from any cloud to be plugged in. Specifically, it uses the `CloudProvider` interface defined in [`cloud.go`](https://github.com/kubernetes/cloud-provider/blob/release-1.17/cloud.go#L42-L62) from [kubernetes/cloud-provider](https://github.com/kubernetes/cloud-provider). diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md index 57414a415f..30dc0d4af9 100644 --- a/content/en/docs/concepts/architecture/nodes.md +++ b/content/en/docs/concepts/architecture/nodes.md @@ -346,26 +346,43 @@ the kubelet can use topology hints when making resource assignment decisions. See [Control Topology Management Policies on a Node](/docs/tasks/administer-cluster/topology-manager/) for more information. -## Graceful Node Shutdown {#graceful-node-shutdown} +## Graceful node shutdown {#graceful-node-shutdown} -{{< feature-state state="alpha" for_k8s_version="v1.20" >}} +{{< feature-state state="beta" for_k8s_version="v1.21" >}} + +The kubelet attempts to detect node system shutdown and terminates pods running on the node. -If you have enabled the `GracefulNodeShutdown` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/), then the kubelet attempts to detect the node system shutdown and terminates pods running on the node. Kubelet ensures that pods follow the normal [pod termination process](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) during the node shutdown. -When the `GracefulNodeShutdown` feature gate is enabled, kubelet uses [systemd inhibitor locks](https://www.freedesktop.org/wiki/Software/systemd/inhibit/) to delay the node shutdown with a given duration. During a shutdown, kubelet terminates pods in two phases: +The Graceful node shutdown feature depends on systemd since it takes advantage of +[systemd inhibitor locks](https://www.freedesktop.org/wiki/Software/systemd/inhibit/) to +delay the node shutdown with a given duration. + +Graceful node shutdown is controlled with the `GracefulNodeShutdown` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) which is +enabled by default in 1.21. + +Note that by default, both configuration options described below, +`ShutdownGracePeriod` and `ShutdownGracePeriodCriticalPods` are set to zero, +thus not activating Graceful node shutdown functionality. +To activate the feature, the two kubelet config settings should be configured appropriately and set to non-zero values. + +During a graceful shutdown, kubelet terminates pods in two phases: 1. Terminate regular pods running on the node. 2. Terminate [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) running on the node. -Graceful Node Shutdown feature is configured with two [`KubeletConfiguration`](/docs/tasks/administer-cluster/kubelet-config-file/) options: +Graceful node shutdown feature is configured with two [`KubeletConfiguration`](/docs/tasks/administer-cluster/kubelet-config-file/) options: * `ShutdownGracePeriod`: * Specifies the total duration that the node should delay the shutdown by. This is the total grace period for pod termination for both regular and [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical). * `ShutdownGracePeriodCriticalPods`: - * Specifies the duration used to terminate [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) during a node shutdown. This should be less than `ShutdownGracePeriod`. - -For example, if `ShutdownGracePeriod=30s`, and `ShutdownGracePeriodCriticalPods=10s`, kubelet will delay the node shutdown by 30 seconds. During the shutdown, the first 20 (30-10) seconds would be reserved for gracefully terminating normal pods, and the last 10 seconds would be reserved for terminating [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical). + * Specifies the duration used to terminate [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) during a node shutdown. This value should be less than `ShutdownGracePeriod`. +For example, if `ShutdownGracePeriod=30s`, and +`ShutdownGracePeriodCriticalPods=10s`, kubelet will delay the node shutdown by +30 seconds. During the shutdown, the first 20 (30-10) seconds would be reserved +for gracefully terminating normal pods, and the last 10 seconds would be +reserved for terminating [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical). ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/cluster-administration/logging.md b/content/en/docs/concepts/cluster-administration/logging.md index d8c0a0615c..e75fdea4a5 100644 --- a/content/en/docs/concepts/cluster-administration/logging.md +++ b/content/en/docs/concepts/cluster-administration/logging.md @@ -83,12 +83,15 @@ As an example, you can find detailed information about how `kube-up.sh` sets up logging for COS image on GCP in the corresponding [`configure-helper` script](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh). +When using a **CRI container runtime**, the kubelet is responsible for rotating the logs and managing the logging directory structure. The kubelet +sends this information to the CRI container runtime and the runtime writes the container logs to the given location. The two kubelet flags `container-log-max-size` and `container-log-max-files` can be used to configure the maximum size for each log file and the maximum number of files allowed for each container respectively. + When you run [`kubectl logs`](/docs/reference/generated/kubectl/kubectl-commands#logs) as in the basic logging example, the kubelet on the node handles the request and reads directly from the log file. The kubelet returns the content of the log file. {{< note >}} -If an external system has performed the rotation, +If an external system has performed the rotation or a CRI container runtime is used, only the contents of the latest log file will be available through `kubectl logs`. For example, if there's a 10MB file, `logrotate` performs the rotation and there are two files: one file that is 10MB in size and a second file that is empty. diff --git a/content/en/docs/concepts/cluster-administration/system-metrics.md b/content/en/docs/concepts/cluster-administration/system-metrics.md index 3c7e137ded..9852f9cc99 100644 --- a/content/en/docs/concepts/cluster-administration/system-metrics.md +++ b/content/en/docs/concepts/cluster-administration/system-metrics.md @@ -134,7 +134,7 @@ cloudprovider_gce_api_request_duration_seconds { request = "list_disk"} ### kube-scheduler metrics -{{< feature-state for_k8s_version="v1.20" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} The scheduler exposes optional metrics that reports the requested resources and the desired limits of all running pods. These metrics can be used to build capacity planning dashboards, assess current or historical scheduling limits, quickly identify workloads that cannot schedule due to lack of resources, and compare actual usage to the pod's request. @@ -152,6 +152,24 @@ Once a pod reaches completion (has a `restartPolicy` of `Never` or `OnFailure` a The metrics are exposed at the HTTP endpoint `/metrics/resources` and require the same authorization as the `/metrics` endpoint on the scheduler. You must use the `--show-hidden-metrics-for-version=1.20` flag to expose these alpha stability metrics. +## Disabling metrics + +You can explicitly turn off metrics via command line flag `--disabled-metrics`. This may be desired if, for example, a metric is causing a performance problem. The input is a list of disabled metrics (i.e. `--disabled-metrics=metric1,metric2`). + +## Metric cardinality enforcement + +Metrics with unbounded dimensions could cause memory issues in the components they instrument. To limit resource use, you can use the `--allow-label-value` command line option to dynamically configure an allow-list of label values for a metric. + +In alpha stage, the flag can only take in a series of mappings as metric label allow-list. +Each mapping is of the format `,=` where +`` is a comma-separated list of acceptable label names. + +The overall format looks like: +`--allow-label-value ,=', ...', ,=', ...', ...`. + +Here is an example: +`--allow-label-value number_count_metric,odd_number='1,3,5', number_count_metric,even_number='2,4,6', date_gauge_metric,weekend='Saturday,Sunday'` + ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/configuration/configmap.md b/content/en/docs/concepts/configuration/configmap.md index b5f5bd8d28..3af8d6ae2c 100644 --- a/content/en/docs/concepts/configuration/configmap.md +++ b/content/en/docs/concepts/configuration/configmap.md @@ -236,9 +236,9 @@ ConfigMaps consumed as environment variables are not updated automatically and r ## Immutable ConfigMaps {#configmap-immutable} -{{< feature-state for_k8s_version="v1.19" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} -The Kubernetes beta feature _Immutable Secrets and ConfigMaps_ provides an option to set +The Kubernetes feature _Immutable Secrets and ConfigMaps_ provides an option to set individual Secrets and ConfigMaps as immutable. For clusters that extensively use ConfigMaps (at least tens of thousands of unique ConfigMap to Pod mounts), preventing changes to their data has the following advantages: diff --git a/content/en/docs/concepts/configuration/secret.md b/content/en/docs/concepts/configuration/secret.md index d41c7eacf9..111a405a7a 100644 --- a/content/en/docs/concepts/configuration/secret.md +++ b/content/en/docs/concepts/configuration/secret.md @@ -749,9 +749,9 @@ There are third party solutions for triggering restarts when secrets change. ## Immutable Secrets {#secret-immutable} -{{< feature-state for_k8s_version="v1.19" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} -The Kubernetes beta feature _Immutable Secrets and ConfigMaps_ provides an option to set +The Kubernetes feature _Immutable Secrets and ConfigMaps_ provides an option to set individual Secrets and ConfigMaps as immutable. For clusters that extensively use Secrets (at least tens of thousands of unique Secret to Pod mounts), preventing changes to their data has the following advantages: diff --git a/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md b/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md index 8b1747b857..8f39284a96 100644 --- a/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md +++ b/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md @@ -193,9 +193,69 @@ for these devices: // node resources consumed by pods and containers on the node service PodResourcesLister { rpc List(ListPodResourcesRequest) returns (ListPodResourcesResponse) {} + rpc GetAllocatableResources(AllocatableResourcesRequest) returns (AllocatableResourcesResponse) {} } ``` +The `List` endpoint provides information on resources of running pods, with details such as the +id of exclusively allocated CPUs, device id as it was reported by device plugins and id of +the NUMA node where these devices are allocated. + +```gRPC +// ListPodResourcesResponse is the response returned by List function +message ListPodResourcesResponse { + repeated PodResources pod_resources = 1; +} + +// PodResources contains information about the node resources assigned to a pod +message PodResources { + string name = 1; + string namespace = 2; + repeated ContainerResources containers = 3; +} + +// ContainerResources contains information about the resources assigned to a container +message ContainerResources { + string name = 1; + repeated ContainerDevices devices = 2; + repeated int64 cpu_ids = 3; +} + +// Topology describes hardware topology of the resource +message TopologyInfo { + repeated NUMANode nodes = 1; +} + +// NUMA representation of NUMA node +message NUMANode { + int64 ID = 1; +} + +// ContainerDevices contains information about the devices assigned to a container +message ContainerDevices { + string resource_name = 1; + repeated string device_ids = 2; + TopologyInfo topology = 3; +} +``` + +GetAllocatableResources provides information on resources initially available on the worker node. +It provides more information than kubelet exports to APIServer. + +```gRPC +// AllocatableResourcesResponses contains informations about all the devices known by the kubelet +message AllocatableResourcesResponse { + repeated ContainerDevices devices = 1; + repeated int64 cpu_ids = 2; +} + +``` + +`ContainerDevices` do expose the topology information declaring to which NUMA cells the device is affine. +The NUMA cells are identified using a opaque integer ID, which value is consistent to what device +plugins report [when they register themselves to the kubelet](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-integration-with-the-topology-manager). + + The gRPC service is served over a unix socket at `/var/lib/kubelet/pod-resources/kubelet.sock`. Monitoring agents for device plugin resources can be deployed as a daemon, or as a DaemonSet. The canonical directory `/var/lib/kubelet/pod-resources` requires privileged access, so monitoring @@ -204,7 +264,7 @@ DaemonSet, `/var/lib/kubelet/pod-resources` must be mounted as a {{< glossary_tooltip term_id="volume" >}} in the device monitoring agent's [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core). -Support for the "PodResources service" requires `KubeletPodResources` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. +Support for the `PodResourcesLister service` requires `KubeletPodResources` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. It is enabled by default starting with Kubernetes 1.15 and is v1 since Kubernetes 1.20. ## Device Plugin integration with the Topology Manager @@ -256,5 +316,3 @@ Here are some examples of device plugin implementations: * Learn about [advertising extended resources](/docs/tasks/administer-cluster/extended-resource-node/) on a node * Read about using [hardware acceleration for TLS ingress](https://kubernetes.io/blog/2019/04/24/hardware-accelerated-ssl/tls-termination-in-ingress-controllers-using-kubernetes-device-plugins-and-runtimeclass/) with Kubernetes * Learn about the [Topology Manager](/docs/tasks/administer-cluster/topology-manager/) - - diff --git a/content/en/docs/concepts/overview/working-with-objects/namespaces.md b/content/en/docs/concepts/overview/working-with-objects/namespaces.md index b7ae176d7c..8f740c866b 100644 --- a/content/en/docs/concepts/overview/working-with-objects/namespaces.md +++ b/content/en/docs/concepts/overview/working-with-objects/namespaces.md @@ -30,7 +30,7 @@ Namespaces are a way to divide cluster resources between multiple users (via [re It is not necessary to use multiple namespaces to separate slightly different resources, such as different versions of the same software: use -[labels](/docs/concepts/overview/working-with-objects/labels) to distinguish +{{< glossary_tooltip text="labels" term_id="label" >}} to distinguish resources within the same namespace. ## Working with Namespaces @@ -114,6 +114,16 @@ kubectl api-resources --namespaced=true kubectl api-resources --namespaced=false ``` +## Automatic labelling + +{{< feature-state state="beta" for_k8s_version="1.21" >}} + +The Kubernetes control plane sets an immutable {{< glossary_tooltip text="label" term_id="label" >}} +`kubernetes.io/metadata.name` on all namespaces, provided that the `NamespaceDefaultLabelName` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled. +The value of the label is the namespace name. + + ## {{% heading "whatsnext" %}} * Learn more about [creating a new namespace](/docs/tasks/administer-cluster/namespaces/#creating-a-new-namespace). diff --git a/content/en/docs/concepts/policy/node-resource-managers.md b/content/en/docs/concepts/policy/node-resource-managers.md new file mode 100644 index 0000000000..ce9e6be98b --- /dev/null +++ b/content/en/docs/concepts/policy/node-resource-managers.md @@ -0,0 +1,22 @@ +--- +reviewers: +- derekwaynecarr +- klueska +title: Node Resource Managers +content_type: concept +weight: 50 +--- + + + +In order to support latency-critical and high-throughput workloads, Kubernetes offers a suite of Resource Managers. The managers aim to co-ordinate and optimise node's resources alignment for pods configured with a specific requirement for CPUs, devices, and memory (hugepages) resources. + + + +The main manager, the Topology Manager, is a Kubelet component that co-ordinates the overall resource management process through its [policy](/docs/tasks/administer-cluster/topology-manager/). + +The configuration of individual managers is elaborated in dedicated documents: + +- [CPU Manager Policies](/docs/tasks/administer-cluster/cpu-management-policies/) +- [Device Manager](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-integration-with-the-topology-manager) +- [Memory Manger Policies](/docs/tasks/administer-cluster/memory-manager/) \ No newline at end of file diff --git a/content/en/docs/concepts/policy/pod-security-policy.md b/content/en/docs/concepts/policy/pod-security-policy.md index f355a8f539..f0884c3dea 100644 --- a/content/en/docs/concepts/policy/pod-security-policy.md +++ b/content/en/docs/concepts/policy/pod-security-policy.md @@ -9,7 +9,9 @@ weight: 30 -{{< feature-state state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="deprecated" >}} + +PodSecurityPolicy is deprecated as of Kubernetes v1.21, and will be removed in v1.25. Pod Security Policies enable fine-grained authorization of pod creation and updates. diff --git a/content/en/docs/concepts/policy/resource-quotas.md b/content/en/docs/concepts/policy/resource-quotas.md index bc5eca8754..1d0e9d4ecd 100644 --- a/content/en/docs/concepts/policy/resource-quotas.md +++ b/content/en/docs/concepts/policy/resource-quotas.md @@ -124,6 +124,10 @@ In release 1.8, quota support for local ephemeral storage is added as an alpha f | `limits.ephemeral-storage` | Across all pods in the namespace, the sum of local ephemeral storage limits cannot exceed this value. | | `ephemeral-storage` | Same as `requests.ephemeral-storage`. | +{{< note >}} +When using a CRI container runtime, container logs will count against the ephemeral storage quota. This can result in the unexpected eviction of pods that have exhausted their storage quotas. Refer to [Logging Architecture](/docs/concepts/cluster-administration/logging/) for details. +{{< /note >}} + ## Object Count Quota You can set quota for the total number of certain resources of all standard, @@ -189,6 +193,7 @@ Resources specified on the quota outside of the allowed set results in a validat | `BestEffort` | Match pods that have best effort quality of service. | | `NotBestEffort` | Match pods that do not have best effort quality of service. | | `PriorityClass` | Match pods that references the specified [priority class](/docs/concepts/configuration/pod-priority-preemption). | +| `CrossNamespacePodAffinity` | Match pods that have cross-namespace pod [(anti)affinity terms](/docs/concepts/scheduling-eviction/assign-pod-node). | The `BestEffort` scope restricts a quota to tracking the following resource: @@ -429,6 +434,63 @@ memory 0 20Gi pods 0 10 ``` +### Cross-namespace Pod Affinity Quota + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +Operators can use `CrossNamespacePodAffinity` quota scope to limit which namespaces are allowed to +have pods with affinity terms that cross namespaces. Specifically, it controls which pods are allowed +to set `namespaces` or `namespaceSelector` fields in pod affinity terms. + +Preventing users from using cross-namespace affinity terms might be desired since a pod +with anti-affinity constraints can block pods from all other namespaces +from getting scheduled in a failure domain. + +Using this scope operators can prevent certain namespaces (`foo-ns` in the example below) +from having pods that use cross-namespace pod affinity by creating a resource quota object in +that namespace with `CrossNamespaceAffinity` scope and hard limit of 0: + +```yaml +apiVersion: v1 +kind: ResourceQuota +metadata: + name: disable-cross-namespace-affinity + namespace: foo-ns +spec: + hard: + pods: "0" + scopeSelector: + matchExpressions: + - scopeName: CrossNamespaceAffinity +``` + +If operators want to disallow using `namespaces` and `namespaceSelector` by default, and +only allow it for specific namespaces, they could configure `CrossNamespaceAffinity` +as a limited resource by setting the kube-apiserver flag --admission-control-config-file +to the path of the following configuration file: + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: AdmissionConfiguration +plugins: +- name: "ResourceQuota" + configuration: + apiVersion: apiserver.config.k8s.io/v1 + kind: ResourceQuotaConfiguration + limitedResources: + - resource: pods + matchScopes: + - scopeName: CrossNamespaceAffinity +``` + +With the above configuration, pods can use `namespaces` and `namespaceSelector` in pod affinity only +if the namespace where they are created have a resource quota object with +`CrossNamespaceAffinity` scope and a hard limit greater than or equal to the number of pods using those fields. + +This feature is alpha and disabled by default. You can enable it by setting the +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +`PodAffinityNamespaceSelector` in both kube-apiserver and kube-scheduler. + ## Requests compared to Limits {#requests-vs-limits} When allocating compute resources, each container may specify a request and a limit value for either CPU or memory. diff --git a/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md b/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md index c2c332afb0..88ca9e8128 100644 --- a/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md +++ b/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md @@ -270,6 +270,18 @@ If omitted or empty, it defaults to the namespace of the pod where the affinity/ All `matchExpressions` associated with `requiredDuringSchedulingIgnoredDuringExecution` affinity and anti-affinity must be satisfied for the pod to be scheduled onto a node. +#### Namespace selector +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +Users can also select matching namespaces using `namespaceSelector`, which is a label query over the set of namespaces. +The affinity term is applied to the union of the namespaces selected by `namespaceSelector` and the ones listed in the `namespaces` field. +Note that an empty `namespaceSelector` ({}) matches all namespaces, while a null or empty `namespaces` list and +null `namespaceSelector` means "this pod's namespace". + +This feature is alpha and disabled by default. You can enable it by setting the +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +`PodAffinityNamespaceSelector` in both kube-apiserver and kube-scheduler. + #### More Practical Use-cases Interpod Affinity and AntiAffinity can be even more useful when they are used with higher diff --git a/content/en/docs/concepts/services-networking/dual-stack.md b/content/en/docs/concepts/services-networking/dual-stack.md index 20cbcb5f33..a85226beed 100644 --- a/content/en/docs/concepts/services-networking/dual-stack.md +++ b/content/en/docs/concepts/services-networking/dual-stack.md @@ -16,11 +16,11 @@ weight: 70 -{{< feature-state for_k8s_version="v1.16" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} - IPv4/IPv6 dual-stack enables the allocation of both IPv4 and IPv6 addresses to {{< glossary_tooltip text="Pods" term_id="pod" >}} and {{< glossary_tooltip text="Services" term_id="service" >}}. +IPv4/IPv6 dual-stack networking enables the allocation of both IPv4 and IPv6 addresses to {{< glossary_tooltip text="Pods" term_id="pod" >}} and {{< glossary_tooltip text="Services" term_id="service" >}}. -If you enable IPv4/IPv6 dual-stack networking for your Kubernetes cluster, the cluster will support the simultaneous assignment of both IPv4 and IPv6 addresses. +IPv4/IPv6 dual-stack networking is enabled by default for your Kubernetes cluster starting in 1.21, allowing the simultaneous assignment of both IPv4 and IPv6 addresses. @@ -28,7 +28,7 @@ If you enable IPv4/IPv6 dual-stack networking for your Kubernetes cluster, the c ## Supported Features -Enabling IPv4/IPv6 dual-stack on your Kubernetes cluster provides the following features: +IPv4/IPv6 dual-stack on your Kubernetes cluster provides the following features: * Dual-stack Pod networking (a single IPv4 and IPv6 address assignment per Pod) * IPv4 and IPv6 enabled Services @@ -45,34 +45,34 @@ The following prerequisites are needed in order to utilize IPv4/IPv6 dual-stack * Provider support for dual-stack networking (Cloud provider or otherwise must be able to provide Kubernetes nodes with routable IPv4/IPv6 network interfaces) * A network plugin that supports dual-stack (such as Kubenet or Calico) -## Enable IPv4/IPv6 dual-stack +## Configure IPv4/IPv6 dual-stack -To enable IPv4/IPv6 dual-stack, enable the `IPv6DualStack` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for the relevant components of your cluster, and set dual-stack cluster network assignments: +To use IPv4/IPv6 dual-stack, ensure the `IPv6DualStack` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled for the relevant components of your cluster. (Starting in 1.21, IPv4/IPv6 dual-stack defaults to enabled.) + +To configure IPv4/IPv6 dual-stack, set dual-stack cluster network assignments: * kube-apiserver: - * `--feature-gates="IPv6DualStack=true"` * `--service-cluster-ip-range=,` * kube-controller-manager: - * `--feature-gates="IPv6DualStack=true"` * `--cluster-cidr=,` * `--service-cluster-ip-range=,` * `--node-cidr-mask-size-ipv4|--node-cidr-mask-size-ipv6` defaults to /24 for IPv4 and /64 for IPv6 - * kubelet: - * `--feature-gates="IPv6DualStack=true"` * kube-proxy: * `--cluster-cidr=,` - * `--feature-gates="IPv6DualStack=true"` {{< note >}} An example of an IPv4 CIDR: `10.244.0.0/16` (though you would supply your own address range) An example of an IPv6 CIDR: `fdXY:IJKL:MNOP:15::/64` (this shows the format but is not a valid address - see [RFC 4193](https://tools.ietf.org/html/rfc4193)) +Starting in 1.21, IPv4/IPv6 dual-stack defaults to enabled. +You can disable it when necessary by specifying `--feature-gates="IPv6DualStack=false"` +on the kube-apiserver, kube-controller-manager, kubelet, and kube-proxy command line. {{< /note >}} ## Services -If your cluster has dual-stack enabled, you can create {{< glossary_tooltip text="Services" term_id="service" >}} which can use IPv4, IPv6, or both. +You can create {{< glossary_tooltip text="Services" term_id="service" >}} which can use IPv4, IPv6, or both. The address family of a Service defaults to the address family of the first service cluster IP range (configured via the `--service-cluster-ip-range` flag to the kube-apiserver). @@ -81,11 +81,9 @@ set the `.spec.ipFamilyPolicy` field to one of the following values: * `SingleStack`: Single-stack service. The control plane allocates a cluster IP for the Service, using the first configured service cluster IP range. * `PreferDualStack`: - * Only used if the cluster has dual-stack enabled. Allocates IPv4 and IPv6 cluster IPs for the Service - * If the cluster does not have dual-stack enabled, this setting follows the same behavior as `SingleStack`. + * Allocates IPv4 and IPv6 cluster IPs for the Service. (If the cluster has `--feature-gates="IPv6DualStack=false"`, this setting follows the same behavior as `SingleStack`.) * `RequireDualStack`: Allocates Service `.spec.ClusterIPs` from both IPv4 and IPv6 address ranges. * Selects the `.spec.ClusterIP` from the list of `.spec.ClusterIPs` based on the address family of the first element in the `.spec.ipFamilies` array. - * The cluster must have dual-stack networking configured. If you would like to define which IP family to use for single stack or define the order of IP families for dual-stack, you can choose the address families by setting an optional field, `.spec.ipFamilies`, on the Service. @@ -126,7 +124,7 @@ These examples demonstrate the behavior of various dual-stack Service configurat #### Dual-stack defaults on existing Services -These examples demonstrate the default behavior when dual-stack is newly enabled on a cluster where Services already exist. +These examples demonstrate the default behavior when dual-stack is newly enabled on a cluster where Services already exist. (Upgrading an existing cluster to 1.21 will enable dual-stack unless `--feature-gates="IPv6DualStack=false"` is set.) 1. When dual-stack is enabled on a cluster, existing Services (whether `IPv4` or `IPv6`) are configured by the control plane to set `.spec.ipFamilyPolicy` to `SingleStack` and set `.spec.ipFamilies` to the address family of the existing Service. The existing Service cluster IP will be stored in `.spec.ClusterIPs`. @@ -242,3 +240,5 @@ Ensure your {{< glossary_tooltip text="CNI" term_id="cni" >}} provider supports * [Validate IPv4/IPv6 dual-stack](/docs/tasks/network/validate-dual-stack) networking +* [Enable dual-stack networking using kubeadm +](/docs/setup/production-environment/tools/kubeadm/dual-stack-support/) diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md index 6abf1f6ed1..fdcbd0ed50 100644 --- a/content/en/docs/concepts/services-networking/endpoint-slices.md +++ b/content/en/docs/concepts/services-networking/endpoint-slices.md @@ -3,13 +3,13 @@ reviewers: - freehan title: EndpointSlices content_type: concept -weight: 35 +weight: 45 --- -{{< feature-state for_k8s_version="v1.17" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} _EndpointSlices_ provide a simple way to track network endpoints within a Kubernetes cluster. They offer a more scalable and extensible alternative to @@ -52,7 +52,7 @@ As an example, here's a sample EndpointSlice resource for the `example` Kubernetes Service. ```yaml -apiVersion: discovery.k8s.io/v1beta1 +apiVersion: discovery.k8s.io/v1 kind: EndpointSlice metadata: name: example-abc @@ -69,9 +69,8 @@ endpoints: conditions: ready: true hostname: pod-1 - topology: - kubernetes.io/hostname: node-1 - topology.kubernetes.io/zone: us-west2-a + nodeName: node-1 + zone: us-west2-a ``` By default, the control plane creates and manages EndpointSlices to have no @@ -135,30 +134,26 @@ For pods, this is any pod that has a deletion timestamp set. ### Topology information {#topology} -{{< feature-state for_k8s_version="v1.20" state="deprecated" >}} +Each endpoint within an EndpointSlice can contain relevant topology information. +The topology information includes the location of the endpoint and information +about the corresponding Node and zone. These are available in the following +per endpoint fields on EndpointSlices: + +* `nodeName` - The name of the Node this endpoint is on. +* `zone` - The zone this endpoint is in. {{< note >}} -The topology field in EndpointSlices has been deprecated and will be removed in -a future release. A new `nodeName` field will be used instead of setting -`kubernetes.io/hostname` in topology. It was determined that other topology -fields covering zone and region would be better represented as EndpointSlice -labels that would apply to all endpoints within the EndpointSlice. +In the v1 API, the per endpoint `topology` was effectively removed in favor of +the dedicated fields `nodeName` and `zone`. + +Setting arbitrary topology fields on the `endpoint` field of an `EndpointSlice` +resource has been deprecated and is not be supported in the v1 API. Instead, +the v1 API supports setting individual `nodeName` and `zone` fields. These +fields are automatically translated between API versions. For example, the +value of the `"topology.kubernetes.io/zone"` key in the `topology` field in +the v1beta1 API is accessible as the `zone` field in the v1 API. {{< /note >}} -Each endpoint within an EndpointSlice can contain relevant topology information. -This is used to indicate where an endpoint is, containing information about the -corresponding Node, zone, and region. When the values are available, the -control plane sets the following Topology labels for EndpointSlices: - -* `kubernetes.io/hostname` - The name of the Node this endpoint is on. -* `topology.kubernetes.io/zone` - The zone this endpoint is in. -* `topology.kubernetes.io/region` - The region this endpoint is in. - -The values of these labels are derived from resources associated with each -endpoint in a slice. The hostname label represents the value of the NodeName -field on the corresponding Pod. The zone and region labels represent the value -of the labels with the same names on the corresponding Node. - ### Management Most often, the control plane (specifically, the endpoint slice diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md index b6be91cb9a..e41b629f20 100644 --- a/content/en/docs/concepts/services-networking/ingress.md +++ b/content/en/docs/concepts/services-networking/ingress.md @@ -220,7 +220,19 @@ of the controller that should implement the class. {{< codenew file="service/networking/external-lb.yaml" >}} IngressClass resources contain an optional parameters field. This can be used to -reference additional configuration for this class. +reference additional implementation-specific configuration for this class. + +#### Namespace-scoped parameters + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +`Parameters` field has a `scope` and `namespace` field that can be used to +reference a namespace-specific resource for configuration of an Ingress class. +`Scope` field defaults to `Cluster`, meaning, the default is cluster-scoped +resource. Setting `Scope` to `Namespace` and setting the `Namespace` field +will reference a paramters resource in a specific namespace: + +{{< codenew file="service/networking/namespaced-params.yaml" >}} ### Deprecated annotation diff --git a/content/en/docs/concepts/services-networking/network-policies.md b/content/en/docs/concepts/services-networking/network-policies.md index 2000d838b4..764fedbcc7 100644 --- a/content/en/docs/concepts/services-networking/network-policies.md +++ b/content/en/docs/concepts/services-networking/network-policies.md @@ -221,18 +221,72 @@ When the feature gate is enabled, you can set the `protocol` field of a NetworkP You must be using a {{< glossary_tooltip text="CNI" term_id="cni" >}} plugin that supports SCTP protocol NetworkPolicies. {{< /note >}} +## Targeting a range of Ports + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +When writing a NetworkPolicy, you can target a range of ports instead of a single port. + +This is achievable with the usage of the `endPort` field, as the following example: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: multi-port-egress + namespace: default +spec: + podSelector: + matchLabels: + role: db + policyTypes: + - Egress + egress: + - to: + - ipBlock: + cidr: 10.0.0.0/24 + ports: + - protocol: TCP + port: 32000 + endPort: 32768 +``` + +The above rule allows any Pod with label `db` on the namespace `default` to communicate with any IP within the range `10.0.0.0/24` over TCP, provided that the target port is between the range 32000 and 32768. + +The following restrictions apply when using this field: +* As an alpha feature, this is disabled by default. To enable the `endPort` field at a cluster level, you (or your cluster administrator) need to enable the `NetworkPolicyEndPort` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for the API server with `--feature-gates=NetworkPolicyEndPort=true,…`. +* The `endPort` field must be equal than or greater to the `port` field. +* `endPort` can only be defined if `port` is also defined. +* Both ports must be numeric. + +{{< note >}} +Your cluster must be using a {{< glossary_tooltip text="CNI" term_id="cni" >}} plugin that +supports the `endPort` field in NetworkPolicy specifications. +{{< /note >}} + +## Targeting a Namespace by its name + +{{< feature-state state="beta" for_k8s_version="1.21" >}} + +The Kubernetes control plane sets an immutable label `kubernetes.io/metadata.name` on all +namespaces, provided that the `NamespaceDefaultLabelName` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled. +The value of the label is the namespace name. + +While NetworkPolicy cannot target a namespace by its name with some object field, you can use the +standardized label to target a specific namespace. + ## What you can't do with network policies (at least, not yet) -As of Kubernetes 1.20, the following functionality does not exist in the NetworkPolicy API, but you might be able to implement workarounds using Operating System components (such as SELinux, OpenVSwitch, IPTables, and so on) or Layer 7 technologies (Ingress controllers, Service Mesh implementations) or admission controllers. In case you are new to network security in Kubernetes, its worth noting that the following User Stories cannot (yet) be implemented using the NetworkPolicy API. Some (but not all) of these user stories are actively being discussed for future releases of the NetworkPolicy API. +As of Kubernetes {{< skew latestVersion >}}, the following functionality does not exist in the NetworkPolicy API, but you might be able to implement workarounds using Operating System components (such as SELinux, OpenVSwitch, IPTables, and so on) or Layer 7 technologies (Ingress controllers, Service Mesh implementations) or admission controllers. In case you are new to network security in Kubernetes, its worth noting that the following User Stories cannot (yet) be implemented using the NetworkPolicy API. - Forcing internal cluster traffic to go through a common gateway (this might be best served with a service mesh or other proxy). - Anything TLS related (use a service mesh or ingress controller for this). - Node specific policies (you can use CIDR notation for these, but you cannot target nodes by their Kubernetes identities specifically). -- Targeting of namespaces or services by name (you can, however, target pods or namespaces by their {{< glossary_tooltip text="labels" term_id="label" >}}, which is often a viable workaround). +- Targeting of services by name (you can, however, target pods or namespaces by their {{< glossary_tooltip text="labels" term_id="label" >}}, which is often a viable workaround). - Creation or management of "Policy requests" that are fulfilled by a third party. - Default policies which are applied to all namespaces or pods (there are some third party Kubernetes distributions and projects which can do this). - Advanced policy querying and reachability tooling. -- The ability to target ranges of Ports in a single policy declaration. - The ability to log network security events (for example connections that are blocked or accepted). - The ability to explicitly deny policies (currently the model for NetworkPolicies are deny by default, with only the ability to add allow rules). - The ability to prevent loopback or incoming host traffic (Pods cannot currently block localhost access, nor do they have the ability to block access from their resident node). diff --git a/content/en/docs/concepts/services-networking/service-topology.md b/content/en/docs/concepts/services-networking/service-topology.md index 66976b23fb..e906dff81d 100644 --- a/content/en/docs/concepts/services-networking/service-topology.md +++ b/content/en/docs/concepts/services-networking/service-topology.md @@ -2,12 +2,7 @@ reviewers: - johnbelamaric - imroc -title: Service Topology -feature: - title: Service Topology - description: > - Routing of service traffic based upon cluster topology. - +title: Topology-aware traffic routing with topology keys content_type: concept weight: 10 --- @@ -15,7 +10,16 @@ weight: 10 -{{< feature-state for_k8s_version="v1.17" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="deprecated" >}} + +{{< note >}} + +This feature, specifically the alpha `topologyKeys` API, is deprecated since +Kubernetes v1.21. +[Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), +introduced in Kubernetes v1.21, provide similar functionality. + +{{}} _Service Topology_ enables a service to route traffic based upon the Node topology of the cluster. For example, a service can specify that traffic be @@ -23,33 +27,32 @@ preferentially routed to endpoints that are on the same Node as the client, or in the same availability zone. - -## Introduction +## Topology-aware traffic routing By default, traffic sent to a `ClusterIP` or `NodePort` Service may be routed to -any backend address for the Service. Since Kubernetes 1.7 it has been possible -to route "external" traffic to the Pods running on the Node that received the -traffic, but this is not supported for `ClusterIP` Services, and more complex -topologies — such as routing zonally — have not been possible. The -_Service Topology_ feature resolves this by allowing the Service creator to -define a policy for routing traffic based upon the Node labels for the -originating and destination Nodes. - -By using Node label matching between the source and destination, the operator -may designate groups of Nodes that are "closer" and "farther" from one another, -using whatever metric makes sense for that operator's requirements. For many -operators in public clouds, for example, there is a preference to keep service -traffic within the same zone, because interzonal traffic has a cost associated -with it, while intrazonal traffic does not. Other common needs include being able -to route traffic to a local Pod managed by a DaemonSet, or keeping traffic to -Nodes connected to the same top-of-rack switch for the lowest latency. +any backend address for the Service. Kubernetes 1.7 made it possible to +route "external" traffic to the Pods running on the same Node that received the +traffic. For `ClusterIP` Services, the equivalent same-node preference for +routing wasn't possible; nor could you configure your cluster to favor routing +to endpoints within the same zone. +By setting `topologyKeys` on a Service, you're able to define a policy for routing +traffic based upon the Node labels for the originating and destination Nodes. +The label matching between the source and destination lets you, as a cluster +operator, designate sets of Nodes that are "closer" and "farther" from one another. +You can define labels to represent whatever metric makes sense for your own +requirements. +In public clouds, for example, you might prefer to keep network traffic within the +same zone, because interzonal traffic has a cost associated with it (and intrazonal +traffic typically does not). Other common needs include being able to route traffic +to a local Pod managed by a DaemonSet, or directing traffic to Nodes connected to the +same top-of-rack switch for the lowest latency. ## Using Service Topology -If your cluster has Service Topology enabled, you can control Service traffic +If your cluster has the `ServiceTopology` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled, you can control Service traffic routing by specifying the `topologyKeys` field on the Service spec. This field is a preference-order list of Node labels which will be used to sort endpoints when accessing this Service. Traffic will be directed to a Node whose value for @@ -200,4 +203,3 @@ spec: * Read about [enabling Service Topology](/docs/tasks/administer-cluster/enabling-service-topology) * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) - diff --git a/content/en/docs/concepts/services-networking/service-traffic-policy.md b/content/en/docs/concepts/services-networking/service-traffic-policy.md new file mode 100644 index 0000000000..fb55a3d833 --- /dev/null +++ b/content/en/docs/concepts/services-networking/service-traffic-policy.md @@ -0,0 +1,73 @@ +--- +reviewers: +- maplain +title: Service Internal Traffic Policy +content_type: concept +weight: 45 +--- + + + + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +_Service Internal Traffic Policy_ enables internal traffic restrictions to only route +internal traffic to endpoints within the node the traffic originated from. The +"internal" traffic here refers to traffic originated from Pods in the current +cluster. This can help to reduce costs and improve performance. + + + +## Using Service Internal Traffic Policy + +Once you have enabled the `ServiceInternalTrafficPolicy` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/), +you can enable an internal-only traffic policy for a +{{< glossary_tooltip text="Services" term_id="service" >}}, by setting its +`.spec.internalTrafficPolicy` to `Local`. +This tells kube-proxy to only use node local endpoints for cluster internal traffic. + +{{< note >}} +For pods on nodes with no endpoints for a given Service, the Service +behaves as if it has zero endpoints (for Pods on this node) even if the service +does have endpoints on other nodes. +{{< /note >}} + +The following example shows what a Service looks like when you set +`.spec.internalTrafficPolicy` to `Local`: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: my-service +spec: + selector: + app: MyApp + ports: + - protocol: TCP + port: 80 + targetPort: 9376 + internalTrafficPolicy: Local +``` + +## How it works + +The kube-proxy filters the endpoints it routes to based on the +`spec.internalTrafficPolicy` setting. When it's set to `Local`, only node local +endpoints are considered. When it's `Cluster` or missing, all endpoints are +considered. +When the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +`ServiceInternalTrafficPolicy` is enabled, `spec.internalTrafficPolicy` defaults to "Cluster". + +## Constraints + +* Service Internal Traffic Policy is not used when `externalTrafficPolicy` is set + to `Local` on a Service. It is possible to use both features in the same cluster + on different Services, just not on the same Service. + +## {{% heading "whatsnext" %}} + +* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints) +* Read about [Service External Traffic Policy](/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) +* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index d6f451bc85..d057f05533 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -187,9 +187,14 @@ An ExternalName Service is a special case of Service that does not have selectors and uses DNS names instead. For more information, see the [ExternalName](#externalname) section later in this document. +### Over Capacity Endpoints +If an Endpoints resource has more than 1000 endpoints then a Kubernetes v1.21 (or later) +cluster annotates that Endpoints with `endpoints.kubernetes.io/over-capacity: warning`. +This annotation indicates that the affected Endpoints object is over capacity. + ### EndpointSlices -{{< feature-state for_k8s_version="v1.17" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} EndpointSlices are an API resource that can provide a more scalable alternative to Endpoints. Although conceptually quite similar to Endpoints, EndpointSlices @@ -635,6 +640,25 @@ is set to `false` on an existing Service with allocated node ports, those node p You must explicitly remove the `nodePorts` entry in every Service port to de-allocate those node ports. You must enable the `ServiceLBNodePortControl` feature gate to use this field. +#### Specifying class of load balancer implementation {#load-balancer-class} + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +Starting in v1.21, you can optionally specify the class of a load balancer implementation for +`LoadBalancer` type of Service by setting the field `spec.loadBalancerClass`. +By default, `spec.loadBalancerClass` is `nil` and a `LoadBalancer` type of Service uses +the cloud provider's default load balancer implementation. +If `spec.loadBalancerClass` is specified, it is assumed that a load balancer +implementation that matches the specified class is watching for Services. +Any default load balancer implementation (for example, the one provided by +the cloud provider) will ignore Services that have this field set. +`spec.loadBalancerClass` can be set on a Service of type `LoadBalancer` only. +Once set, it cannot be changed. +The value of `spec.loadBalancerClass` must be a label-style identifier, +with an optional prefix such as "`internal-vip`" or "`example.com/internal-vip`". +Unprefixed names are reserved for end-users. +You must enable the `ServiceLoadBalancerClass` feature gate to use this field. + #### Internal load balancer In a mixed environment it is sometimes necessary to route traffic from Services inside the same diff --git a/content/en/docs/concepts/services-networking/topology-aware-hints.md b/content/en/docs/concepts/services-networking/topology-aware-hints.md new file mode 100644 index 0000000000..c2c15878ff --- /dev/null +++ b/content/en/docs/concepts/services-networking/topology-aware-hints.md @@ -0,0 +1,160 @@ +--- +reviewers: +- robscott +title: Topology Aware Hints +content_type: concept +weight: 45 +--- + + + + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +_Topology Aware Hints_ enable topology aware routing by including suggestions +for how clients should consume endpoints. This approach adds metadata to enable +consumers of EndpointSlice and / or and Endpoints objects, so that traffic to +those network endpoints can be routed closer to where it originated. + +For example, you can route traffic within a locality to reduce +costs, or to improve network performance. + + + +## Motivation + +Kubernetes clusters are increasingly deployed in multi-zone environments. +_Topology Aware Hints_ provides a mechanism to help keep traffic within the zone +it originated from. This concept is commonly referred to as "Topology Aware +Routing". When calculating the endpoints for a {{< glossary_tooltip term_id="Service" >}}, +the EndpointSlice controller considers the topology (region and zone) of each endpoint +and populates the hints field to allocate it to a zone. +Cluster components such as the {{< glossary_tooltip term_id="kube-proxy" text="kube-proxy" >}} +can then consume those hints, and use them to influence how traffic to is routed +(favoring topologically closer endpoints). + +## Using Topology Aware Hints + +If you have [enabled](/docs/tasks/administer-cluster/enabling-topology-aware-hints) the +overall feature, you can activate Topology Aware Hints for a Service by setting the +`service.kubernetes.io/topology-aware-hints` annotation to `auto`. This tells +the EndpointSlice controller to set topology hints if it is deemed safe. +Importantly, this does not guarantee that hints will always be set. + +## How it works {#implementation} + +The functionality enabling this feature is split into two components: The +EndpointSlice controller and the kube-proxy. This section provides a high level overview +of how each component implements this feature. + +### EndpointSlice controller {#implementation-control-plane} + +The EndpointSlice controller is responsible for setting hints on EndpointSlices +when this feature is enabled. The controller allocates a proportional amount of +endpoints to each zone. This proportion is based on the +[allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) +CPU cores for nodes running in that zone. For example, if one zone had 2 CPU +cores and another zone only had 1 CPU core, the controller would allocated twice +as many endpoints to the zone with 2 CPU cores. + +The following example shows what an EndpointSlice looks like when hints have +been populated: + +```yaml +apiVersion: discovery.k8s.io/v1 +kind: EndpointSlice +metadata: + name: example-hints + labels: + kubernetes.io/service-name: example-svc +addressType: IPv4 +ports: + - name: http + protocol: TCP + port: 80 +endpoints: + - addresses: + - "10.1.2.3" + conditions: + ready: true + hostname: pod-1 + zone: zone-a + hints: + forZones: + - name: "zone-a" +``` + +### kube-proxy {#implementation-kube-proxy} + +The kube-proxy component filters the endpoints it routes to based on the hints set by +the EndpointSlice controller. In most cases, this means that the kube-proxy is able +to route traffic to endpoints in the same zone. Sometimes the controller allocates endpoints +from a different zone to ensure more even distribution of endpoints between zones. +This would result in some traffic being routed to other zones. + +## Safeguards + +The Kubernetes control plane and the kube-proxy on each node apply some +safeguard rules before using Topology Aware Hints. If these don't check out, +the kube-proxy selects endpoints from anywhere in your cluster, regardless of the +zone. + +1. **Insufficient number of endpoints:** If there are less endpoints than zones + in a cluster, the controller will not assign any hints. + +2. **Impossible to achieve balanced allocation:** In some cases, it will be + impossible to achieve a balanced allocation of endpoints among zones. For + example, if zone-a is twice as large as zone-b, but there are only 2 + endpoints, an endpoint allocated to zone-a may receive twice as much traffic + as zone-b. The controller does not assign hints if it can't get this "expected + overload" value below an acceptable threshold for each zone. Importantly this + is not based on real-time feedback. It is still possible for individual + endpoints to become overloaded. + +3. **One or more Nodes has insufficient information:** If any node does not have + a `topology.kubernetes.io/zone` label or is not reporting a value for + allocatable CPU, the control plane does not set any topology-aware endpoint + hints and so kube-proxy does not filter endpoints by zone. + +4. **One or more endpoints does not have a zone hint:** When this happens, + the kube-proxy assumes that a transition from or to Topology Aware Hints is + underway. Filtering endpoints for a Service in this state would be dangerous + so the kube-proxy falls back to using all endpoints. + +5. **A zone is not represented in hints:** If the kube-proxy is unable to find + at least one endpoint with a hint targeting the zone it is running in, it falls + to using endpoints from all zones. This is most likely to happen as you add + a new zone into your existing cluster. + +## Constraints + +* Topology Aware Hints are not used when either `externalTrafficPolicy` or + `internalTrafficPolicy` is set to `Local` on a Service. It is possible to use + both features in the same cluster on different Services, just not on the same + Service. + +* This approach will not work well for Services that have a large proportion of + traffic originating from a subset of zones. Instead this assumes that incoming + traffic will be roughly proportional to the capacity of the Nodes in each + zone. + +* The EndpointSlice controller ignores unready nodes as it calculates the + proportions of each zone. This could have unintended consequences if a large + portion of nodes are unready. + +* The EndpointSlice controller does not take into account {{< glossary_tooltip + text="tolerations" term_id="toleration" >}} when deploying calculating the + proportions of each zone. If the Pods backing a Service are limited to a + subset of Nodes in the cluster, this will not be taken into account. + +* This may not work well with autoscaling. For example, if a lot of traffic is + originating from a single zone, only the endpoints allocated to that zone will + be handling that traffic. That could result in {{< glossary_tooltip + text="Horizontal Pod Autoscaler" term_id="horizontal-pod-autoscaler" >}} + either not picking up on this event, or newly added pods starting in a + different zone. + +## {{% heading "whatsnext" %}} + +* Read about [enabling Topology Aware Hints](/docs/tasks/administer-cluster/enabling-topology-aware-hints/) +* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) diff --git a/content/en/docs/concepts/storage/ephemeral-volumes.md b/content/en/docs/concepts/storage/ephemeral-volumes.md index bc391a3f36..dc715d7c46 100644 --- a/content/en/docs/concepts/storage/ephemeral-volumes.md +++ b/content/en/docs/concepts/storage/ephemeral-volumes.md @@ -131,12 +131,15 @@ As a cluster administrator, you can use a [PodSecurityPolicy](/docs/concepts/pol ### Generic ephemeral volumes {{< feature-state for_k8s_version="v1.19" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} This feature requires the `GenericEphemeralVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be -enabled. Because this is an alpha feature, it is disabled by default. +enabled. Because this is a beta feature, it is enabled by default. -Generic ephemeral volumes are similar to `emptyDir` volumes, except more -flexible: +Generic ephemeral volumes are similar to `emptyDir` volumes in the +sense that they provide a per-pod directory for scratch data that is +usually empty after provisioning. But they may also have additional +features: - Storage can be local or network-attached. - Volumes can have a fixed size that Pods are not able to exceed. @@ -243,14 +246,16 @@ PVCs indirectly if they can create Pods, even if they do not have permission to create PVCs directly. Cluster administrators must be aware of this. If this does not fit their security model, they have two choices: -- Explicitly disable the feature through the feature gate, to avoid - being surprised when some future Kubernetes version enables it - by default. +- Explicitly disable the feature through the feature gate. - Use a [Pod Security Policy](/docs/concepts/policy/pod-security-policy/) where the - `volumes` list does not contain the `ephemeral` volume type. + `volumes` list does not contain the `ephemeral` volume type + (deprecated in Kubernetes 1.21). +- Use an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) + which rejects objects like Pods that have a generic ephemeral + volume. -The normal namespace quota for PVCs in a namespace still applies, so +The normal [namespace quota for PVCs](/docs/concepts/policy/resource-quotas/#storage-resource-quota) still applies, so even if users are allowed to use this new mechanism, they cannot use it to circumvent other policies. diff --git a/content/en/docs/concepts/storage/storage-capacity.md b/content/en/docs/concepts/storage/storage-capacity.md index d5993d4f59..13ae8ab722 100644 --- a/content/en/docs/concepts/storage/storage-capacity.md +++ b/content/en/docs/concepts/storage/storage-capacity.md @@ -17,6 +17,7 @@ which a pod runs: network-attached storage might not be accessible by all nodes, or storage is local to a node to begin with. {{< feature-state for_k8s_version="v1.19" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} This page describes how Kubernetes keeps track of storage capacity and how the scheduler uses that information to schedule Pods onto nodes @@ -103,34 +104,10 @@ to handle this automatically. ## Enabling storage capacity tracking -Storage capacity tracking is an *alpha feature* and only enabled when -the `CSIStorageCapacity` [feature -gate](/docs/reference/command-line-tools-reference/feature-gates/) and -the `storage.k8s.io/v1alpha1` {{< glossary_tooltip text="API group" term_id="api-group" >}} are enabled. For details on -that, see the `--feature-gates` and `--runtime-config` [kube-apiserver -parameters](/docs/reference/command-line-tools-reference/kube-apiserver/). - -A quick check -whether a Kubernetes cluster supports the feature is to list -CSIStorageCapacity objects with: -```shell -kubectl get csistoragecapacities --all-namespaces -``` - -If your cluster supports CSIStorageCapacity, the response is either a list of CSIStorageCapacity objects or: -``` -No resources found -``` - -If not supported, this error is printed instead: -``` -error: the server doesn't have a resource type "csistoragecapacities" -``` - -In addition to enabling the feature in the cluster, a CSI -driver also has to -support it. Please refer to the driver's documentation for -details. +Storage capacity tracking is a beta feature and enabled by default in +a Kubernetes cluster since Kubernetes 1.21. In addition to having the +feature enabled in the cluster, a CSI driver also has to support +it. Please refer to the driver's documentation for details. ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/storage/volume-health-monitoring.md b/content/en/docs/concepts/storage/volume-health-monitoring.md new file mode 100644 index 0000000000..c5fb9c1929 --- /dev/null +++ b/content/en/docs/concepts/storage/volume-health-monitoring.md @@ -0,0 +1,35 @@ +--- +reviewers: +- jsafrane +- saad-ali +- msau42 +- xing-yang +title: Volume Health Monitoring +content_type: concept +--- + + + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +{{< glossary_tooltip text="CSI" term_id="csi" >}} volume health monitoring allows CSI Drivers to detect abnormal volume conditions from the underlying storage systems and report them as events on {{< glossary_tooltip text="PVCs" term_id="persistent-volume-claim" >}} or {{< glossary_tooltip text="Pods" term_id="pod" >}}. + + + +## Volume health monitoring + +Kubernetes _volume health monitoring_ is part of how Kubernetes implements the Container Storage Interface (CSI). Volume health monitoring feature is implemented in two components: an External Health Monitor controller, and the {{< glossary_tooltip term_id="kubelet" text="kubelet" >}}. + +If a CSI Driver supports Volume Health Monitoring feature from the controller side, an event will be reported on the related {{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}} (PVC) when an abnormal volume condition is detected on a CSI volume. + +The External Health Monitor {{< glossary_tooltip text="controller" term_id="controller" >}} also watches for node failure events. You can enable node failure monitoring by setting the `enable-node-watcher` flag to true. When the external health monitor detects a node failure event, the controller reports an Event will be reported on the PVC to indicate that pods using this PVC are on a failed node. + +If a CSI Driver supports Volume Health Monitoring feature from the node side, an Event will be reported on every Pod using the PVC when an abnormal volume condition is detected on a CSI volume. + +{{< note >}} +You need to enable the `CSIVolumeHealth` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to use this feature from the node side. +{{< /note >}} + +## {{% heading "whatsnext" %}} + +See the [CSI driver documentation](https://kubernetes-csi.github.io/docs/drivers.html) to find out which CSI drivers have implemented this feature. diff --git a/content/en/docs/concepts/storage/volumes.md b/content/en/docs/concepts/storage/volumes.md index 9743ec34f8..6a7016dd13 100644 --- a/content/en/docs/concepts/storage/volumes.md +++ b/content/en/docs/concepts/storage/volumes.md @@ -153,14 +153,16 @@ For more details, see the [`azureFile` volume plugin](https://github.com/kuberne #### azureFile CSI migration -{{< feature-state for_k8s_version="v1.15" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} The `CSIMigration` feature for `azureFile`, when enabled, redirects all plugin operations from the existing in-tree plugin to the `file.csi.azure.com` Container Storage Interface (CSI) Driver. In order to use this feature, the [Azure File CSI Driver](https://github.com/kubernetes-sigs/azurefile-csi-driver) must be installed on the cluster and the `CSIMigration` and `CSIMigrationAzureFile` -alpha features must be enabled. +[feature gates](/docs/reference/command-line-tools-reference/feature-gates/) must be enabled. + +Azure File CSI driver does not support using same volume with different fsgroups, if Azurefile CSI migration is enabled, using same volume with different fsgroups won't be supported at all. ### cephfs @@ -209,14 +211,17 @@ spec: #### OpenStack CSI migration -{{< feature-state for_k8s_version="v1.18" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} -The `CSIMigration` feature for Cinder, when enabled, redirects all plugin operations -from the existing in-tree plugin to the `cinder.csi.openstack.org` Container -Storage Interface (CSI) Driver. In order to use this feature, the [OpenStack Cinder CSI -Driver](https://github.com/kubernetes/cloud-provider-openstack/blob/master/docs/cinder-csi-plugin/using-cinder-csi-plugin.md) -must be installed on the cluster and the `CSIMigration` and `CSIMigrationOpenStack` -beta features must be enabled. +The `CSIMigration` feature for Cinder is enabled by default in Kubernetes 1.21. +It redirects all plugin operations from the existing in-tree plugin to the +`cinder.csi.openstack.org` Container Storage Interface (CSI) Driver. +[OpenStack Cinder CSI Driver](https://github.com/kubernetes/cloud-provider-openstack/blob/master/docs/cinder-csi-plugin/using-cinder-csi-plugin.md) +must be installed on the cluster. +You can disable Cinder CSI migration for your cluster by setting the `CSIMigrationOpenStack` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to `false`. +If you disable the `CSIMigrationOpenStack` feature, the in-tree Cinder volume plugin takes responsibility +for all aspects of Cinder volume storage management. ### configMap diff --git a/content/en/docs/concepts/workloads/controllers/cron-jobs.md b/content/en/docs/concepts/workloads/controllers/cron-jobs.md index 3624135a20..7127924411 100644 --- a/content/en/docs/concepts/workloads/controllers/cron-jobs.md +++ b/content/en/docs/concepts/workloads/controllers/cron-jobs.md @@ -10,7 +10,7 @@ weight: 80 -{{< feature-state for_k8s_version="v1.8" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} A _CronJob_ creates {{< glossary_tooltip term_id="job" text="Jobs" >}} on a repeating schedule. @@ -116,12 +116,17 @@ be down for the same period as the previous example (`08:29:00` to `10:21:00`,) The CronJob is only responsible for creating Jobs that match its schedule, and the Job in turn is responsible for the management of the Pods it represents. -## New controller +## Controller version {#new-controller} -There's an alternative implementation of the CronJob controller, available as an alpha feature since Kubernetes 1.20. To select version 2 of the CronJob controller, pass the following [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) flag to the {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}}. +Starting with Kubernetes v1.21 the second version of the CronJob controller +is the default implementation. To disable the default CronJob controller +and use the original CronJob controller instead, one pass the `CronJobControllerV2` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +flag to the {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}}, +and set this flag to `false`. For example: ``` ---feature-gates="CronJobControllerV2=true" +--feature-gates="CronJobControllerV2=false" ``` diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md index be4393d891..a23c37ad0d 100644 --- a/content/en/docs/concepts/workloads/controllers/job.md +++ b/content/en/docs/concepts/workloads/controllers/job.md @@ -16,7 +16,8 @@ weight: 50 A Job creates one or more Pods and will continue to retry execution of the Pods until a specified number of them successfully terminate. As pods successfully complete, the Job tracks the successful completions. When a specified number of successful completions is reached, the task (ie, Job) is complete. Deleting a Job will clean up -the Pods it created. +the Pods it created. Suspending a Job will delete its active Pods until the Job +is resumed again. A simple case is to create one Job object in order to reliably run one Pod to completion. The Job object will start a new Pod if the first Pod fails or is deleted (for example @@ -145,8 +146,8 @@ There are three main types of task suitable to run as a Job: - the Job is complete as soon as its Pod terminates successfully. 1. Parallel Jobs with a *fixed completion count*: - specify a non-zero positive value for `.spec.completions`. - - the Job represents the overall task, and is complete when there is one successful Pod for each value in the range 1 to `.spec.completions`. - - **not implemented yet:** Each Pod is passed a different index in the range 1 to `.spec.completions`. + - the Job represents the overall task, and is complete when there are `.spec.completions` successful Pods. + - when using `.spec.completionMode="Indexed"`, each Pod gets a different index in the range 0 to `.spec.completions-1`. 1. Parallel Jobs with a *work queue*: - do not specify `.spec.completions`, default to `.spec.parallelism`. - the Pods must coordinate amongst themselves or an external service to determine what each should work on. For example, a Pod might fetch a batch of up to N items from the work queue. @@ -166,7 +167,6 @@ a non-negative integer. For more information about how to make use of the different types of job, see the [job patterns](#job-patterns) section. - #### Controlling parallelism The requested parallelism (`.spec.parallelism`) can be set to any non-negative value. @@ -185,6 +185,33 @@ parallelism, for a variety of reasons: - The Job controller may throttle new Pod creation due to excessive previous pod failures in the same Job. - When a Pod is gracefully shut down, it takes time to stop. +### Completion mode + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +{{< note >}} +To be able to create Indexed Jobs, make sure to enable the `IndexedJob` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +on the [API server](docs/reference/command-line-tools-reference/kube-apiserver/) +and the [controller manager](/docs/reference/command-line-tools-reference/kube-controller-manager/). +{{< /note >}} + +Jobs with _fixed completion count_ - that is, jobs that have non null +`.spec.completions` - can have a completion mode that is specified in `.spec.completionMode`: + +- `NonIndexed` (default): the Job is considered complete when there have been + `.spec.completions` successfully completed Pods. In other words, each Pod + completion is homologous to each other. Note that Jobs that have null + `.spec.completions` are implicitly `NonIndexed`. +- `Indexed`: the Pods of a Job get an associated completion index from 0 to + `.spec.completions-1`, available in the annotation `batch.kubernetes.io/job-completion-index`. + The Job is considered complete when there is one successfully completed Pod + for each index. For more information about how to use this mode, see + [Indexed Job for Parallel Processing with Static Work Assignment](/docs/tasks/job/indexed-parallel-processing-static/). + Note that, although rare, more than one Pod could be started for the same + index, but only one of them will count towards the completion count. + + ## Handling Pod and container failures A container in a Pod may fail for a number of reasons, such as because the process in it exited with @@ -348,12 +375,12 @@ The tradeoffs are: The tradeoffs are summarized here, with columns 2 to 4 corresponding to the above tradeoffs. The pattern names are also links to examples and more detailed description. -| Pattern | Single Job object | Fewer pods than work items? | Use app unmodified? | Works in Kube 1.1? | -| -------------------------------------------------------------------- |:-----------------:|:---------------------------:|:-------------------:|:-------------------:| -| [Job Template Expansion](/docs/tasks/job/parallel-processing-expansion/) | | | ✓ | ✓ | -| [Queue with Pod Per Work Item](/docs/tasks/job/coarse-parallel-processing-work-queue/) | ✓ | | sometimes | ✓ | -| [Queue with Variable Pod Count](/docs/tasks/job/fine-parallel-processing-work-queue/) | ✓ | ✓ | | ✓ | -| Single Job with Static Work Assignment | ✓ | | ✓ | | +| Pattern | Single Job object | Fewer pods than work items? | Use app unmodified? | +| ----------------------------------------- |:-----------------:|:---------------------------:|:-------------------:| +| [Queue with Pod Per Work Item] | ✓ | | sometimes | +| [Queue with Variable Pod Count] | ✓ | ✓ | | +| [Indexed Job with Static Work Assignment] | ✓ | | ✓ | +| [Job Template Expansion] | | | ✓ | When you specify completions with `.spec.completions`, each Pod created by the Job controller has an identical [`spec`](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status). This means that @@ -364,16 +391,121 @@ are different ways to arrange for pods to work on different things. This table shows the required settings for `.spec.parallelism` and `.spec.completions` for each of the patterns. Here, `W` is the number of work items. -| Pattern | `.spec.completions` | `.spec.parallelism` | -| -------------------------------------------------------------------- |:-------------------:|:--------------------:| -| [Job Template Expansion](/docs/tasks/job/parallel-processing-expansion/) | 1 | should be 1 | -| [Queue with Pod Per Work Item](/docs/tasks/job/coarse-parallel-processing-work-queue/) | W | any | -| [Queue with Variable Pod Count](/docs/tasks/job/fine-parallel-processing-work-queue/) | 1 | any | -| Single Job with Static Work Assignment | W | any | +| Pattern | `.spec.completions` | `.spec.parallelism` | +| ----------------------------------------- |:-------------------:|:--------------------:| +| [Queue with Pod Per Work Item] | W | any | +| [Queue with Variable Pod Count] | null | any | +| [Indexed Job with Static Work Assignment] | W | any | +| [Job Template Expansion] | 1 | should be 1 | +[Queue with Pod Per Work Item]: /docs/tasks/job/coarse-parallel-processing-work-queue/ +[Queue with Variable Pod Count]: /docs/tasks/job/fine-parallel-processing-work-queue/ +[Indexed Job with Static Work Assignment]: /docs/tasks/job/indexed-parallel-processing-static/ +[Job Template Expansion]: /docs/tasks/job/parallel-processing-expansion/ ## Advanced usage +### Suspending a Job + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +{{< note >}} +Suspending Jobs is available in Kubernetes versions 1.21 and above. You must +enable the `SuspendJob` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +on the [API server](docs/reference/command-line-tools-reference/kube-apiserver/) +and the [controller manager](/docs/reference/command-line-tools-reference/kube-controller-manager/) +in order to use this feature. +{{< /note >}} + +When a Job is created, the Job controller will immediately begin creating Pods +to satisfy the Job's requirements and will continue to do so until the Job is +complete. However, you may want to temporarily suspend a Job's execution and +resume it later. To suspend a Job, you can update the `.spec.suspend` field of +the Job to true; later, when you want to resume it again, update it to false. +Creating a Job with `.spec.suspend` set to true will create it in the suspended +state. + +When a Job is resumed from suspension, its `.status.startTime` field will be +reset to the current time. This means that the `.spec.activeDeadlineSeconds` +timer will be stopped and reset when a Job is suspended and resumed. + +Remember that suspending a Job will delete all active Pods. When the Job is +suspended, your [Pods will be terminated](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) +with a SIGTERM signal. The Pod's graceful termination period will be honored and +your Pod must handle this signal in this period. This may involve saving +progress for later or undoing changes. Pods terminated this way will not count +towards the Job's `completions` count. + +An example Job definition in the suspended state can be like so: + +```shell +kubectl get job myjob -o yaml +``` + +```yaml +apiVersion: batch/v1 +kind: Job +metadata: + name: myjob +spec: + suspend: true + parallelism: 1 + completions: 5 + template: + spec: + ... +``` + +The Job's status can be used to determine if a Job is suspended or has been +suspended in the past: + +```shell +kubectl get jobs/myjob -o yaml +``` + +```json +apiVersion: batch/v1 +kind: Job +# .metadata and .spec omitted +status: + conditions: + - lastProbeTime: "2021-02-05T13:14:33Z" + lastTransitionTime: "2021-02-05T13:14:33Z" + status: "True" + type: Suspended + startTime: "2021-02-05T13:13:48Z" +``` + +The Job condition of type "Suspended" with status "True" means the Job is +suspended; the `lastTransitionTime` field can be used to determine how long the +Job has been suspended for. If the status of that condition is "False", then the +Job was previously suspended and is now running. If such a condition does not +exist in the Job's status, the Job has never been stopped. + +Events are also created when the Job is suspended and resumed: + +```shell +kubectl describe jobs/myjob +``` + +``` +Name: myjob +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulCreate 12m job-controller Created pod: myjob-hlrpl + Normal SuccessfulDelete 11m job-controller Deleted pod: myjob-hlrpl + Normal Suspended 11m job-controller Job suspended + Normal SuccessfulCreate 3s job-controller Created pod: myjob-jvb44 + Normal Resumed 3s job-controller Job resumed +``` + +The last four events, particularly the "Suspended" and "Resumed" events, are +directly a result of toggling the `.spec.suspend` field. In the time between +these two events, we see that no Pods were created, but Pod creation restarted +as soon as the Job was resumed. + ### Specifying your own Pod selector Normally, when you create a Job object, you do not specify `.spec.selector`. diff --git a/content/en/docs/concepts/workloads/controllers/replicaset.md b/content/en/docs/concepts/workloads/controllers/replicaset.md index 4766c56578..316b6a3b6c 100644 --- a/content/en/docs/concepts/workloads/controllers/replicaset.md +++ b/content/en/docs/concepts/workloads/controllers/replicaset.md @@ -310,6 +310,48 @@ assuming that the number of replicas is not also changed). A ReplicaSet can be easily scaled up or down by simply updating the `.spec.replicas` field. The ReplicaSet controller ensures that a desired number of Pods with a matching label selector are available and operational. +When scaling down, the ReplicaSet controller chooses which pods to delete by sorting the available pods to +prioritize scaling down pods based on the following general algorithm: + 1. Pending (and unschedulable) pods are scaled down first + 2. If controller.kubernetes.io/pod-deletion-cost annotation is set, then + the pod with the lower value will come first. + 3. Pods on nodes with more replicas come before pods on nodes with fewer replicas. + 4. If the pods' creation times differ, the pod that was created more recently + comes before the older pod (the creation times are bucketed on an integer log scale + when the `LogarithmicScaleDown` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) + +If all of the above match, then selection is random. + +### Pod deletion cost +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +Using the [`controller.kubernetes.io/pod-deletion-cost`](/docs/reference/command-line-tools-reference/labels-annotations-taints/#pod-deletion-cost) +annotation, users can set a preference regarding which pods to remove first when downscaling a ReplicaSet. + +The annotation should be set on the pod, the range is [-2147483647, 2147483647]. It represents the cost of +deleting a pod compared to other pods belonging to the same ReplicaSet. Pods with lower deletion +cost are preferred to be deleted before pods with higher deletion cost. + +The implicit value for this annotation for pods that don't set it is 0; negative values are permitted. +Invalid values will be rejected by the API server. + +This feature is alpha and disabled by default. You can enable it by setting the +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +`PodDeletionCost` in both kube-apiserver and kube-controller-manager. + +{{< note >}} +- This is honored on a best-effort basis, so it does not offer any guarantees on pod deletion order. +- Users should avoid updating the annotation frequently, such as updating it based on a metric value, + because doing so will generate a significant number of pod updates on the apiserver. +{{< /note >}} + +#### Example Use Case +The different pods of an application could have different utilization levels. On scale down, the application +may prefer to remove the pods with lower utilization. To avoid frequently updating the pods, the application +should update `controller.kubernetes.io/pod-deletion-cost` once before issuing a scale down (setting the +annotation to a value proportional to pod utilization level). This works if the application itself controls +the down scaling; for example, the driver pod of a Spark deployment. + ### ReplicaSet as a Horizontal Pod Autoscaler Target A ReplicaSet can also be a target for diff --git a/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md b/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md index 65527e5ce2..266e72a79f 100644 --- a/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md +++ b/content/en/docs/concepts/workloads/controllers/ttlafterfinished.md @@ -8,7 +8,7 @@ weight: 70 -{{< feature-state for_k8s_version="v1.12" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} The TTL controller provides a TTL (time to live) mechanism to limit the lifetime of resource objects that have finished execution. TTL controller only handles @@ -16,9 +16,9 @@ objects that have finished execution. TTL controller only handles and may be expanded to handle other resources that will finish execution, such as Pods and custom resources. -Alpha Disclaimer: this feature is currently alpha, and can be enabled with both kube-apiserver and kube-controller-manager +This feature is currently beta and enabled by default, and can be disabled via [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) -`TTLAfterFinished`. +`TTLAfterFinished` in both kube-apiserver and kube-controller-manager. diff --git a/content/en/docs/concepts/workloads/pods/disruptions.md b/content/en/docs/concepts/workloads/pods/disruptions.md index d0a8bbf5a9..c791ed42f3 100644 --- a/content/en/docs/concepts/workloads/pods/disruptions.md +++ b/content/en/docs/concepts/workloads/pods/disruptions.md @@ -90,7 +90,7 @@ disruptions, if any, to expect. ## Pod disruption budgets -{{< feature-state for_k8s_version="v1.5" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} Kubernetes offers features to help you run highly available applications even when you introduce frequent voluntary disruptions. diff --git a/content/en/docs/reference/access-authn-authz/admission-controllers.md b/content/en/docs/reference/access-authn-authz/admission-controllers.md index 9e45e57d37..581c218755 100644 --- a/content/en/docs/reference/access-authn-authz/admission-controllers.md +++ b/content/en/docs/reference/access-authn-authz/admission-controllers.md @@ -94,7 +94,7 @@ kube-apiserver -h | grep enable-admission-plugins In the current version, the default ones are: ```shell -NamespaceLifecycle, LimitRanger, ServiceAccount, TaintNodesByCondition, Priority, DefaultTolerationSeconds, DefaultStorageClass, StorageObjectInUseProtection, PersistentVolumeClaimResize, RuntimeClass, CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, MutatingAdmissionWebhook, ValidatingAdmissionWebhook, ResourceQuota +CertificateApproval, CertificateSigning, CertificateSubjectRestriction, DefaultIngressClass, DefaultStorageClass, DefaultTolerationSeconds, LimitRanger, MutatingAdmissionWebhook, NamespaceLifecycle, PersistentVolumeClaimResize, Priority, ResourceQuota, RuntimeClass, ServiceAccount, StorageObjectInUseProtection, TaintNodesByCondition, ValidatingAdmissionWebhook ``` ## What does each admission controller do? @@ -105,6 +105,12 @@ NamespaceLifecycle, LimitRanger, ServiceAccount, TaintNodesByCondition, Priority This admission controller allows all pods into the cluster. It is deprecated because its behavior is the same as if there were no admission controller at all. +### AlwaysDeny {#alwaysdeny} + +{{< feature-state for_k8s_version="v1.13" state="deprecated" >}} + +Rejects all requests. AlwaysDeny is DEPRECATED as it has no real meaning. + ### AlwaysPullImages {#alwayspullimages} This admission controller modifies every new Pod to force the image pull policy to Always. This is useful in a @@ -115,12 +121,6 @@ scheduled onto the right node), without any authorization check against the imag is enabled, images are always pulled prior to starting containers, which means valid credentials are required. -### AlwaysDeny {#alwaysdeny} - -{{< feature-state for_k8s_version="v1.13" state="deprecated" >}} - -Rejects all requests. AlwaysDeny is DEPRECATED as no real meaning. - ### CertificateApproval {#certificateapproval} This admission controller observes requests to 'approve' CertificateSigningRequest resources and performs additional @@ -145,6 +145,22 @@ This admission controller observes creation of CertificateSigningRequest resourc of `kubernetes.io/kube-apiserver-client`. It rejects any request that specifies a 'group' (or 'organization attribute') of `system:masters`. +### DefaultIngressClass {#defaultingressclass} + +This admission controller observes creation of `Ingress` objects that do not request any specific +ingress class and automatically adds a default ingress class to them. This way, users that do not +request any special ingress class do not need to care about them at all and they will get the +default one. + +This admission controller does not do anything when no default ingress class is configured. When more than one ingress +class is marked as default, it rejects any creation of `Ingress` with an error and an administrator +must revisit their `IngressClass` objects and mark only one as default (with the annotation +"ingressclass.kubernetes.io/is-default-class"). This admission controller ignores any `Ingress` +updates; it acts only on creation. + +See the [ingress](/docs/concepts/services-networking/ingress/) documentation for more about ingress +classes and how to mark one as default. + ### DefaultStorageClass {#defaultstorageclass} This admission controller observes creation of `PersistentVolumeClaim` objects that do not request any specific storage class @@ -169,19 +185,6 @@ have toleration for taints `node.kubernetes.io/not-ready:NoExecute` or `node.kubernetes.io/unreachable:NoExecute`. The default value for `default-not-ready-toleration-seconds` and `default-unreachable-toleration-seconds` is 5 minutes. -### DenyExecOnPrivileged {#denyexeconprivileged} - -{{< feature-state for_k8s_version="v1.13" state="deprecated" >}} - -This admission controller will intercept all requests to exec a command in a pod if that pod has a privileged container. - -This functionality has been merged into [DenyEscalatingExec](#denyescalatingexec). -The DenyExecOnPrivileged admission plugin is deprecated. - -Use of a policy-based admission plugin (like [PodSecurityPolicy](#podsecuritypolicy) or a custom admission plugin) -which can be targeted at specific users or Namespaces and also protects against creation of overly privileged Pods -is recommended instead. - ### DenyEscalatingExec {#denyescalatingexec} {{< feature-state for_k8s_version="v1.13" state="deprecated" >}} @@ -196,6 +199,32 @@ Use of a policy-based admission plugin (like [PodSecurityPolicy](#podsecuritypol which can be targeted at specific users or Namespaces and also protects against creation of overly privileged Pods is recommended instead. +### DenyExecOnPrivileged {#denyexeconprivileged} + +{{< feature-state for_k8s_version="v1.13" state="deprecated" >}} + +This admission controller will intercept all requests to exec a command in a pod if that pod has a privileged container. + +This functionality has been merged into [DenyEscalatingExec](#denyescalatingexec). +The DenyExecOnPrivileged admission plugin is deprecated. + +Use of a policy-based admission plugin (like [PodSecurityPolicy](#podsecuritypolicy) or a custom admission plugin) +which can be targeted at specific users or Namespaces and also protects against creation of overly privileged Pods +is recommended instead. + +### DenyServiceExternalIPs + +This admission controller rejects all net-new usage of the `Service` field `externalIPs`. This +feature is very powerful (allows network traffic interception) and not well +controlled by policy. When enabled, users of the cluster may not create new +Services which use `externalIPs` and may not add new values to `externalIPs` on +existing `Service` objects. Existing uses of `externalIPs` are not affected, +and users may remove values from `externalIPs` on existing `Service` objects. + +Most users do not need this feature at all, and cluster admins should consider disabling it. +Clusters that do need to use this feature should consider using some custom policy to manage usage +of it. + ### EventRateLimit {#eventratelimit} {{< feature-state for_k8s_version="v1.13" state="alpha" >}} @@ -549,6 +578,37 @@ This admission controller also protects the access to `metadata.ownerReferences[ of an object, so that only users with "update" permission to the `finalizers` subresource of the referenced *owner* can change it. +### PersistentVolumeClaimResize {#persistentvolumeclaimresize} + +This admission controller implements additional validations for checking incoming `PersistentVolumeClaim` resize requests. + +{{< note >}} +Support for volume resizing is available as an alpha feature. Admins must set the feature gate `ExpandPersistentVolumes` +to `true` to enable resizing. +{{< /note >}} + +After enabling the `ExpandPersistentVolumes` feature gate, enabling the `PersistentVolumeClaimResize` admission +controller is recommended, too. This admission controller prevents resizing of all claims by default unless a claim's `StorageClass` + explicitly enables resizing by setting `allowVolumeExpansion` to `true`. + +For example: all `PersistentVolumeClaim`s created from the following `StorageClass` support volume expansion: + +```yaml +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: gluster-vol-default +provisioner: kubernetes.io/glusterfs +parameters: + resturl: "http://192.168.10.100:8080" + restuser: "" + secretNamespace: "" + secretName: "" +allowVolumeExpansion: true +``` + +For more information about persistent volume claims, see [PersistentVolumeClaims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). + ### PersistentVolumeLabel {#persistentvolumelabel} {{< feature-state for_k8s_version="v1.13" state="deprecated" >}} @@ -636,37 +696,6 @@ PodNodeSelector allows forcing pods to run on specifically labeled nodes. Also s admission plugin, which allows preventing pods from running on specifically tainted nodes. {{< /note >}} -### PersistentVolumeClaimResize {#persistentvolumeclaimresize} - -This admission controller implements additional validations for checking incoming `PersistentVolumeClaim` resize requests. - -{{< note >}} -Support for volume resizing is available as an alpha feature. Admins must set the feature gate `ExpandPersistentVolumes` -to `true` to enable resizing. -{{< /note >}} - -After enabling the `ExpandPersistentVolumes` feature gate, enabling the `PersistentVolumeClaimResize` admission -controller is recommended, too. This admission controller prevents resizing of all claims by default unless a claim's `StorageClass` - explicitly enables resizing by setting `allowVolumeExpansion` to `true`. - -For example: all `PersistentVolumeClaim`s created from the following `StorageClass` support volume expansion: - -```yaml -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: gluster-vol-default -provisioner: kubernetes.io/glusterfs -parameters: - resturl: "http://192.168.10.100:8080" - restuser: "" - secretNamespace: "" - secretName: "" -allowVolumeExpansion: true -``` - -For more information about persistent volume claims, see [PersistentVolumeClaims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). - ### PodSecurityPolicy {#podsecuritypolicy} This admission controller acts on creation and modification of the pod and determines if it should be admitted diff --git a/content/en/docs/reference/access-authn-authz/service-accounts-admin.md b/content/en/docs/reference/access-authn-authz/service-accounts-admin.md index dd13dfeecc..4aaf6da0a2 100644 --- a/content/en/docs/reference/access-authn-authz/service-accounts-admin.md +++ b/content/en/docs/reference/access-authn-authz/service-accounts-admin.md @@ -60,9 +60,9 @@ It acts synchronously to modify pods as they are created or updated. When this p 1. It adds a `volumeSource` to each container of the pod mounted at `/var/run/secrets/kubernetes.io/serviceaccount`. #### Bound Service Account Token Volume -{{< feature-state for_k8s_version="v1.13" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="beta" >}} -When the `BoundServiceAccountTokenVolume` feature gate is enabled, the service account admission controller will +When the `BoundServiceAccountTokenVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled, the service account admission controller will add a projected service account token volume instead of a secret volume. The service account token will expire after 1 hour by default or the pod is deleted. See more details about [projected volume](/docs/tasks/configure-pod-container/configure-projected-volume-storage/). This feature depends on the `RootCAConfigMap` feature gate enabled which publish a "kube-root-ca.crt" ConfigMap to every namespace. This ConfigMap contains a CA bundle used for verifying connections to the kube-apiserver. @@ -140,4 +140,3 @@ kubectl delete secret mysecretname A ServiceAccount controller manages the ServiceAccounts inside namespaces, and ensures a ServiceAccount named "default" exists in every active namespace. - diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 582ed9da94..726207c9fe 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -59,11 +59,10 @@ different Kubernetes components. | `AnyVolumeDataSource` | `false` | Alpha | 1.18 | | | `AppArmor` | `true` | Beta | 1.4 | | | `BalanceAttachedNodeVolumes` | `false` | Alpha | 1.11 | | -| `BoundServiceAccountTokenVolume` | `false` | Alpha | 1.13 | | +| `BoundServiceAccountTokenVolume` | `false` | Alpha | 1.13 | 1.20 | +| `BoundServiceAccountTokenVolume` | `true` | Beta | 1.21 | | | `CPUManager` | `false` | Alpha | 1.8 | 1.9 | | `CPUManager` | `true` | Beta | 1.10 | | -| `CRIContainerLogRotation` | `false` | Alpha | 1.10 | 1.10 | -| `CRIContainerLogRotation` | `true` | Beta| 1.11 | | | `CSIInlineVolume` | `false` | Alpha | 1.15 | 1.15 | | `CSIInlineVolume` | `true` | Beta | 1.16 | - | | `CSIMigration` | `false` | Alpha | 1.14 | 1.16 | @@ -74,7 +73,8 @@ different Kubernetes components. | `CSIMigrationAzureDisk` | `false` | Alpha | 1.15 | 1.18 | | `CSIMigrationAzureDisk` | `false` | Beta | 1.19 | | | `CSIMigrationAzureDiskComplete` | `false` | Alpha | 1.17 | | -| `CSIMigrationAzureFile` | `false` | Alpha | 1.15 | | +| `CSIMigrationAzureFile` | `false` | Alpha | 1.15 | 1.19 | +| `CSIMigrationAzureFile` | `false` | Beta | 1.21 | | | `CSIMigrationAzureFileComplete` | `false` | Alpha | 1.17 | | | `CSIMigrationGCE` | `false` | Alpha | 1.14 | 1.16 | | `CSIMigrationGCE` | `false` | Beta | 1.17 | | @@ -84,13 +84,16 @@ different Kubernetes components. | `CSIMigrationOpenStackComplete` | `false` | Alpha | 1.17 | | | `CSIMigrationvSphere` | `false` | Beta | 1.19 | | | `CSIMigrationvSphereComplete` | `false` | Beta | 1.19 | | -| `CSIServiceAccountToken` | `false` | Alpha | 1.20 | | -| `CSIStorageCapacity` | `false` | Alpha | 1.19 | | +| `CSIServiceAccountToken` | `false` | Alpha | 1.20 | 1.20 | +| `CSIServiceAccountToken` | `true` | Beta | 1.21 | | +| `CSIStorageCapacity` | `false` | Alpha | 1.19 | 1.20 | +| `CSIStorageCapacity` | `true` | Beta | 1.21 | | | `CSIVolumeFSGroupPolicy` | `false` | Alpha | 1.19 | 1.19 | | `CSIVolumeFSGroupPolicy` | `true` | Beta | 1.20 | | | `ConfigurableFSGroupPolicy` | `false` | Alpha | 1.18 | 1.19 | | `ConfigurableFSGroupPolicy` | `true` | Beta | 1.20 | | -| `CronJobControllerV2` | `false` | Alpha | 1.20 | | +| `CronJobControllerV2` | `false` | Alpha | 1.20 | 1.20 | +| `CronJobControllerV2` | `true` | Beta | 1.21 | | | `CustomCPUCFSQuotaPeriod` | `false` | Alpha | 1.12 | | | `DefaultPodTopologySpread` | `false` | Alpha | 1.19 | 1.19 | | `DefaultPodTopologySpread` | `true` | Beta | 1.20 | | @@ -98,14 +101,11 @@ different Kubernetes components. | `DevicePlugins` | `true` | Beta | 1.10 | | | `DisableAcceleratorUsageMetrics` | `false` | Alpha | 1.19 | 1.19 | | `DisableAcceleratorUsageMetrics` | `true` | Beta | 1.20 | | -| `DownwardAPIHugePages` | `false` | Alpha | 1.20 | | +| `DownwardAPIHugePages` | `false` | Alpha | 1.20 | 1.20 | +| `DownwardAPIHugePages` | `false` | Beta | 1.21 | | | `DynamicKubeletConfig` | `false` | Alpha | 1.4 | 1.10 | | `DynamicKubeletConfig` | `true` | Beta | 1.11 | | | `EfficientWatchResumption` | `false` | Alpha | 1.20 | | -| `EndpointSlice` | `false` | Alpha | 1.16 | 1.16 | -| `EndpointSlice` | `false` | Beta | 1.17 | | -| `EndpointSlice` | `true` | Beta | 1.18 | | -| `EndpointSliceNodeName` | `false` | Alpha | 1.20 | | | `EndpointSliceProxying` | `false` | Alpha | 1.18 | 1.18 | | `EndpointSliceProxying` | `true` | Beta | 1.19 | | | `EndpointSliceTerminatingCondition` | `false` | Alpha | 1.20 | | @@ -117,15 +117,17 @@ different Kubernetes components. | `ExpandPersistentVolumes` | `false` | Alpha | 1.8 | 1.10 | | `ExpandPersistentVolumes` | `true` | Beta | 1.11 | | | `ExperimentalHostUserNamespaceDefaulting` | `false` | Beta | 1.5 | | -| `GenericEphemeralVolume` | `false` | Alpha | 1.19 | | -| `GracefulNodeShutdown` | `false` | Alpha | 1.20 | | +| `GenericEphemeralVolume` | `false` | Alpha | 1.19 | 1.20 | +| `GenericEphemeralVolume` | `true` | Beta | 1.21 | | +| `GracefulNodeShutdown` | `false` | Alpha | 1.20 | 1.20 | +| `GracefulNodeShutdown` | `true` | Beta | 1.21 | | | `HPAContainerMetrics` | `false` | Alpha | 1.20 | | | `HPAScaleToZero` | `false` | Alpha | 1.16 | | | `HugePageStorageMediumSize` | `false` | Alpha | 1.18 | 1.18 | | `HugePageStorageMediumSize` | `true` | Beta | 1.19 | | -| `IPv6DualStack` | `false` | Alpha | 1.15 | | -| `ImmutableEphemeralVolumes` | `false` | Alpha | 1.18 | 1.18 | -| `ImmutableEphemeralVolumes` | `true` | Beta | 1.19 | | +| `IngressClassNamespacedParams` | `false` | Alpha | 1.21 | | +| `IPv6DualStack` | `false` | Alpha | 1.15 | 1.20 | +| `IPv6DualStack` | `true` | Beta | 1.21 | | | `KubeletCredentialProviders` | `false` | Alpha | 1.20 | | | `KubeletPodResources` | `true` | Alpha | 1.13 | 1.14 | | `KubeletPodResources` | `true` | Beta | 1.15 | | @@ -134,22 +136,25 @@ different Kubernetes components. | `LocalStorageCapacityIsolation` | `false` | Alpha | 1.7 | 1.9 | | `LocalStorageCapacityIsolation` | `true` | Beta | 1.10 | | | `LocalStorageCapacityIsolationFSQuotaMonitoring` | `false` | Alpha | 1.15 | | +| `LogarithmicScaleDown` | `false` | Alpha | 1.21 | | +| `KubeletPodResourcesGetAllocatable` | `false` | Alpha | 1.21 | | | `MixedProtocolLBService` | `false` | Alpha | 1.20 | | +| `NamespaceDefaultLabelName` | `true` | Beta | 1.21 | | +| `NetworkPolicyEndPort` | `false` | Alpha | 1.21 | | | `NodeDisruptionExclusion` | `false` | Alpha | 1.16 | 1.18 | | `NodeDisruptionExclusion` | `true` | Beta | 1.19 | | | `NonPreemptingPriority` | `false` | Alpha | 1.15 | 1.18 | | `NonPreemptingPriority` | `true` | Beta | 1.19 | | -| `PodDisruptionBudget` | `false` | Alpha | 1.3 | 1.4 | -| `PodDisruptionBudget` | `true` | Beta | 1.5 | | +| `PodDeletionCost` | `false` | Alpha | 1.21 | | +| `PodAffinityNamespaceSelector` | `false` | Alpha | 1.21 | | | `PodOverhead` | `false` | Alpha | 1.16 | 1.17 | | `PodOverhead` | `true` | Beta | 1.18 | | +| `ProbeTerminationGracePeriod` | `false` | Alpha | 1.21 | | | `ProcMountType` | `false` | Alpha | 1.12 | | | `QOSReserved` | `false` | Alpha | 1.11 | | | `RemainingItemCount` | `false` | Alpha | 1.15 | | | `RemoveSelfLink` | `false` | Alpha | 1.16 | 1.19 | | `RemoveSelfLink` | `true` | Beta | 1.20 | | -| `RootCAConfigMap` | `false` | Alpha | 1.13 | 1.19 | -| `RootCAConfigMap` | `true` | Beta | 1.20 | | | `RotateKubeletServerCertificate` | `false` | Alpha | 1.7 | 1.11 | | `RotateKubeletServerCertificate` | `true` | Beta | 1.12 | | | `RunAsGroup` | `true` | Beta | 1.14 | | @@ -157,9 +162,9 @@ different Kubernetes components. | `SCTPSupport` | `true` | Beta | 1.19 | | | `ServerSideApply` | `false` | Alpha | 1.14 | 1.15 | | `ServerSideApply` | `true` | Beta | 1.16 | | -| `ServiceAccountIssuerDiscovery` | `false` | Alpha | 1.18 | 1.19 | -| `ServiceAccountIssuerDiscovery` | `true` | Beta | 1.20 | | +| `ServiceInternalTrafficPolicy` | `false` | Alpha | 1.21 | | | `ServiceLBNodePortControl` | `false` | Alpha | 1.20 | | +| `ServiceLoadBalancerClass` | `false` | Alpha | 1.21 | | | `ServiceNodeExclusion` | `false` | Alpha | 1.8 | 1.18 | | `ServiceNodeExclusion` | `true` | Beta | 1.19 | | | `ServiceTopology` | `false` | Alpha | 1.17 | | @@ -169,8 +174,9 @@ different Kubernetes components. | `StorageVersionAPI` | `false` | Alpha | 1.20 | | | `StorageVersionHash` | `false` | Alpha | 1.14 | 1.14 | | `StorageVersionHash` | `true` | Beta | 1.15 | | -| `Sysctls` | `true` | Beta | 1.11 | | +| `SuspendJob` | `false` | Alpha | 1.21 | | | `TTLAfterFinished` | `false` | Alpha | 1.12 | | +| `TopologyAwareHints` | `false` | Alpha | 1.21 | | | `TopologyManager` | `false` | Alpha | 1.16 | 1.17 | | `TopologyManager` | `true` | Beta | 1.18 | | | `ValidateProxyRedirects` | `false` | Alpha | 1.12 | 1.13 | @@ -179,7 +185,8 @@ different Kubernetes components. | `WinDSR` | `false` | Alpha | 1.14 | | | `WinOverlay` | `false` | Alpha | 1.14 | 1.19 | | `WinOverlay` | `true` | Beta | 1.20 | | -| `WindowsEndpointSliceProxying` | `false` | Alpha | 1.19 | | +| `WindowsEndpointSliceProxying` | `false` | Alpha | 1.19 | 1.20 | +| `WindowsEndpointSliceProxying` | `true` | beta | 1.21 | | {{< /table >}} ### Feature gates for graduated or deprecated features @@ -200,6 +207,9 @@ different Kubernetes components. | `BlockVolume` | `false` | Alpha | 1.9 | 1.12 | | `BlockVolume` | `true` | Beta | 1.13 | 1.17 | | `BlockVolume` | `true` | GA | 1.18 | - | +| `CRIContainerLogRotation` | `false` | Alpha | 1.10 | 1.10 | +| `CRIContainerLogRotation` | `true` | Beta | 1.11 | 1.20 | +| `CRIContainerLogRotation` | `true` | GA | 1.21 | - | | `CSIBlockVolume` | `false` | Alpha | 1.11 | 1.13 | | `CSIBlockVolume` | `true` | Beta | 1.14 | 1.17 | | `CSIBlockVolume` | `true` | GA | 1.18 | - | @@ -215,6 +225,7 @@ different Kubernetes components. | `CSIPersistentVolume` | `false` | Alpha | 1.9 | 1.9 | | `CSIPersistentVolume` | `true` | Beta | 1.10 | 1.12 | | `CSIPersistentVolume` | `true` | GA | 1.13 | - | +| `CSIVolumeHealth` | `false` | Alpha | 1.21 | - | | `CustomPodDNS` | `false` | Alpha | 1.9 | 1.9 | | `CustomPodDNS` | `true` | Beta| 1.10 | 1.13 | | `CustomPodDNS` | `true` | GA | 1.14 | - | @@ -245,6 +256,12 @@ different Kubernetes components. | `EnableAggregatedDiscoveryTimeout` | `true` | Deprecated | 1.16 | - | | `EnableEquivalenceClassCache` | `false` | Alpha | 1.8 | 1.14 | | `EnableEquivalenceClassCache` | - | Deprecated | 1.15 | - | +| `EndpointSlice` | `false` | Alpha | 1.16 | 1.16 | +| `EndpointSlice` | `false` | Beta | 1.17 | 1.17 | +| `EndpointSlice` | `true` | Beta | 1.18 | 1.21 | +| `EndpointSlice` | `true` | GA | 1.21 | - | +| `EndpointSliceNodeName` | `false` | Alpha | 1.20 | 1.21 | +| `EndpointSliceNodeName` | `true` | GA | 1.21 | - | | `ExperimentalCriticalPodAnnotation` | `false` | Alpha | 1.5 | 1.12 | | `ExperimentalCriticalPodAnnotation` | `false` | Deprecated | 1.13 | - | | `EvenPodsSpread` | `false` | Alpha | 1.16 | 1.17 | @@ -258,6 +275,10 @@ different Kubernetes components. | `HugePages` | `true` | GA | 1.14 | - | | `HyperVContainer` | `false` | Alpha | 1.10 | 1.19 | | `HyperVContainer` | `false` | Deprecated | 1.20 | - | +| `ImmutableEphemeralVolumes` | `false` | Alpha | 1.18 | 1.18 | +| `ImmutableEphemeralVolumes` | `true` | Beta | 1.19 | 1.20 | +| `ImmutableEphemeralVolumes` | `true` | GA | 1.21 | | +| `IndexedJob` | `false` | Alpha | 1.21 | | | `Initializers` | `false` | Alpha | 1.7 | 1.13 | | `Initializers` | - | Deprecated | 1.14 | - | | `KubeletConfigFile` | `false` | Alpha | 1.8 | 1.9 | @@ -281,6 +302,9 @@ different Kubernetes components. | `PersistentLocalVolumes` | `false` | Alpha | 1.7 | 1.9 | | `PersistentLocalVolumes` | `true` | Beta | 1.10 | 1.13 | | `PersistentLocalVolumes` | `true` | GA | 1.14 | - | +| `PodDisruptionBudget` | `false` | Alpha | 1.3 | 1.4 | +| `PodDisruptionBudget` | `true` | Beta | 1.5 | 1.20 | +| `PodDisruptionBudget` | `true` | GA | 1.21 | - | | `PodPriority` | `false` | Alpha | 1.8 | 1.10 | | `PodPriority` | `true` | Beta | 1.11 | 1.13 | | `PodPriority` | `true` | GA | 1.14 | - | @@ -296,6 +320,9 @@ different Kubernetes components. | `ResourceQuotaScopeSelectors` | `false` | Alpha | 1.11 | 1.11 | | `ResourceQuotaScopeSelectors` | `true` | Beta | 1.12 | 1.16 | | `ResourceQuotaScopeSelectors` | `true` | GA | 1.17 | - | +| `RootCAConfigMap` | `false` | Alpha | 1.13 | 1.19 | +| `RootCAConfigMap` | `true` | Beta | 1.20 | 1.20 | +| `RootCAConfigMap` | `true` | GA | 1.21 | - | | `RotateKubeletClientCertificate` | `true` | Beta | 1.8 | 1.18 | | `RotateKubeletClientCertificate` | `true` | GA | 1.19 | - | | `RuntimeClass` | `false` | Alpha | 1.12 | 1.13 | @@ -307,6 +334,9 @@ different Kubernetes components. | `SCTPSupport` | `false` | Alpha | 1.12 | 1.18 | | `SCTPSupport` | `true` | Beta | 1.19 | 1.19 | | `SCTPSupport` | `true` | GA | 1.20 | - | +| `ServiceAccountIssuerDiscovery` | `false` | Alpha | 1.18 | 1.19 | +| `ServiceAccountIssuerDiscovery` | `true` | Beta | 1.20 | 1.20 | +| `ServiceAccountIssuerDiscovery` | `true` | GA | 1.21 | - | | `ServiceAppProtocol` | `false` | Alpha | 1.18 | 1.18 | | `ServiceAppProtocol` | `true` | Beta | 1.19 | | | `ServiceAppProtocol` | `true` | GA | 1.20 | - | @@ -331,6 +361,8 @@ different Kubernetes components. | `SupportPodPidsLimit` | `false` | Alpha | 1.10 | 1.13 | | `SupportPodPidsLimit` | `true` | Beta | 1.14 | 1.19 | | `SupportPodPidsLimit` | `true` | GA | 1.20 | - | +| `Sysctls` | `true` | Beta | 1.11 | 1.20 | +| `Sysctls` | `true` | GA | 1.21 | | | `TaintBasedEvictions` | `false` | Alpha | 1.6 | 1.12 | | `TaintBasedEvictions` | `true` | Beta | 1.13 | 1.17 | | `TaintBasedEvictions` | `true` | GA | 1.18 | - | @@ -343,6 +375,7 @@ different Kubernetes components. | `TokenRequestProjection` | `false` | Alpha | 1.11 | 1.11 | | `TokenRequestProjection` | `true` | Beta | 1.12 | 1.19 | | `TokenRequestProjection` | `true` | GA | 1.20 | - | +| `VolumeCapacityPriority` | `false` | Alpha | 1.21 | - | | `VolumeSnapshotDataSource` | `false` | Alpha | 1.12 | 1.16 | | `VolumeSnapshotDataSource` | `true` | Beta | 1.17 | 1.19 | | `VolumeSnapshotDataSource` | `true` | GA | 1.20 | - | @@ -444,7 +477,9 @@ Each feature gate is designed for enabling/disabling a specific feature: for more details. - `CPUManager`: Enable container level CPU affinity support, see [CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/). -- `CRIContainerLogRotation`: Enable container log rotation for cri container runtime. +- `CRIContainerLogRotation`: Enable container log rotation for CRI container runtime. The default max size of a log file is 10MB and the + default max number of log files allowed for a container is 5. These values can be configured in the kubelet config. + See the [logging at node level](/docs/concepts/cluster-administration/logging/#logging-at-the-node-level) documentation for more details. - `CSIBlockVolume`: Enable external CSI volume drivers to support block storage. See the [`csi` raw block volume support](/docs/concepts/storage/volumes/#csi-raw-block-volume-support) documentation for more details. @@ -525,6 +560,7 @@ Each feature gate is designed for enabling/disabling a specific feature: - `CSIVolumeFSGroupPolicy`: Allows CSIDrivers to use the `fsGroupPolicy` field. This field controls whether volumes created by a CSIDriver support volume ownership and permission modifications when these volumes are mounted. +- `CSIVolumeHealth`: Enable support for CSI volume health monitoring on node. - `ConfigurableFSGroupPolicy`: Allows user to configure volume permission change policy for fsGroups when mounting a volume in a Pod. See [Configure volume permission and ownership change policy for Pods](/docs/tasks/configure-pod-container/security-context/#configure-volume-permission-and-ownership-change-policy-for-pods) @@ -623,10 +659,15 @@ Each feature gate is designed for enabling/disabling a specific feature: - `HyperVContainer`: Enable [Hyper-V isolation](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container) for Windows containers. -- `IPv6DualStack`: Enable [dual stack](/docs/concepts/services-networking/dual-stack/) - support for IPv6. - `ImmutableEphemeralVolumes`: Allows for marking individual Secrets and ConfigMaps as immutable for better safety and performance. +- `IndexedJob`: Allows the [Job](/docs/concepts/workloads/controllers/job/) + controller to manage Pod completions per completion index. +- `IngressClassNamespacedParams`: Allow namespace-scoped parameters reference in + `IngressClass` resouce. This feature adds two fields - `Scope` and `Namespace` + to `IngressClass.spec.parameters`. +- `IPv6DualStack`: Enable [dual stack](/docs/concepts/services-networking/dual-stack/) + support for IPv6. - `KubeletConfigFile` (*deprecated*): Enable loading kubelet configuration from a file specified using a config file. See [setting kubelet parameters via a config file](/docs/tasks/administer-cluster/kubelet-config-file/) @@ -637,6 +678,9 @@ Each feature gate is designed for enabling/disabling a specific feature: - `KubeletPodResources`: Enable the kubelet's pod resources gRPC endpoint. See [Support Device Monitoring](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/606-compute-device-assignment/README.md) for more details. +- `KubeletPodResourcesGetAllocatable`: Enable the kubelet's pod resources `GetAllocatableResources` functionality. + This API augments the [resource allocation reporting](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#monitoring-device-plugin-resources) + with informations about the allocatable resources, enabling clients to properly track the free compute resources on a node. - `LegacyNodeRoleBehavior`: When disabled, legacy behavior in service load balancers and node disruption will ignore the `node-role.kubernetes.io/master` label in favor of the feature-specific labels provided by `NodeDisruptionExclusion` and `ServiceNodeExclusion`. @@ -651,21 +695,30 @@ Each feature gate is designed for enabling/disabling a specific feature: supports project quotas and they are enabled, use project quotas to monitor [emptyDir volume](/docs/concepts/storage/volumes/#emptydir) storage consumption rather than filesystem walk for better performance and accuracy. +- `LogarithmicScaleDown`: Enable semi-random selection of pods to evict on controller scaledown + based on logarithmic bucketing of pod timestamps. - `MixedProtocolLBService`: Enable using different protocols in the same `LoadBalancer` type Service instance. - `MountContainers` (*deprecated*): Enable using utility containers on host as the volume mounter. - `MountPropagation`: Enable sharing volume mounted by one container to other containers or pods. For more details, please see [mount propagation](/docs/concepts/storage/volumes/#mount-propagation). +- `NamespaceDefaultLabelName`: Configure the API Server to set an immutable {{< glossary_tooltip text="label" term_id="label" >}} + `kubernetes.io/metadata.name` on all namespaces, containing the namespace name. +- `NetworkPolicyEndPort`: Enable use of the field `endPort` in NetworkPolicy objects, allowing the selection of a port range instead of a single port. - `NodeDisruptionExclusion`: Enable use of the Node label `node.kubernetes.io/exclude-disruption` which prevents nodes from being evacuated during zone failures. - `NodeLease`: Enable the new Lease API to report node heartbeats, which could be used as a node health signal. - `NonPreemptingPriority`: Enable `preemptionPolicy` field for PriorityClass and Pod. - `PVCProtection`: Enable the prevention of a PersistentVolumeClaim (PVC) from being deleted when it is still used by any Pod. +- `PodDeletionCost`: Enable the [Pod Deletion Cost](/docs/content/en/docs/concepts/workloads/controllers/replicaset/#pod-deletion-cost) + feature which allows users to influence ReplicaSet downscaling order. - `PersistentLocalVolumes`: Enable the usage of `local` volume type in Pods. Pod affinity has to be specified if requesting a `local` volume. - `PodDisruptionBudget`: Enable the [PodDisruptionBudget](/docs/tasks/run-application/configure-pdb/) feature. +- `PodAffinityNamespaceSelector`: Enable the [Pod Affinity Namespace Selector](/docs/concepts/scheduling-eviction/assign-pod-node/#namespace-selector) + and [CrossNamespacePodAffinity](/docs/concepts/policy/resource-quotas/#cross-namespace-pod-affinity-quota) quota scope features. - `PodOverhead`: Enable the [PodOverhead](/docs/concepts/scheduling-eviction/pod-overhead/) feature to account for pod overheads. - `PodPriority`: Enable the descheduling and preemption of Pods based on their @@ -676,6 +729,9 @@ Each feature gate is designed for enabling/disabling a specific feature: - `PodShareProcessNamespace`: Enable the setting of `shareProcessNamespace` in a Pod for sharing a single process namespace between containers running in a pod. More details can be found in [Share Process Namespace between Containers in a Pod](/docs/tasks/configure-pod-container/share-process-namespace/). +- `ProbeTerminationGracePeriod`: Enable [setting probe-level + `terminationGracePeriodSeconds`](/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#probe-level-terminationGracePeriodSeconds) + on pods. See the [enhancement proposal](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2238-liveness-probe-grace-period) for more details. - `ProcMountType`: Enables control over the type proc mounts for containers by setting the `procMount` field of a SecurityContext. - `QOSReserved`: Allows resource reservations at the QoS level preventing pods @@ -717,8 +773,10 @@ Each feature gate is designed for enabling/disabling a specific feature: [Configure Service Accounts for Pods](/docs/tasks/configure-pod-container/configure-service-account/#service-account-issuer-discovery) for more details. - `ServiceAppProtocol`: Enables the `AppProtocol` field on Services and Endpoints. +- `ServiceInternalTrafficPolicy`: Enables the `InternalTrafficPolicy` field on Services - `ServiceLBNodePortControl`: Enables the `spec.allocateLoadBalancerNodePorts` field on Services. +- `ServiceLoadBalancerClass`: Enables the `LoadBalancerClass` field on Services. See [Specifying class of load balancer implementation](/docs/concepts/services-networking/service/#specifying-class-of-load-balancer-implementation-load-balancer-class) for more details. - `ServiceLoadBalancerFinalizer`: Enable finalizer protection for Service load balancers. - `ServiceNodeExclusion`: Enable the exclusion of nodes from load balancers created by a cloud provider. A node is eligible for exclusion if labelled with @@ -752,6 +810,9 @@ Each feature gate is designed for enabling/disabling a specific feature: options can be specified to ensure that the specified number of process IDs will be reserved for the system as a whole and for Kubernetes system daemons respectively. +- `SuspendJob`: Enable support to suspend and resume Jobs. See + [the Jobs docs](/docs/concepts/workloads/controllers/job/) for + more details. - `Sysctls`: Enable support for namespaced kernel parameters (sysctls) that can be set for each pod. See [sysctls](/docs/tasks/administer-cluster/sysctl-cluster/) for more details. @@ -767,9 +828,15 @@ Each feature gate is designed for enabling/disabling a specific feature: - `TokenRequest`: Enable the `TokenRequest` endpoint on service account resources. - `TokenRequestProjection`: Enable the injection of service account tokens into a Pod through a [`projected` volume](/docs/concepts/storage/volumes/#projected). +- `TopologyAwareHints`: Enables topology aware routing based on topology hints + in EndpointSlices. See [Topology Aware + Hints](/docs/concepts/services-networking/topology-aware-hints/) for more + details. - `TopologyManager`: Enable a mechanism to coordinate fine-grained hardware resource assignments for different components in Kubernetes. See [Control Topology Management Policies on a node](/docs/tasks/administer-cluster/topology-manager/). +- 'VolumeCapacityPriority`: Enable support for prioritizing nodes in different + topologies based on available PV capacity. - `VolumePVCDataSource`: Enable support for specifying an existing PVC as a DataSource. - `VolumeScheduling`: Enable volume topology aware scheduling and make the PersistentVolumeClaim (PVC) binding aware of scheduling decisions. It also diff --git a/content/en/docs/reference/command-line-tools-reference/kubelet.md b/content/en/docs/reference/command-line-tools-reference/kubelet.md index 0e4ed2216e..66eb5785de 100644 --- a/content/en/docs/reference/command-line-tools-reference/kubelet.md +++ b/content/en/docs/reference/command-line-tools-reference/kubelet.md @@ -224,14 +224,14 @@ kubelet [flags] --container-log-max-files int32     Default: 5 -<Warning: Beta feature> Set the maximum number of container log files that can be present for a container. The number must be ≥ 2. This flag can only be used with `--container-runtime=remote`. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.) +Set the maximum number of container log files that can be present for a container. The number must be ≥ 2. This flag can only be used with `--container-runtime=remote`. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.) --container-log-max-size string     Default: `10Mi` -<Warning: Beta feature> Set the maximum size (e.g. 10Mi) of container log file before it is rotated. This flag can only be used with `--container-runtime=remote`. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.) +Set the maximum size (e.g. 10Mi) of container log file before it is rotated. This flag can only be used with `--container-runtime=remote`. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.) @@ -298,13 +298,6 @@ kubelet [flags] The Kubelet will use this directory for checkpointing downloaded configurations and tracking configuration health. The Kubelet will create this directory if it does not already exist. The path may be absolute or relative; relative paths start at the Kubelet's current working directory. Providing this flag enables dynamic Kubelet configuration. The `DynamicKubeletConfig` feature gate must be enabled to pass this flag; this gate currently defaults to `true` because the feature is beta. - ---enable-cadvisor-json-endpoints     Default: `false` - - -Enable cAdvisor json `/spec` and `/stats/*` endpoints. This flag has no effect on the /stats/summary endpoint. (DEPRECATED: will be removed in a future version) - - --enable-controller-attach-detach     Default: `true` @@ -462,7 +455,6 @@ AppArmor=true|false (BETA - default=true)
BalanceAttachedNodeVolumes=true|false (ALPHA - default=false)
BoundServiceAccountTokenVolume=true|false (ALPHA - default=false)
CPUManager=true|false (BETA - default=true)
-CRIContainerLogRotation=true|false (BETA - default=true)
CSIInlineVolume=true|false (BETA - default=true)
CSIMigration=true|false (BETA - default=true)
CSIMigrationAWS=true|false (BETA - default=false)
diff --git a/content/en/docs/reference/kubernetes-api/authorization-resources/self-subject-rules-review-v1.md b/content/en/docs/reference/kubernetes-api/authorization-resources/self-subject-rules-review-v1.md index aa3d95332b..a890598ddf 100644 --- a/content/en/docs/reference/kubernetes-api/authorization-resources/self-subject-rules-review-v1.md +++ b/content/en/docs/reference/kubernetes-api/authorization-resources/self-subject-rules-review-v1.md @@ -51,13 +51,13 @@ SelfSubjectRulesReview enumerates the set of actions the current user can perfor *NonResourceRule holds information that describes a rule for the non-resource* - - **status.nonResourceRules.verbs** ([]string), required + - **status.nonResourceRules.verbs** ([]string), required - Verb is a list of kubernetes non-resource API verbs, like: get, post, put, delete, patch, head, options. "*" means all. + Verb is a list of kubernetes non-resource API verbs, like: get, post, put, delete, patch, head, options. "*" means all. - - **status.nonResourceRules.nonResourceURLs** ([]string) + - **status.nonResourceRules.nonResourceURLs** ([]string) - NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path. "*" means all. + NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path. "*" means all. - **status.resourceRules** ([]ResourceRule), required @@ -66,22 +66,22 @@ SelfSubjectRulesReview enumerates the set of actions the current user can perfor *ResourceRule is the list of actions the subject is allowed to perform on resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete.* - - **status.resourceRules.verbs** ([]string), required + - **status.resourceRules.verbs** ([]string), required - Verb is a list of kubernetes resource API verbs, like: get, list, watch, create, update, delete, proxy. "*" means all. + Verb is a list of kubernetes resource API verbs, like: get, list, watch, create, update, delete, proxy. "*" means all. - - **status.resourceRules.apiGroups** ([]string) + - **status.resourceRules.apiGroups** ([]string) - APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. "*" means all. + APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. "*" means all. - - **status.resourceRules.resourceNames** ([]string) + - **status.resourceRules.resourceNames** ([]string) - ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. "*" means all. + ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. "*" means all. - - **status.resourceRules.resources** ([]string) + - **status.resourceRules.resources** ([]string) - Resources is a list of resources this rule applies to. "*" means all in the specified apiGroups. - "*/foo" represents the subresource 'foo' for all resources in the specified apiGroups. + Resources is a list of resources this rule applies to. "*" means all in the specified apiGroups. + "*/foo" represents the subresource 'foo' for all resources in the specified apiGroups. - **status.evaluationError** (string) diff --git a/content/en/docs/reference/kubernetes-api/cluster-resources/event-v1.md b/content/en/docs/reference/kubernetes-api/cluster-resources/event-v1.md index 065cf5a7e7..cf321c1f44 100644 --- a/content/en/docs/reference/kubernetes-api/cluster-resources/event-v1.md +++ b/content/en/docs/reference/kubernetes-api/cluster-resources/event-v1.md @@ -26,6 +26,10 @@ Event is a report of an event somewhere in the cluster. It generally denotes som - **kind**: Event +- **metadata** (}}">ObjectMeta) + + Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + - **eventTime** (MicroTime), required eventTime is the time when this Event was first observed. It is required. @@ -33,9 +37,6 @@ Event is a report of an event somewhere in the cluster. It generally denotes som *MicroTime is version of Time with microsecond level precision.* -- **metadata** (}}">ObjectMeta), required - - - **action** (string) action is what action was taken/failed regarding to the regarding object. It is machine-readable. This field cannot be empty for new Events and it can have at most 128 characters. diff --git a/content/en/docs/reference/kubernetes-api/cluster-resources/flow-schema-v1beta1.md b/content/en/docs/reference/kubernetes-api/cluster-resources/flow-schema-v1beta1.md index 8f94555ee2..0c221dea87 100644 --- a/content/en/docs/reference/kubernetes-api/cluster-resources/flow-schema-v1beta1.md +++ b/content/en/docs/reference/kubernetes-api/cluster-resources/flow-schema-v1beta1.md @@ -92,43 +92,43 @@ FlowSchemaSpec describes how the FlowSchema's specification looks like. *Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account.* - - **rules.subjects.kind** (string), required + - **rules.subjects.kind** (string), required - Required + Required - - **rules.subjects.group** (GroupSubject) + - **rules.subjects.group** (GroupSubject) - - *GroupSubject holds detailed information for group-kind subject.* + + *GroupSubject holds detailed information for group-kind subject.* - - **rules.subjects.group.name** (string), required + - **rules.subjects.group.name** (string), required - name is the user group that matches, or "*" to match all user groups. See https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/user/user.go for some well-known group names. Required. + name is the user group that matches, or "*" to match all user groups. See https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/user/user.go for some well-known group names. Required. - - **rules.subjects.serviceAccount** (ServiceAccountSubject) + - **rules.subjects.serviceAccount** (ServiceAccountSubject) - - *ServiceAccountSubject holds detailed information for service-account-kind subject.* + + *ServiceAccountSubject holds detailed information for service-account-kind subject.* - - **rules.subjects.serviceAccount.name** (string), required + - **rules.subjects.serviceAccount.name** (string), required - `name` is the name of matching ServiceAccount objects, or "*" to match regardless of name. Required. + `name` is the name of matching ServiceAccount objects, or "*" to match regardless of name. Required. - - **rules.subjects.serviceAccount.namespace** (string), required + - **rules.subjects.serviceAccount.namespace** (string), required - `namespace` is the namespace of matching ServiceAccount objects. Required. + `namespace` is the namespace of matching ServiceAccount objects. Required. - - **rules.subjects.user** (UserSubject) + - **rules.subjects.user** (UserSubject) - - *UserSubject holds detailed information for user-kind subject.* + + *UserSubject holds detailed information for user-kind subject.* - - **rules.subjects.user.name** (string), required + - **rules.subjects.user.name** (string), required - `name` is the username that matches, or "*" to match all usernames. Required. + `name` is the username that matches, or "*" to match all usernames. Required. - **rules.nonResourceRules** ([]NonResourcePolicyRule) @@ -139,23 +139,23 @@ FlowSchemaSpec describes how the FlowSchema's specification looks like. *NonResourcePolicyRule is a predicate that matches non-resource requests according to their verb and the target non-resource URL. A NonResourcePolicyRule matches a request if and only if both (a) at least one member of verbs matches the request and (b) at least one member of nonResourceURLs matches the request.* - - **rules.nonResourceRules.nonResourceURLs** ([]string), required + - **rules.nonResourceRules.nonResourceURLs** ([]string), required - *Set: unique values will be kept during a merge* - - `nonResourceURLs` is a set of url prefixes that a user should have access to and may not be empty. For example: - - "/healthz" is legal - - "/hea*" is illegal - - "/hea" is legal but matches nothing - - "/hea/*" also matches nothing - - "/healthz/*" matches all per-component health checks. - "*" matches all non-resource urls. if it is present, it must be the only entry. Required. + *Set: unique values will be kept during a merge* + + `nonResourceURLs` is a set of url prefixes that a user should have access to and may not be empty. For example: + - "/healthz" is legal + - "/hea*" is illegal + - "/hea" is legal but matches nothing + - "/hea/*" also matches nothing + - "/healthz/*" matches all per-component health checks. + "*" matches all non-resource urls. if it is present, it must be the only entry. Required. - - **rules.nonResourceRules.verbs** ([]string), required + - **rules.nonResourceRules.verbs** ([]string), required - *Set: unique values will be kept during a merge* - - `verbs` is a list of matching verbs and may not be empty. "*" matches all verbs. If it is present, it must be the only entry. Required. + *Set: unique values will be kept during a merge* + + `verbs` is a list of matching verbs and may not be empty. "*" matches all verbs. If it is present, it must be the only entry. Required. - **rules.resourceRules** ([]ResourcePolicyRule) @@ -166,33 +166,33 @@ FlowSchemaSpec describes how the FlowSchema's specification looks like. *ResourcePolicyRule is a predicate that matches some resource requests, testing the request's verb and the target resource. A ResourcePolicyRule matches a resource request if and only if: (a) at least one member of verbs matches the request, (b) at least one member of apiGroups matches the request, (c) at least one member of resources matches the request, and (d) least one member of namespaces matches the request.* - - **rules.resourceRules.apiGroups** ([]string), required + - **rules.resourceRules.apiGroups** ([]string), required - *Set: unique values will be kept during a merge* - - `apiGroups` is a list of matching API groups and may not be empty. "*" matches all API groups and, if present, must be the only entry. Required. + *Set: unique values will be kept during a merge* + + `apiGroups` is a list of matching API groups and may not be empty. "*" matches all API groups and, if present, must be the only entry. Required. - - **rules.resourceRules.resources** ([]string), required + - **rules.resourceRules.resources** ([]string), required - *Set: unique values will be kept during a merge* - - `resources` is a list of matching resources (i.e., lowercase and plural) with, if desired, subresource. For example, [ "services", "nodes/status" ]. This list may not be empty. "*" matches all resources and, if present, must be the only entry. Required. + *Set: unique values will be kept during a merge* + + `resources` is a list of matching resources (i.e., lowercase and plural) with, if desired, subresource. For example, [ "services", "nodes/status" ]. This list may not be empty. "*" matches all resources and, if present, must be the only entry. Required. - - **rules.resourceRules.verbs** ([]string), required + - **rules.resourceRules.verbs** ([]string), required - *Set: unique values will be kept during a merge* - - `verbs` is a list of matching verbs and may not be empty. "*" matches all verbs and, if present, must be the only entry. Required. + *Set: unique values will be kept during a merge* + + `verbs` is a list of matching verbs and may not be empty. "*" matches all verbs and, if present, must be the only entry. Required. - - **rules.resourceRules.clusterScope** (boolean) + - **rules.resourceRules.clusterScope** (boolean) - `clusterScope` indicates whether to match requests that do not specify a namespace (which happens either because the resource is not namespaced or the request targets all namespaces). If this field is omitted or false then the `namespaces` field must contain a non-empty list. + `clusterScope` indicates whether to match requests that do not specify a namespace (which happens either because the resource is not namespaced or the request targets all namespaces). If this field is omitted or false then the `namespaces` field must contain a non-empty list. - - **rules.resourceRules.namespaces** ([]string) + - **rules.resourceRules.namespaces** ([]string) - *Set: unique values will be kept during a merge* - - `namespaces` is a list of target namespaces that restricts matches. A request that specifies a target namespace matches only if either (a) this list contains that target namespace or (b) this list contains "*". Note that "*" matches any specified namespace but does not match a request that _does not specify_ a namespace (see the `clusterScope` field for that). This list may be empty, but only if `clusterScope` is true. + *Set: unique values will be kept during a merge* + + `namespaces` is a list of target namespaces that restricts matches. A request that specifies a target namespace matches only if either (a) this list contains that target namespace or (b) this list contains "*". Note that "*" matches any specified namespace but does not match a request that _does not specify_ a namespace (see the `clusterScope` field for that). This list may be empty, but only if `clusterScope` is true. diff --git a/content/en/docs/reference/kubernetes-api/cluster-resources/node-v1.md b/content/en/docs/reference/kubernetes-api/cluster-resources/node-v1.md index a5e796904f..d48dc829ab 100644 --- a/content/en/docs/reference/kubernetes-api/cluster-resources/node-v1.md +++ b/content/en/docs/reference/kubernetes-api/cluster-resources/node-v1.md @@ -62,25 +62,25 @@ NodeSpec describes the attributes that a node is created with. *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* - - **configSource.configMap.kubeletConfigKey** (string), required + - **configSource.configMap.kubeletConfigKey** (string), required - KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. + KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. - - **configSource.configMap.name** (string), required + - **configSource.configMap.name** (string), required - Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. + Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. - - **configSource.configMap.namespace** (string), required + - **configSource.configMap.namespace** (string), required - Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. + Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. - - **configSource.configMap.resourceVersion** (string) + - **configSource.configMap.resourceVersion** (string) - ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - - **configSource.configMap.uid** (string) + - **configSource.configMap.uid** (string) - UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - **externalID** (string) @@ -216,32 +216,32 @@ NodeStatus is information about the current status of a node. *NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.* - - **config.active.configMap** (ConfigMapNodeConfigSource) + - **config.active.configMap** (ConfigMapNodeConfigSource) - ConfigMap is a reference to a Node's ConfigMap + ConfigMap is a reference to a Node's ConfigMap - - *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* + + *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* - - **config.active.configMap.kubeletConfigKey** (string), required + - **config.active.configMap.kubeletConfigKey** (string), required - KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. + KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. - - **config.active.configMap.name** (string), required + - **config.active.configMap.name** (string), required - Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. + Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. - - **config.active.configMap.namespace** (string), required + - **config.active.configMap.namespace** (string), required - Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. + Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. - - **config.active.configMap.resourceVersion** (string) + - **config.active.configMap.resourceVersion** (string) - ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - - **config.active.configMap.uid** (string) + - **config.active.configMap.uid** (string) - UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - **config.assigned** (NodeConfigSource) @@ -250,32 +250,32 @@ NodeStatus is information about the current status of a node. *NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.* - - **config.assigned.configMap** (ConfigMapNodeConfigSource) + - **config.assigned.configMap** (ConfigMapNodeConfigSource) - ConfigMap is a reference to a Node's ConfigMap + ConfigMap is a reference to a Node's ConfigMap - - *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* + + *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* - - **config.assigned.configMap.kubeletConfigKey** (string), required + - **config.assigned.configMap.kubeletConfigKey** (string), required - KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. + KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. - - **config.assigned.configMap.name** (string), required + - **config.assigned.configMap.name** (string), required - Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. + Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. - - **config.assigned.configMap.namespace** (string), required + - **config.assigned.configMap.namespace** (string), required - Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. + Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. - - **config.assigned.configMap.resourceVersion** (string) + - **config.assigned.configMap.resourceVersion** (string) - ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - - **config.assigned.configMap.uid** (string) + - **config.assigned.configMap.uid** (string) - UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - **config.error** (string) @@ -288,32 +288,32 @@ NodeStatus is information about the current status of a node. *NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil.* - - **config.lastKnownGood.configMap** (ConfigMapNodeConfigSource) + - **config.lastKnownGood.configMap** (ConfigMapNodeConfigSource) - ConfigMap is a reference to a Node's ConfigMap + ConfigMap is a reference to a Node's ConfigMap - - *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* + + *ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node.* - - **config.lastKnownGood.configMap.kubeletConfigKey** (string), required + - **config.lastKnownGood.configMap.kubeletConfigKey** (string), required - KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. + KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. - - **config.lastKnownGood.configMap.name** (string), required + - **config.lastKnownGood.configMap.name** (string), required - Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. + Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. - - **config.lastKnownGood.configMap.namespace** (string), required + - **config.lastKnownGood.configMap.namespace** (string), required - Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. + Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. - - **config.lastKnownGood.configMap.resourceVersion** (string) + - **config.lastKnownGood.configMap.resourceVersion** (string) - ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - - **config.lastKnownGood.configMap.uid** (string) + - **config.lastKnownGood.configMap.uid** (string) - UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. + UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - **daemonEndpoints** (NodeDaemonEndpoints) @@ -329,9 +329,9 @@ NodeStatus is information about the current status of a node. *DaemonEndpoint contains information about a single Daemon endpoint.* - - **daemonEndpoints.kubeletEndpoint.Port** (int32), required + - **daemonEndpoints.kubeletEndpoint.Port** (int32), required - Port number of the given endpoint. + Port number of the given endpoint. - **images** ([]ContainerImage) diff --git a/content/en/docs/reference/kubernetes-api/cluster-resources/priority-level-configuration-v1beta1.md b/content/en/docs/reference/kubernetes-api/cluster-resources/priority-level-configuration-v1beta1.md index f5776972a0..073da2a28a 100644 --- a/content/en/docs/reference/kubernetes-api/cluster-resources/priority-level-configuration-v1beta1.md +++ b/content/en/docs/reference/kubernetes-api/cluster-resources/priority-level-configuration-v1beta1.md @@ -76,28 +76,28 @@ PriorityLevelConfigurationSpec specifies the configuration of a priority level. *LimitResponse defines how to handle requests that can not be executed right now.* - - **limited.limitResponse.type** (string), required + - **limited.limitResponse.type** (string), required - `type` is "Queue" or "Reject". "Queue" means that requests that can not be executed upon arrival are held in a queue until they can be executed or a queuing limit is reached. "Reject" means that requests that can not be executed upon arrival are rejected. Required. + `type` is "Queue" or "Reject". "Queue" means that requests that can not be executed upon arrival are held in a queue until they can be executed or a queuing limit is reached. "Reject" means that requests that can not be executed upon arrival are rejected. Required. - - **limited.limitResponse.queuing** (QueuingConfiguration) + - **limited.limitResponse.queuing** (QueuingConfiguration) - `queuing` holds the configuration parameters for queuing. This field may be non-empty only if `type` is `"Queue"`. + `queuing` holds the configuration parameters for queuing. This field may be non-empty only if `type` is `"Queue"`. - - *QueuingConfiguration holds the configuration parameters for queuing* + + *QueuingConfiguration holds the configuration parameters for queuing* - - **limited.limitResponse.queuing.handSize** (int32) + - **limited.limitResponse.queuing.handSize** (int32) - `handSize` is a small positive number that configures the shuffle sharding of requests into queues. When enqueuing a request at this priority level the request's flow identifier (a string pair) is hashed and the hash value is used to shuffle the list of queues and deal a hand of the size specified here. The request is put into one of the shortest queues in that hand. `handSize` must be no larger than `queues`, and should be significantly smaller (so that a few heavy flows do not saturate most of the queues). See the user-facing documentation for more extensive guidance on setting this field. This field has a default value of 8. + `handSize` is a small positive number that configures the shuffle sharding of requests into queues. When enqueuing a request at this priority level the request's flow identifier (a string pair) is hashed and the hash value is used to shuffle the list of queues and deal a hand of the size specified here. The request is put into one of the shortest queues in that hand. `handSize` must be no larger than `queues`, and should be significantly smaller (so that a few heavy flows do not saturate most of the queues). See the user-facing documentation for more extensive guidance on setting this field. This field has a default value of 8. - - **limited.limitResponse.queuing.queueLengthLimit** (int32) + - **limited.limitResponse.queuing.queueLengthLimit** (int32) - `queueLengthLimit` is the maximum number of requests allowed to be waiting in a given queue of this priority level at a time; excess requests are rejected. This value must be positive. If not specified, it will be defaulted to 50. + `queueLengthLimit` is the maximum number of requests allowed to be waiting in a given queue of this priority level at a time; excess requests are rejected. This value must be positive. If not specified, it will be defaulted to 50. - - **limited.limitResponse.queuing.queues** (int32) + - **limited.limitResponse.queuing.queues** (int32) - `queues` is the number of queues for this priority level. The queues exist independently at each apiserver. The value must be positive. Setting it to 1 effectively precludes shufflesharding and thus makes the distinguisher method of associated flow schemas irrelevant. This field has a default value of 64. + `queues` is the number of queues for this priority level. The queues exist independently at each apiserver. The value must be positive. Setting it to 1 effectively precludes shufflesharding and thus makes the distinguisher method of associated flow schemas irrelevant. This field has a default value of 64. diff --git a/content/en/docs/reference/kubernetes-api/cluster-resources/runtime-class-v1.md b/content/en/docs/reference/kubernetes-api/cluster-resources/runtime-class-v1.md index 040c894ae3..8b08e83dd3 100644 --- a/content/en/docs/reference/kubernetes-api/cluster-resources/runtime-class-v1.md +++ b/content/en/docs/reference/kubernetes-api/cluster-resources/runtime-class-v1.md @@ -67,25 +67,25 @@ RuntimeClass defines a class of container runtime supported in the cluster. The *The pod this Toleration is attached to tolerates any taint that matches the triple using the matching operator .* - - **scheduling.tolerations.key** (string) + - **scheduling.tolerations.key** (string) - Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. + Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - - **scheduling.tolerations.operator** (string) + - **scheduling.tolerations.operator** (string) - Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. + Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - - **scheduling.tolerations.value** (string) + - **scheduling.tolerations.value** (string) - Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. + Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - - **scheduling.tolerations.effect** (string) + - **scheduling.tolerations.effect** (string) - Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. + Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - - **scheduling.tolerations.tolerationSeconds** (int64) + - **scheduling.tolerations.tolerationSeconds** (int64) - TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. + TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/label-selector.md b/content/en/docs/reference/kubernetes-api/common-definitions/label-selector.md index a588677077..58d94dd5b8 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/label-selector.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/label-selector.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "A label selector is a label query over a set of resources." title: "LabelSelector" -weight: 7 +weight: 2 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/list-meta.md b/content/en/docs/reference/kubernetes-api/common-definitions/list-meta.md index 0b703734b0..af9749a02c 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/list-meta.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/list-meta.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ListMeta describes metadata that synthetic resources must have, including lists and various status objects." title: "ListMeta" -weight: 8 +weight: 3 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/local-object-reference.md b/content/en/docs/reference/kubernetes-api/common-definitions/local-object-reference.md index e97b84aca9..83d4d046b1 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/local-object-reference.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/local-object-reference.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace." title: "LocalObjectReference" -weight: 9 +weight: 4 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md b/content/en/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md index 3e8b935ef7..ad5c95bf4c 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values." title: "NodeSelectorRequirement" -weight: 11 +weight: 5 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/object-field-selector.md b/content/en/docs/reference/kubernetes-api/common-definitions/object-field-selector.md index c109fa3fdf..ba4cf37ef0 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/object-field-selector.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/object-field-selector.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ObjectFieldSelector selects an APIVersioned field of an object." title: "ObjectFieldSelector" -weight: 12 +weight: 6 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/object-meta.md b/content/en/docs/reference/kubernetes-api/common-definitions/object-meta.md index b3bc31e716..46361d861b 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/object-meta.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/object-meta.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create." title: "ObjectMeta" -weight: 13 +weight: 7 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/object-reference.md b/content/en/docs/reference/kubernetes-api/common-definitions/object-reference.md index 71c40a0702..b1ae24f612 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/object-reference.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/object-reference.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ObjectReference contains enough information to let you inspect or modify the referred object." title: "ObjectReference" -weight: 14 +weight: 8 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/patch.md b/content/en/docs/reference/kubernetes-api/common-definitions/patch.md index 054508e807..eaf37c8d15 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/patch.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/patch.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "Patch is provided to give a concrete name and type to the Kubernetes PATCH request body." title: "Patch" -weight: 15 +weight: 9 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/quantity.md b/content/en/docs/reference/kubernetes-api/common-definitions/quantity.md index c049cd40e4..f0386bb66f 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/quantity.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/quantity.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "Quantity is a fixed-point representation of a number." title: "Quantity" -weight: 18 +weight: 10 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/resource-field-selector.md b/content/en/docs/reference/kubernetes-api/common-definitions/resource-field-selector.md index 85e7a9a814..3d3b8d68a3 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/resource-field-selector.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/resource-field-selector.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ResourceFieldSelector represents container resources (cpu, memory) and their output format." title: "ResourceFieldSelector" -weight: 19 +weight: 11 --- diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/status.md b/content/en/docs/reference/kubernetes-api/common-definitions/status.md index 634e5068fb..a134ed1407 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/status.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/status.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "Status is a return value for calls that don't return other objects." title: "Status" -weight: 20 +weight: 12 --- @@ -40,21 +40,21 @@ Status is a return value for calls that don't return other objects. *StatusCause provides more information about an api.Status failure, including cases when multiple errors are encountered.* - - **details.causes.field** (string) + - **details.causes.field** (string) - The field of the resource that has caused this error, as named by its JSON serialization. May include dot and postfix notation for nested attributes. Arrays are zero-indexed. Fields may appear more than once in an array of causes due to fields having multiple errors. Optional. - - Examples: - "name" - the field "name" on the current resource - "items[0].name" - the field "name" on the first array entry in "items" + The field of the resource that has caused this error, as named by its JSON serialization. May include dot and postfix notation for nested attributes. Arrays are zero-indexed. Fields may appear more than once in an array of causes due to fields having multiple errors. Optional. + + Examples: + "name" - the field "name" on the current resource + "items[0].name" - the field "name" on the first array entry in "items" - - **details.causes.message** (string) + - **details.causes.message** (string) - A human-readable description of the cause of the error. This field may be presented as-is to a reader. + A human-readable description of the cause of the error. This field may be presented as-is to a reader. - - **details.causes.reason** (string) + - **details.causes.reason** (string) - A machine-readable description of the cause of the error. If this value is empty there is no information available. + A machine-readable description of the cause of the error. If this value is empty there is no information available. - **details.group** (string) diff --git a/content/en/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md b/content/en/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md index c03c3c8409..2ec9fd5176 100644 --- a/content/en/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md +++ b/content/en/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the same namespace." title: "TypedLocalObjectReference" -weight: 22 +weight: 13 --- diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1.md index b543e6c9ac..7d7dac6bf0 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1.md @@ -40,7 +40,7 @@ ConfigMap holds configuration data for pods to consume. - **immutable** (boolean) - Immutable, if set to true, ensures that data stored in the ConfigMap cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. This is a beta field enabled by ImmutableEphemeralVolumes feature gate. + Immutable, if set to true, ensures that data stored in the ConfigMap cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md index b1c634b6b2..ddcef415e8 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-driver-v1.md @@ -47,17 +47,23 @@ CSIDriverSpec is the specification of a CSIDriver. - **attachRequired** (boolean) attachRequired indicates this CSI volume driver requires an attach operation (because it implements the CSI ControllerPublishVolume() method), and that the Kubernetes attach detach controller should call the attach volume interface which checks the volumeattachment status and waits until the volume is attached before proceeding to mounting. The CSI external-attacher coordinates with CSI volume driver and updates the volumeattachment status when the attach operation is complete. If the CSIDriverRegistry feature gate is enabled and the value is specified to false, the attach operation will be skipped. Otherwise the attach operation will be called. + + This field is immutable. - **fsGroupPolicy** (string) Defines if the underlying volume supports changing ownership and permission of the volume before being mounted. Refer to the specific FSGroupPolicy values for additional details. This field is alpha-level, and is only honored by servers that enable the CSIVolumeFSGroupPolicy feature gate. + + This field is immutable. - **podInfoOnMount** (boolean) - If set to true, podInfoOnMount indicates this CSI volume driver requires additional pod information (like podName, podUID, etc.) during mount operations. If set to false, pod information will not be passed on mount. Default is false. The CSI driver specifies podInfoOnMount as part of driver deployment. If true, Kubelet will pass pod information as VolumeContext in the CSI NodePublishVolume() calls. The CSI driver is responsible for parsing and validating the information passed in as VolumeContext. The following VolumeConext will be passed if podInfoOnMount is set to true. This list might grow, but the prefix will be used. "csi.storage.k8s.io/pod.name": pod.Name "csi.storage.k8s.io/pod.namespace": pod.Namespace "csi.storage.k8s.io/pod.uid": string(pod.UID) "csi.storage.k8s.io/ephemeral": "true" iff the volume is an ephemeral inline volume + If set to true, podInfoOnMount indicates this CSI volume driver requires additional pod information (like podName, podUID, etc.) during mount operations. If set to false, pod information will not be passed on mount. Default is false. The CSI driver specifies podInfoOnMount as part of driver deployment. If true, Kubelet will pass pod information as VolumeContext in the CSI NodePublishVolume() calls. The CSI driver is responsible for parsing and validating the information passed in as VolumeContext. The following VolumeConext will be passed if podInfoOnMount is set to true. This list might grow, but the prefix will be used. "csi.storage.k8s.io/pod.name": pod.Name "csi.storage.k8s.io/pod.namespace": pod.Namespace "csi.storage.k8s.io/pod.uid": string(pod.UID) "csi.storage.k8s.io/ephemeral": "true" if the volume is an ephemeral inline volume defined by a CSIVolumeSource, otherwise "false" "csi.storage.k8s.io/ephemeral" is a new feature in Kubernetes 1.16. It is only required for drivers which support both the "Persistent" and "Ephemeral" VolumeLifecycleMode. Other drivers can leave pod info disabled and/or ignore this field. As Kubernetes 1.15 doesn't support this field, drivers can only support one mode when deployed on such a cluster and the deployment determines which mode that is, for example via a command line parameter of the driver. + + This field is immutable. - **requiresRepublish** (boolean) @@ -65,7 +71,7 @@ CSIDriverSpec is the specification of a CSIDriver. Note: After a successful initial NodePublishVolume call, subsequent calls to NodePublishVolume should only update the contents of the volume. New mount points will not be seen by a running container. - This is an alpha feature and only available when the CSIServiceAccountToken feature is enabled. + This is a beta feature and only available when the CSIServiceAccountToken feature is enabled. - **storageCapacity** (boolean) @@ -75,7 +81,9 @@ CSIDriverSpec is the specification of a CSIDriver. Alternatively, the driver can be deployed with the field unset or false and it can be flipped later when storage capacity information has been published. - This is an alpha field and only available when the CSIStorageCapacity feature is enabled. The default is false. + This field is immutable. + + This is a beta field and only available when the CSIStorageCapacity feature is enabled. The default is false. - **tokenRequests** ([]TokenRequest) @@ -91,7 +99,7 @@ CSIDriverSpec is the specification of a CSIDriver. Note: Audience in each TokenRequest should be different and at most one token is empty string. To receive a new token after expiry, RequiresRepublish can be used to trigger NodePublishVolume periodically. - This is an alpha feature and only available when the CSIServiceAccountToken feature is enabled. + This is a beta feature and only available when the CSIServiceAccountToken feature is enabled. *TokenRequest contains parameters of a service account token.* @@ -109,6 +117,8 @@ CSIDriverSpec is the specification of a CSIDriver. *Set: unique values will be kept during a merge* volumeLifecycleModes defines what kind of volumes this CSI volume driver supports. The default if the list is empty is "Persistent", which is the usage defined by the CSI specification and implemented in Kubernetes via the usual PV/PVC mechanism. The other mode is "Ephemeral". In this mode, volumes are defined inline inside the pod spec with CSIVolumeSource and their lifecycle is tied to the lifecycle of that pod. A driver has to be aware of this because it is only going to get a NodePublishVolume call for such a volume. For more information about implementing this mode, see https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html A driver can support one or more of these modes and more modes may be added in the future. This field is beta. + + This field is immutable. diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-node-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-node-v1.md index aaee041979..d918d4568f 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-node-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-node-v1.md @@ -68,9 +68,9 @@ CSINodeSpec holds information about the specification of all CSI drivers install *VolumeNodeResources is a set of resource limits for scheduling of volumes.* - - **drivers.allocatable.count** (int32) + - **drivers.allocatable.count** (int32) - Maximum number of unique volumes managed by the CSI driver that can be used on a node. A volume that is both attached and mounted on a node is considered to be used once, not twice. The same rule applies for a unique volume that is shared among multiple pods on the same node. If this field is not specified, then the supported number of volumes on this node is unbounded. + Maximum number of unique volumes managed by the CSI driver that can be used on a node. A volume that is both attached and mounted on a node is considered to be used once, not twice. The same rule applies for a unique volume that is shared among multiple pods on the same node. If this field is not specified, then the supported number of volumes on this node is unbounded. - **drivers.topologyKeys** ([]string) diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-storage-capacity-v1beta1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-storage-capacity-v1beta1.md new file mode 100644 index 0000000000..1b619a0ef2 --- /dev/null +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/csi-storage-capacity-v1beta1.md @@ -0,0 +1,566 @@ +--- +api_metadata: + apiVersion: "storage.k8s.io/v1beta1" + import: "k8s.io/api/storage/v1beta1" + kind: "CSIStorageCapacity" +content_type: "api_reference" +description: "CSIStorageCapacity stores the result of one CSI GetCapacity call." +title: "CSIStorageCapacity v1beta1" +weight: 10 +--- + +`apiVersion: storage.k8s.io/v1beta1` + +`import "k8s.io/api/storage/v1beta1"` + + +## CSIStorageCapacity {#CSIStorageCapacity} + +CSIStorageCapacity stores the result of one CSI GetCapacity call. For a given StorageClass, this describes the available capacity in a particular topology segment. This can be used when considering where to instantiate new PersistentVolumes. + +For example this can express things like: - StorageClass "standard" has "1234 GiB" available in "topology.kubernetes.io/zone=us-east1" - StorageClass "localssd" has "10 GiB" available in "kubernetes.io/hostname=knode-abc123" + +The following three cases all imply that no capacity is available for a certain combination: - no object exists with suitable topology and storage class name - such an object exists, but the capacity is unset - such an object exists, but the capacity is zero + +The producer of these objects can decide which approach is more suitable. + +They are consumed by the kube-scheduler if the CSIStorageCapacity beta feature gate is enabled there and a CSI driver opts into capacity-aware scheduling with CSIDriver.StorageCapacity. + +
+ +- **apiVersion**: storage.k8s.io/v1beta1 + + +- **kind**: CSIStorageCapacity + + +- **metadata** (}}">ObjectMeta) + + Standard object's metadata. The name has no particular meaning. It must be be a DNS subdomain (dots allowed, 253 characters). To ensure that there are no conflicts with other CSI drivers on the cluster, the recommendation is to use csisc-\, a generated name, or a reverse-domain name which ends with the unique CSI driver name. + + Objects are namespaced. + + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +- **storageClassName** (string), required + + The name of the StorageClass that the reported capacity applies to. It must meet the same requirements as the name of a StorageClass object (non-empty, DNS subdomain). If that object no longer exists, the CSIStorageCapacity object is obsolete and should be removed by its creator. This field is immutable. + +- **capacity** (}}">Quantity) + + Capacity is the value reported by the CSI driver in its GetCapacityResponse for a GetCapacityRequest with topology and parameters that match the previous fields. + + The semantic is currently (CSI spec 1.2) defined as: The available capacity, in bytes, of the storage that can be used to provision volumes. If not set, that information is currently unavailable and treated like zero capacity. + +- **maximumVolumeSize** (}}">Quantity) + + MaximumVolumeSize is the value reported by the CSI driver in its GetCapacityResponse for a GetCapacityRequest with topology and parameters that match the previous fields. + + This is defined since CSI spec 1.4.0 as the largest size that may be used in a CreateVolumeRequest.capacity_range.required_bytes field to create a volume with the same parameters as those in GetCapacityRequest. The corresponding value in the Kubernetes API is ResourceRequirements.Requests in a volume claim. + +- **nodeTopology** (}}">LabelSelector) + + NodeTopology defines which nodes have access to the storage for which capacity was reported. If not set, the storage is not accessible from any node in the cluster. If empty, the storage is accessible from all nodes. This field is immutable. + + + + + +## CSIStorageCapacityList {#CSIStorageCapacityList} + +CSIStorageCapacityList is a collection of CSIStorageCapacity objects. + +
+ +- **apiVersion**: storage.k8s.io/v1beta1 + + +- **kind**: CSIStorageCapacityList + + +- **metadata** (}}">ListMeta) + + Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +- **items** ([]}}">CSIStorageCapacity), required + + *Map: unique values on key name will be kept during a merge* + + Items is the list of CSIStorageCapacity objects. + + + + + +## Operations {#Operations} + + + +
+ + + + + + +### `get` read the specified CSIStorageCapacity + +#### HTTP Request + +GET /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CSIStorageCapacity + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CSIStorageCapacity): OK + +401: Unauthorized + + +### `list` list or watch objects of kind CSIStorageCapacity + +#### HTTP Request + +GET /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">CSIStorageCapacityList): OK + +401: Unauthorized + + +### `list` list or watch objects of kind CSIStorageCapacity + +#### HTTP Request + +GET /apis/storage.k8s.io/v1beta1/csistoragecapacities + +#### Parameters + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">CSIStorageCapacityList): OK + +401: Unauthorized + + +### `create` create a CSIStorageCapacity + +#### HTTP Request + +POST /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">CSIStorageCapacity, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CSIStorageCapacity): OK + +201 (}}">CSIStorageCapacity): Created + +202 (}}">CSIStorageCapacity): Accepted + +401: Unauthorized + + +### `update` replace the specified CSIStorageCapacity + +#### HTTP Request + +PUT /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CSIStorageCapacity + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">CSIStorageCapacity, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CSIStorageCapacity): OK + +201 (}}">CSIStorageCapacity): Created + +401: Unauthorized + + +### `patch` partially update the specified CSIStorageCapacity + +#### HTTP Request + +PATCH /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CSIStorageCapacity + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CSIStorageCapacity): OK + +401: Unauthorized + + +### `delete` delete a CSIStorageCapacity + +#### HTTP Request + +DELETE /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CSIStorageCapacity + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + + +#### Response + + +200 (}}">Status): OK + +202 (}}">Status): Accepted + +401: Unauthorized + + +### `deletecollection` delete collection of CSIStorageCapacity + +#### HTTP Request + +DELETE /apis/storage.k8s.io/v1beta1/namespaces/{namespace}/csistoragecapacities + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **continue** (*in query*): string + + }}">continue + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + + +#### Response + + +200 (}}">Status): OK + +401: Unauthorized + diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1.md index 23b4f3214e..b05083deb4 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1.md @@ -65,11 +65,11 @@ PersistentVolumeClaimSpec describes the common attributes of storage devices and - **resources.limits** (map[string]}}">Quantity) - Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ + Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ - **resources.requests** (map[string]}}">Quantity) - Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ + Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ - **volumeName** (string) diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1.md index cbc4a613d5..e02238f3ad 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1.md @@ -78,20 +78,20 @@ PersistentVolumeSpec is the specification of a persistent volume. *A node selector represents the union of the results of one or more label queries over a set of nodes; that is, it represents the OR of the selectors represented by the node selector terms.* - - **nodeAffinity.required.nodeSelectorTerms** ([]NodeSelectorTerm), required + - **nodeAffinity.required.nodeSelectorTerms** ([]NodeSelectorTerm), required - Required. A list of node selector terms. The terms are ORed. + Required. A list of node selector terms. The terms are ORed. - - *A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.* + + *A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.* - - **nodeAffinity.required.nodeSelectorTerms.matchExpressions** ([]}}">NodeSelectorRequirement) + - **nodeAffinity.required.nodeSelectorTerms.matchExpressions** ([]}}">NodeSelectorRequirement) - A list of node selector requirements by node's labels. + A list of node selector requirements by node's labels. - - **nodeAffinity.required.nodeSelectorTerms.matchFields** ([]}}">NodeSelectorRequirement) + - **nodeAffinity.required.nodeSelectorTerms.matchFields** ([]}}">NodeSelectorRequirement) - A list of node selector requirements by node's fields. + A list of node selector requirements by node's fields. - **persistentVolumeReclaimPolicy** (string) @@ -252,13 +252,13 @@ PersistentVolumeSpec is the specification of a persistent volume. *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - **cephfs.secretRef.name** (string) + - **cephfs.secretRef.name** (string) - Name is unique within a namespace to reference a secret resource. + Name is unique within a namespace to reference a secret resource. - - **cephfs.secretRef.namespace** (string) + - **cephfs.secretRef.namespace** (string) - Namespace defines the space within which the secret name must be unique. + Namespace defines the space within which the secret name must be unique. - **cephfs.user** (string) @@ -290,13 +290,100 @@ PersistentVolumeSpec is the specification of a persistent volume. *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - **cinder.secretRef.name** (string) + - **cinder.secretRef.name** (string) - Name is unique within a namespace to reference a secret resource. + Name is unique within a namespace to reference a secret resource. - - **cinder.secretRef.namespace** (string) + - **cinder.secretRef.namespace** (string) - Namespace defines the space within which the secret name must be unique. + Namespace defines the space within which the secret name must be unique. + +- **csi** (CSIPersistentVolumeSource) + + CSI represents storage that is handled by an external CSI driver (Beta feature). + + + *Represents storage that is managed by an external CSI volume driver (Beta feature)* + + - **csi.driver** (string), required + + Driver is the name of the driver to use for this volume. Required. + + - **csi.volumeHandle** (string), required + + VolumeHandle is the unique volume name returned by the CSI volume plugin’s CreateVolume to refer to the volume on all subsequent calls. Required. + + - **csi.controllerExpandSecretRef** (SecretReference) + + ControllerExpandSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI ControllerExpandVolume call. This is an alpha field and requires enabling ExpandCSIVolumes feature gate. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. + + + *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* + + - **csi.controllerExpandSecretRef.name** (string) + + Name is unique within a namespace to reference a secret resource. + + - **csi.controllerExpandSecretRef.namespace** (string) + + Namespace defines the space within which the secret name must be unique. + + - **csi.controllerPublishSecretRef** (SecretReference) + + ControllerPublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI ControllerPublishVolume and ControllerUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. + + + *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* + + - **csi.controllerPublishSecretRef.name** (string) + + Name is unique within a namespace to reference a secret resource. + + - **csi.controllerPublishSecretRef.namespace** (string) + + Namespace defines the space within which the secret name must be unique. + + - **csi.fsType** (string) + + Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". + + - **csi.nodePublishSecretRef** (SecretReference) + + NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. + + + *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* + + - **csi.nodePublishSecretRef.name** (string) + + Name is unique within a namespace to reference a secret resource. + + - **csi.nodePublishSecretRef.namespace** (string) + + Namespace defines the space within which the secret name must be unique. + + - **csi.nodeStageSecretRef** (SecretReference) + + NodeStageSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodeStageVolume and NodeStageVolume and NodeUnstageVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. + + + *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* + + - **csi.nodeStageSecretRef.name** (string) + + Name is unique within a namespace to reference a secret resource. + + - **csi.nodeStageSecretRef.namespace** (string) + + Namespace defines the space within which the secret name must be unique. + + - **csi.readOnly** (boolean) + + Optional: The value to pass to ControllerPublishVolumeRequest. Defaults to false (read/write). + + - **csi.volumeAttributes** (map[string]string) + + Attributes of the volume to publish. - **fc** (FCVolumeSource) @@ -355,13 +442,13 @@ PersistentVolumeSpec is the specification of a persistent volume. *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - **flexVolume.secretRef.name** (string) + - **flexVolume.secretRef.name** (string) - Name is unique within a namespace to reference a secret resource. + Name is unique within a namespace to reference a secret resource. - - **flexVolume.secretRef.namespace** (string) + - **flexVolume.secretRef.namespace** (string) - Namespace defines the space within which the secret name must be unique. + Namespace defines the space within which the secret name must be unique. - **flocker** (FlockerVolumeSource) @@ -480,13 +567,13 @@ PersistentVolumeSpec is the specification of a persistent volume. *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - **iscsi.secretRef.name** (string) + - **iscsi.secretRef.name** (string) - Name is unique within a namespace to reference a secret resource. + Name is unique within a namespace to reference a secret resource. - - **iscsi.secretRef.namespace** (string) + - **iscsi.secretRef.namespace** (string) - Namespace defines the space within which the secret name must be unique. + Namespace defines the space within which the secret name must be unique. - **nfs** (NFSVolumeSource) @@ -610,13 +697,13 @@ PersistentVolumeSpec is the specification of a persistent volume. *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - **rbd.secretRef.name** (string) + - **rbd.secretRef.name** (string) - Name is unique within a namespace to reference a secret resource. + Name is unique within a namespace to reference a secret resource. - - **rbd.secretRef.namespace** (string) + - **rbd.secretRef.namespace** (string) - Namespace defines the space within which the secret name must be unique. + Namespace defines the space within which the secret name must be unique. - **rbd.user** (string) @@ -640,13 +727,13 @@ PersistentVolumeSpec is the specification of a persistent volume. *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - **scaleIO.secretRef.name** (string) + - **scaleIO.secretRef.name** (string) - Name is unique within a namespace to reference a secret resource. + Name is unique within a namespace to reference a secret resource. - - **scaleIO.secretRef.namespace** (string) + - **scaleIO.secretRef.namespace** (string) - Namespace defines the space within which the secret name must be unique. + Namespace defines the space within which the secret name must be unique. - **scaleIO.system** (string), required @@ -730,96 +817,6 @@ PersistentVolumeSpec is the specification of a persistent volume. Storage Policy Based Management (SPBM) profile name. -### Beta level - - -- **csi** (CSIPersistentVolumeSource) - - CSI represents storage that is handled by an external CSI driver (Beta feature). - - - *Represents storage that is managed by an external CSI volume driver (Beta feature)* - - - **csi.driver** (string), required - - Driver is the name of the driver to use for this volume. Required. - - - **csi.volumeHandle** (string), required - - VolumeHandle is the unique volume name returned by the CSI volume plugin’s CreateVolume to refer to the volume on all subsequent calls. Required. - - - **csi.controllerExpandSecretRef** (SecretReference) - - ControllerExpandSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI ControllerExpandVolume call. This is an alpha field and requires enabling ExpandCSIVolumes feature gate. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - - - *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - - **csi.controllerExpandSecretRef.name** (string) - - Name is unique within a namespace to reference a secret resource. - - - **csi.controllerExpandSecretRef.namespace** (string) - - Namespace defines the space within which the secret name must be unique. - - - **csi.controllerPublishSecretRef** (SecretReference) - - ControllerPublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI ControllerPublishVolume and ControllerUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - - - *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - - **csi.controllerPublishSecretRef.name** (string) - - Name is unique within a namespace to reference a secret resource. - - - **csi.controllerPublishSecretRef.namespace** (string) - - Namespace defines the space within which the secret name must be unique. - - - **csi.fsType** (string) - - Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". - - - **csi.nodePublishSecretRef** (SecretReference) - - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - - - *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - - **csi.nodePublishSecretRef.name** (string) - - Name is unique within a namespace to reference a secret resource. - - - **csi.nodePublishSecretRef.namespace** (string) - - Namespace defines the space within which the secret name must be unique. - - - **csi.nodeStageSecretRef** (SecretReference) - - NodeStageSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodeStageVolume and NodeStageVolume and NodeUnstageVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - - - *SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace* - - - **csi.nodeStageSecretRef.name** (string) - - Name is unique within a namespace to reference a secret resource. - - - **csi.nodeStageSecretRef.namespace** (string) - - Namespace defines the space within which the secret name must be unique. - - - **csi.readOnly** (boolean) - - Optional: The value to pass to ControllerPublishVolumeRequest. Defaults to false (read/write). - - - **csi.volumeAttributes** (map[string]string) - - Attributes of the volume to publish. - ## PersistentVolumeStatus {#PersistentVolumeStatus} diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1.md index 84d9a08c0f..8dd7eb4a48 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1.md @@ -36,11 +36,11 @@ Secret holds secret data of a certain type. The total bytes of the values in the - **immutable** (boolean) - Immutable, if set to true, ensures that data stored in the Secret cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. This is a beta field enabled by ImmutableEphemeralVolumes feature gate. + Immutable, if set to true, ensures that data stored in the Secret cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. - **stringData** (map[string]string) - stringData allows specifying non-binary secret data in string form. It is provided as a write-only convenience method. All keys and values are merged into the data field on write, overwriting any existing values. It is never output when reading from the API. + stringData allows specifying non-binary secret data in string form. It is provided as a write-only input field for convenience. All keys and values are merged into the data field on write, overwriting any existing values. The stringData field is never output when reading from the API. - **type** (string) diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1.md index 752735f6f6..24d9636d49 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1.md @@ -54,13 +54,13 @@ StorageClasses are non-namespaced; the name of the storage class according to et *A topology selector requirement is a selector that matches given label. This is an alpha feature and may change in the future.* - - **allowedTopologies.matchLabelExpressions.key** (string), required + - **allowedTopologies.matchLabelExpressions.key** (string), required - The label key that the selector applies to. + The label key that the selector applies to. - - **allowedTopologies.matchLabelExpressions.values** ([]string), required + - **allowedTopologies.matchLabelExpressions.values** ([]string), required - An array of string values. One value must match the label to be selected. Each entry in Values is ORed. + An array of string values. One value must match the label to be selected. Each entry in Values is ORed. - **mountOptions** ([]string) diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume-attachment-v1.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume-attachment-v1.md index 95102c3988..8e83398b69 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume-attachment-v1.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume-attachment-v1.md @@ -67,7 +67,7 @@ VolumeAttachmentSpec is the specification of a VolumeAttachment request. - **source.inlineVolumeSpec** (}}">PersistentVolumeSpec) - inlineVolumeSpec contains all the information necessary to attach a persistent volume defined by a pod's inline VolumeSource. This field is populated only for the CSIMigration feature. It contains translated fields from a pod's inline VolumeSource to a PersistentVolumeSpec. This field is alpha-level and is only honored by servers that enabled the CSIMigration feature. + inlineVolumeSpec contains all the information necessary to attach a persistent volume defined by a pod's inline VolumeSource. This field is populated only for the CSIMigration feature. It contains translated fields from a pod's inline VolumeSource to a PersistentVolumeSpec. This field is beta-level and is only honored by servers that enabled the CSIMigration feature. - **source.persistentVolumeName** (string) diff --git a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume.md b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume.md index ff45652ace..ff72bda7f0 100644 --- a/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume.md +++ b/content/en/docs/reference/kubernetes-api/config-and-storage-resources/volume.md @@ -14,6 +14,8 @@ weight: 3 `import "k8s.io/api/core/v1"` +## Volume {#Volume} + Volume represents a named volume in a pod that may be accessed by any container in the pod.
@@ -24,7 +26,7 @@ Volume represents a named volume in a pod that may be accessed by any container -### Exposed Persistent volumes {#Exposed-Persistent-volumes} +### Exposed Persistent volumes - **persistentVolumeClaim** (PersistentVolumeClaimVolumeSource) @@ -42,7 +44,7 @@ Volume represents a named volume in a pod that may be accessed by any container Will force the ReadOnly setting in VolumeMounts. Default false. -### Projections {#Projections} +### Projections - **configMap** (ConfigMapVolumeSource) @@ -66,7 +68,7 @@ Volume represents a named volume in a pod that may be accessed by any container Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - - **configMap.items** ([]}}">KeyToPath) + - **configMap.items** ([]}}">KeyToPath) If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. @@ -91,7 +93,7 @@ Volume represents a named volume in a pod that may be accessed by any container Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - - **secret.items** ([]}}">KeyToPath) + - **secret.items** ([]}}">KeyToPath) If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. @@ -106,7 +108,7 @@ Volume represents a named volume in a pod that may be accessed by any container Optional: mode bits to use on created files by default. Must be a Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - - **downwardAPI.items** ([]}}">DownwardAPIVolumeFile) + - **downwardAPI.items** ([]}}">DownwardAPIVolumeFile) Items is a list of downward API volume file @@ -128,79 +130,79 @@ Volume represents a named volume in a pod that may be accessed by any container *Projection that may be projected along with other supported volume types* - - **projected.sources.configMap** (ConfigMapProjection) + - **projected.sources.configMap** (ConfigMapProjection) - information about the configMap data to project + information about the configMap data to project - - *Adapts a ConfigMap into a projected volume. - - The contents of the target ConfigMap's Data field will be presented in a projected volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. Note that this is identical to a configmap volume source without the default mode.* + + *Adapts a ConfigMap into a projected volume. + + The contents of the target ConfigMap's Data field will be presented in a projected volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. Note that this is identical to a configmap volume source without the default mode.* - - **projected.sources.configMap.name** (string) + - **projected.sources.configMap.name** (string) - Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - - **projected.sources.configMap.optional** (boolean) + - **projected.sources.configMap.optional** (boolean) - Specify whether the ConfigMap or its keys must be defined + Specify whether the ConfigMap or its keys must be defined - - **projected.sources.configMap.items** ([]}}">KeyToPath) + - **projected.sources.configMap.items** ([]}}">KeyToPath) - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. + If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - - **projected.sources.downwardAPI** (DownwardAPIProjection) + - **projected.sources.downwardAPI** (DownwardAPIProjection) - information about the downwardAPI data to project + information about the downwardAPI data to project - - *Represents downward API info for projecting into a projected volume. Note that this is identical to a downwardAPI volume source without the default mode.* + + *Represents downward API info for projecting into a projected volume. Note that this is identical to a downwardAPI volume source without the default mode.* - - **projected.sources.downwardAPI.items** ([]}}">DownwardAPIVolumeFile) + - **projected.sources.downwardAPI.items** ([]}}">DownwardAPIVolumeFile) - Items is a list of DownwardAPIVolume file + Items is a list of DownwardAPIVolume file - - **projected.sources.secret** (SecretProjection) + - **projected.sources.secret** (SecretProjection) - information about the secret data to project + information about the secret data to project - - *Adapts a secret into a projected volume. - - The contents of the target Secret's Data field will be presented in a projected volume as files using the keys in the Data field as the file names. Note that this is identical to a secret volume source without the default mode.* + + *Adapts a secret into a projected volume. + + The contents of the target Secret's Data field will be presented in a projected volume as files using the keys in the Data field as the file names. Note that this is identical to a secret volume source without the default mode.* - - **projected.sources.secret.name** (string) + - **projected.sources.secret.name** (string) - Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - - **projected.sources.secret.optional** (boolean) + - **projected.sources.secret.optional** (boolean) - Specify whether the Secret or its key must be defined + Specify whether the Secret or its key must be defined - - **projected.sources.secret.items** ([]}}">KeyToPath) + - **projected.sources.secret.items** ([]}}">KeyToPath) - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. + If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - - **projected.sources.serviceAccountToken** (ServiceAccountTokenProjection) + - **projected.sources.serviceAccountToken** (ServiceAccountTokenProjection) - information about the serviceAccountToken data to project + information about the serviceAccountToken data to project - - *ServiceAccountTokenProjection represents a projected service account token volume. This projection can be used to insert a service account token into the pods runtime filesystem for use against APIs (Kubernetes API Server or otherwise).* + + *ServiceAccountTokenProjection represents a projected service account token volume. This projection can be used to insert a service account token into the pods runtime filesystem for use against APIs (Kubernetes API Server or otherwise).* - - **projected.sources.serviceAccountToken.path** (string), required + - **projected.sources.serviceAccountToken.path** (string), required - Path is the path relative to the mount point of the file to project the token into. + Path is the path relative to the mount point of the file to project the token into. - - **projected.sources.serviceAccountToken.audience** (string) + - **projected.sources.serviceAccountToken.audience** (string) - Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. + Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - - **projected.sources.serviceAccountToken.expirationSeconds** (int64) + - **projected.sources.serviceAccountToken.expirationSeconds** (int64) - ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. + ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. -### Local / Temporary Directory {#Local-Temporary-Directory} +### Local / Temporary Directory - **emptyDir** (EmptyDirVolumeSource) @@ -233,7 +235,7 @@ Volume represents a named volume in a pod that may be accessed by any container Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath -### Persistent volumes {#Persistent-volumes} +### Persistent volumes - **awsElasticBlockStore** (AWSElasticBlockStoreVolumeSource) @@ -365,6 +367,33 @@ Volume represents a named volume in a pod that may be accessed by any container Optional: points to a secret object containing parameters used to connect to OpenStack. +- **csi** (CSIVolumeSource) + + CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). + + + *Represents a source location of a volume to mount, managed by an external CSI driver* + + - **csi.driver** (string), required + + Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. + + - **csi.fsType** (string) + + Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. + + - **csi.nodePublishSecretRef** (}}">LocalObjectReference) + + NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. + + - **csi.readOnly** (boolean) + + Specifies a read-only configuration for the volume. Defaults to false (read/write). + + - **csi.volumeAttributes** (map[string]string) + + VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. + - **fc** (FCVolumeSource) FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. @@ -749,42 +778,12 @@ Volume represents a named volume in a pod that may be accessed by any container Storage Policy Based Management (SPBM) profile name. -### Beta level {#Beta-level} - - -- **csi** (CSIVolumeSource) - - CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). - - - *Represents a source location of a volume to mount, managed by an external CSI driver* - - - **csi.driver** (string), required - - Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - - - **csi.fsType** (string) - - Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - - - **csi.nodePublishSecretRef** (}}">LocalObjectReference) - - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - - - **csi.readOnly** (boolean) - - Specifies a read-only configuration for the volume. Defaults to false (read/write). - - - **csi.volumeAttributes** (map[string]string) - - VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -### Alpha level {#Alpha-level} +### Alpha level - **ephemeral** (EphemeralVolumeSource) - Ephemeral represents a volume that is handled by a cluster storage driver (Alpha feature). The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. + Ephemeral represents a volume that is handled by a cluster storage driver. The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity tracking are needed, @@ -798,14 +797,12 @@ Volume represents a named volume in a pod that may be accessed by any container Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information. A pod can use both types of ephemeral volumes and persistent volumes at the same time. + + This is a beta feature and only available when the GenericEphemeralVolume feature gate is enabled. *Represents an ephemeral volume that is handled by a normal storage driver.* - - **ephemeral.readOnly** (boolean) - - Specifies a read-only configuration for the volume. Defaults to false (read/write). - - **ephemeral.volumeClaimTemplate** (PersistentVolumeClaimTemplate) Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be `\-\` where `\` is the name from the `PodSpec.Volumes` array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long). @@ -819,15 +816,15 @@ Volume represents a named volume in a pod that may be accessed by any container *PersistentVolumeClaimTemplate is used to produce PersistentVolumeClaim objects as part of an EphemeralVolumeSource.* - - **ephemeral.volumeClaimTemplate.spec** (}}">PersistentVolumeClaimSpec), required + - **ephemeral.volumeClaimTemplate.spec** (}}">PersistentVolumeClaimSpec), required - The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. + The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. - - **ephemeral.volumeClaimTemplate.metadata** (}}">ObjectMeta) + - **ephemeral.volumeClaimTemplate.metadata** (}}">ObjectMeta) - May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. + May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. -### Deprecated {#Deprecated} +### Deprecated - **gitRepo** (GitRepoVolumeSource) @@ -853,3 +850,51 @@ Volume represents a named volume in a pod that may be accessed by any container +## DownwardAPIVolumeFile {#DownwardAPIVolumeFile} + +DownwardAPIVolumeFile represents information to create the file containing the pod field + +
+ +- **path** (string), required + + Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' + +- **fieldRef** (}}">ObjectFieldSelector) + + Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. + +- **mode** (int32) + + Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. + +- **resourceFieldRef** (}}">ResourceFieldSelector) + + Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. + + + + + +## KeyToPath {#KeyToPath} + +Maps a string key to a path within a volume. + +
+ +- **key** (string), required + + The key to project. + +- **path** (string), required + + The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. + +- **mode** (int32) + + Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. + + + + + diff --git a/content/en/docs/reference/kubernetes-api/extend-resources/custom-resource-definition-v1.md b/content/en/docs/reference/kubernetes-api/extend-resources/custom-resource-definition-v1.md index 8aa8ed0c78..5597325fac 100644 --- a/content/en/docs/reference/kubernetes-api/extend-resources/custom-resource-definition-v1.md +++ b/content/en/docs/reference/kubernetes-api/extend-resources/custom-resource-definition-v1.md @@ -112,29 +112,29 @@ CustomResourceDefinitionSpec describes how a user wants their resource to appear *CustomResourceColumnDefinition specifies a column for server side printing.* - - **versions.additionalPrinterColumns.jsonPath** (string), required + - **versions.additionalPrinterColumns.jsonPath** (string), required - jsonPath is a simple JSON path (i.e. with array notation) which is evaluated against each custom resource to produce the value for this column. + jsonPath is a simple JSON path (i.e. with array notation) which is evaluated against each custom resource to produce the value for this column. - - **versions.additionalPrinterColumns.name** (string), required + - **versions.additionalPrinterColumns.name** (string), required - name is a human readable name for the column. + name is a human readable name for the column. - - **versions.additionalPrinterColumns.type** (string), required + - **versions.additionalPrinterColumns.type** (string), required - type is an OpenAPI type definition for this column. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for details. + type is an OpenAPI type definition for this column. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for details. - - **versions.additionalPrinterColumns.description** (string) + - **versions.additionalPrinterColumns.description** (string) - description is a human readable description of this column. + description is a human readable description of this column. - - **versions.additionalPrinterColumns.format** (string) + - **versions.additionalPrinterColumns.format** (string) - format is an optional OpenAPI type definition for this column. The 'name' format is applied to the primary identifier column to assist in clients identifying column is the resource name. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for details. + format is an optional OpenAPI type definition for this column. The 'name' format is applied to the primary identifier column to assist in clients identifying column is the resource name. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for details. - - **versions.additionalPrinterColumns.priority** (int32) + - **versions.additionalPrinterColumns.priority** (int32) - priority is an integer defining the relative importance of this column compared to others. Lower numbers are considered higher priority. Columns that may be omitted in limited space scenarios should be given a priority greater than 0. + priority is an integer defining the relative importance of this column compared to others. Lower numbers are considered higher priority. Columns that may be omitted in limited space scenarios should be given a priority greater than 0. - **versions.deprecated** (boolean) @@ -151,9 +151,9 @@ CustomResourceDefinitionSpec describes how a user wants their resource to appear *CustomResourceValidation is a list of validation methods for CustomResources.* - - **versions.schema.openAPIV3Schema** (}}">JSONSchemaProps) + - **versions.schema.openAPIV3Schema** (}}">JSONSchemaProps) - openAPIV3Schema is the OpenAPI v3 schema to use for validation and pruning. + openAPIV3Schema is the OpenAPI v3 schema to use for validation and pruning. - **versions.subresources** (CustomResourceSubresources) @@ -162,31 +162,31 @@ CustomResourceDefinitionSpec describes how a user wants their resource to appear *CustomResourceSubresources defines the status and scale subresources for CustomResources.* - - **versions.subresources.scale** (CustomResourceSubresourceScale) + - **versions.subresources.scale** (CustomResourceSubresourceScale) - scale indicates the custom resource should serve a `/scale` subresource that returns an `autoscaling/v1` Scale object. + scale indicates the custom resource should serve a `/scale` subresource that returns an `autoscaling/v1` Scale object. - - *CustomResourceSubresourceScale defines how to serve the scale subresource for CustomResources.* + + *CustomResourceSubresourceScale defines how to serve the scale subresource for CustomResources.* - - **versions.subresources.scale.specReplicasPath** (string), required + - **versions.subresources.scale.specReplicasPath** (string), required - specReplicasPath defines the JSON path inside of a custom resource that corresponds to Scale `spec.replicas`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.spec`. If there is no value under the given path in the custom resource, the `/scale` subresource will return an error on GET. + specReplicasPath defines the JSON path inside of a custom resource that corresponds to Scale `spec.replicas`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.spec`. If there is no value under the given path in the custom resource, the `/scale` subresource will return an error on GET. - - **versions.subresources.scale.statusReplicasPath** (string), required + - **versions.subresources.scale.statusReplicasPath** (string), required - statusReplicasPath defines the JSON path inside of a custom resource that corresponds to Scale `status.replicas`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.status`. If there is no value under the given path in the custom resource, the `status.replicas` value in the `/scale` subresource will default to 0. + statusReplicasPath defines the JSON path inside of a custom resource that corresponds to Scale `status.replicas`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.status`. If there is no value under the given path in the custom resource, the `status.replicas` value in the `/scale` subresource will default to 0. - - **versions.subresources.scale.labelSelectorPath** (string) + - **versions.subresources.scale.labelSelectorPath** (string) - labelSelectorPath defines the JSON path inside of a custom resource that corresponds to Scale `status.selector`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.status` or `.spec`. Must be set to work with HorizontalPodAutoscaler. The field pointed by this JSON path must be a string field (not a complex selector struct) which contains a serialized label selector in string form. More info: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions#scale-subresource If there is no value under the given path in the custom resource, the `status.selector` value in the `/scale` subresource will default to the empty string. + labelSelectorPath defines the JSON path inside of a custom resource that corresponds to Scale `status.selector`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.status` or `.spec`. Must be set to work with HorizontalPodAutoscaler. The field pointed by this JSON path must be a string field (not a complex selector struct) which contains a serialized label selector in string form. More info: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions#scale-subresource If there is no value under the given path in the custom resource, the `status.selector` value in the `/scale` subresource will default to the empty string. - - **versions.subresources.status** (CustomResourceSubresourceStatus) + - **versions.subresources.status** (CustomResourceSubresourceStatus) - status indicates the custom resource should serve a `/status` subresource. When enabled: 1. requests to the custom resource primary endpoint ignore changes to the `status` stanza of the object. 2. requests to the custom resource `/status` subresource ignore changes to anything other than the `status` stanza of the object. + status indicates the custom resource should serve a `/status` subresource. When enabled: 1. requests to the custom resource primary endpoint ignore changes to the `status` stanza of the object. 2. requests to the custom resource `/status` subresource ignore changes to anything other than the `status` stanza of the object. - - *CustomResourceSubresourceStatus defines how to serve the status subresource for CustomResources. Status is represented by the `.status` JSON path inside of a CustomResource. When set, * exposes a /status subresource for the custom resource * PUT requests to the /status subresource take a custom resource object, and ignore changes to anything except the status stanza * PUT/POST/PATCH requests to the custom resource ignore changes to the status stanza* + + *CustomResourceSubresourceStatus defines how to serve the status subresource for CustomResources. Status is represented by the `.status` JSON path inside of a CustomResource. When set, * exposes a /status subresource for the custom resource * PUT requests to the /status subresource take a custom resource object, and ignore changes to anything except the status stanza * PUT/POST/PATCH requests to the custom resource ignore changes to the status stanza* - **conversion** (CustomResourceConversion) @@ -207,59 +207,59 @@ CustomResourceDefinitionSpec describes how a user wants their resource to appear *WebhookConversion describes how to call a conversion webhook* - - **conversion.webhook.conversionReviewVersions** ([]string), required + - **conversion.webhook.conversionReviewVersions** ([]string), required - conversionReviewVersions is an ordered list of preferred `ConversionReview` versions the Webhook expects. The API server will use the first version in the list which it supports. If none of the versions specified in this list are supported by API server, conversion will fail for the custom resource. If a persisted Webhook configuration specifies allowed versions and does not include any versions known to the API Server, calls to the webhook will fail. + conversionReviewVersions is an ordered list of preferred `ConversionReview` versions the Webhook expects. The API server will use the first version in the list which it supports. If none of the versions specified in this list are supported by API server, conversion will fail for the custom resource. If a persisted Webhook configuration specifies allowed versions and does not include any versions known to the API Server, calls to the webhook will fail. - - **conversion.webhook.clientConfig** (WebhookClientConfig) + - **conversion.webhook.clientConfig** (WebhookClientConfig) - clientConfig is the instructions for how to call the webhook if strategy is `Webhook`. + clientConfig is the instructions for how to call the webhook if strategy is `Webhook`. - - *WebhookClientConfig contains the information to make a TLS connection with the webhook.* + + *WebhookClientConfig contains the information to make a TLS connection with the webhook.* - - **conversion.webhook.clientConfig.caBundle** ([]byte) + - **conversion.webhook.clientConfig.caBundle** ([]byte) - caBundle is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. + caBundle is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. - - **conversion.webhook.clientConfig.service** (ServiceReference) + - **conversion.webhook.clientConfig.service** (ServiceReference) - service is a reference to the service for this webhook. Either service or url must be specified. - - If the webhook is running within the cluster, then you should use `service`. + service is a reference to the service for this webhook. Either service or url must be specified. + + If the webhook is running within the cluster, then you should use `service`. - - *ServiceReference holds a reference to Service.legacy.k8s.io* + + *ServiceReference holds a reference to Service.legacy.k8s.io* - - **conversion.webhook.clientConfig.service.name** (string), required + - **conversion.webhook.clientConfig.service.name** (string), required - name is the name of the service. Required + name is the name of the service. Required - - **conversion.webhook.clientConfig.service.namespace** (string), required + - **conversion.webhook.clientConfig.service.namespace** (string), required - namespace is the namespace of the service. Required + namespace is the namespace of the service. Required - - **conversion.webhook.clientConfig.service.path** (string) + - **conversion.webhook.clientConfig.service.path** (string) - path is an optional URL path at which the webhook will be contacted. + path is an optional URL path at which the webhook will be contacted. - - **conversion.webhook.clientConfig.service.port** (int32) + - **conversion.webhook.clientConfig.service.port** (int32) - port is an optional service port at which the webhook will be contacted. `port` should be a valid port number (1-65535, inclusive). Defaults to 443 for backward compatibility. + port is an optional service port at which the webhook will be contacted. `port` should be a valid port number (1-65535, inclusive). Defaults to 443 for backward compatibility. - - **conversion.webhook.clientConfig.url** (string) + - **conversion.webhook.clientConfig.url** (string) - url gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. - - The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. - - Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installations are likely to be non-portable or not readily run in a new cluster. - - The scheme must be "https"; the URL must begin with "https://". - - A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. - - Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. + url gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. + + The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. + + Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster. + + The scheme must be "https"; the URL must begin with "https://". + + A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. + + Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. - **preserveUnknownFields** (boolean) @@ -269,6 +269,218 @@ CustomResourceDefinitionSpec describes how a user wants their resource to appear +## JSONSchemaProps {#JSONSchemaProps} + +JSONSchemaProps is a JSON-Schema following Specification Draft 4 (http://json-schema.org/). + +
+ +- **$ref** (string) + + +- **$schema** (string) + + +- **additionalItems** (JSONSchemaPropsOrBool) + + + + *JSONSchemaPropsOrBool represents JSONSchemaProps or a boolean value. Defaults to true for the boolean property.* + +- **additionalProperties** (JSONSchemaPropsOrBool) + + + + *JSONSchemaPropsOrBool represents JSONSchemaProps or a boolean value. Defaults to true for the boolean property.* + +- **allOf** ([]}}">JSONSchemaProps) + + +- **anyOf** ([]}}">JSONSchemaProps) + + +- **default** (JSON) + + default is a default value for undefined object fields. Defaulting is a beta feature under the CustomResourceDefaulting feature gate. Defaulting requires spec.preserveUnknownFields to be false. + + + *JSON represents any valid JSON value. These types are supported: bool, int64, float64, string, []interface{}, map[string]interface{} and nil.* + +- **definitions** (map[string]}}">JSONSchemaProps) + + +- **dependencies** (map[string]JSONSchemaPropsOrStringArray) + + + + *JSONSchemaPropsOrStringArray represents a JSONSchemaProps or a string array.* + +- **description** (string) + + +- **enum** ([]JSON) + + + + *JSON represents any valid JSON value. These types are supported: bool, int64, float64, string, []interface{}, map[string]interface{} and nil.* + +- **example** (JSON) + + + + *JSON represents any valid JSON value. These types are supported: bool, int64, float64, string, []interface{}, map[string]interface{} and nil.* + +- **exclusiveMaximum** (boolean) + + +- **exclusiveMinimum** (boolean) + + +- **externalDocs** (ExternalDocumentation) + + + + *ExternalDocumentation allows referencing an external resource for extended documentation.* + + - **externalDocs.description** (string) + + + - **externalDocs.url** (string) + + +- **format** (string) + + format is an OpenAPI v3 format string. Unknown formats are ignored. The following formats are validated: + + - bsonobjectid: a bson object ID, i.e. a 24 characters hex string - uri: an URI as parsed by Golang net/url.ParseRequestURI - email: an email address as parsed by Golang net/mail.ParseAddress - hostname: a valid representation for an Internet host name, as defined by RFC 1034, section 3.1 [RFC1034]. - ipv4: an IPv4 IP as parsed by Golang net.ParseIP - ipv6: an IPv6 IP as parsed by Golang net.ParseIP - cidr: a CIDR as parsed by Golang net.ParseCIDR - mac: a MAC address as parsed by Golang net.ParseMAC - uuid: an UUID that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$ - uuid3: an UUID3 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?3[0-9a-f]{3}-?[0-9a-f]{4}-?[0-9a-f]{12}$ - uuid4: an UUID4 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?4[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$ - uuid5: an UUID5 that allows uppercase defined by the regex (?i)^[0-9a-f]{8}-?[0-9a-f]{4}-?5[0-9a-f]{3}-?[89ab][0-9a-f]{3}-?[0-9a-f]{12}$ - isbn: an ISBN10 or ISBN13 number string like "0321751043" or "978-0321751041" - isbn10: an ISBN10 number string like "0321751043" - isbn13: an ISBN13 number string like "978-0321751041" - creditcard: a credit card number defined by the regex ^(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|6(?:011|5[0-9][0-9])[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|(?:2131|1800|35\d{3})\d{11})$ with any non digit characters mixed in - ssn: a U.S. social security number following the regex ^\d{3}[- ]?\d{2}[- ]?\d{4}$ - hexcolor: an hexadecimal color code like "#FFFFFF: following the regex ^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - rgbcolor: an RGB color code like rgb like "rgb(255,255,2559" - byte: base64 encoded binary data - password: any kind of string - date: a date string like "2006-01-02" as defined by full-date in RFC3339 - duration: a duration string like "22 ns" as parsed by Golang time.ParseDuration or compatible with Scala duration format - datetime: a date time string like "2014-12-15T19:30:20.000Z" as defined by date-time in RFC3339. + +- **id** (string) + + +- **items** (JSONSchemaPropsOrArray) + + + + *JSONSchemaPropsOrArray represents a value that can either be a JSONSchemaProps or an array of JSONSchemaProps. Mainly here for serialization purposes.* + +- **maxItems** (int64) + + +- **maxLength** (int64) + + +- **maxProperties** (int64) + + +- **maximum** (double) + + +- **minItems** (int64) + + +- **minLength** (int64) + + +- **minProperties** (int64) + + +- **minimum** (double) + + +- **multipleOf** (double) + + +- **not** (}}">JSONSchemaProps) + + +- **nullable** (boolean) + + +- **oneOf** ([]}}">JSONSchemaProps) + + +- **pattern** (string) + + +- **patternProperties** (map[string]}}">JSONSchemaProps) + + +- **properties** (map[string]}}">JSONSchemaProps) + + +- **required** ([]string) + + +- **title** (string) + + +- **type** (string) + + +- **uniqueItems** (boolean) + + +- **x-kubernetes-embedded-resource** (boolean) + + x-kubernetes-embedded-resource defines that the value is an embedded Kubernetes runtime.Object, with TypeMeta and ObjectMeta. The type must be object. It is allowed to further restrict the embedded object. kind, apiVersion and metadata are validated automatically. x-kubernetes-preserve-unknown-fields is allowed to be true, but does not have to be if the object is fully specified (up to kind, apiVersion, metadata). + +- **x-kubernetes-int-or-string** (boolean) + + x-kubernetes-int-or-string specifies that this value is either an integer or a string. If this is true, an empty type is allowed and type as child of anyOf is permitted if following one of the following patterns: + + 1) anyOf: + - type: integer + - type: string + 2) allOf: + - anyOf: + - type: integer + - type: string + - ... zero or more + +- **x-kubernetes-list-map-keys** ([]string) + + x-kubernetes-list-map-keys annotates an array with the x-kubernetes-list-type `map` by specifying the keys used as the index of the map. + + This tag MUST only be used on lists that have the "x-kubernetes-list-type" extension set to "map". Also, the values specified for this attribute must be a scalar typed field of the child structure (no nesting is supported). + + The properties specified must either be required or have a default value, to ensure those properties are present for all list items. + +- **x-kubernetes-list-type** (string) + + x-kubernetes-list-type annotates an array to further describe its topology. This extension must only be used on lists and may have 3 possible values: + + 1) `atomic`: the list is treated as a single entity, like a scalar. + Atomic lists will be entirely replaced when updated. This extension + may be used on any type of list (struct, scalar, ...). + 2) `set`: + Sets are lists that must not have multiple items with the same value. Each + value must be a scalar, an object with x-kubernetes-map-type `atomic` or an + array with x-kubernetes-list-type `atomic`. + 3) `map`: + These lists are like maps in that their elements have a non-index key + used to identify them. Order is preserved upon merge. The map tag + must only be used on a list with elements of type object. + Defaults to atomic for arrays. + +- **x-kubernetes-map-type** (string) + + x-kubernetes-map-type annotates an object to further describe its topology. This extension must only be used when type is object and may have 2 possible values: + + 1) `granular`: + These maps are actual maps (key-value pairs) and each fields are independent + from each other (they can each be manipulated by separate actors). This is + the default behaviour for all maps. + 2) `atomic`: the list is treated as a single entity, like a scalar. + Atomic maps will be entirely replaced when updated. + +- **x-kubernetes-preserve-unknown-fields** (boolean) + + x-kubernetes-preserve-unknown-fields stops the API server decoding step from pruning fields which are not specified in the validation schema. This affects fields recursively, but switches back to normal pruning behaviour if nested properties or additionalProperties are specified in the schema. This can either be true or undefined. False is forbidden. + + + + + ## CustomResourceDefinitionStatus {#CustomResourceDefinitionStatus} CustomResourceDefinitionStatus indicates the state of the CustomResourceDefinition @@ -308,6 +520,8 @@ CustomResourceDefinitionStatus indicates the state of the CustomResourceDefiniti - **conditions** ([]CustomResourceDefinitionCondition) + *Map: unique values on key type will be kept during a merge* + conditions indicate state for particular aspects of a CustomResourceDefinition @@ -350,19 +564,21 @@ CustomResourceDefinitionList is a list of CustomResourceDefinition objects.
-- **apiVersion**: apiextensions.k8s.io/v1 - - -- **kind**: CustomResourceDefinitionList - - -- **metadata** (}}">ListMeta) - - - **items** ([]}}">CustomResourceDefinition), required items list individual CustomResourceDefinition objects +- **apiVersion** (string) + + APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +- **kind** (string) + + Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + +- **metadata** (}}">ListMeta) + + diff --git a/content/en/docs/reference/kubernetes-api/extend-resources/mutating-webhook-configuration-v1.md b/content/en/docs/reference/kubernetes-api/extend-resources/mutating-webhook-configuration-v1.md index 9e17c11ae3..59f3b7c457 100644 --- a/content/en/docs/reference/kubernetes-api/extend-resources/mutating-webhook-configuration-v1.md +++ b/content/en/docs/reference/kubernetes-api/extend-resources/mutating-webhook-configuration-v1.md @@ -50,48 +50,48 @@ MutatingWebhookConfiguration describes the configuration of and admission webhoo *WebhookClientConfig contains the information to make a TLS connection with the webhook* - - **webhooks.clientConfig.caBundle** ([]byte) + - **webhooks.clientConfig.caBundle** ([]byte) - `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. + `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. - - **webhooks.clientConfig.service** (ServiceReference) + - **webhooks.clientConfig.service** (ServiceReference) - `service` is a reference to the service for this webhook. Either `service` or `url` must be specified. - - If the webhook is running within the cluster, then you should use `service`. + `service` is a reference to the service for this webhook. Either `service` or `url` must be specified. + + If the webhook is running within the cluster, then you should use `service`. - - *ServiceReference holds a reference to Service.legacy.k8s.io* + + *ServiceReference holds a reference to Service.legacy.k8s.io* - - **webhooks.clientConfig.service.name** (string), required + - **webhooks.clientConfig.service.name** (string), required - `name` is the name of the service. Required + `name` is the name of the service. Required - - **webhooks.clientConfig.service.namespace** (string), required + - **webhooks.clientConfig.service.namespace** (string), required - `namespace` is the namespace of the service. Required + `namespace` is the namespace of the service. Required - - **webhooks.clientConfig.service.path** (string) + - **webhooks.clientConfig.service.path** (string) - `path` is an optional URL path which will be sent in any request to this service. + `path` is an optional URL path which will be sent in any request to this service. - - **webhooks.clientConfig.service.port** (int32) + - **webhooks.clientConfig.service.port** (int32) - If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). + If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). - - **webhooks.clientConfig.url** (string) + - **webhooks.clientConfig.url** (string) - `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. - - The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. - - Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installations are likely to be non-portable or not readily run in a new cluster. - - The scheme must be "https"; the URL must begin with "https://". - - A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. - - Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. + `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. + + The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. + + Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster. + + The scheme must be "https"; the URL must begin with "https://". + + A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. + + Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. - **webhooks.name** (string), required @@ -99,7 +99,7 @@ MutatingWebhookConfiguration describes the configuration of and admission webhoo - **webhooks.sideEffects** (string), required - SideEffects states whether this webhook has side effects. Acceptable values are: None, NoneOnDryRun (webhooks created via v1beta1 may also specify Some or Unknown). Webhooks with side effects MUST implement a reconciliation system, since a request may be rejected by a future step in the admission change and the side effects therefore need to be undone. Requests with the dryRun attribute will be auto-rejected if they match a webhook with sideEffects == Unknown or Some. + SideEffects states whether this webhook has side effects. Acceptable values are: None, NoneOnDryRun (webhooks created via v1beta1 may also specify Some or Unknown). Webhooks with side effects MUST implement a reconciliation system, since a request may be rejected by a future step in the admission chain and the side effects therefore need to be undone. Requests with the dryRun attribute will be auto-rejected if they match a webhook with sideEffects == Unknown or Some. - **webhooks.failurePolicy** (string) @@ -170,31 +170,31 @@ MutatingWebhookConfiguration describes the configuration of and admission webhoo *RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid.* - - **webhooks.rules.apiGroups** ([]string) + - **webhooks.rules.apiGroups** ([]string) - APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. + APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. - - **webhooks.rules.apiVersions** ([]string) + - **webhooks.rules.apiVersions** ([]string) - APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. + APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. - - **webhooks.rules.operations** ([]string) + - **webhooks.rules.operations** ([]string) - Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. + Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. - - **webhooks.rules.resources** ([]string) + - **webhooks.rules.resources** ([]string) - Resources is a list of resources this rule applies to. - - For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. - - If wildcard is present, the validation rule will ensure resources do not overlap with each other. - - Depending on the enclosing object, subresources might not be allowed. Required. + Resources is a list of resources this rule applies to. + + For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. + + If wildcard is present, the validation rule will ensure resources do not overlap with each other. + + Depending on the enclosing object, subresources might not be allowed. Required. - - **webhooks.rules.scope** (string) + - **webhooks.rules.scope** (string) - scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". + scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". - **webhooks.timeoutSeconds** (int32) diff --git a/content/en/docs/reference/kubernetes-api/extend-resources/validating-webhook-configuration-v1.md b/content/en/docs/reference/kubernetes-api/extend-resources/validating-webhook-configuration-v1.md index 84d26265a3..41bf5b2905 100644 --- a/content/en/docs/reference/kubernetes-api/extend-resources/validating-webhook-configuration-v1.md +++ b/content/en/docs/reference/kubernetes-api/extend-resources/validating-webhook-configuration-v1.md @@ -50,48 +50,48 @@ ValidatingWebhookConfiguration describes the configuration of and admission webh *WebhookClientConfig contains the information to make a TLS connection with the webhook* - - **webhooks.clientConfig.caBundle** ([]byte) + - **webhooks.clientConfig.caBundle** ([]byte) - `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. + `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. - - **webhooks.clientConfig.service** (ServiceReference) + - **webhooks.clientConfig.service** (ServiceReference) - `service` is a reference to the service for this webhook. Either `service` or `url` must be specified. - - If the webhook is running within the cluster, then you should use `service`. + `service` is a reference to the service for this webhook. Either `service` or `url` must be specified. + + If the webhook is running within the cluster, then you should use `service`. - - *ServiceReference holds a reference to Service.legacy.k8s.io* + + *ServiceReference holds a reference to Service.legacy.k8s.io* - - **webhooks.clientConfig.service.name** (string), required + - **webhooks.clientConfig.service.name** (string), required - `name` is the name of the service. Required + `name` is the name of the service. Required - - **webhooks.clientConfig.service.namespace** (string), required + - **webhooks.clientConfig.service.namespace** (string), required - `namespace` is the namespace of the service. Required + `namespace` is the namespace of the service. Required - - **webhooks.clientConfig.service.path** (string) + - **webhooks.clientConfig.service.path** (string) - `path` is an optional URL path which will be sent in any request to this service. + `path` is an optional URL path which will be sent in any request to this service. - - **webhooks.clientConfig.service.port** (int32) + - **webhooks.clientConfig.service.port** (int32) - If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). + If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). - - **webhooks.clientConfig.url** (string) + - **webhooks.clientConfig.url** (string) - `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. - - The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. - - Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installations are likely to be non-portable or not readily run in a new cluster. - - The scheme must be "https"; the URL must begin with "https://". - - A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. - - Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. + `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. + + The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. + + Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster. + + The scheme must be "https"; the URL must begin with "https://". + + A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. + + Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. - **webhooks.name** (string), required @@ -99,7 +99,7 @@ ValidatingWebhookConfiguration describes the configuration of and admission webh - **webhooks.sideEffects** (string), required - SideEffects states whether this webhook has side effects. Acceptable values are: None, NoneOnDryRun (webhooks created via v1beta1 may also specify Some or Unknown). Webhooks with side effects MUST implement a reconciliation system, since a request may be rejected by a future step in the admission change and the side effects therefore need to be undone. Requests with the dryRun attribute will be auto-rejected if they match a webhook with sideEffects == Unknown or Some. + SideEffects states whether this webhook has side effects. Acceptable values are: None, NoneOnDryRun (webhooks created via v1beta1 may also specify Some or Unknown). Webhooks with side effects MUST implement a reconciliation system, since a request may be rejected by a future step in the admission chain and the side effects therefore need to be undone. Requests with the dryRun attribute will be auto-rejected if they match a webhook with sideEffects == Unknown or Some. - **webhooks.failurePolicy** (string) @@ -160,31 +160,31 @@ ValidatingWebhookConfiguration describes the configuration of and admission webh *RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid.* - - **webhooks.rules.apiGroups** ([]string) + - **webhooks.rules.apiGroups** ([]string) - APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. + APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. - - **webhooks.rules.apiVersions** ([]string) + - **webhooks.rules.apiVersions** ([]string) - APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. + APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. - - **webhooks.rules.operations** ([]string) + - **webhooks.rules.operations** ([]string) - Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. + Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. - - **webhooks.rules.resources** ([]string) + - **webhooks.rules.resources** ([]string) - Resources is a list of resources this rule applies to. - - For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. - - If wildcard is present, the validation rule will ensure resources do not overlap with each other. - - Depending on the enclosing object, subresources might not be allowed. Required. + Resources is a list of resources this rule applies to. + + For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. + + If wildcard is present, the validation rule will ensure resources do not overlap with each other. + + Depending on the enclosing object, subresources might not be allowed. Required. - - **webhooks.rules.scope** (string) + - **webhooks.rules.scope** (string) - scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". + scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". - **webhooks.timeoutSeconds** (int32) diff --git a/content/en/docs/reference/kubernetes-api/policy-resources/limit-range-v1.md b/content/en/docs/reference/kubernetes-api/policy-resources/limit-range-v1.md index 00982c5ab8..d1f45d5557 100644 --- a/content/en/docs/reference/kubernetes-api/policy-resources/limit-range-v1.md +++ b/content/en/docs/reference/kubernetes-api/policy-resources/limit-range-v1.md @@ -97,7 +97,7 @@ LimitRangeList is a list of LimitRange items. - **items** ([]}}">LimitRange), required - Items is a list of LimitRange objects. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ + Items is a list of LimitRange objects. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ diff --git a/content/en/docs/reference/kubernetes-api/policy-resources/network-policy-v1.md b/content/en/docs/reference/kubernetes-api/policy-resources/network-policy-v1.md index 78e4868d94..2288204257 100644 --- a/content/en/docs/reference/kubernetes-api/policy-resources/network-policy-v1.md +++ b/content/en/docs/reference/kubernetes-api/policy-resources/network-policy-v1.md @@ -50,7 +50,7 @@ NetworkPolicySpec provides the specification of a NetworkPolicy - **policyTypes** ([]string) - List of rule types that the NetworkPolicy relates to. Valid options are "Ingress", "Egress", or "Ingress,Egress". If this field is not specified, it will default based on the existence of Ingress or Egress rules; policies that contain an Egress section are assumed to affect Egress, and all policies (whether or not they contain an Ingress section) are assumed to affect Ingress. If you want to write an egress-only policy, you must explicitly specify policyTypes [ "Egress" ]. Likewise, if you want to write a policy that specifies that no egress is allowed, you must specify a policyTypes value that include "Egress" (since such a policy would not include an Egress section and would otherwise default to just [ "Ingress" ]). This field is beta-level in 1.8 + List of rule types that the NetworkPolicy relates to. Valid options are ["Ingress"], ["Egress"], or ["Ingress", "Egress"]. If this field is not specified, it will default based on the existence of Ingress or Egress rules; policies that contain an Egress section are assumed to affect Egress, and all policies (whether or not they contain an Ingress section) are assumed to affect Ingress. If you want to write an egress-only policy, you must explicitly specify policyTypes [ "Egress" ]. Likewise, if you want to write a policy that specifies that no egress is allowed, you must specify a policyTypes value that include "Egress" (since such a policy would not include an Egress section and would otherwise default to just [ "Ingress" ]). This field is beta-level in 1.8 - **ingress** ([]NetworkPolicyIngressRule) @@ -66,32 +66,32 @@ NetworkPolicySpec provides the specification of a NetworkPolicy *NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain combinations of fields are allowed* - - **ingress.from.ipBlock** (IPBlock) + - **ingress.from.ipBlock** (IPBlock) - IPBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be. + IPBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be. - - *IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule.* + + *IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule.* - - **ingress.from.ipBlock.cidr** (string), required + - **ingress.from.ipBlock.cidr** (string), required - CIDR is a string representing the IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" + CIDR is a string representing the IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" - - **ingress.from.ipBlock.except** ([]string) + - **ingress.from.ipBlock.except** ([]string) - Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" Except values will be rejected if they are outside the CIDR range + Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" Except values will be rejected if they are outside the CIDR range - - **ingress.from.namespaceSelector** (}}">LabelSelector) + - **ingress.from.namespaceSelector** (}}">LabelSelector) - Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. - - If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. + Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. + + If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. - - **ingress.from.podSelector** (}}">LabelSelector) + - **ingress.from.podSelector** (}}">LabelSelector) - This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. - - If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy's own Namespace. + This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. + + If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy's own Namespace. - **ingress.ports** ([]NetworkPolicyPort) @@ -100,16 +100,20 @@ NetworkPolicySpec provides the specification of a NetworkPolicy *NetworkPolicyPort describes a port to allow traffic on* - - **ingress.ports.port** (IntOrString) + - **ingress.ports.port** (IntOrString) - The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. + The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. If present, only traffic on the specified protocol AND port will be matched. - - *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* - - **ingress.ports.protocol** (string) + - **ingress.ports.endPort** (int32) - The protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP. + If set, indicates that the range of ports from port to endPort, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port. This feature is in Alpha state and should be enabled using the Feature Gate "NetworkPolicyEndPort". + + - **ingress.ports.protocol** (string) + + The protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP. - **egress** ([]NetworkPolicyEgressRule) @@ -125,32 +129,32 @@ NetworkPolicySpec provides the specification of a NetworkPolicy *NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain combinations of fields are allowed* - - **egress.to.ipBlock** (IPBlock) + - **egress.to.ipBlock** (IPBlock) - IPBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be. + IPBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be. - - *IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule.* + + *IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule.* - - **egress.to.ipBlock.cidr** (string), required + - **egress.to.ipBlock.cidr** (string), required - CIDR is a string representing the IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" + CIDR is a string representing the IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" - - **egress.to.ipBlock.except** ([]string) + - **egress.to.ipBlock.except** ([]string) - Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" Except values will be rejected if they are outside the CIDR range + Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" Except values will be rejected if they are outside the CIDR range - - **egress.to.namespaceSelector** (}}">LabelSelector) + - **egress.to.namespaceSelector** (}}">LabelSelector) - Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. - - If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. + Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. + + If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. - - **egress.to.podSelector** (}}">LabelSelector) + - **egress.to.podSelector** (}}">LabelSelector) - This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. - - If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy's own Namespace. + This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. + + If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy's own Namespace. - **egress.ports** ([]NetworkPolicyPort) @@ -159,16 +163,20 @@ NetworkPolicySpec provides the specification of a NetworkPolicy *NetworkPolicyPort describes a port to allow traffic on* - - **egress.ports.port** (IntOrString) + - **egress.ports.port** (IntOrString) - The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. + The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. If present, only traffic on the specified protocol AND port will be matched. - - *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* - - **egress.ports.protocol** (string) + - **egress.ports.endPort** (int32) - The protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP. + If set, indicates that the range of ports from port to endPort, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port. This feature is in Alpha state and should be enabled using the Feature Gate "NetworkPolicyEndPort". + + - **egress.ports.protocol** (string) + + The protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP. diff --git a/content/en/docs/reference/kubernetes-api/policy-resources/pod-disruption-budget-v1.md b/content/en/docs/reference/kubernetes-api/policy-resources/pod-disruption-budget-v1.md new file mode 100644 index 0000000000..841f1bb82a --- /dev/null +++ b/content/en/docs/reference/kubernetes-api/policy-resources/pod-disruption-budget-v1.md @@ -0,0 +1,787 @@ +--- +api_metadata: + apiVersion: "policy/v1" + import: "k8s.io/api/policy/v1" + kind: "PodDisruptionBudget" +content_type: "api_reference" +description: "PodDisruptionBudget is an object to define the max disruption that can be caused to a collection of pods." +title: "PodDisruptionBudget" +weight: 4 +--- + +`apiVersion: policy/v1` + +`import "k8s.io/api/policy/v1"` + + +## PodDisruptionBudget {#PodDisruptionBudget} + +PodDisruptionBudget is an object to define the max disruption that can be caused to a collection of pods + +
+ +- **apiVersion**: policy/v1 + + +- **kind**: PodDisruptionBudget + + +- **metadata** (}}">ObjectMeta) + + Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +- **spec** (}}">PodDisruptionBudgetSpec) + + Specification of the desired behavior of the PodDisruptionBudget. + +- **status** (}}">PodDisruptionBudgetStatus) + + Most recently observed status of the PodDisruptionBudget. + + + + + +## PodDisruptionBudgetSpec {#PodDisruptionBudgetSpec} + +PodDisruptionBudgetSpec is a description of a PodDisruptionBudget. + +
+ +- **maxUnavailable** (IntOrString) + + An eviction is allowed if at most "maxUnavailable" pods selected by "selector" are unavailable after the eviction, i.e. even in absence of the evicted pod. For example, one can prevent all voluntary evictions by specifying 0. This is a mutually exclusive setting with "minAvailable". + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + +- **minAvailable** (IntOrString) + + An eviction is allowed if at least "minAvailable" pods selected by "selector" will still be available after the eviction, i.e. even in the absence of the evicted pod. So for example you can prevent all voluntary evictions by specifying "100%". + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + +- **selector** (}}">LabelSelector) + + Label query over pods whose evictions are managed by the disruption budget. A null selector will match no pods, while an empty ({}) selector will select all pods within the namespace. + + + + + +## PodDisruptionBudgetStatus {#PodDisruptionBudgetStatus} + +PodDisruptionBudgetStatus represents information about the status of a PodDisruptionBudget. Status may trail the actual state of a system. + +
+ +- **currentHealthy** (int32), required + + current number of healthy pods + +- **desiredHealthy** (int32), required + + minimum desired number of healthy pods + +- **disruptionsAllowed** (int32), required + + Number of pod disruptions that are currently allowed. + +- **expectedPods** (int32), required + + total number of pods counted by this disruption budget + +- **conditions** ([]Condition) + + *Patch strategy: merge on key `type`* + + *Map: unique values on key type will be kept during a merge* + + Conditions contain conditions for PDB. The disruption controller sets the DisruptionAllowed condition. The following are known values for the reason field (additional reasons could be added in the future): - SyncFailed: The controller encountered an error and wasn't able to compute + the number of allowed disruptions. Therefore no disruptions are + allowed and the status of the condition will be False. + - InsufficientPods: The number of pods are either at or below the number + required by the PodDisruptionBudget. No disruptions are + allowed and the status of the condition will be False. + - SufficientPods: There are more pods than required by the PodDisruptionBudget. + The condition will be True, and the number of allowed + disruptions are provided by the disruptionsAllowed property. + + + *Condition contains details for one aspect of the current state of this API Resource.* + + - **conditions.lastTransitionTime** (Time), required + + lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **conditions.message** (string), required + + message is a human readable message indicating details about the transition. This may be an empty string. + + - **conditions.reason** (string), required + + reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. + + - **conditions.status** (string), required + + status of the condition, one of True, False, Unknown. + + - **conditions.type** (string), required + + type of condition in CamelCase or in foo.example.com/CamelCase. + + - **conditions.observedGeneration** (int64) + + observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. + +- **disruptedPods** (map[string]Time) + + DisruptedPods contains information about pods whose eviction was processed by the API server eviction subresource handler but has not yet been observed by the PodDisruptionBudget controller. A pod will be in this map from the time when the API server processed the eviction request to the time when the pod is seen by PDB controller as having been marked for deletion (or after a timeout). The key in the map is the name of the pod and the value is the time when the API server processed the eviction request. If the deletion didn't occur and a pod is still there it will be removed from the list automatically by PodDisruptionBudget controller after some time. If everything goes smooth this map should be empty for the most of the time. Large number of entries in the map may indicate problems with pod deletions. + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + +- **observedGeneration** (int64) + + Most recent generation observed when updating this PDB status. DisruptionsAllowed and other status information is valid only if observedGeneration equals to PDB's object generation. + + + + + +## PodDisruptionBudgetList {#PodDisruptionBudgetList} + +PodDisruptionBudgetList is a collection of PodDisruptionBudgets. + +
+ +- **apiVersion**: policy/v1 + + +- **kind**: PodDisruptionBudgetList + + +- **metadata** (}}">ListMeta) + + Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +- **items** ([]}}">PodDisruptionBudget), required + + Items is a list of PodDisruptionBudgets + + + + + +## Operations {#Operations} + + + +
+ + + + + + +### `get` read the specified PodDisruptionBudget + +#### HTTP Request + +GET /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +401: Unauthorized + + +### `get` read status of the specified PodDisruptionBudget + +#### HTTP Request + +GET /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name}/status + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +401: Unauthorized + + +### `list` list or watch objects of kind PodDisruptionBudget + +#### HTTP Request + +GET /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">PodDisruptionBudgetList): OK + +401: Unauthorized + + +### `list` list or watch objects of kind PodDisruptionBudget + +#### HTTP Request + +GET /apis/policy/v1/poddisruptionbudgets + +#### Parameters + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">PodDisruptionBudgetList): OK + +401: Unauthorized + + +### `create` create a PodDisruptionBudget + +#### HTTP Request + +POST /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">PodDisruptionBudget, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +201 (}}">PodDisruptionBudget): Created + +202 (}}">PodDisruptionBudget): Accepted + +401: Unauthorized + + +### `update` replace the specified PodDisruptionBudget + +#### HTTP Request + +PUT /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">PodDisruptionBudget, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +201 (}}">PodDisruptionBudget): Created + +401: Unauthorized + + +### `update` replace status of the specified PodDisruptionBudget + +#### HTTP Request + +PUT /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name}/status + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">PodDisruptionBudget, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +201 (}}">PodDisruptionBudget): Created + +401: Unauthorized + + +### `patch` partially update the specified PodDisruptionBudget + +#### HTTP Request + +PATCH /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +401: Unauthorized + + +### `patch` partially update status of the specified PodDisruptionBudget + +#### HTTP Request + +PATCH /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name}/status + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">PodDisruptionBudget): OK + +401: Unauthorized + + +### `delete` delete a PodDisruptionBudget + +#### HTTP Request + +DELETE /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the PodDisruptionBudget + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + + +#### Response + + +200 (}}">Status): OK + +202 (}}">Status): Accepted + +401: Unauthorized + + +### `deletecollection` delete collection of PodDisruptionBudget + +#### HTTP Request + +DELETE /apis/policy/v1/namespaces/{namespace}/poddisruptionbudgets + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **continue** (*in query*): string + + }}">continue + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + + +#### Response + + +200 (}}">Status): OK + +401: Unauthorized + diff --git a/content/en/docs/reference/kubernetes-api/policy-resources/pod-security-policy-v1beta1.md b/content/en/docs/reference/kubernetes-api/policy-resources/pod-security-policy-v1beta1.md index 59444cbbcf..a499f1dc6d 100644 --- a/content/en/docs/reference/kubernetes-api/policy-resources/pod-security-policy-v1beta1.md +++ b/content/en/docs/reference/kubernetes-api/policy-resources/pod-security-policy-v1beta1.md @@ -16,7 +16,7 @@ weight: 5 ## PodSecurityPolicy {#PodSecurityPolicy} -PodSecurityPolicy governs the ability to make requests that affect the Security Context that will be applied to a pod and container. +PodSecurityPolicy governs the ability to make requests that affect the Security Context that will be applied to a pod and container. Deprecated in 1.21.
@@ -62,13 +62,13 @@ PodSecurityPolicySpec defines the policy enforced. *IDRange provides a min/max of an allowed range of IDs.* - - **runAsUser.ranges.max** (int64), required + - **runAsUser.ranges.max** (int64), required - max is the end of the range, inclusive. + max is the end of the range, inclusive. - - **runAsUser.ranges.min** (int64), required + - **runAsUser.ranges.min** (int64), required - min is the start of the range, inclusive. + min is the start of the range, inclusive. - **runAsGroup** (RunAsGroupStrategyOptions) @@ -88,13 +88,13 @@ PodSecurityPolicySpec defines the policy enforced. *IDRange provides a min/max of an allowed range of IDs.* - - **runAsGroup.ranges.max** (int64), required + - **runAsGroup.ranges.max** (int64), required - max is the end of the range, inclusive. + max is the end of the range, inclusive. - - **runAsGroup.ranges.min** (int64), required + - **runAsGroup.ranges.min** (int64), required - min is the start of the range, inclusive. + min is the start of the range, inclusive. - **fsGroup** (FSGroupStrategyOptions), required @@ -110,13 +110,13 @@ PodSecurityPolicySpec defines the policy enforced. *IDRange provides a min/max of an allowed range of IDs.* - - **fsGroup.ranges.max** (int64), required + - **fsGroup.ranges.max** (int64), required - max is the end of the range, inclusive. + max is the end of the range, inclusive. - - **fsGroup.ranges.min** (int64), required + - **fsGroup.ranges.min** (int64), required - min is the start of the range, inclusive. + min is the start of the range, inclusive. - **fsGroup.rule** (string) @@ -136,13 +136,13 @@ PodSecurityPolicySpec defines the policy enforced. *IDRange provides a min/max of an allowed range of IDs.* - - **supplementalGroups.ranges.max** (int64), required + - **supplementalGroups.ranges.max** (int64), required - max is the end of the range, inclusive. + max is the end of the range, inclusive. - - **supplementalGroups.ranges.min** (int64), required + - **supplementalGroups.ranges.min** (int64), required - min is the start of the range, inclusive. + min is the start of the range, inclusive. - **supplementalGroups.rule** (string) @@ -166,21 +166,21 @@ PodSecurityPolicySpec defines the policy enforced. *SELinuxOptions are the labels to be applied to the container* - - **seLinux.seLinuxOptions.level** (string) + - **seLinux.seLinuxOptions.level** (string) - Level is SELinux level label that applies to the container. + Level is SELinux level label that applies to the container. - - **seLinux.seLinuxOptions.role** (string) + - **seLinux.seLinuxOptions.role** (string) - Role is a SELinux role label that applies to the container. + Role is a SELinux role label that applies to the container. - - **seLinux.seLinuxOptions.type** (string) + - **seLinux.seLinuxOptions.type** (string) - Type is a SELinux type label that applies to the container. + Type is a SELinux type label that applies to the container. - - **seLinux.seLinuxOptions.user** (string) + - **seLinux.seLinuxOptions.user** (string) - User is a SELinux user label that applies to the container. + User is a SELinux user label that applies to the container. - **readOnlyRootFilesystem** (boolean) diff --git a/content/en/docs/reference/kubernetes-api/policy-resources/resource-quota-v1.md b/content/en/docs/reference/kubernetes-api/policy-resources/resource-quota-v1.md index 93b8cbc9e8..00818ec921 100644 --- a/content/en/docs/reference/kubernetes-api/policy-resources/resource-quota-v1.md +++ b/content/en/docs/reference/kubernetes-api/policy-resources/resource-quota-v1.md @@ -66,17 +66,17 @@ ResourceQuotaSpec defines the desired hard limits to enforce for Quota. *A scoped-resource selector requirement is a selector that contains values, a scope name, and an operator that relates the scope name and values.* - - **scopeSelector.matchExpressions.operator** (string), required + - **scopeSelector.matchExpressions.operator** (string), required - Represents a scope's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. + Represents a scope's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. - - **scopeSelector.matchExpressions.scopeName** (string), required + - **scopeSelector.matchExpressions.scopeName** (string), required - The name of the scope that the selector applies to. + The name of the scope that the selector applies to. - - **scopeSelector.matchExpressions.values** ([]string) + - **scopeSelector.matchExpressions.values** ([]string) - An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. + An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - **scopes** ([]string) diff --git a/content/en/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1.md b/content/en/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1.md new file mode 100644 index 0000000000..d296130937 --- /dev/null +++ b/content/en/docs/reference/kubernetes-api/service-resources/endpoint-slice-v1.md @@ -0,0 +1,635 @@ +--- +api_metadata: + apiVersion: "discovery.k8s.io/v1" + import: "k8s.io/api/discovery/v1" + kind: "EndpointSlice" +content_type: "api_reference" +description: "EndpointSlice represents a subset of the endpoints that implement a service." +title: "EndpointSlice" +weight: 3 +--- + +`apiVersion: discovery.k8s.io/v1` + +`import "k8s.io/api/discovery/v1"` + + +## EndpointSlice {#EndpointSlice} + +EndpointSlice represents a subset of the endpoints that implement a service. For a given service there may be multiple EndpointSlice objects, selected by labels, which must be joined to produce the full set of endpoints. + +
+ +- **apiVersion**: discovery.k8s.io/v1 + + +- **kind**: EndpointSlice + + +- **metadata** (}}">ObjectMeta) + + Standard object's metadata. + +- **addressType** (string), required + + addressType specifies the type of address carried by this EndpointSlice. All addresses in this slice must be the same type. This field is immutable after creation. The following address types are currently supported: * IPv4: Represents an IPv4 Address. * IPv6: Represents an IPv6 Address. * FQDN: Represents a Fully Qualified Domain Name. + +- **endpoints** ([]Endpoint), required + + *Atomic: will be replaced during a merge* + + endpoints is a list of unique endpoints in this slice. Each slice may include a maximum of 1000 endpoints. + + + *Endpoint represents a single logical "backend" implementing a service.* + + - **endpoints.addresses** ([]string), required + + *Set: unique values will be kept during a merge* + + addresses of this endpoint. The contents of this field are interpreted according to the corresponding EndpointSlice addressType field. Consumers must handle different types of addresses in the context of their own capabilities. This must contain at least one address but no more than 100. + + - **endpoints.conditions** (EndpointConditions) + + conditions contains information about the current status of the endpoint. + + + *EndpointConditions represents the current condition of an endpoint.* + + - **endpoints.conditions.ready** (boolean) + + ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be "true" for terminating endpoints. + + - **endpoints.conditions.serving** (boolean) + + serving is identical to ready except that it is set regardless of the terminating state of endpoints. This condition should be set to true for a ready endpoint that is terminating. If nil, consumers should defer to the ready condition. This field can be enabled with the EndpointSliceTerminatingCondition feature gate. + + - **endpoints.conditions.terminating** (boolean) + + terminating indicates that this endpoint is terminating. A nil value indicates an unknown state. Consumers should interpret this unknown state to mean that the endpoint is not terminating. This field can be enabled with the EndpointSliceTerminatingCondition feature gate. + + - **endpoints.deprecatedTopology** (map[string]string) + + deprecatedTopology contains topology information part of the v1beta1 API. This field is deprecated, and will be removed when the v1beta1 API is removed (no sooner than kubernetes v1.24). While this field can hold values, it is not writable through the v1 API, and any attempts to write to it will be silently ignored. Topology information can be found in the zone and nodeName fields instead. + + - **endpoints.hints** (EndpointHints) + + hints contains information associated with how an endpoint should be consumed. + + + *EndpointHints provides hints describing how an endpoint should be consumed.* + + - **endpoints.hints.forZones** ([]ForZone) + + *Atomic: will be replaced during a merge* + + forZones indicates the zone(s) this endpoint should be consumed by to enable topology aware routing. + + + *ForZone provides information about which zones should consume this endpoint.* + + - **endpoints.hints.forZones.name** (string), required + + name represents the name of the zone. + + - **endpoints.hostname** (string) + + hostname of this endpoint. This field may be used by consumers of endpoints to distinguish endpoints from each other (e.g. in DNS names). Multiple endpoints which use the same hostname should be considered fungible (e.g. multiple A values in DNS). Must be lowercase and pass DNS Label (RFC 1123) validation. + + - **endpoints.nodeName** (string) + + nodeName represents the name of the Node hosting this endpoint. This can be used to determine endpoints local to a Node. This field can be enabled with the EndpointSliceNodeName feature gate. + + - **endpoints.targetRef** (}}">ObjectReference) + + targetRef is a reference to a Kubernetes object that represents this endpoint. + + - **endpoints.zone** (string) + + zone is the name of the Zone this endpoint exists in. + +- **ports** ([]EndpointPort) + + *Atomic: will be replaced during a merge* + + ports specifies the list of network ports exposed by each endpoint in this slice. Each port must have a unique name. When ports is empty, it indicates that there are no defined ports. When a port is defined with a nil port value, it indicates "all ports". Each slice may include a maximum of 100 ports. + + + *EndpointPort represents a Port used by an EndpointSlice* + + - **ports.port** (int32) + + The port number of the endpoint. If this is not specified, ports are not restricted and must be interpreted in the context of the specific consumer. + + - **ports.protocol** (string) + + The IP protocol for this port. Must be UDP, TCP, or SCTP. Default is TCP. + + - **ports.name** (string) + + The name of this port. All ports in an EndpointSlice must have a unique name. If the EndpointSlice is dervied from a Kubernetes service, this corresponds to the Service.ports[].name. Name must either be an empty string or pass DNS_LABEL validation: * must be no more than 63 characters long. * must consist of lower case alphanumeric characters or '-'. * must start and end with an alphanumeric character. Default is empty string. + + - **ports.appProtocol** (string) + + The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and http://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol. + + + + + +## EndpointSliceList {#EndpointSliceList} + +EndpointSliceList represents a list of endpoint slices + +
+ +- **apiVersion**: discovery.k8s.io/v1 + + +- **kind**: EndpointSliceList + + +- **metadata** (}}">ListMeta) + + Standard list metadata. + +- **items** ([]}}">EndpointSlice), required + + List of endpoint slices + + + + + +## Operations {#Operations} + + + +
+ + + + + + +### `get` read the specified EndpointSlice + +#### HTTP Request + +GET /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EndpointSlice + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EndpointSlice): OK + +401: Unauthorized + + +### `list` list or watch objects of kind EndpointSlice + +#### HTTP Request + +GET /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">EndpointSliceList): OK + +401: Unauthorized + + +### `list` list or watch objects of kind EndpointSlice + +#### HTTP Request + +GET /apis/discovery.k8s.io/v1/endpointslices + +#### Parameters + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">EndpointSliceList): OK + +401: Unauthorized + + +### `create` create an EndpointSlice + +#### HTTP Request + +POST /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">EndpointSlice, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EndpointSlice): OK + +201 (}}">EndpointSlice): Created + +202 (}}">EndpointSlice): Accepted + +401: Unauthorized + + +### `update` replace the specified EndpointSlice + +#### HTTP Request + +PUT /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EndpointSlice + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">EndpointSlice, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EndpointSlice): OK + +201 (}}">EndpointSlice): Created + +401: Unauthorized + + +### `patch` partially update the specified EndpointSlice + +#### HTTP Request + +PATCH /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EndpointSlice + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EndpointSlice): OK + +401: Unauthorized + + +### `delete` delete an EndpointSlice + +#### HTTP Request + +DELETE /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EndpointSlice + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + + +#### Response + + +200 (}}">Status): OK + +202 (}}">Status): Accepted + +401: Unauthorized + + +### `deletecollection` delete collection of EndpointSlice + +#### HTTP Request + +DELETE /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **continue** (*in query*): string + + }}">continue + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + + +#### Response + + +200 (}}">Status): OK + +401: Unauthorized + diff --git a/content/en/docs/reference/kubernetes-api/service-resources/endpoints-v1.md b/content/en/docs/reference/kubernetes-api/service-resources/endpoints-v1.md index ce5c582b30..223f9d2d54 100644 --- a/content/en/docs/reference/kubernetes-api/service-resources/endpoints-v1.md +++ b/content/en/docs/reference/kubernetes-api/service-resources/endpoints-v1.md @@ -62,21 +62,21 @@ Endpoints is a collection of endpoints that implement the actual service. Exampl *EndpointAddress is a tuple that describes single IP address.* - - **subsets.addresses.ip** (string), required + - **subsets.addresses.ip** (string), required - The IP of this endpoint. May not be loopback (127.0.0.0/8), link-local (169.254.0.0/16), or link-local multicast ((224.0.0.0/24). IPv6 is also accepted but not fully supported on all platforms. Also, certain kubernetes components, like kube-proxy, are not IPv6 ready. + The IP of this endpoint. May not be loopback (127.0.0.0/8), link-local (169.254.0.0/16), or link-local multicast ((224.0.0.0/24). IPv6 is also accepted but not fully supported on all platforms. Also, certain kubernetes components, like kube-proxy, are not IPv6 ready. - - **subsets.addresses.hostname** (string) + - **subsets.addresses.hostname** (string) - The Hostname of this endpoint + The Hostname of this endpoint - - **subsets.addresses.nodeName** (string) + - **subsets.addresses.nodeName** (string) - Optional: Node hosting this endpoint. This can be used to determine endpoints local to a node. + Optional: Node hosting this endpoint. This can be used to determine endpoints local to a node. - - **subsets.addresses.targetRef** (}}">ObjectReference) + - **subsets.addresses.targetRef** (}}">ObjectReference) - Reference to object providing the endpoint. + Reference to object providing the endpoint. - **subsets.notReadyAddresses** ([]EndpointAddress) @@ -85,21 +85,21 @@ Endpoints is a collection of endpoints that implement the actual service. Exampl *EndpointAddress is a tuple that describes single IP address.* - - **subsets.notReadyAddresses.ip** (string), required + - **subsets.notReadyAddresses.ip** (string), required - The IP of this endpoint. May not be loopback (127.0.0.0/8), link-local (169.254.0.0/16), or link-local multicast ((224.0.0.0/24). IPv6 is also accepted but not fully supported on all platforms. Also, certain kubernetes components, like kube-proxy, are not IPv6 ready. + The IP of this endpoint. May not be loopback (127.0.0.0/8), link-local (169.254.0.0/16), or link-local multicast ((224.0.0.0/24). IPv6 is also accepted but not fully supported on all platforms. Also, certain kubernetes components, like kube-proxy, are not IPv6 ready. - - **subsets.notReadyAddresses.hostname** (string) + - **subsets.notReadyAddresses.hostname** (string) - The Hostname of this endpoint + The Hostname of this endpoint - - **subsets.notReadyAddresses.nodeName** (string) + - **subsets.notReadyAddresses.nodeName** (string) - Optional: Node hosting this endpoint. This can be used to determine endpoints local to a node. + Optional: Node hosting this endpoint. This can be used to determine endpoints local to a node. - - **subsets.notReadyAddresses.targetRef** (}}">ObjectReference) + - **subsets.notReadyAddresses.targetRef** (}}">ObjectReference) - Reference to object providing the endpoint. + Reference to object providing the endpoint. - **subsets.ports** ([]EndpointPort) @@ -108,21 +108,21 @@ Endpoints is a collection of endpoints that implement the actual service. Exampl *EndpointPort is a tuple that describes a single port.* - - **subsets.ports.port** (int32), required + - **subsets.ports.port** (int32), required - The port number of the endpoint. + The port number of the endpoint. - - **subsets.ports.protocol** (string) + - **subsets.ports.protocol** (string) - The IP protocol for this port. Must be UDP, TCP, or SCTP. Default is TCP. + The IP protocol for this port. Must be UDP, TCP, or SCTP. Default is TCP. - - **subsets.ports.name** (string) + - **subsets.ports.name** (string) - The name of this port. This must match the 'name' field in the corresponding ServicePort. Must be a DNS_LABEL. Optional only if one port is defined. + The name of this port. This must match the 'name' field in the corresponding ServicePort. Must be a DNS_LABEL. Optional only if one port is defined. - - **subsets.ports.appProtocol** (string) + - **subsets.ports.appProtocol** (string) - The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and http://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol. This is a beta field that is guarded by the ServiceAppProtocol feature gate and enabled by default. + The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and http://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol. This is a beta field that is guarded by the ServiceAppProtocol feature gate and enabled by default. diff --git a/content/en/docs/reference/kubernetes-api/service-resources/ingress-class-v1.md b/content/en/docs/reference/kubernetes-api/service-resources/ingress-class-v1.md index 92ad085310..a6dd55e7c7 100644 --- a/content/en/docs/reference/kubernetes-api/service-resources/ingress-class-v1.md +++ b/content/en/docs/reference/kubernetes-api/service-resources/ingress-class-v1.md @@ -48,10 +48,33 @@ IngressClassSpec provides information about the class of an Ingress. Controller refers to the name of the controller that should handle this class. This allows for different "flavors" that are controlled by the same controller. For example, you may have different Parameters for the same implementing controller. This should be specified as a domain-prefixed path no more than 250 characters in length, e.g. "acme.io/ingress-controller". This field is immutable. -- **parameters** (}}">TypedLocalObjectReference) +- **parameters** (IngressClassParametersReference) Parameters is a link to a custom resource containing additional configuration for the controller. This is optional if the controller does not require extra parameters. + + *IngressClassParametersReference identifies an API object. This can be used to specify a cluster or namespace-scoped resource.* + + - **parameters.kind** (string), required + + Kind is the type of resource being referenced. + + - **parameters.name** (string), required + + Name is the name of resource being referenced. + + - **parameters.apiGroup** (string) + + APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. + + - **parameters.namespace** (string) + + Namespace is the namespace of the resource being referenced. This field is required when scope is set to "Namespace" and must be unset when scope is set to "Cluster". + + - **parameters.scope** (string) + + Scope represents if this refers to a cluster or namespace scoped resource. This may be set to "Cluster" (default) or "Namespace". Field can be enabled with IngressClassNamespacedParams feature gate. + diff --git a/content/en/docs/reference/kubernetes-api/service-resources/ingress-v1.md b/content/en/docs/reference/kubernetes-api/service-resources/ingress-v1.md index 72a0383f96..6f8ebf1aad 100644 --- a/content/en/docs/reference/kubernetes-api/service-resources/ingress-v1.md +++ b/content/en/docs/reference/kubernetes-api/service-resources/ingress-v1.md @@ -48,43 +48,10 @@ IngressSpec describes the Ingress the user wishes to exist.
-- **defaultBackend** (IngressBackend) +- **defaultBackend** (}}">IngressBackend) DefaultBackend is the backend that should handle requests that don't match any rule. If Rules are not specified, DefaultBackend must be specified. If DefaultBackend is not set, the handling of requests that do not match any of the rules will be up to the Ingress controller. - - *IngressBackend describes all endpoints for a given service and port.* - - - **defaultBackend.resource** (}}">TypedLocalObjectReference) - - Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object. If resource is specified, a service.Name and service.Port must not be specified. This is a mutually exclusive setting with "Service". - - - **defaultBackend.service** (IngressServiceBackend) - - Service references a Service as a Backend. This is a mutually exclusive setting with "Resource". - - - *IngressServiceBackend references a Kubernetes Service as a Backend.* - - - **defaultBackend.service.name** (string), required - - Name is the referenced service. The service must exist in the same namespace as the Ingress object. - - - **defaultBackend.service.port** (ServiceBackendPort) - - Port of the referenced service. A port name or port number is required for a IngressServiceBackend. - - - *ServiceBackendPort is the service port being referenced.* - - - **defaultBackend.service.port.name** (string) - - Name is the name of the port on the Service. This is a mutually exclusive setting with "Number". - - - **defaultBackend.service.port.number** (int32) - - Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name". - - **ingressClassName** (string) IngressClassName is the name of the IngressClass cluster resource. The associated IngressClass defines which controller will implement the resource. This replaces the deprecated `kubernetes.io/ingress.class` annotation. For backwards compatibility, when that annotation is set, it must be given precedence over this field. The controller may emit a warning if the field and annotation have different values. Implementations of this API should ignore Ingresses without a class specified. An IngressClass resource may be marked as default, which can be used to set a default value for this field. For more information, refer to the IngressClass documentation. @@ -115,69 +82,36 @@ IngressSpec describes the Ingress the user wishes to exist. *HTTPIngressRuleValue is a list of http selectors pointing to backends. In the example: http:///? -> backend where where parts of the url correspond to RFC 3986, this resource will be used to match against everything after the last '/' and before the first '?' or '#'.* - - **rules.http.paths** ([]HTTPIngressPath), required + - **rules.http.paths** ([]HTTPIngressPath), required - *Atomic: will be replaced during a merge* - - A collection of paths that map requests to backends. + *Atomic: will be replaced during a merge* + + A collection of paths that map requests to backends. - - *HTTPIngressPath associates a path with a backend. Incoming urls matching the path are forwarded to the backend.* + + *HTTPIngressPath associates a path with a backend. Incoming urls matching the path are forwarded to the backend.* - - **rules.http.paths.backend** (IngressBackend), required + - **rules.http.paths.backend** (}}">IngressBackend), required - Backend defines the referenced service endpoint to which the traffic will be forwarded to. + Backend defines the referenced service endpoint to which the traffic will be forwarded to. - - *IngressBackend describes all endpoints for a given service and port.* + - **rules.http.paths.path** (string) - - **rules.http.paths.backend.resource** (}}">TypedLocalObjectReference) + Path is matched against the path of an incoming request. Currently it can contain characters disallowed from the conventional "path" part of a URL as defined by RFC 3986. Paths must begin with a '/'. When unspecified, all paths from incoming requests are matched. - Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object. If resource is specified, a service.Name and service.Port must not be specified. This is a mutually exclusive setting with "Service". + - **rules.http.paths.pathType** (string) - - **rules.http.paths.backend.service** (IngressServiceBackend) - - Service references a Service as a Backend. This is a mutually exclusive setting with "Resource". - - - *IngressServiceBackend references a Kubernetes Service as a Backend.* - - - **rules.http.paths.backend.service.name** (string), required - - Name is the referenced service. The service must exist in the same namespace as the Ingress object. - - - **rules.http.paths.backend.service.port** (ServiceBackendPort) - - Port of the referenced service. A port name or port number is required for a IngressServiceBackend. - - - *ServiceBackendPort is the service port being referenced.* - - - **rules.http.paths.backend.service.port.name** (string) - - Name is the name of the port on the Service. This is a mutually exclusive setting with "Number". - - - **rules.http.paths.backend.service.port.number** (int32) - - Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name". - - - **rules.http.paths.path** (string) - - Path is matched against the path of an incoming request. Currently it can contain characters disallowed from the conventional "path" part of a URL as defined by RFC 3986. Paths must begin with a '/'. When unspecified, all paths from incoming requests are matched. - - - **rules.http.paths.pathType** (string) - - PathType determines the interpretation of the Path matching. PathType can be one of the following values: * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is - done on a path element by element basis. A path element refers is the - list of labels in the path split by the '/' separator. A request is a - match for path p if every p is an element-wise prefix of p of the - request path. Note that if the last element of the path is a substring - of the last element in request path, it is not a match (e.g. /foo/bar - matches /foo/bar/baz, but does not match /foo/barbaz). - * ImplementationSpecific: Interpretation of the Path matching is up to - the IngressClass. Implementations can treat this as a separate PathType - or treat it identically to Prefix or Exact path types. - Implementations are required to support all path types. + PathType determines the interpretation of the Path matching. PathType can be one of the following values: * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is + done on a path element by element basis. A path element refers is the + list of labels in the path split by the '/' separator. A request is a + match for path p if every p is an element-wise prefix of p of the + request path. Note that if the last element of the path is a substring + of the last element in request path, it is not a match (e.g. /foo/bar + matches /foo/bar/baz, but does not match /foo/barbaz). + * ImplementationSpecific: Interpretation of the Path matching is up to + the IngressClass. Implementations can treat this as a separate PathType + or treat it identically to Prefix or Exact path types. + Implementations are required to support all path types. - **tls** ([]IngressTLS) @@ -202,6 +136,46 @@ IngressSpec describes the Ingress the user wishes to exist. +## IngressBackend {#IngressBackend} + +IngressBackend describes all endpoints for a given service and port. + +
+ +- **resource** (}}">TypedLocalObjectReference) + + Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object. If resource is specified, a service.Name and service.Port must not be specified. This is a mutually exclusive setting with "Service". + +- **service** (IngressServiceBackend) + + Service references a Service as a Backend. This is a mutually exclusive setting with "Resource". + + + *IngressServiceBackend references a Kubernetes Service as a Backend.* + + - **service.name** (string), required + + Name is the referenced service. The service must exist in the same namespace as the Ingress object. + + - **service.port** (ServiceBackendPort) + + Port of the referenced service. A port name or port number is required for a IngressServiceBackend. + + + *ServiceBackendPort is the service port being referenced.* + + - **service.port.name** (string) + + Name is the name of the port on the Service. This is a mutually exclusive setting with "Number". + + - **service.port.number** (int32) + + Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name". + + + + + ## IngressStatus {#IngressStatus} IngressStatus describe the current state of the Ingress. @@ -222,37 +196,37 @@ IngressStatus describe the current state of the Ingress. *LoadBalancerIngress represents the status of a load-balancer ingress point: traffic intended for the service should be sent to an ingress point.* - - **loadBalancer.ingress.hostname** (string) + - **loadBalancer.ingress.hostname** (string) - Hostname is set for load-balancer ingress points that are DNS based (typically AWS load-balancers) + Hostname is set for load-balancer ingress points that are DNS based (typically AWS load-balancers) - - **loadBalancer.ingress.ip** (string) + - **loadBalancer.ingress.ip** (string) - IP is set for load-balancer ingress points that are IP based (typically GCE or OpenStack load-balancers) + IP is set for load-balancer ingress points that are IP based (typically GCE or OpenStack load-balancers) - - **loadBalancer.ingress.ports** ([]PortStatus) + - **loadBalancer.ingress.ports** ([]PortStatus) - *Atomic: will be replaced during a merge* - - Ports is a list of records of service ports If used, every port defined in the service should have an entry in it + *Atomic: will be replaced during a merge* + + Ports is a list of records of service ports If used, every port defined in the service should have an entry in it - - ** + + ** - - **loadBalancer.ingress.ports.port** (int32), required + - **loadBalancer.ingress.ports.port** (int32), required - Port is the port number of the service port of which status is recorded here + Port is the port number of the service port of which status is recorded here - - **loadBalancer.ingress.ports.protocol** (string), required + - **loadBalancer.ingress.ports.protocol** (string), required - Protocol is the protocol of the service port of which status is recorded here The supported values are: "TCP", "UDP", "SCTP" + Protocol is the protocol of the service port of which status is recorded here The supported values are: "TCP", "UDP", "SCTP" - - **loadBalancer.ingress.ports.error** (string) + - **loadBalancer.ingress.ports.error** (string) - Error is to record the problem with the service port The format of the error shall comply with the following rules: - built-in error values shall be specified in this file and those shall use - CamelCase names - - cloud provider specific error values must have names that comply with the - format foo.example.com/CamelCase. + Error is to record the problem with the service port The format of the error shall comply with the following rules: - built-in error values shall be specified in this file and those shall use + CamelCase names + - cloud provider specific error values must have names that comply with the + format foo.example.com/CamelCase. @@ -264,20 +238,22 @@ IngressList is a collection of Ingress.
-- **apiVersion**: networking.k8s.io/v1 +- **items** ([]}}">Ingress), required + Items is the list of Ingress. -- **kind**: IngressList +- **apiVersion** (string) + APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +- **kind** (string) + + Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - **metadata** (}}">ListMeta) Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata -- **items** ([]}}">Ingress), required - - Items is the list of Ingress. - diff --git a/content/en/docs/reference/kubernetes-api/service-resources/service-v1.md b/content/en/docs/reference/kubernetes-api/service-resources/service-v1.md index 3ed9e93d96..ab17bf3f0e 100644 --- a/content/en/docs/reference/kubernetes-api/service-resources/service-v1.md +++ b/content/en/docs/reference/kubernetes-api/service-resources/service-v1.md @@ -134,14 +134,22 @@ ServiceSpec describes the attributes that a user creates on a service. If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature." More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/ +- **loadBalancerClass** (string) + + loadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix, e.g. "internal-vip" or "example.com/internal-vip". Unprefixed names are reserved for end-users. This field can only be set when the Service type is 'LoadBalancer'. If not set, the default load balancer implementation is used, today this is typically done through the cloud provider integration, but should apply for any default implementation. If set, it is assumed that a load balancer implementation is watching for Services with a matching class. Any default load balancer implementation (e.g. cloud providers) should ignore Services that set this field. This field can only be set when creating or updating a Service to type 'LoadBalancer'. Once set, it can not be changed. This field will be wiped when a service is updated to a non 'LoadBalancer' type. + - **externalName** (string) - externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires Type to be + externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires `type` to be "ExternalName". - **externalTrafficPolicy** (string) externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. "Local" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. "Cluster" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading. +- **internalTrafficPolicy** (string) + + InternalTrafficPolicy specifies if the cluster internal traffic should be routed to all endpoints or node-local endpoints only. "Cluster" routes internal traffic to a Service to all endpoints. "Local" routes traffic to node-local endpoints only, traffic is dropped if no node-local endpoints are ready. The default value is "Cluster". + - **healthCheckNodePort** (int32) healthCheckNodePort specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used. If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type). @@ -164,13 +172,13 @@ ServiceSpec describes the attributes that a user creates on a service. *ClientIPConfig represents the configurations of Client IP based session affinity.* - - **sessionAffinityConfig.clientIP.timeoutSeconds** (int32) + - **sessionAffinityConfig.clientIP.timeoutSeconds** (int32) - timeoutSeconds specifies the seconds of ClientIP type session sticky time. The value must be >0 && \<=86400(for 1 day) if ServiceAffinity == "ClientIP". Default value is 10800(for 3 hours). + timeoutSeconds specifies the seconds of ClientIP type session sticky time. The value must be >0 && \<=86400(for 1 day) if ServiceAffinity == "ClientIP". Default value is 10800(for 3 hours). - **topologyKeys** ([]string) - topologyKeys is a preference-order list of topology keys which implementations of services should use to preferentially sort endpoints when accessing this Service, it can not be used at the same time as externalTrafficPolicy=Local. Topology keys must be valid label keys and at most 16 keys may be specified. Endpoints are chosen based on the first topology key with available backends. If this field is specified and all entries have no backends that match the topology of the client, the service has no backends for that client and connections should fail. The special value "*" may be used to mean "any topology". This catch-all value, if used, only makes sense as the last value in the list. If this is not specified or empty, no topology constraints will be applied. This field is alpha-level and is only honored by servers that enable the ServiceTopology feature. + topologyKeys is a preference-order list of topology keys which implementations of services should use to preferentially sort endpoints when accessing this Service, it can not be used at the same time as externalTrafficPolicy=Local. Topology keys must be valid label keys and at most 16 keys may be specified. Endpoints are chosen based on the first topology key with available backends. If this field is specified and all entries have no backends that match the topology of the client, the service has no backends for that client and connections should fail. The special value "*" may be used to mean "any topology". This catch-all value, if used, only makes sense as the last value in the list. If this is not specified or empty, no topology constraints will be applied. This field is alpha-level and is only honored by servers that enable the ServiceTopology feature. This field is deprecated and will be removed in a future version. - **allocateLoadBalancerNodePorts** (boolean) @@ -238,37 +246,37 @@ ServiceStatus represents the current status of a service. *LoadBalancerIngress represents the status of a load-balancer ingress point: traffic intended for the service should be sent to an ingress point.* - - **loadBalancer.ingress.hostname** (string) + - **loadBalancer.ingress.hostname** (string) - Hostname is set for load-balancer ingress points that are DNS based (typically AWS load-balancers) + Hostname is set for load-balancer ingress points that are DNS based (typically AWS load-balancers) - - **loadBalancer.ingress.ip** (string) + - **loadBalancer.ingress.ip** (string) - IP is set for load-balancer ingress points that are IP based (typically GCE or OpenStack load-balancers) + IP is set for load-balancer ingress points that are IP based (typically GCE or OpenStack load-balancers) - - **loadBalancer.ingress.ports** ([]PortStatus) + - **loadBalancer.ingress.ports** ([]PortStatus) - *Atomic: will be replaced during a merge* - - Ports is a list of records of service ports If used, every port defined in the service should have an entry in it + *Atomic: will be replaced during a merge* + + Ports is a list of records of service ports If used, every port defined in the service should have an entry in it - - ** + + ** - - **loadBalancer.ingress.ports.port** (int32), required + - **loadBalancer.ingress.ports.port** (int32), required - Port is the port number of the service port of which status is recorded here + Port is the port number of the service port of which status is recorded here - - **loadBalancer.ingress.ports.protocol** (string), required + - **loadBalancer.ingress.ports.protocol** (string), required - Protocol is the protocol of the service port of which status is recorded here The supported values are: "TCP", "UDP", "SCTP" + Protocol is the protocol of the service port of which status is recorded here The supported values are: "TCP", "UDP", "SCTP" - - **loadBalancer.ingress.ports.error** (string) + - **loadBalancer.ingress.ports.error** (string) - Error is to record the problem with the service port The format of the error shall comply with the following rules: - built-in error values shall be specified in this file and those shall use - CamelCase names - - cloud provider specific error values must have names that comply with the - format foo.example.com/CamelCase. + Error is to record the problem with the service port The format of the error shall comply with the following rules: - built-in error values shall be specified in this file and those shall use + CamelCase names + - cloud provider specific error values must have names that comply with the + format foo.example.com/CamelCase. diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/controller-revision-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/controller-revision-v1.md index 5caea2a5d9..d13ae1b404 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/controller-revision-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/controller-revision-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ControllerRevision implements an immutable snapshot of state data." title: "ControllerRevision" -weight: 9 +weight: 8 --- `apiVersion: apps/v1` diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/cron-job-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/cron-job-v1.md new file mode 100644 index 0000000000..f6196ef14d --- /dev/null +++ b/content/en/docs/reference/kubernetes-api/workload-resources/cron-job-v1.md @@ -0,0 +1,755 @@ +--- +api_metadata: + apiVersion: "batch/v1" + import: "k8s.io/api/batch/v1" + kind: "CronJob" +content_type: "api_reference" +description: "CronJob represents the configuration of a single cron job." +title: "CronJob" +weight: 11 +--- + +`apiVersion: batch/v1` + +`import "k8s.io/api/batch/v1"` + + +## CronJob {#CronJob} + +CronJob represents the configuration of a single cron job. + +
+ +- **apiVersion**: batch/v1 + + +- **kind**: CronJob + + +- **metadata** (}}">ObjectMeta) + + Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +- **spec** (}}">CronJobSpec) + + Specification of the desired behavior of a cron job, including the schedule. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status + +- **status** (}}">CronJobStatus) + + Current status of a cron job. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status + + + + + +## CronJobSpec {#CronJobSpec} + +CronJobSpec describes how the job execution will look like and when it will actually run. + +
+ +- **jobTemplate** (JobTemplateSpec), required + + Specifies the job that will be created when executing a CronJob. + + + *JobTemplateSpec describes the data a Job should have when created from a template* + + - **jobTemplate.metadata** (}}">ObjectMeta) + + Standard object's metadata of the jobs created from this template. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + + - **jobTemplate.spec** (}}">JobSpec) + + Specification of the desired behavior of the job. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status + +- **schedule** (string), required + + The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron. + +- **concurrencyPolicy** (string) + + Specifies how to treat concurrent executions of a Job. Valid values are: - "Allow" (default): allows CronJobs to run concurrently; - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet; - "Replace": cancels currently running job and replaces it with a new one + +- **startingDeadlineSeconds** (int64) + + Optional deadline in seconds for starting the job if it misses scheduled time for any reason. Missed jobs executions will be counted as failed ones. + +- **suspend** (boolean) + + This flag tells the controller to suspend subsequent executions, it does not apply to already started executions. Defaults to false. + +- **successfulJobsHistoryLimit** (int32) + + The number of successful finished jobs to retain. Value must be non-negative integer. Defaults to 3. + +- **failedJobsHistoryLimit** (int32) + + The number of failed finished jobs to retain. Value must be non-negative integer. Defaults to 1. + + + + + +## CronJobStatus {#CronJobStatus} + +CronJobStatus represents the current state of a cron job. + +
+ +- **active** ([]}}">ObjectReference) + + *Atomic: will be replaced during a merge* + + A list of pointers to currently running jobs. + +- **lastScheduleTime** (Time) + + Information when was the last time the job was successfully scheduled. + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + +- **lastSuccessfulTime** (Time) + + Information when was the last time the job successfully completed. + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + + + + +## CronJobList {#CronJobList} + +CronJobList is a collection of cron jobs. + +
+ +- **apiVersion**: batch/v1 + + +- **kind**: CronJobList + + +- **metadata** (}}">ListMeta) + + Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata + +- **items** ([]}}">CronJob), required + + items is the list of CronJobs. + + + + + +## Operations {#Operations} + + + +
+ + + + + + +### `get` read the specified CronJob + +#### HTTP Request + +GET /apis/batch/v1/namespaces/{namespace}/cronjobs/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +401: Unauthorized + + +### `get` read status of the specified CronJob + +#### HTTP Request + +GET /apis/batch/v1/namespaces/{namespace}/cronjobs/{name}/status + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +401: Unauthorized + + +### `list` list or watch objects of kind CronJob + +#### HTTP Request + +GET /apis/batch/v1/namespaces/{namespace}/cronjobs + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">CronJobList): OK + +401: Unauthorized + + +### `list` list or watch objects of kind CronJob + +#### HTTP Request + +GET /apis/batch/v1/cronjobs + +#### Parameters + + +- **allowWatchBookmarks** (*in query*): boolean + + }}">allowWatchBookmarks + + +- **continue** (*in query*): string + + }}">continue + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + +- **watch** (*in query*): boolean + + }}">watch + + + +#### Response + + +200 (}}">CronJobList): OK + +401: Unauthorized + + +### `create` create a CronJob + +#### HTTP Request + +POST /apis/batch/v1/namespaces/{namespace}/cronjobs + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">CronJob, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +201 (}}">CronJob): Created + +202 (}}">CronJob): Accepted + +401: Unauthorized + + +### `update` replace the specified CronJob + +#### HTTP Request + +PUT /apis/batch/v1/namespaces/{namespace}/cronjobs/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">CronJob, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +201 (}}">CronJob): Created + +401: Unauthorized + + +### `update` replace status of the specified CronJob + +#### HTTP Request + +PUT /apis/batch/v1/namespaces/{namespace}/cronjobs/{name}/status + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">CronJob, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +201 (}}">CronJob): Created + +401: Unauthorized + + +### `patch` partially update the specified CronJob + +#### HTTP Request + +PATCH /apis/batch/v1/namespaces/{namespace}/cronjobs/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +401: Unauthorized + + +### `patch` partially update status of the specified CronJob + +#### HTTP Request + +PATCH /apis/batch/v1/namespaces/{namespace}/cronjobs/{name}/status + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">CronJob): OK + +401: Unauthorized + + +### `delete` delete a CronJob + +#### HTTP Request + +DELETE /apis/batch/v1/namespaces/{namespace}/cronjobs/{name} + +#### Parameters + + +- **name** (*in path*): string, required + + name of the CronJob + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + + +#### Response + + +200 (}}">Status): OK + +202 (}}">Status): Accepted + +401: Unauthorized + + +### `deletecollection` delete collection of CronJob + +#### HTTP Request + +DELETE /apis/batch/v1/namespaces/{namespace}/cronjobs + +#### Parameters + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">DeleteOptions + + + + +- **continue** (*in query*): string + + }}">continue + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldSelector** (*in query*): string + + }}">fieldSelector + + +- **gracePeriodSeconds** (*in query*): integer + + }}">gracePeriodSeconds + + +- **labelSelector** (*in query*): string + + }}">labelSelector + + +- **limit** (*in query*): integer + + }}">limit + + +- **pretty** (*in query*): string + + }}">pretty + + +- **propagationPolicy** (*in query*): string + + }}">propagationPolicy + + +- **resourceVersion** (*in query*): string + + }}">resourceVersion + + +- **resourceVersionMatch** (*in query*): string + + }}">resourceVersionMatch + + +- **timeoutSeconds** (*in query*): integer + + }}">timeoutSeconds + + + +#### Response + + +200 (}}">Status): OK + +401: Unauthorized + diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/daemon-set-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/daemon-set-v1.md index 169d361c2a..a40aa4c592 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/daemon-set-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/daemon-set-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "DaemonSet represents the configuration of a daemon set." title: "DaemonSet" -weight: 10 +weight: 9 --- `apiVersion: apps/v1` @@ -78,12 +78,19 @@ DaemonSetSpec is the specification of a daemon set. *Spec to control the desired behavior of daemon set rolling update.* - - **updateStrategy.rollingUpdate.maxUnavailable** (IntOrString) + - **updateStrategy.rollingUpdate.maxSurge** (IntOrString) - The maximum number of DaemonSet pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of total number of DaemonSet pods at the start of the update (ex: 10%). Absolute number is calculated from percentage by rounding up. This cannot be 0. Default value is 1. Example: when this is set to 30%, at most 30% of the total number of nodes that should be running the daemon pod (i.e. status.desiredNumberScheduled) can have their pods stopped for an update at any given time. The update starts by stopping at most 30% of those DaemonSet pods and then brings up new DaemonSet pods in their place. Once the new pods are available, it then proceeds onto other DaemonSet pods, thus ensuring that at least 70% of original number of DaemonSet pods are available at all times during the update. + The maximum number of nodes with an existing available DaemonSet pod that can have an updated DaemonSet pod during during an update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). This can not be 0 if MaxUnavailable is 0. Absolute number is calculated from percentage by rounding up to a minimum of 1. Default value is 0. Example: when this is set to 30%, at most 30% of the total number of nodes that should be running the daemon pod (i.e. status.desiredNumberScheduled) can have their a new pod created before the old pod is marked as deleted. The update starts by launching new pods on 30% of nodes. Once an updated pod is available (Ready for at least minReadySeconds) the old DaemonSet pod on that node is marked deleted. If the old pod becomes unavailable for any reason (Ready transitions to false, is evicted, or is drained) an updated pod is immediatedly created on that node without considering surge limits. Allowing surge implies the possibility that the resources consumed by the daemonset on any given node can double if the readiness check fails, and so resource intensive daemonsets should take into account that they may cause evictions during disruption. This is an alpha field and requires enabling DaemonSetUpdateSurge feature gate. - - *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + - **updateStrategy.rollingUpdate.maxUnavailable** (IntOrString) + + The maximum number of DaemonSet pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of total number of DaemonSet pods at the start of the update (ex: 10%). Absolute number is calculated from percentage by rounding down to a minimum of one. This cannot be 0 if MaxSurge is 0 Default value is 1. Example: when this is set to 30%, at most 30% of the total number of nodes that should be running the daemon pod (i.e. status.desiredNumberScheduled) can have their pods stopped for an update at any given time. The update starts by stopping at most 30% of those DaemonSet pods and then brings up new DaemonSet pods in their place. Once the new pods are available, it then proceeds onto other DaemonSet pods, thus ensuring that at least 70% of original number of DaemonSet pods are available at all times during the update. + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* - **revisionHistoryLimit** (int32) diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/deployment-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/deployment-v1.md index 052a54bcc8..b455760a4c 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/deployment-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/deployment-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "Deployment enables declarative updates for Pods and ReplicaSets." title: "Deployment" -weight: 7 +weight: 6 --- `apiVersion: apps/v1` @@ -84,19 +84,19 @@ DeploymentSpec is the specification of the desired behavior of the Deployment. *Spec to control the desired behavior of rolling update.* - - **strategy.rollingUpdate.maxSurge** (IntOrString) + - **strategy.rollingUpdate.maxSurge** (IntOrString) - The maximum number of pods that can be scheduled above the desired number of pods. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). This can not be 0 if MaxUnavailable is 0. Absolute number is calculated from percentage by rounding up. Defaults to 25%. Example: when this is set to 30%, the new ReplicaSet can be scaled up immediately when the rolling update starts, such that the total number of old and new pods do not exceed 130% of desired pods. Once old pods have been killed, new ReplicaSet can be scaled up further, ensuring that total number of pods running at any time during the update is at most 130% of desired pods. + The maximum number of pods that can be scheduled above the desired number of pods. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). This can not be 0 if MaxUnavailable is 0. Absolute number is calculated from percentage by rounding up. Defaults to 25%. Example: when this is set to 30%, the new ReplicaSet can be scaled up immediately when the rolling update starts, such that the total number of old and new pods do not exceed 130% of desired pods. Once old pods have been killed, new ReplicaSet can be scaled up further, ensuring that total number of pods running at any time during the update is at most 130% of desired pods. - - *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* - - **strategy.rollingUpdate.maxUnavailable** (IntOrString) + - **strategy.rollingUpdate.maxUnavailable** (IntOrString) - The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding down. This can not be 0 if MaxSurge is 0. Defaults to 25%. Example: when this is set to 30%, the old ReplicaSet can be scaled down to 70% of desired pods immediately when the rolling update starts. Once new pods are ready, old ReplicaSet can be scaled down further, followed by scaling up the new ReplicaSet, ensuring that the total number of pods available at all times during the update is at least 70% of desired pods. + The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding down. This can not be 0 if MaxSurge is 0. Defaults to 25%. Example: when this is set to 30%, the old ReplicaSet can be scaled down to 70% of desired pods immediately when the rolling update starts. Once new pods are ready, old ReplicaSet can be scaled down further, followed by scaling up the new ReplicaSet, ensuring that the total number of pods available at all times during the update is at least 70% of desired pods. - - *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* - **revisionHistoryLimit** (int32) diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/ephemeral-containers-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/ephemeral-containers-v1.md new file mode 100644 index 0000000000..05957e573a --- /dev/null +++ b/content/en/docs/reference/kubernetes-api/workload-resources/ephemeral-containers-v1.md @@ -0,0 +1,609 @@ +--- +api_metadata: + apiVersion: "v1" + import: "k8s.io/api/core/v1" + kind: "EphemeralContainers" +content_type: "api_reference" +description: "A list of ephemeral containers used with the Pod ephemeralcontainers subresource." +title: "EphemeralContainers" +weight: 2 +--- + +`apiVersion: v1` + +`import "k8s.io/api/core/v1"` + + +## EphemeralContainers {#EphemeralContainers} + +A list of ephemeral containers used with the Pod ephemeralcontainers subresource. + +
+ +- **apiVersion**: v1 + + +- **kind**: EphemeralContainers + + +- **metadata** (}}">ObjectMeta) + + +- **ephemeralContainers** ([]}}">EphemeralContainer), required + + *Patch strategy: merge on key `name`* + + A list of ephemeral containers associated with this pod. New ephemeral containers may be appended to this list, but existing ephemeral containers may not be removed or modified. + + + + + +## EphemeralContainer {#EphemeralContainer} + +An EphemeralContainer is a container that may be added temporarily to an existing pod for user-initiated activities such as debugging. Ephemeral containers have no resource or scheduling guarantees, and they will not be restarted when they exit or when a pod is removed or restarted. If an ephemeral container causes a pod to exceed its resource allocation, the pod may be evicted. Ephemeral containers may not be added by directly updating the pod spec. They must be added via the pod's ephemeralcontainers subresource, and they will appear in the pod spec once added. This is an alpha feature enabled by the EphemeralContainers feature flag. + +
+ +- **name** (string), required + + Name of the ephemeral container specified as a DNS_LABEL. This name must be unique among all containers, init containers and ephemeral containers. + +- **targetContainerName** (string) + + If set, the name of the container from PodSpec that this ephemeral container targets. The ephemeral container will be run in the namespaces (IPC, PID, etc) of this container. If not set then the ephemeral container is run in whatever namespaces are shared for the pod. Note that the container runtime must support this feature. + + + +### Image + + +- **image** (string) + + Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images + +- **imagePullPolicy** (string) + + Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images + +### Entrypoint + + +- **command** ([]string) + + Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell + +- **args** ([]string) + + Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell + +- **workingDir** (string) + + Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. + +### Environment variables + + +- **env** ([]EnvVar) + + *Patch strategy: merge on key `name`* + + List of environment variables to set in the container. Cannot be updated. + + + *EnvVar represents an environment variable present in a Container.* + + - **env.name** (string), required + + Name of the environment variable. Must be a C_IDENTIFIER. + + - **env.value** (string) + + Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". + + - **env.valueFrom** (EnvVarSource) + + Source for the environment variable's value. Cannot be used if value is not empty. + + + *EnvVarSource represents a source for the value of an EnvVar.* + + - **env.valueFrom.configMapKeyRef** (ConfigMapKeySelector) + + Selects a key of a ConfigMap. + + + *Selects a key from a ConfigMap.* + + - **env.valueFrom.configMapKeyRef.key** (string), required + + The key to select. + + - **env.valueFrom.configMapKeyRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **env.valueFrom.configMapKeyRef.optional** (boolean) + + Specify whether the ConfigMap or its key must be defined + + - **env.valueFrom.fieldRef** (}}">ObjectFieldSelector) + + Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['\']`, `metadata.annotations['\']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. + + - **env.valueFrom.resourceFieldRef** (}}">ResourceFieldSelector) + + Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. + + - **env.valueFrom.secretKeyRef** (SecretKeySelector) + + Selects a key of a secret in the pod's namespace + + + *SecretKeySelector selects a key of a Secret.* + + - **env.valueFrom.secretKeyRef.key** (string), required + + The key of the secret to select from. Must be a valid secret key. + + - **env.valueFrom.secretKeyRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **env.valueFrom.secretKeyRef.optional** (boolean) + + Specify whether the Secret or its key must be defined + +- **envFrom** ([]EnvFromSource) + + List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. + + + *EnvFromSource represents the source of a set of ConfigMaps* + + - **envFrom.configMapRef** (ConfigMapEnvSource) + + The ConfigMap to select from + + + *ConfigMapEnvSource selects a ConfigMap to populate the environment variables with. + + The contents of the target ConfigMap's Data field will represent the key-value pairs as environment variables.* + + - **envFrom.configMapRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **envFrom.configMapRef.optional** (boolean) + + Specify whether the ConfigMap must be defined + + - **envFrom.prefix** (string) + + An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. + + - **envFrom.secretRef** (SecretEnvSource) + + The Secret to select from + + + *SecretEnvSource selects a Secret to populate the environment variables with. + + The contents of the target Secret's Data field will represent the key-value pairs as environment variables.* + + - **envFrom.secretRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **envFrom.secretRef.optional** (boolean) + + Specify whether the Secret must be defined + +### Volumes + + +- **volumeMounts** ([]VolumeMount) + + *Patch strategy: merge on key `mountPath`* + + Pod volumes to mount into the container's filesystem. Cannot be updated. + + + *VolumeMount describes a mounting of a Volume within a container.* + + - **volumeMounts.mountPath** (string), required + + Path within the container at which the volume should be mounted. Must not contain ':'. + + - **volumeMounts.name** (string), required + + This must match the Name of a Volume. + + - **volumeMounts.mountPropagation** (string) + + mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. + + - **volumeMounts.readOnly** (boolean) + + Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. + + - **volumeMounts.subPath** (string) + + Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). + + - **volumeMounts.subPathExpr** (string) + + Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. + +- **volumeDevices** ([]VolumeDevice) + + *Patch strategy: merge on key `devicePath`* + + volumeDevices is the list of block devices to be used by the container. + + + *volumeDevice describes a mapping of a raw block device within a container.* + + - **volumeDevices.devicePath** (string), required + + devicePath is the path inside of the container that the device will be mapped to. + + - **volumeDevices.name** (string), required + + name must match the name of a persistentVolumeClaim in the pod + +### Lifecycle + + +- **terminationMessagePath** (string) + + Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. + +- **terminationMessagePolicy** (string) + + Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. + +### Debugging + + +- **stdin** (boolean) + + Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. + +- **stdinOnce** (boolean) + + Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false + +- **tty** (boolean) + + Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. + +### Not allowed + + +- **ports** ([]ContainerPort) + + Ports are not allowed for ephemeral containers. + + + *ContainerPort represents a network port in a single container.* + + - **ports.containerPort** (int32), required + + Number of port to expose on the pod's IP address. This must be a valid port number, 0 \< x \< 65536. + + - **ports.hostIP** (string) + + What host IP to bind the external port to. + + - **ports.hostPort** (int32) + + Number of port to expose on the host. If specified, this must be a valid port number, 0 \< x \< 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. + + - **ports.name** (string) + + If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. + + - **ports.protocol** (string) + + Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". + +- **resources** (ResourceRequirements) + + Resources are not allowed for ephemeral containers. Ephemeral containers use spare resources already allocated to the pod. + + + *ResourceRequirements describes the compute resource requirements.* + + - **resources.limits** (map[string]}}">Quantity) + + Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + - **resources.requests** (map[string]}}">Quantity) + + Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +- **lifecycle** (Lifecycle) + + Lifecycle is not allowed for ephemeral containers. + + + *Lifecycle describes actions that the management system should take in response to container lifecycle events. For the PostStart and PreStop lifecycle handlers, management of the container blocks until the action is complete, unless the container process fails, in which case the handler is aborted.* + + - **lifecycle.postStart** (}}">Handler) + + PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks + + - **lifecycle.preStop** (}}">Handler) + + PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks + +- **livenessProbe** (}}">Probe) + + Probes are not allowed for ephemeral containers. + +- **readinessProbe** (}}">Probe) + + Probes are not allowed for ephemeral containers. + +- **securityContext** (SecurityContext) + + SecurityContext is not allowed for ephemeral containers. + + + *SecurityContext holds security configuration that will be applied to a container. Some fields are present in both SecurityContext and PodSecurityContext. When both are set, the values in SecurityContext take precedence.* + + - **securityContext.runAsUser** (int64) + + The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + - **securityContext.runAsNonRoot** (boolean) + + Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + - **securityContext.runAsGroup** (int64) + + The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + - **securityContext.readOnlyRootFilesystem** (boolean) + + Whether this container has a read-only root filesystem. Default is false. + + - **securityContext.procMount** (string) + + procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. + + - **securityContext.privileged** (boolean) + + Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. + + - **securityContext.allowPrivilegeEscalation** (boolean) + + AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN + + - **securityContext.capabilities** (Capabilities) + + The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. + + + *Adds and removes POSIX capabilities from running containers.* + + - **securityContext.capabilities.add** ([]string) + + Added capabilities + + - **securityContext.capabilities.drop** ([]string) + + Removed capabilities + + - **securityContext.seccompProfile** (SeccompProfile) + + The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. + + + *SeccompProfile defines a pod/container's seccomp profile settings. Only one profile source may be set.* + + - **securityContext.seccompProfile.type** (string), required + + type indicates which kind of seccomp profile will be applied. Valid options are: + + Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. + + - **securityContext.seccompProfile.localhostProfile** (string) + + localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". + + - **securityContext.seLinuxOptions** (SELinuxOptions) + + The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + + *SELinuxOptions are the labels to be applied to the container* + + - **securityContext.seLinuxOptions.level** (string) + + Level is SELinux level label that applies to the container. + + - **securityContext.seLinuxOptions.role** (string) + + Role is a SELinux role label that applies to the container. + + - **securityContext.seLinuxOptions.type** (string) + + Type is a SELinux type label that applies to the container. + + - **securityContext.seLinuxOptions.user** (string) + + User is a SELinux user label that applies to the container. + + - **securityContext.windowsOptions** (WindowsSecurityContextOptions) + + The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + + *WindowsSecurityContextOptions contain Windows-specific options and credentials.* + + - **securityContext.windowsOptions.gmsaCredentialSpec** (string) + + GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. + + - **securityContext.windowsOptions.gmsaCredentialSpecName** (string) + + GMSACredentialSpecName is the name of the GMSA credential spec to use. + + - **securityContext.windowsOptions.runAsUserName** (string) + + The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + +- **startupProbe** (}}">Probe) + + Probes are not allowed for ephemeral containers. + + + +## Operations {#Operations} + + + +
+ + + + + + +### `get` read ephemeralcontainers of the specified Pod + +#### HTTP Request + +GET /api/v1/namespaces/{namespace}/pods/{name}/ephemeralcontainers + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EphemeralContainers + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EphemeralContainers): OK + +401: Unauthorized + + +### `update` replace ephemeralcontainers of the specified Pod + +#### HTTP Request + +PUT /api/v1/namespaces/{namespace}/pods/{name}/ephemeralcontainers + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EphemeralContainers + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">EphemeralContainers, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EphemeralContainers): OK + +201 (}}">EphemeralContainers): Created + +401: Unauthorized + + +### `patch` partially update ephemeralcontainers of the specified Pod + +#### HTTP Request + +PATCH /api/v1/namespaces/{namespace}/pods/{name}/ephemeralcontainers + +#### Parameters + + +- **name** (*in path*): string, required + + name of the EphemeralContainers + + +- **namespace** (*in path*): string, required + + }}">namespace + + +- **body**: }}">Patch, required + + + + +- **dryRun** (*in query*): string + + }}">dryRun + + +- **fieldManager** (*in query*): string + + }}">fieldManager + + +- **force** (*in query*): boolean + + }}">force + + +- **pretty** (*in query*): string + + }}">pretty + + + +#### Response + + +200 (}}">EphemeralContainers): OK + +401: Unauthorized + diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v1.md index 8ed1581cbe..42d61cb3b2 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "configuration of a horizontal pod autoscaler." title: "HorizontalPodAutoscaler" -weight: 14 +weight: 12 --- `apiVersion: autoscaling/v1` diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v2beta2.md b/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v2beta2.md index 2f8f15d505..0ed4942e1b 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v2beta2.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v2beta2.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "HorizontalPodAutoscaler is the configuration for a horizontal pod autoscaler, which automatically manages the replica count of any resource implementing the scale subresource based on the metrics specified." title: "HorizontalPodAutoscaler v2beta2" -weight: 15 +weight: 13 --- `apiVersion: autoscaling/v2beta2` @@ -89,32 +89,32 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *HPAScalingRules configures the scaling behavior for one direction. These Rules are applied after calculating DesiredReplicas from metrics for the HPA. They can limit the scaling velocity by specifying scaling policies. They can prevent flapping by specifying the stabilization window, so that the number of replicas is not set instantly, instead, the safest value from the stabilization window is chosen.* - - **behavior.scaleDown.policies** ([]HPAScalingPolicy) + - **behavior.scaleDown.policies** ([]HPAScalingPolicy) - policies is a list of potential scaling polices which can be used during scaling. At least one policy must be specified, otherwise the HPAScalingRules will be discarded as invalid + policies is a list of potential scaling polices which can be used during scaling. At least one policy must be specified, otherwise the HPAScalingRules will be discarded as invalid - - *HPAScalingPolicy is a single policy which must hold true for a specified past interval.* + + *HPAScalingPolicy is a single policy which must hold true for a specified past interval.* - - **behavior.scaleDown.policies.type** (string), required + - **behavior.scaleDown.policies.type** (string), required - Type is used to specify the scaling policy. + Type is used to specify the scaling policy. - - **behavior.scaleDown.policies.value** (int32), required + - **behavior.scaleDown.policies.value** (int32), required - Value contains the amount of change which is permitted by the policy. It must be greater than zero + Value contains the amount of change which is permitted by the policy. It must be greater than zero - - **behavior.scaleDown.policies.periodSeconds** (int32), required + - **behavior.scaleDown.policies.periodSeconds** (int32), required - PeriodSeconds specifies the window of time for which the policy should hold true. PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min). + PeriodSeconds specifies the window of time for which the policy should hold true. PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min). - - **behavior.scaleDown.selectPolicy** (string) + - **behavior.scaleDown.selectPolicy** (string) - selectPolicy is used to specify which policy should be used. If not set, the default value MaxPolicySelect is used. + selectPolicy is used to specify which policy should be used. If not set, the default value MaxPolicySelect is used. - - **behavior.scaleDown.stabilizationWindowSeconds** (int32) + - **behavior.scaleDown.stabilizationWindowSeconds** (int32) - StabilizationWindowSeconds is the number of seconds for which past recommendations should be considered while scaling up or scaling down. StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). If not set, use the default values: - For scale up: 0 (i.e. no stabilization is done). - For scale down: 300 (i.e. the stabilization window is 300 seconds long). + StabilizationWindowSeconds is the number of seconds for which past recommendations should be considered while scaling up or scaling down. StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). If not set, use the default values: - For scale up: 0 (i.e. no stabilization is done). - For scale down: 300 (i.e. the stabilization window is 300 seconds long). - **behavior.scaleUp** (HPAScalingRules) @@ -126,32 +126,32 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *HPAScalingRules configures the scaling behavior for one direction. These Rules are applied after calculating DesiredReplicas from metrics for the HPA. They can limit the scaling velocity by specifying scaling policies. They can prevent flapping by specifying the stabilization window, so that the number of replicas is not set instantly, instead, the safest value from the stabilization window is chosen.* - - **behavior.scaleUp.policies** ([]HPAScalingPolicy) + - **behavior.scaleUp.policies** ([]HPAScalingPolicy) - policies is a list of potential scaling polices which can be used during scaling. At least one policy must be specified, otherwise the HPAScalingRules will be discarded as invalid + policies is a list of potential scaling polices which can be used during scaling. At least one policy must be specified, otherwise the HPAScalingRules will be discarded as invalid - - *HPAScalingPolicy is a single policy which must hold true for a specified past interval.* + + *HPAScalingPolicy is a single policy which must hold true for a specified past interval.* - - **behavior.scaleUp.policies.type** (string), required + - **behavior.scaleUp.policies.type** (string), required - Type is used to specify the scaling policy. + Type is used to specify the scaling policy. - - **behavior.scaleUp.policies.value** (int32), required + - **behavior.scaleUp.policies.value** (int32), required - Value contains the amount of change which is permitted by the policy. It must be greater than zero + Value contains the amount of change which is permitted by the policy. It must be greater than zero - - **behavior.scaleUp.policies.periodSeconds** (int32), required + - **behavior.scaleUp.policies.periodSeconds** (int32), required - PeriodSeconds specifies the window of time for which the policy should hold true. PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min). + PeriodSeconds specifies the window of time for which the policy should hold true. PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min). - - **behavior.scaleUp.selectPolicy** (string) + - **behavior.scaleUp.selectPolicy** (string) - selectPolicy is used to specify which policy should be used. If not set, the default value MaxPolicySelect is used. + selectPolicy is used to specify which policy should be used. If not set, the default value MaxPolicySelect is used. - - **behavior.scaleUp.stabilizationWindowSeconds** (int32) + - **behavior.scaleUp.stabilizationWindowSeconds** (int32) - StabilizationWindowSeconds is the number of seconds for which past recommendations should be considered while scaling up or scaling down. StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). If not set, use the default values: - For scale up: 0 (i.e. no stabilization is done). - For scale down: 300 (i.e. the stabilization window is 300 seconds long). + StabilizationWindowSeconds is the number of seconds for which past recommendations should be considered while scaling up or scaling down. StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). If not set, use the default values: - For scale up: 0 (i.e. no stabilization is done). - For scale down: 300 (i.e. the stabilization window is 300 seconds long). - **metrics** ([]MetricSpec) @@ -171,36 +171,36 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *ContainerResourceMetricSource indicates how to scale on a resource metric known to Kubernetes, as specified in requests and limits, describing each pod in the current scale target (e.g. CPU or memory). The values will be averaged together before being compared to the target. Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the "pods" source. Only one "target" type should be set.* - - **metrics.containerResource.container** (string), required + - **metrics.containerResource.container** (string), required - container is the name of the container in the pods of the scaling target + container is the name of the container in the pods of the scaling target - - **metrics.containerResource.name** (string), required + - **metrics.containerResource.name** (string), required - name is the name of the resource in question. + name is the name of the resource in question. - - **metrics.containerResource.target** (MetricTarget), required + - **metrics.containerResource.target** (MetricTarget), required - target specifies the target value for the given metric + target specifies the target value for the given metric - - *MetricTarget defines the target value, average value, or average utilization of a specific metric* + + *MetricTarget defines the target value, average value, or average utilization of a specific metric* - - **metrics.containerResource.target.type** (string), required + - **metrics.containerResource.target.type** (string), required - type represents whether the metric type is Utilization, Value, or AverageValue + type represents whether the metric type is Utilization, Value, or AverageValue - - **metrics.containerResource.target.averageUtilization** (int32) + - **metrics.containerResource.target.averageUtilization** (int32) - averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type + averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type - - **metrics.containerResource.target.averageValue** (}}">Quantity) + - **metrics.containerResource.target.averageValue** (}}">Quantity) - averageValue is the target value of the average of the metric across all relevant pods (as a quantity) + averageValue is the target value of the average of the metric across all relevant pods (as a quantity) - - **metrics.containerResource.target.value** (}}">Quantity) + - **metrics.containerResource.target.value** (}}">Quantity) - value is the target value of the metric (as a quantity). + value is the target value of the metric (as a quantity). - **metrics.external** (ExternalMetricSource) @@ -209,43 +209,43 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *ExternalMetricSource indicates how to scale on a metric not associated with any Kubernetes object (for example length of queue in cloud messaging service, or QPS from loadbalancer running outside of cluster).* - - **metrics.external.metric** (MetricIdentifier), required + - **metrics.external.metric** (MetricIdentifier), required - metric identifies the target metric by name and selector + metric identifies the target metric by name and selector - - *MetricIdentifier defines the name and optionally selector for a metric* + + *MetricIdentifier defines the name and optionally selector for a metric* - - **metrics.external.metric.name** (string), required + - **metrics.external.metric.name** (string), required - name is the name of the given metric + name is the name of the given metric - - **metrics.external.metric.selector** (}}">LabelSelector) + - **metrics.external.metric.selector** (}}">LabelSelector) - selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. + selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. - - **metrics.external.target** (MetricTarget), required + - **metrics.external.target** (MetricTarget), required - target specifies the target value for the given metric + target specifies the target value for the given metric - - *MetricTarget defines the target value, average value, or average utilization of a specific metric* + + *MetricTarget defines the target value, average value, or average utilization of a specific metric* - - **metrics.external.target.type** (string), required + - **metrics.external.target.type** (string), required - type represents whether the metric type is Utilization, Value, or AverageValue + type represents whether the metric type is Utilization, Value, or AverageValue - - **metrics.external.target.averageUtilization** (int32) + - **metrics.external.target.averageUtilization** (int32) - averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type + averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type - - **metrics.external.target.averageValue** (}}">Quantity) + - **metrics.external.target.averageValue** (}}">Quantity) - averageValue is the target value of the average of the metric across all relevant pods (as a quantity) + averageValue is the target value of the average of the metric across all relevant pods (as a quantity) - - **metrics.external.target.value** (}}">Quantity) + - **metrics.external.target.value** (}}">Quantity) - value is the target value of the metric (as a quantity). + value is the target value of the metric (as a quantity). - **metrics.object** (ObjectMetricSource) @@ -254,61 +254,61 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *ObjectMetricSource indicates how to scale on a metric describing a kubernetes object (for example, hits-per-second on an Ingress object).* - - **metrics.object.describedObject** (CrossVersionObjectReference), required + - **metrics.object.describedObject** (CrossVersionObjectReference), required - - *CrossVersionObjectReference contains enough information to let you identify the referred resource.* + + *CrossVersionObjectReference contains enough information to let you identify the referred resource.* - - **metrics.object.describedObject.kind** (string), required + - **metrics.object.describedObject.kind** (string), required - Kind of the referent; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds" + Kind of the referent; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds" - - **metrics.object.describedObject.name** (string), required + - **metrics.object.describedObject.name** (string), required - Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names + Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names - - **metrics.object.describedObject.apiVersion** (string) + - **metrics.object.describedObject.apiVersion** (string) - API version of the referent + API version of the referent - - **metrics.object.metric** (MetricIdentifier), required + - **metrics.object.metric** (MetricIdentifier), required - metric identifies the target metric by name and selector + metric identifies the target metric by name and selector - - *MetricIdentifier defines the name and optionally selector for a metric* + + *MetricIdentifier defines the name and optionally selector for a metric* - - **metrics.object.metric.name** (string), required + - **metrics.object.metric.name** (string), required - name is the name of the given metric + name is the name of the given metric - - **metrics.object.metric.selector** (}}">LabelSelector) + - **metrics.object.metric.selector** (}}">LabelSelector) - selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. + selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. - - **metrics.object.target** (MetricTarget), required + - **metrics.object.target** (MetricTarget), required - target specifies the target value for the given metric + target specifies the target value for the given metric - - *MetricTarget defines the target value, average value, or average utilization of a specific metric* + + *MetricTarget defines the target value, average value, or average utilization of a specific metric* - - **metrics.object.target.type** (string), required + - **metrics.object.target.type** (string), required - type represents whether the metric type is Utilization, Value, or AverageValue + type represents whether the metric type is Utilization, Value, or AverageValue - - **metrics.object.target.averageUtilization** (int32) + - **metrics.object.target.averageUtilization** (int32) - averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type + averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type - - **metrics.object.target.averageValue** (}}">Quantity) + - **metrics.object.target.averageValue** (}}">Quantity) - averageValue is the target value of the average of the metric across all relevant pods (as a quantity) + averageValue is the target value of the average of the metric across all relevant pods (as a quantity) - - **metrics.object.target.value** (}}">Quantity) + - **metrics.object.target.value** (}}">Quantity) - value is the target value of the metric (as a quantity). + value is the target value of the metric (as a quantity). - **metrics.pods** (PodsMetricSource) @@ -317,43 +317,43 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *PodsMetricSource indicates how to scale on a metric describing each pod in the current scale target (for example, transactions-processed-per-second). The values will be averaged together before being compared to the target value.* - - **metrics.pods.metric** (MetricIdentifier), required + - **metrics.pods.metric** (MetricIdentifier), required - metric identifies the target metric by name and selector + metric identifies the target metric by name and selector - - *MetricIdentifier defines the name and optionally selector for a metric* + + *MetricIdentifier defines the name and optionally selector for a metric* - - **metrics.pods.metric.name** (string), required + - **metrics.pods.metric.name** (string), required - name is the name of the given metric + name is the name of the given metric - - **metrics.pods.metric.selector** (}}">LabelSelector) + - **metrics.pods.metric.selector** (}}">LabelSelector) - selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. + selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. - - **metrics.pods.target** (MetricTarget), required + - **metrics.pods.target** (MetricTarget), required - target specifies the target value for the given metric + target specifies the target value for the given metric - - *MetricTarget defines the target value, average value, or average utilization of a specific metric* + + *MetricTarget defines the target value, average value, or average utilization of a specific metric* - - **metrics.pods.target.type** (string), required + - **metrics.pods.target.type** (string), required - type represents whether the metric type is Utilization, Value, or AverageValue + type represents whether the metric type is Utilization, Value, or AverageValue - - **metrics.pods.target.averageUtilization** (int32) + - **metrics.pods.target.averageUtilization** (int32) - averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type + averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type - - **metrics.pods.target.averageValue** (}}">Quantity) + - **metrics.pods.target.averageValue** (}}">Quantity) - averageValue is the target value of the average of the metric across all relevant pods (as a quantity) + averageValue is the target value of the average of the metric across all relevant pods (as a quantity) - - **metrics.pods.target.value** (}}">Quantity) + - **metrics.pods.target.value** (}}">Quantity) - value is the target value of the metric (as a quantity). + value is the target value of the metric (as a quantity). - **metrics.resource** (ResourceMetricSource) @@ -362,32 +362,32 @@ HorizontalPodAutoscalerSpec describes the desired functionality of the Horizonta *ResourceMetricSource indicates how to scale on a resource metric known to Kubernetes, as specified in requests and limits, describing each pod in the current scale target (e.g. CPU or memory). The values will be averaged together before being compared to the target. Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the "pods" source. Only one "target" type should be set.* - - **metrics.resource.name** (string), required + - **metrics.resource.name** (string), required - name is the name of the resource in question. + name is the name of the resource in question. - - **metrics.resource.target** (MetricTarget), required + - **metrics.resource.target** (MetricTarget), required - target specifies the target value for the given metric + target specifies the target value for the given metric - - *MetricTarget defines the target value, average value, or average utilization of a specific metric* + + *MetricTarget defines the target value, average value, or average utilization of a specific metric* - - **metrics.resource.target.type** (string), required + - **metrics.resource.target.type** (string), required - type represents whether the metric type is Utilization, Value, or AverageValue + type represents whether the metric type is Utilization, Value, or AverageValue - - **metrics.resource.target.averageUtilization** (int32) + - **metrics.resource.target.averageUtilization** (int32) - averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type + averageUtilization is the target value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. Currently only valid for Resource metric source type - - **metrics.resource.target.averageValue** (}}">Quantity) + - **metrics.resource.target.averageValue** (}}">Quantity) - averageValue is the target value of the average of the metric across all relevant pods (as a quantity) + averageValue is the target value of the average of the metric across all relevant pods (as a quantity) - - **metrics.resource.target.value** (}}">Quantity) + - **metrics.resource.target.value** (}}">Quantity) - value is the target value of the metric (as a quantity). + value is the target value of the metric (as a quantity). @@ -455,32 +455,32 @@ HorizontalPodAutoscalerStatus describes the current status of a horizontal pod a *ContainerResourceMetricStatus indicates the current value of a resource metric known to Kubernetes, as specified in requests and limits, describing a single container in each pod in the current scale target (e.g. CPU or memory). Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the "pods" source.* - - **currentMetrics.containerResource.container** (string), required + - **currentMetrics.containerResource.container** (string), required - Container is the name of the container in the pods of the scaling target + Container is the name of the container in the pods of the scaling target - - **currentMetrics.containerResource.current** (MetricValueStatus), required + - **currentMetrics.containerResource.current** (MetricValueStatus), required - current contains the current value for the given metric + current contains the current value for the given metric - - *MetricValueStatus holds the current value for a metric* + + *MetricValueStatus holds the current value for a metric* - - **currentMetrics.containerResource.current.averageUtilization** (int32) + - **currentMetrics.containerResource.current.averageUtilization** (int32) - currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. + currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. - - **currentMetrics.containerResource.current.averageValue** (}}">Quantity) + - **currentMetrics.containerResource.current.averageValue** (}}">Quantity) - averageValue is the current value of the average of the metric across all relevant pods (as a quantity) + averageValue is the current value of the average of the metric across all relevant pods (as a quantity) - - **currentMetrics.containerResource.current.value** (}}">Quantity) + - **currentMetrics.containerResource.current.value** (}}">Quantity) - value is the current value of the metric (as a quantity). + value is the current value of the metric (as a quantity). - - **currentMetrics.containerResource.name** (string), required + - **currentMetrics.containerResource.name** (string), required - Name is the name of the resource in question. + Name is the name of the resource in question. - **currentMetrics.external** (ExternalMetricStatus) @@ -489,39 +489,39 @@ HorizontalPodAutoscalerStatus describes the current status of a horizontal pod a *ExternalMetricStatus indicates the current value of a global metric not associated with any Kubernetes object.* - - **currentMetrics.external.current** (MetricValueStatus), required + - **currentMetrics.external.current** (MetricValueStatus), required - current contains the current value for the given metric + current contains the current value for the given metric - - *MetricValueStatus holds the current value for a metric* + + *MetricValueStatus holds the current value for a metric* - - **currentMetrics.external.current.averageUtilization** (int32) + - **currentMetrics.external.current.averageUtilization** (int32) - currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. + currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. - - **currentMetrics.external.current.averageValue** (}}">Quantity) + - **currentMetrics.external.current.averageValue** (}}">Quantity) - averageValue is the current value of the average of the metric across all relevant pods (as a quantity) + averageValue is the current value of the average of the metric across all relevant pods (as a quantity) - - **currentMetrics.external.current.value** (}}">Quantity) + - **currentMetrics.external.current.value** (}}">Quantity) - value is the current value of the metric (as a quantity). + value is the current value of the metric (as a quantity). - - **currentMetrics.external.metric** (MetricIdentifier), required + - **currentMetrics.external.metric** (MetricIdentifier), required - metric identifies the target metric by name and selector + metric identifies the target metric by name and selector - - *MetricIdentifier defines the name and optionally selector for a metric* + + *MetricIdentifier defines the name and optionally selector for a metric* - - **currentMetrics.external.metric.name** (string), required + - **currentMetrics.external.metric.name** (string), required - name is the name of the given metric + name is the name of the given metric - - **currentMetrics.external.metric.selector** (}}">LabelSelector) + - **currentMetrics.external.metric.selector** (}}">LabelSelector) - selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. + selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. - **currentMetrics.object** (ObjectMetricStatus) @@ -530,57 +530,57 @@ HorizontalPodAutoscalerStatus describes the current status of a horizontal pod a *ObjectMetricStatus indicates the current value of a metric describing a kubernetes object (for example, hits-per-second on an Ingress object).* - - **currentMetrics.object.current** (MetricValueStatus), required + - **currentMetrics.object.current** (MetricValueStatus), required - current contains the current value for the given metric + current contains the current value for the given metric - - *MetricValueStatus holds the current value for a metric* + + *MetricValueStatus holds the current value for a metric* - - **currentMetrics.object.current.averageUtilization** (int32) + - **currentMetrics.object.current.averageUtilization** (int32) - currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. + currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. - - **currentMetrics.object.current.averageValue** (}}">Quantity) + - **currentMetrics.object.current.averageValue** (}}">Quantity) - averageValue is the current value of the average of the metric across all relevant pods (as a quantity) + averageValue is the current value of the average of the metric across all relevant pods (as a quantity) - - **currentMetrics.object.current.value** (}}">Quantity) + - **currentMetrics.object.current.value** (}}">Quantity) - value is the current value of the metric (as a quantity). + value is the current value of the metric (as a quantity). - - **currentMetrics.object.describedObject** (CrossVersionObjectReference), required + - **currentMetrics.object.describedObject** (CrossVersionObjectReference), required - - *CrossVersionObjectReference contains enough information to let you identify the referred resource.* + + *CrossVersionObjectReference contains enough information to let you identify the referred resource.* - - **currentMetrics.object.describedObject.kind** (string), required + - **currentMetrics.object.describedObject.kind** (string), required - Kind of the referent; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds" + Kind of the referent; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds" - - **currentMetrics.object.describedObject.name** (string), required + - **currentMetrics.object.describedObject.name** (string), required - Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names + Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names - - **currentMetrics.object.describedObject.apiVersion** (string) + - **currentMetrics.object.describedObject.apiVersion** (string) - API version of the referent + API version of the referent - - **currentMetrics.object.metric** (MetricIdentifier), required + - **currentMetrics.object.metric** (MetricIdentifier), required - metric identifies the target metric by name and selector + metric identifies the target metric by name and selector - - *MetricIdentifier defines the name and optionally selector for a metric* + + *MetricIdentifier defines the name and optionally selector for a metric* - - **currentMetrics.object.metric.name** (string), required + - **currentMetrics.object.metric.name** (string), required - name is the name of the given metric + name is the name of the given metric - - **currentMetrics.object.metric.selector** (}}">LabelSelector) + - **currentMetrics.object.metric.selector** (}}">LabelSelector) - selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. + selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. - **currentMetrics.pods** (PodsMetricStatus) @@ -589,39 +589,39 @@ HorizontalPodAutoscalerStatus describes the current status of a horizontal pod a *PodsMetricStatus indicates the current value of a metric describing each pod in the current scale target (for example, transactions-processed-per-second).* - - **currentMetrics.pods.current** (MetricValueStatus), required + - **currentMetrics.pods.current** (MetricValueStatus), required - current contains the current value for the given metric + current contains the current value for the given metric - - *MetricValueStatus holds the current value for a metric* + + *MetricValueStatus holds the current value for a metric* - - **currentMetrics.pods.current.averageUtilization** (int32) + - **currentMetrics.pods.current.averageUtilization** (int32) - currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. + currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. - - **currentMetrics.pods.current.averageValue** (}}">Quantity) + - **currentMetrics.pods.current.averageValue** (}}">Quantity) - averageValue is the current value of the average of the metric across all relevant pods (as a quantity) + averageValue is the current value of the average of the metric across all relevant pods (as a quantity) - - **currentMetrics.pods.current.value** (}}">Quantity) + - **currentMetrics.pods.current.value** (}}">Quantity) - value is the current value of the metric (as a quantity). + value is the current value of the metric (as a quantity). - - **currentMetrics.pods.metric** (MetricIdentifier), required + - **currentMetrics.pods.metric** (MetricIdentifier), required - metric identifies the target metric by name and selector + metric identifies the target metric by name and selector - - *MetricIdentifier defines the name and optionally selector for a metric* + + *MetricIdentifier defines the name and optionally selector for a metric* - - **currentMetrics.pods.metric.name** (string), required + - **currentMetrics.pods.metric.name** (string), required - name is the name of the given metric + name is the name of the given metric - - **currentMetrics.pods.metric.selector** (}}">LabelSelector) + - **currentMetrics.pods.metric.selector** (}}">LabelSelector) - selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. + selector is the string-encoded form of a standard kubernetes label selector for the given metric When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. When unset, just the metricName will be used to gather metrics. - **currentMetrics.resource** (ResourceMetricStatus) @@ -630,28 +630,28 @@ HorizontalPodAutoscalerStatus describes the current status of a horizontal pod a *ResourceMetricStatus indicates the current value of a resource metric known to Kubernetes, as specified in requests and limits, describing each pod in the current scale target (e.g. CPU or memory). Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the "pods" source.* - - **currentMetrics.resource.current** (MetricValueStatus), required + - **currentMetrics.resource.current** (MetricValueStatus), required - current contains the current value for the given metric + current contains the current value for the given metric - - *MetricValueStatus holds the current value for a metric* + + *MetricValueStatus holds the current value for a metric* - - **currentMetrics.resource.current.averageUtilization** (int32) + - **currentMetrics.resource.current.averageUtilization** (int32) - currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. + currentAverageUtilization is the current value of the average of the resource metric across all relevant pods, represented as a percentage of the requested value of the resource for the pods. - - **currentMetrics.resource.current.averageValue** (}}">Quantity) + - **currentMetrics.resource.current.averageValue** (}}">Quantity) - averageValue is the current value of the average of the metric across all relevant pods (as a quantity) + averageValue is the current value of the average of the metric across all relevant pods (as a quantity) - - **currentMetrics.resource.current.value** (}}">Quantity) + - **currentMetrics.resource.current.value** (}}">Quantity) - value is the current value of the metric (as a quantity). + value is the current value of the metric (as a quantity). - - **currentMetrics.resource.name** (string), required + - **currentMetrics.resource.name** (string), required - Name is the name of the resource in question. + Name is the name of the resource in question. - **lastScaleTime** (Time) diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/job-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/job-v1.md index f01c257e45..da8c6422e1 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/job-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/job-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "Job represents the configuration of a single job." title: "Job" -weight: 11 +weight: 10 --- `apiVersion: batch/v1` @@ -68,18 +68,32 @@ JobSpec describes how the job execution will look like. Specifies the desired number of successfully finished pods the job should be run with. Setting to nil means that the success of any pod signals the success of all pods, and allows parallelism to have any positive value. Setting to 1 means that parallelism is limited to 1 and the success of that pod signals the success of the job. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ +- **completionMode** (string) + + CompletionMode specifies how Pod completions are tracked. It can be `NonIndexed` (default) or `Indexed`. + + `NonIndexed` means that the Job is considered complete when there have been .spec.completions successfully completed Pods. Each Pod completion is homologous to each other. + + `Indexed` means that the Pods of a Job get an associated completion index from 0 to (.spec.completions - 1), available in the annotation batch.kubernetes.io/job-completion-index. The Job is considered complete when there is one successfully completed Pod for each index. When value is `Indexed`, .spec.completions must be specified and `.spec.parallelism` must be less than or equal to 10^5. + + This field is alpha-level and is only honored by servers that enable the IndexedJob feature gate. More completion modes can be added in the future. If the Job controller observes a mode that it doesn't recognize, the controller skips updates for the Job. + - **backoffLimit** (int32) Specifies the number of retries before marking this job failed. Defaults to 6 - **activeDeadlineSeconds** (int64) - Specifies the duration in seconds relative to the startTime that the job may be active before the system tries to terminate it; value must be positive integer + Specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it; value must be positive integer. If a Job is suspended (at creation or through an update), this timer will effectively be stopped and reset when the Job is resumed again. - **ttlSecondsAfterFinished** (int32) ttlSecondsAfterFinished limits the lifetime of a Job that has finished execution (either Complete or Failed). If this field is set, ttlSecondsAfterFinished after the Job finishes, it is eligible to be automatically deleted. When the Job is being deleted, its lifecycle guarantees (e.g. finalizers) will be honored. If this field is unset, the Job won't be automatically deleted. If this field is set to zero, the Job becomes eligible to be deleted immediately after it finishes. This field is alpha-level and is only honored by servers that enable the TTLAfterFinished feature. +- **suspend** (boolean) + + Suspend specifies whether the Job controller should create Pods or not. If a Job is created with suspend set to true, no Pods are created by the Job controller. If a Job is suspended after creation (i.e. the flag goes from false to true), the Job controller will delete all active Pods associated with this Job. Users must design their workload to gracefully handle this. Suspending a Job will reset the StartTime field of the Job, effectively resetting the ActiveDeadlineSeconds timer too. This is an alpha field and requires the SuspendJob feature gate to be enabled; otherwise this field may not be set to true. Defaults to false. + ### Selector @@ -101,7 +115,7 @@ JobStatus represents the current state of a Job. - **startTime** (Time) - Represents time when the job was acknowledged by the job controller. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC. + Represents time when the job controller started processing a job. When a Job is created in the suspended state, this field is not set until the first time it is resumed. This field is reset every time a Job is resumed from suspension. It is represented in RFC3339 form and is in UTC. *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* @@ -125,11 +139,17 @@ JobStatus represents the current state of a Job. The number of pods which reached phase Succeeded. +- **completedIndexes** (string) + + CompletedIndexes holds the completed indexes when .spec.completionMode = "Indexed" in a text format. The indexes are represented as decimal integers separated by commas. The numbers are listed in increasing order. Three or more consecutive numbers are compressed and represented by the first and last element of the series, separated by a hyphen. For example, if the completed indexes are 1, 3, 4, 5 and 7, they are represented as "1,3-5,7". + - **conditions** ([]JobCondition) *Patch strategy: merge on key `type`* - The latest available observations of an object's current state. When a job fails, one of the conditions will have type == "Failed". More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ + *Atomic: will be replaced during a merge* + + The latest available observations of an object's current state. When a Job fails, one of the conditions will have type "Failed" and status true. When a Job is suspended, one of the conditions will have type "Suspended" and status true; when the Job is resumed, the status of this condition will become false. When a Job is completed, one of the conditions will have type "Complete" and status true. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ *JobCondition describes current state of a job.* diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/pod-template-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/pod-template-v1.md index 663ab6bea4..5cbe3e4894 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/pod-template-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/pod-template-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "PodTemplate describes a template for creating copies of a predefined pod." title: "PodTemplate" -weight: 4 +weight: 3 --- `apiVersion: v1` diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/pod-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/pod-v1.md index 4be3289e9f..6553afa238 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/pod-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/pod-v1.md @@ -53,13 +53,13 @@ PodSpec is a description of a pod. ### Containers -- **containers** ([]}}">Container), required +- **containers** ([]}}">Container), required *Patch strategy: merge on key `name`* List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. -- **initContainers** ([]}}">Container) +- **initContainers** ([]}}">Container) *Patch strategy: merge on key `name`* @@ -102,15 +102,15 @@ PodSpec is a description of a pod. *Affinity is a group of affinity scheduling rules.* - - **affinity.nodeAffinity** (}}">NodeAffinity) + - **affinity.nodeAffinity** (}}">NodeAffinity) Describes node affinity scheduling rules for the pod. - - **affinity.podAffinity** (}}">PodAffinity) + - **affinity.podAffinity** (}}">PodAffinity) Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - - **affinity.podAntiAffinity** (}}">PodAntiAffinity) + - **affinity.podAntiAffinity** (}}">PodAntiAffinity) Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). @@ -157,6 +157,36 @@ PodSpec is a description of a pod. The priority value. Various system components use this field to find the priority of the pod. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. +- **topologySpreadConstraints** ([]TopologySpreadConstraint) + + *Patch strategy: merge on key `topologyKey`* + + *Map: unique values on keys `topologyKey, whenUnsatisfiable` will be kept during a merge* + + TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. + + + *TopologySpreadConstraint specifies how to spread matching pods among the given topology.* + + - **topologySpreadConstraints.maxSkew** (int32), required + + MaxSkew describes the degree to which pods may be unevenly distributed. When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference between the number of matching pods in the target topology and the global minimum. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: | zone1 | zone2 | zone3 | | P | P | | - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence to topologies that satisfy it. It's a required field. Default value is 1 and 0 is not allowed. + + - **topologySpreadConstraints.topologyKey** (string), required + + TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each \ as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. + + - **topologySpreadConstraints.whenUnsatisfiable** (string), required + + WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it. - ScheduleAnyway tells the scheduler to schedule the pod in any location, + but giving higher precedence to topologies that would help reduce the + skew. + A constraint is considered "Unsatisfiable" for an incoming pod if and only if every possible node assigment for that pod would violate "MaxSkew" on some topology. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: | zone1 | zone2 | zone3 | | P P P | P | P | If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. + + - **topologySpreadConstraints.labelSelector** (}}">LabelSelector) + + LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. + ### Lifecycle @@ -166,7 +196,7 @@ PodSpec is a description of a pod. - **terminationGracePeriodSeconds** (int64) - Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. + Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down). If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. - **activeDeadlineSeconds** (int64) @@ -233,11 +263,11 @@ PodSpec is a description of a pod. *PodDNSConfigOption defines DNS resolver options of a pod.* - - **dnsConfig.options.name** (string) + - **dnsConfig.options.name** (string) - Required. + Required. - - **dnsConfig.options.value** (string) + - **dnsConfig.options.value** (string) - **dnsConfig.searches** ([]string) @@ -323,15 +353,15 @@ PodSpec is a description of a pod. *SeccompProfile defines a pod/container's seccomp profile settings. Only one profile source may be set.* - - **securityContext.seccompProfile.type** (string), required + - **securityContext.seccompProfile.type** (string), required - type indicates which kind of seccomp profile will be applied. Valid options are: - - Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. + type indicates which kind of seccomp profile will be applied. Valid options are: + + Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. - - **securityContext.seccompProfile.localhostProfile** (string) + - **securityContext.seccompProfile.localhostProfile** (string) - localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". + localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". - **securityContext.seLinuxOptions** (SELinuxOptions) @@ -340,21 +370,21 @@ PodSpec is a description of a pod. *SELinuxOptions are the labels to be applied to the container* - - **securityContext.seLinuxOptions.level** (string) + - **securityContext.seLinuxOptions.level** (string) - Level is SELinux level label that applies to the container. + Level is SELinux level label that applies to the container. - - **securityContext.seLinuxOptions.role** (string) + - **securityContext.seLinuxOptions.role** (string) - Role is a SELinux role label that applies to the container. + Role is a SELinux role label that applies to the container. - - **securityContext.seLinuxOptions.type** (string) + - **securityContext.seLinuxOptions.type** (string) - Type is a SELinux type label that applies to the container. + Type is a SELinux type label that applies to the container. - - **securityContext.seLinuxOptions.user** (string) + - **securityContext.seLinuxOptions.user** (string) - User is a SELinux user label that applies to the container. + User is a SELinux user label that applies to the container. - **securityContext.sysctls** ([]Sysctl) @@ -363,13 +393,13 @@ PodSpec is a description of a pod. *Sysctl defines a kernel parameter to be set* - - **securityContext.sysctls.name** (string), required + - **securityContext.sysctls.name** (string), required - Name of a property to set + Name of a property to set - - **securityContext.sysctls.value** (string), required + - **securityContext.sysctls.value** (string), required - Value of a property to set + Value of a property to set - **securityContext.windowsOptions** (WindowsSecurityContextOptions) @@ -378,68 +408,38 @@ PodSpec is a description of a pod. *WindowsSecurityContextOptions contain Windows-specific options and credentials.* - - **securityContext.windowsOptions.gmsaCredentialSpec** (string) + - **securityContext.windowsOptions.gmsaCredentialSpec** (string) - GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. + GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - - **securityContext.windowsOptions.gmsaCredentialSpecName** (string) + - **securityContext.windowsOptions.gmsaCredentialSpecName** (string) - GMSACredentialSpecName is the name of the GMSA credential spec to use. + GMSACredentialSpecName is the name of the GMSA credential spec to use. - - **securityContext.windowsOptions.runAsUserName** (string) + - **securityContext.windowsOptions.runAsUserName** (string) - The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. ### Beta level +- **preemptionPolicy** (string) + + PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. + - **overhead** (map[string]}}">Quantity) Overhead represents the resource overhead associated with running a pod for a given RuntimeClass. This field will be autopopulated at admission time by the RuntimeClass admission controller. If the RuntimeClass admission controller is enabled, overhead must not be set in Pod create requests. The RuntimeClass admission controller will reject Pod create requests which have the overhead already set. If RuntimeClass is configured and selected in the PodSpec, Overhead will be set to the value defined in the corresponding RuntimeClass, otherwise it will remain unset and treated as zero. More info: https://git.k8s.io/enhancements/keps/sig-node/20190226-pod-overhead.md This field is alpha-level as of Kubernetes v1.16, and is only honored by servers that enable the PodOverhead feature. -- **topologySpreadConstraints** ([]TopologySpreadConstraint) - - *Patch strategy: merge on key `topologyKey`* - - *Map: unique values on keys `topologyKey, whenUnsatisfiable` will be kept during a merge* - - TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - - - *TopologySpreadConstraint specifies how to spread matching pods among the given topology.* - - - **topologySpreadConstraints.maxSkew** (int32), required - - MaxSkew describes the degree to which pods may be unevenly distributed. When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference between the number of matching pods in the target topology and the global minimum. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: | zone1 | zone2 | zone3 | | P | P | | - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence to topologies that satisfy it. It's a required field. Default value is 1 and 0 is not allowed. - - - **topologySpreadConstraints.topologyKey** (string), required - - TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each \ as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. - - - **topologySpreadConstraints.whenUnsatisfiable** (string), required - - WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it. - ScheduleAnyway tells the scheduler to schedule the pod in any location, - but giving higher precedence to topologies that would help reduce the - skew. - A constraint is considered "Unsatisfiable" for an incoming pod if and only if every possible node assigment for that pod would violate "MaxSkew" on some topology. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: | zone1 | zone2 | zone3 | | P P P | P | P | If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. - - - **topologySpreadConstraints.labelSelector** (}}">LabelSelector) - - LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - ### Alpha level -- **ephemeralContainers** ([]}}">EphemeralContainer) +- **ephemeralContainers** ([]}}">EphemeralContainer) *Patch strategy: merge on key `name`* List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. -- **preemptionPolicy** (string) - - PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - ### Deprecated @@ -449,6 +449,810 @@ PodSpec is a description of a pod. +## Container {#Container} + +A single application container that you want to run within a pod. + +
+ +- **name** (string), required + + Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. + + + +### Image + + +- **image** (string) + + Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. + +- **imagePullPolicy** (string) + + Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images + +### Entrypoint + + +- **command** ([]string) + + Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell + +- **args** ([]string) + + Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell + +- **workingDir** (string) + + Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. + +### Ports + + +- **ports** ([]ContainerPort) + + *Patch strategy: merge on key `containerPort`* + + *Map: unique values on keys `containerPort, protocol` will be kept during a merge* + + List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. + + + *ContainerPort represents a network port in a single container.* + + - **ports.containerPort** (int32), required + + Number of port to expose on the pod's IP address. This must be a valid port number, 0 \< x \< 65536. + + - **ports.hostIP** (string) + + What host IP to bind the external port to. + + - **ports.hostPort** (int32) + + Number of port to expose on the host. If specified, this must be a valid port number, 0 \< x \< 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. + + - **ports.name** (string) + + If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. + + - **ports.protocol** (string) + + Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". + +### Environment variables + + +- **env** ([]EnvVar) + + *Patch strategy: merge on key `name`* + + List of environment variables to set in the container. Cannot be updated. + + + *EnvVar represents an environment variable present in a Container.* + + - **env.name** (string), required + + Name of the environment variable. Must be a C_IDENTIFIER. + + - **env.value** (string) + + Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". + + - **env.valueFrom** (EnvVarSource) + + Source for the environment variable's value. Cannot be used if value is not empty. + + + *EnvVarSource represents a source for the value of an EnvVar.* + + - **env.valueFrom.configMapKeyRef** (ConfigMapKeySelector) + + Selects a key of a ConfigMap. + + + *Selects a key from a ConfigMap.* + + - **env.valueFrom.configMapKeyRef.key** (string), required + + The key to select. + + - **env.valueFrom.configMapKeyRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **env.valueFrom.configMapKeyRef.optional** (boolean) + + Specify whether the ConfigMap or its key must be defined + + - **env.valueFrom.fieldRef** (}}">ObjectFieldSelector) + + Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['\']`, `metadata.annotations['\']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. + + - **env.valueFrom.resourceFieldRef** (}}">ResourceFieldSelector) + + Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. + + - **env.valueFrom.secretKeyRef** (SecretKeySelector) + + Selects a key of a secret in the pod's namespace + + + *SecretKeySelector selects a key of a Secret.* + + - **env.valueFrom.secretKeyRef.key** (string), required + + The key of the secret to select from. Must be a valid secret key. + + - **env.valueFrom.secretKeyRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **env.valueFrom.secretKeyRef.optional** (boolean) + + Specify whether the Secret or its key must be defined + +- **envFrom** ([]EnvFromSource) + + List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. + + + *EnvFromSource represents the source of a set of ConfigMaps* + + - **envFrom.configMapRef** (ConfigMapEnvSource) + + The ConfigMap to select from + + + *ConfigMapEnvSource selects a ConfigMap to populate the environment variables with. + + The contents of the target ConfigMap's Data field will represent the key-value pairs as environment variables.* + + - **envFrom.configMapRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **envFrom.configMapRef.optional** (boolean) + + Specify whether the ConfigMap must be defined + + - **envFrom.prefix** (string) + + An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. + + - **envFrom.secretRef** (SecretEnvSource) + + The Secret to select from + + + *SecretEnvSource selects a Secret to populate the environment variables with. + + The contents of the target Secret's Data field will represent the key-value pairs as environment variables.* + + - **envFrom.secretRef.name** (string) + + Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + + - **envFrom.secretRef.optional** (boolean) + + Specify whether the Secret must be defined + +### Volumes + + +- **volumeMounts** ([]VolumeMount) + + *Patch strategy: merge on key `mountPath`* + + Pod volumes to mount into the container's filesystem. Cannot be updated. + + + *VolumeMount describes a mounting of a Volume within a container.* + + - **volumeMounts.mountPath** (string), required + + Path within the container at which the volume should be mounted. Must not contain ':'. + + - **volumeMounts.name** (string), required + + This must match the Name of a Volume. + + - **volumeMounts.mountPropagation** (string) + + mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. + + - **volumeMounts.readOnly** (boolean) + + Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. + + - **volumeMounts.subPath** (string) + + Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). + + - **volumeMounts.subPathExpr** (string) + + Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. + +- **volumeDevices** ([]VolumeDevice) + + *Patch strategy: merge on key `devicePath`* + + volumeDevices is the list of block devices to be used by the container. + + + *volumeDevice describes a mapping of a raw block device within a container.* + + - **volumeDevices.devicePath** (string), required + + devicePath is the path inside of the container that the device will be mapped to. + + - **volumeDevices.name** (string), required + + name must match the name of a persistentVolumeClaim in the pod + +### Resources + + +- **resources** (ResourceRequirements) + + Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + + *ResourceRequirements describes the compute resource requirements.* + + - **resources.limits** (map[string]}}">Quantity) + + Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + + - **resources.requests** (map[string]}}">Quantity) + + Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +### Lifecycle + + +- **lifecycle** (Lifecycle) + + Actions that the management system should take in response to container lifecycle events. Cannot be updated. + + + *Lifecycle describes actions that the management system should take in response to container lifecycle events. For the PostStart and PreStop lifecycle handlers, management of the container blocks until the action is complete, unless the container process fails, in which case the handler is aborted.* + + - **lifecycle.postStart** (}}">Handler) + + PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks + + - **lifecycle.preStop** (}}">Handler) + + PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks + +- **terminationMessagePath** (string) + + Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. + +- **terminationMessagePolicy** (string) + + Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. + +- **livenessProbe** (}}">Probe) + + Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes + +- **readinessProbe** (}}">Probe) + + Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes + +- **startupProbe** (}}">Probe) + + StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes + +### Security Context + + +- **securityContext** (SecurityContext) + + Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ + + + *SecurityContext holds security configuration that will be applied to a container. Some fields are present in both SecurityContext and PodSecurityContext. When both are set, the values in SecurityContext take precedence.* + + - **securityContext.runAsUser** (int64) + + The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + - **securityContext.runAsNonRoot** (boolean) + + Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + - **securityContext.runAsGroup** (int64) + + The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + - **securityContext.readOnlyRootFilesystem** (boolean) + + Whether this container has a read-only root filesystem. Default is false. + + - **securityContext.procMount** (string) + + procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. + + - **securityContext.privileged** (boolean) + + Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. + + - **securityContext.allowPrivilegeEscalation** (boolean) + + AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN + + - **securityContext.capabilities** (Capabilities) + + The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. + + + *Adds and removes POSIX capabilities from running containers.* + + - **securityContext.capabilities.add** ([]string) + + Added capabilities + + - **securityContext.capabilities.drop** ([]string) + + Removed capabilities + + - **securityContext.seccompProfile** (SeccompProfile) + + The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. + + + *SeccompProfile defines a pod/container's seccomp profile settings. Only one profile source may be set.* + + - **securityContext.seccompProfile.type** (string), required + + type indicates which kind of seccomp profile will be applied. Valid options are: + + Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. + + - **securityContext.seccompProfile.localhostProfile** (string) + + localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". + + - **securityContext.seLinuxOptions** (SELinuxOptions) + + The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + + *SELinuxOptions are the labels to be applied to the container* + + - **securityContext.seLinuxOptions.level** (string) + + Level is SELinux level label that applies to the container. + + - **securityContext.seLinuxOptions.role** (string) + + Role is a SELinux role label that applies to the container. + + - **securityContext.seLinuxOptions.type** (string) + + Type is a SELinux type label that applies to the container. + + - **securityContext.seLinuxOptions.user** (string) + + User is a SELinux user label that applies to the container. + + - **securityContext.windowsOptions** (WindowsSecurityContextOptions) + + The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + + + *WindowsSecurityContextOptions contain Windows-specific options and credentials.* + + - **securityContext.windowsOptions.gmsaCredentialSpec** (string) + + GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. + + - **securityContext.windowsOptions.gmsaCredentialSpecName** (string) + + GMSACredentialSpecName is the name of the GMSA credential spec to use. + + - **securityContext.windowsOptions.runAsUserName** (string) + + The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. + +### Debugging + + +- **stdin** (boolean) + + Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. + +- **stdinOnce** (boolean) + + Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false + +- **tty** (boolean) + + Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. + + + +## Handler {#Handler} + +Handler defines a specific action that should be taken + +
+ +- **exec** (ExecAction) + + One and only one of the following should be specified. Exec specifies the action to take. + + + *ExecAction describes a "run in container" action.* + + - **exec.command** ([]string) + + Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. + +- **httpGet** (HTTPGetAction) + + HTTPGet specifies the http request to perform. + + + *HTTPGetAction describes an action based on HTTP Get requests.* + + - **httpGet.port** (IntOrString), required + + Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + - **httpGet.host** (string) + + Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. + + - **httpGet.httpHeaders** ([]HTTPHeader) + + Custom headers to set in the request. HTTP allows repeated headers. + + + *HTTPHeader describes a custom header to be used in HTTP probes* + + - **httpGet.httpHeaders.name** (string), required + + The header field name + + - **httpGet.httpHeaders.value** (string), required + + The header field value + + - **httpGet.path** (string) + + Path to access on the HTTP server. + + - **httpGet.scheme** (string) + + Scheme to use for connecting to the host. Defaults to HTTP. + +- **tcpSocket** (TCPSocketAction) + + TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported + + + *TCPSocketAction describes an action based on opening a socket* + + - **tcpSocket.port** (IntOrString), required + + Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + - **tcpSocket.host** (string) + + Optional: Host name to connect to, defaults to the pod IP. + + + + + +## NodeAffinity {#NodeAffinity} + +Node affinity is a group of node affinity scheduling rules. + +
+ +- **preferredDuringSchedulingIgnoredDuringExecution** ([]PreferredSchedulingTerm) + + The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. + + + *An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op).* + + - **preferredDuringSchedulingIgnoredDuringExecution.preference** (NodeSelectorTerm), required + + A node selector term, associated with the corresponding weight. + + + *A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.* + + - **preferredDuringSchedulingIgnoredDuringExecution.preference.matchExpressions** ([]}}">NodeSelectorRequirement) + + A list of node selector requirements by node's labels. + + - **preferredDuringSchedulingIgnoredDuringExecution.preference.matchFields** ([]}}">NodeSelectorRequirement) + + A list of node selector requirements by node's fields. + + - **preferredDuringSchedulingIgnoredDuringExecution.weight** (int32), required + + Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. + +- **requiredDuringSchedulingIgnoredDuringExecution** (NodeSelector) + + If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. + + + *A node selector represents the union of the results of one or more label queries over a set of nodes; that is, it represents the OR of the selectors represented by the node selector terms.* + + - **requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms** ([]NodeSelectorTerm), required + + Required. A list of node selector terms. The terms are ORed. + + + *A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.* + + - **requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms.matchExpressions** ([]}}">NodeSelectorRequirement) + + A list of node selector requirements by node's labels. + + - **requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms.matchFields** ([]}}">NodeSelectorRequirement) + + A list of node selector requirements by node's fields. + + + + + +## PodAffinity {#PodAffinity} + +Pod affinity is a group of inter pod affinity scheduling rules. + +
+ +- **preferredDuringSchedulingIgnoredDuringExecution** ([]WeightedPodAffinityTerm) + + The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. + + + *The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s)* + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm** (PodAffinityTerm), required + + Required. A pod affinity term, associated with the corresponding weight. + + + *Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key matches that of any node on which a pod of the set of pods is running* + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.topologyKey** (string), required + + This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.labelSelector** (}}">LabelSelector) + + A label query over a set of resources, in this case pods. + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.namespaceSelector** (}}">LabelSelector) + + A label query over the set of namespaces that the term applies to. The term is applied to the union of the namespaces selected by this field and the ones listed in the namespaces field. null selector and null or empty namespaces list means "this pod's namespace". An empty selector ({}) matches all namespaces. This field is alpha-level and is only honored when PodAffinityNamespaceSelector feature is enabled. + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.namespaces** ([]string) + + namespaces specifies a static list of namespace names that the term applies to. The term is applied to the union of the namespaces listed in this field and the ones selected by namespaceSelector. null or empty namespaces list and null namespaceSelector means "this pod's namespace" + + - **preferredDuringSchedulingIgnoredDuringExecution.weight** (int32), required + + weight associated with matching the corresponding podAffinityTerm, in the range 1-100. + +- **requiredDuringSchedulingIgnoredDuringExecution** ([]PodAffinityTerm) + + If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. + + + *Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key matches that of any node on which a pod of the set of pods is running* + + - **requiredDuringSchedulingIgnoredDuringExecution.topologyKey** (string), required + + This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. + + - **requiredDuringSchedulingIgnoredDuringExecution.labelSelector** (}}">LabelSelector) + + A label query over a set of resources, in this case pods. + + - **requiredDuringSchedulingIgnoredDuringExecution.namespaceSelector** (}}">LabelSelector) + + A label query over the set of namespaces that the term applies to. The term is applied to the union of the namespaces selected by this field and the ones listed in the namespaces field. null selector and null or empty namespaces list means "this pod's namespace". An empty selector ({}) matches all namespaces. This field is alpha-level and is only honored when PodAffinityNamespaceSelector feature is enabled. + + - **requiredDuringSchedulingIgnoredDuringExecution.namespaces** ([]string) + + namespaces specifies a static list of namespace names that the term applies to. The term is applied to the union of the namespaces listed in this field and the ones selected by namespaceSelector. null or empty namespaces list and null namespaceSelector means "this pod's namespace" + + + + + +## PodAntiAffinity {#PodAntiAffinity} + +Pod anti affinity is a group of inter pod anti affinity scheduling rules. + +
+ +- **preferredDuringSchedulingIgnoredDuringExecution** ([]WeightedPodAffinityTerm) + + The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. + + + *The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s)* + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm** (PodAffinityTerm), required + + Required. A pod affinity term, associated with the corresponding weight. + + + *Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key matches that of any node on which a pod of the set of pods is running* + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.topologyKey** (string), required + + This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.labelSelector** (}}">LabelSelector) + + A label query over a set of resources, in this case pods. + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.namespaceSelector** (}}">LabelSelector) + + A label query over the set of namespaces that the term applies to. The term is applied to the union of the namespaces selected by this field and the ones listed in the namespaces field. null selector and null or empty namespaces list means "this pod's namespace". An empty selector ({}) matches all namespaces. This field is alpha-level and is only honored when PodAffinityNamespaceSelector feature is enabled. + + - **preferredDuringSchedulingIgnoredDuringExecution.podAffinityTerm.namespaces** ([]string) + + namespaces specifies a static list of namespace names that the term applies to. The term is applied to the union of the namespaces listed in this field and the ones selected by namespaceSelector. null or empty namespaces list and null namespaceSelector means "this pod's namespace" + + - **preferredDuringSchedulingIgnoredDuringExecution.weight** (int32), required + + weight associated with matching the corresponding podAffinityTerm, in the range 1-100. + +- **requiredDuringSchedulingIgnoredDuringExecution** ([]PodAffinityTerm) + + If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. + + + *Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key matches that of any node on which a pod of the set of pods is running* + + - **requiredDuringSchedulingIgnoredDuringExecution.topologyKey** (string), required + + This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. + + - **requiredDuringSchedulingIgnoredDuringExecution.labelSelector** (}}">LabelSelector) + + A label query over a set of resources, in this case pods. + + - **requiredDuringSchedulingIgnoredDuringExecution.namespaceSelector** (}}">LabelSelector) + + A label query over the set of namespaces that the term applies to. The term is applied to the union of the namespaces selected by this field and the ones listed in the namespaces field. null selector and null or empty namespaces list means "this pod's namespace". An empty selector ({}) matches all namespaces. This field is alpha-level and is only honored when PodAffinityNamespaceSelector feature is enabled. + + - **requiredDuringSchedulingIgnoredDuringExecution.namespaces** ([]string) + + namespaces specifies a static list of namespace names that the term applies to. The term is applied to the union of the namespaces listed in this field and the ones selected by namespaceSelector. null or empty namespaces list and null namespaceSelector means "this pod's namespace" + + + + + +## Probe {#Probe} + +Probe describes a health check to be performed against a container to determine whether it is alive or ready to receive traffic. + +
+ +- **exec** (ExecAction) + + One and only one of the following should be specified. Exec specifies the action to take. + + + *ExecAction describes a "run in container" action.* + + - **exec.command** ([]string) + + Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. + +- **httpGet** (HTTPGetAction) + + HTTPGet specifies the http request to perform. + + + *HTTPGetAction describes an action based on HTTP Get requests.* + + - **httpGet.port** (IntOrString), required + + Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + - **httpGet.host** (string) + + Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. + + - **httpGet.httpHeaders** ([]HTTPHeader) + + Custom headers to set in the request. HTTP allows repeated headers. + + + *HTTPHeader describes a custom header to be used in HTTP probes* + + - **httpGet.httpHeaders.name** (string), required + + The header field name + + - **httpGet.httpHeaders.value** (string), required + + The header field value + + - **httpGet.path** (string) + + Path to access on the HTTP server. + + - **httpGet.scheme** (string) + + Scheme to use for connecting to the host. Defaults to HTTP. + +- **tcpSocket** (TCPSocketAction) + + TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported + + + *TCPSocketAction describes an action based on opening a socket* + + - **tcpSocket.port** (IntOrString), required + + Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. + + + *IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.* + + - **tcpSocket.host** (string) + + Optional: Host name to connect to, defaults to the pod IP. + +- **initialDelaySeconds** (int32) + + Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes + +- **terminationGracePeriodSeconds** (int64) + + Optional duration in seconds the pod needs to terminate gracefully upon probe failure. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. If this value is nil, the pod's terminationGracePeriodSeconds will be used. Otherwise, this value overrides the value provided by the pod spec. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down). This is an alpha field and requires enabling ProbeTerminationGracePeriod feature gate. + +- **periodSeconds** (int32) + + How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. + +- **timeoutSeconds** (int32) + + Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes + +- **failureThreshold** (int32) + + Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. + +- **successThreshold** (int32) + + Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. + + + + + ## PodStatus {#PodStatus} PodStatus represents information about the status of a pod. Status may trail the actual state of a system, especially if the node that hosts the pod cannot contact the control plane. @@ -547,18 +1351,573 @@ PodStatus represents information about the status of a pod. Status may trail the The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md -- **initContainerStatuses** ([]}}">ContainerStatus) +- **initContainerStatuses** ([]ContainerStatus) The list has one entry per init container in the manifest. The most recent successful init container will have ready = true, the most recently started container will have startTime set. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status -- **containerStatuses** ([]}}">ContainerStatus) + + *ContainerStatus contains details for the current status of this container.* + + - **initContainerStatuses.name** (string), required + + This must be a DNS_LABEL. Each container in a pod must have a unique name. Cannot be updated. + + - **initContainerStatuses.image** (string), required + + The image the container is running. More info: https://kubernetes.io/docs/concepts/containers/images + + - **initContainerStatuses.imageID** (string), required + + ImageID of the container's image. + + - **initContainerStatuses.containerID** (string) + + Container's ID in the format 'docker://\'. + + - **initContainerStatuses.state** (ContainerState) + + Details about the container's current condition. + + + *ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting.* + + - **initContainerStatuses.state.running** (ContainerStateRunning) + + Details about a running container + + + *ContainerStateRunning is a running state of a container.* + + - **initContainerStatuses.state.running.startedAt** (Time) + + Time at which the container was last (re-)started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **initContainerStatuses.state.terminated** (ContainerStateTerminated) + + Details about a terminated container + + + *ContainerStateTerminated is a terminated state of a container.* + + - **initContainerStatuses.state.terminated.containerID** (string) + + Container's ID in the format 'docker://\' + + - **initContainerStatuses.state.terminated.exitCode** (int32), required + + Exit status from the last termination of the container + + - **initContainerStatuses.state.terminated.startedAt** (Time) + + Time at which previous execution of the container started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **initContainerStatuses.state.terminated.finishedAt** (Time) + + Time at which the container last terminated + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **initContainerStatuses.state.terminated.message** (string) + + Message regarding the last termination of the container + + - **initContainerStatuses.state.terminated.reason** (string) + + (brief) reason from the last termination of the container + + - **initContainerStatuses.state.terminated.signal** (int32) + + Signal from the last termination of the container + + - **initContainerStatuses.state.waiting** (ContainerStateWaiting) + + Details about a waiting container + + + *ContainerStateWaiting is a waiting state of a container.* + + - **initContainerStatuses.state.waiting.message** (string) + + Message regarding why the container is not yet running. + + - **initContainerStatuses.state.waiting.reason** (string) + + (brief) reason the container is not yet running. + + - **initContainerStatuses.lastState** (ContainerState) + + Details about the container's last termination condition. + + + *ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting.* + + - **initContainerStatuses.lastState.running** (ContainerStateRunning) + + Details about a running container + + + *ContainerStateRunning is a running state of a container.* + + - **initContainerStatuses.lastState.running.startedAt** (Time) + + Time at which the container was last (re-)started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **initContainerStatuses.lastState.terminated** (ContainerStateTerminated) + + Details about a terminated container + + + *ContainerStateTerminated is a terminated state of a container.* + + - **initContainerStatuses.lastState.terminated.containerID** (string) + + Container's ID in the format 'docker://\' + + - **initContainerStatuses.lastState.terminated.exitCode** (int32), required + + Exit status from the last termination of the container + + - **initContainerStatuses.lastState.terminated.startedAt** (Time) + + Time at which previous execution of the container started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **initContainerStatuses.lastState.terminated.finishedAt** (Time) + + Time at which the container last terminated + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **initContainerStatuses.lastState.terminated.message** (string) + + Message regarding the last termination of the container + + - **initContainerStatuses.lastState.terminated.reason** (string) + + (brief) reason from the last termination of the container + + - **initContainerStatuses.lastState.terminated.signal** (int32) + + Signal from the last termination of the container + + - **initContainerStatuses.lastState.waiting** (ContainerStateWaiting) + + Details about a waiting container + + + *ContainerStateWaiting is a waiting state of a container.* + + - **initContainerStatuses.lastState.waiting.message** (string) + + Message regarding why the container is not yet running. + + - **initContainerStatuses.lastState.waiting.reason** (string) + + (brief) reason the container is not yet running. + + - **initContainerStatuses.ready** (boolean), required + + Specifies whether the container has passed its readiness probe. + + - **initContainerStatuses.restartCount** (int32), required + + The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed. Note that this is calculated from dead containers. But those containers are subject to garbage collection. This value will get capped at 5 by GC. + + - **initContainerStatuses.started** (boolean) + + Specifies whether the container has passed its startup probe. Initialized as false, becomes true after startupProbe is considered successful. Resets to false when the container is restarted, or if kubelet loses state temporarily. Is always true when no startupProbe is defined. + +- **containerStatuses** ([]ContainerStatus) The list has one entry per container in the manifest. Each entry is currently the output of `docker inspect`. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status -- **ephemeralContainerStatuses** ([]}}">ContainerStatus) + + *ContainerStatus contains details for the current status of this container.* + + - **containerStatuses.name** (string), required + + This must be a DNS_LABEL. Each container in a pod must have a unique name. Cannot be updated. + + - **containerStatuses.image** (string), required + + The image the container is running. More info: https://kubernetes.io/docs/concepts/containers/images + + - **containerStatuses.imageID** (string), required + + ImageID of the container's image. + + - **containerStatuses.containerID** (string) + + Container's ID in the format 'docker://\'. + + - **containerStatuses.state** (ContainerState) + + Details about the container's current condition. + + + *ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting.* + + - **containerStatuses.state.running** (ContainerStateRunning) + + Details about a running container + + + *ContainerStateRunning is a running state of a container.* + + - **containerStatuses.state.running.startedAt** (Time) + + Time at which the container was last (re-)started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **containerStatuses.state.terminated** (ContainerStateTerminated) + + Details about a terminated container + + + *ContainerStateTerminated is a terminated state of a container.* + + - **containerStatuses.state.terminated.containerID** (string) + + Container's ID in the format 'docker://\' + + - **containerStatuses.state.terminated.exitCode** (int32), required + + Exit status from the last termination of the container + + - **containerStatuses.state.terminated.startedAt** (Time) + + Time at which previous execution of the container started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **containerStatuses.state.terminated.finishedAt** (Time) + + Time at which the container last terminated + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **containerStatuses.state.terminated.message** (string) + + Message regarding the last termination of the container + + - **containerStatuses.state.terminated.reason** (string) + + (brief) reason from the last termination of the container + + - **containerStatuses.state.terminated.signal** (int32) + + Signal from the last termination of the container + + - **containerStatuses.state.waiting** (ContainerStateWaiting) + + Details about a waiting container + + + *ContainerStateWaiting is a waiting state of a container.* + + - **containerStatuses.state.waiting.message** (string) + + Message regarding why the container is not yet running. + + - **containerStatuses.state.waiting.reason** (string) + + (brief) reason the container is not yet running. + + - **containerStatuses.lastState** (ContainerState) + + Details about the container's last termination condition. + + + *ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting.* + + - **containerStatuses.lastState.running** (ContainerStateRunning) + + Details about a running container + + + *ContainerStateRunning is a running state of a container.* + + - **containerStatuses.lastState.running.startedAt** (Time) + + Time at which the container was last (re-)started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **containerStatuses.lastState.terminated** (ContainerStateTerminated) + + Details about a terminated container + + + *ContainerStateTerminated is a terminated state of a container.* + + - **containerStatuses.lastState.terminated.containerID** (string) + + Container's ID in the format 'docker://\' + + - **containerStatuses.lastState.terminated.exitCode** (int32), required + + Exit status from the last termination of the container + + - **containerStatuses.lastState.terminated.startedAt** (Time) + + Time at which previous execution of the container started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **containerStatuses.lastState.terminated.finishedAt** (Time) + + Time at which the container last terminated + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **containerStatuses.lastState.terminated.message** (string) + + Message regarding the last termination of the container + + - **containerStatuses.lastState.terminated.reason** (string) + + (brief) reason from the last termination of the container + + - **containerStatuses.lastState.terminated.signal** (int32) + + Signal from the last termination of the container + + - **containerStatuses.lastState.waiting** (ContainerStateWaiting) + + Details about a waiting container + + + *ContainerStateWaiting is a waiting state of a container.* + + - **containerStatuses.lastState.waiting.message** (string) + + Message regarding why the container is not yet running. + + - **containerStatuses.lastState.waiting.reason** (string) + + (brief) reason the container is not yet running. + + - **containerStatuses.ready** (boolean), required + + Specifies whether the container has passed its readiness probe. + + - **containerStatuses.restartCount** (int32), required + + The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed. Note that this is calculated from dead containers. But those containers are subject to garbage collection. This value will get capped at 5 by GC. + + - **containerStatuses.started** (boolean) + + Specifies whether the container has passed its startup probe. Initialized as false, becomes true after startupProbe is considered successful. Resets to false when the container is restarted, or if kubelet loses state temporarily. Is always true when no startupProbe is defined. + +- **ephemeralContainerStatuses** ([]ContainerStatus) Status for any ephemeral containers that have run in this pod. This field is alpha-level and is only populated by servers that enable the EphemeralContainers feature. + + *ContainerStatus contains details for the current status of this container.* + + - **ephemeralContainerStatuses.name** (string), required + + This must be a DNS_LABEL. Each container in a pod must have a unique name. Cannot be updated. + + - **ephemeralContainerStatuses.image** (string), required + + The image the container is running. More info: https://kubernetes.io/docs/concepts/containers/images + + - **ephemeralContainerStatuses.imageID** (string), required + + ImageID of the container's image. + + - **ephemeralContainerStatuses.containerID** (string) + + Container's ID in the format 'docker://\'. + + - **ephemeralContainerStatuses.state** (ContainerState) + + Details about the container's current condition. + + + *ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting.* + + - **ephemeralContainerStatuses.state.running** (ContainerStateRunning) + + Details about a running container + + + *ContainerStateRunning is a running state of a container.* + + - **ephemeralContainerStatuses.state.running.startedAt** (Time) + + Time at which the container was last (re-)started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **ephemeralContainerStatuses.state.terminated** (ContainerStateTerminated) + + Details about a terminated container + + + *ContainerStateTerminated is a terminated state of a container.* + + - **ephemeralContainerStatuses.state.terminated.containerID** (string) + + Container's ID in the format 'docker://\' + + - **ephemeralContainerStatuses.state.terminated.exitCode** (int32), required + + Exit status from the last termination of the container + + - **ephemeralContainerStatuses.state.terminated.startedAt** (Time) + + Time at which previous execution of the container started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **ephemeralContainerStatuses.state.terminated.finishedAt** (Time) + + Time at which the container last terminated + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **ephemeralContainerStatuses.state.terminated.message** (string) + + Message regarding the last termination of the container + + - **ephemeralContainerStatuses.state.terminated.reason** (string) + + (brief) reason from the last termination of the container + + - **ephemeralContainerStatuses.state.terminated.signal** (int32) + + Signal from the last termination of the container + + - **ephemeralContainerStatuses.state.waiting** (ContainerStateWaiting) + + Details about a waiting container + + + *ContainerStateWaiting is a waiting state of a container.* + + - **ephemeralContainerStatuses.state.waiting.message** (string) + + Message regarding why the container is not yet running. + + - **ephemeralContainerStatuses.state.waiting.reason** (string) + + (brief) reason the container is not yet running. + + - **ephemeralContainerStatuses.lastState** (ContainerState) + + Details about the container's last termination condition. + + + *ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting.* + + - **ephemeralContainerStatuses.lastState.running** (ContainerStateRunning) + + Details about a running container + + + *ContainerStateRunning is a running state of a container.* + + - **ephemeralContainerStatuses.lastState.running.startedAt** (Time) + + Time at which the container was last (re-)started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **ephemeralContainerStatuses.lastState.terminated** (ContainerStateTerminated) + + Details about a terminated container + + + *ContainerStateTerminated is a terminated state of a container.* + + - **ephemeralContainerStatuses.lastState.terminated.containerID** (string) + + Container's ID in the format 'docker://\' + + - **ephemeralContainerStatuses.lastState.terminated.exitCode** (int32), required + + Exit status from the last termination of the container + + - **ephemeralContainerStatuses.lastState.terminated.startedAt** (Time) + + Time at which previous execution of the container started + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **ephemeralContainerStatuses.lastState.terminated.finishedAt** (Time) + + Time at which the container last terminated + + + *Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers.* + + - **ephemeralContainerStatuses.lastState.terminated.message** (string) + + Message regarding the last termination of the container + + - **ephemeralContainerStatuses.lastState.terminated.reason** (string) + + (brief) reason from the last termination of the container + + - **ephemeralContainerStatuses.lastState.terminated.signal** (int32) + + Signal from the last termination of the container + + - **ephemeralContainerStatuses.lastState.waiting** (ContainerStateWaiting) + + Details about a waiting container + + + *ContainerStateWaiting is a waiting state of a container.* + + - **ephemeralContainerStatuses.lastState.waiting.message** (string) + + Message regarding why the container is not yet running. + + - **ephemeralContainerStatuses.lastState.waiting.reason** (string) + + (brief) reason the container is not yet running. + + - **ephemeralContainerStatuses.ready** (boolean), required + + Specifies whether the container has passed its readiness probe. + + - **ephemeralContainerStatuses.restartCount** (int32), required + + The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed. Note that this is calculated from dead containers. But those containers are subject to garbage collection. This value will get capped at 5 by GC. + + - **ephemeralContainerStatuses.started** (boolean) + + Specifies whether the container has passed its startup probe. Initialized as false, becomes true after startupProbe is considered successful. Resets to false when the container is restarted, or if kubelet loses state temporarily. Is always true when no startupProbe is defined. + @@ -569,20 +1928,22 @@ PodList is a list of Pods.
-- **apiVersion**: v1 +- **items** ([]}}">Pod), required + List of pods. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md -- **kind**: PodList +- **apiVersion** (string) + APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + +- **kind** (string) + + Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - **metadata** (}}">ListMeta) Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds -- **items** ([]}}">Pod), required - - List of pods. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/priority-class-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/priority-class-v1.md index 28087807c1..df6c08603f 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/priority-class-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/priority-class-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "PriorityClass defines mapping from a priority class name to the priority integer value." title: "PriorityClass" -weight: 16 +weight: 14 --- `apiVersion: scheduling.k8s.io/v1` diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/replica-set-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/replica-set-v1.md index 708b0fd966..223832c382 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/replica-set-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/replica-set-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ReplicaSet ensures that a specified number of pod replicas are running at any given time." title: "ReplicaSet" -weight: 6 +weight: 5 --- `apiVersion: apps/v1` diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/replication-controller-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/replication-controller-v1.md index 1f7962ee96..29bac77169 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/replication-controller-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/replication-controller-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "ReplicationController represents the configuration of a replication controller." title: "ReplicationController" -weight: 5 +weight: 4 --- `apiVersion: v1` diff --git a/content/en/docs/reference/kubernetes-api/workload-resources/stateful-set-v1.md b/content/en/docs/reference/kubernetes-api/workload-resources/stateful-set-v1.md index 17ea7755f2..7e69ec17bb 100644 --- a/content/en/docs/reference/kubernetes-api/workload-resources/stateful-set-v1.md +++ b/content/en/docs/reference/kubernetes-api/workload-resources/stateful-set-v1.md @@ -6,7 +6,7 @@ api_metadata: content_type: "api_reference" description: "StatefulSet represents a set of pods with consistent identities." title: "StatefulSet" -weight: 8 +weight: 7 --- `apiVersion: apps/v1` @@ -84,9 +84,9 @@ A StatefulSetSpec is the specification of a StatefulSet. *RollingUpdateStatefulSetStrategy is used to communicate parameter for RollingUpdateStatefulSetStrategyType.* - - **updateStrategy.rollingUpdate.partition** (int32) + - **updateStrategy.rollingUpdate.partition** (int32) - Partition indicates the ordinal at which the StatefulSet should be partitioned. Default value is 0. + Partition indicates the ordinal at which the StatefulSet should be partitioned. Default value is 0. - **podManagementPolicy** (string) diff --git a/content/en/docs/reference/labels-annotations-taints.md b/content/en/docs/reference/labels-annotations-taints.md index 8f4327ceca..08861e5811 100644 --- a/content/en/docs/reference/labels-annotations-taints.md +++ b/content/en/docs/reference/labels-annotations-taints.md @@ -30,6 +30,20 @@ Used on: Node The Kubelet populates this with `runtime.GOOS` as defined by Go. This can be handy if you are mixing operating systems in your cluster (for example: mixing Linux and Windows nodes). +## kubernetes.io/metadata.name + +Example: `kubernetes.io/metadata.name=mynamespace` + +Used on: Namespaces + +When the `NamespaceDefaultLabelName` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled, +the Kubernetes API server sets this label on all namespaces. The label value is set to +the name of the namespace. + +This is useful if you want to target a specific namespace with a label +{{< glossary_tooltip text="selector" term_id="selector" >}}. + ## beta.kubernetes.io/arch (deprecated) This label has been deprecated. Please use `kubernetes.io/arch` instead. @@ -48,6 +62,16 @@ The Kubelet populates this label with the hostname. Note that the hostname can b This label is also used as part of the topology hierarchy. See [topology.kubernetes.io/zone](#topologykubernetesiozone) for more information. + +## controller.kubernetes.io/pod-deletion-cost {#pod-deletion-cost} + +Example: `controller.kubernetes.io/pod-deletion-cost=10` + +Used on: Pod + +This annotation is used to set [Pod Deletion Cost](/docs/content/en/docs/concepts/workloads/controllers/replicaset/#pod-deletion-cost) +which allows users to influence ReplicaSet downscaling order. The annotation parses into an `int32` type. + ## 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 >}} @@ -198,6 +222,29 @@ The kubelet can set this annotation on a Node to denote its configured IPv4 addr When kubelet is started with the "external" cloud provider, 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 + +Example: `batch.kubernetes.io/job-completion-index: "3"` + +Used on: Pod + +The Job controller in the kube-controller-manager sets this annotation for Pods +created with Indexed [completion mode](/docs/concepts/workloads/controllers/job/#completion-mode). + +## kubectl.kubernetes.io/default-container + +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. + +## endpoints.kubernetes.io/over-capacity + +Example: `endpoints.kubernetes.io/over-capacity:warning` + +Used on: Endpoints + +In Kubernetes clusters v1.21 (or later), the Endpoints controller adds this annotation to an Endpoints resource if it has more than 1000 endpoints. The annotation indicates that the Endpoints resource is over capacity. + **The taints listed below are always used on Nodes** ## node.kubernetes.io/not-ready @@ -253,4 +300,3 @@ Sets this taint on a node to mark it as unusable, when kubelet is started with t 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`. - diff --git a/content/en/docs/reference/scheduling/config.md b/content/en/docs/reference/scheduling/config.md index 53889a21f3..02a6e8e505 100644 --- a/content/en/docs/reference/scheduling/config.md +++ b/content/en/docs/reference/scheduling/config.md @@ -147,7 +147,12 @@ extension points: Extension points: `Score`. - `VolumeBinding`: Checks if the node has or if it can bind the requested {{< glossary_tooltip text="volumes" term_id="volume" >}}. - Extension points: `PreFilter`, `Filter`, `Reserve`, `PreBind`. + Extension points: `PreFilter`, `Filter`, `Reserve`, `PreBind`, `Score`. + {{< note >}} + `Score` extension point is enabled when `VolumeCapacityPriority` feature is + enabled. It prioritizes the smallest PVs that can fit the requested volume + size. + {{< /note >}} - `VolumeRestrictions`: Checks that volumes mounted in the node satisfy restrictions that are specific to the volume provider. Extension points: `Filter`. diff --git a/content/en/docs/reference/setup-tools/kubeadm/_index.md b/content/en/docs/reference/setup-tools/kubeadm/_index.md index d747c05124..ad84378d1d 100755 --- a/content/en/docs/reference/setup-tools/kubeadm/_index.md +++ b/content/en/docs/reference/setup-tools/kubeadm/_index.md @@ -26,5 +26,7 @@ To install kubeadm, see the [installation guide](/docs/setup/production-environm * [kubeadm config](/docs/reference/setup-tools/kubeadm/kubeadm-config) if you initialized your cluster using kubeadm v1.7.x or lower, to configure your cluster for `kubeadm upgrade` * [kubeadm token](/docs/reference/setup-tools/kubeadm/kubeadm-token) to manage tokens for `kubeadm join` * [kubeadm reset](/docs/reference/setup-tools/kubeadm/kubeadm-reset) to revert any changes made to this host by `kubeadm init` or `kubeadm join` +* [kubeadm certs](/docs/reference/setup-tools/kubeadm/kubeadm-certs) to manage Kubernetes certificates +* [kubeadm kubeconfig](/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig) to manage kubeconfig files * [kubeadm version](/docs/reference/setup-tools/kubeadm/kubeadm-version) to print the kubeadm version * [kubeadm alpha](/docs/reference/setup-tools/kubeadm/kubeadm-alpha) to preview a set of features made available for gathering feedback from the community diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet.md deleted file mode 100644 index 055c8ecac5..0000000000 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet.md +++ /dev/null @@ -1,48 +0,0 @@ - -### Synopsis - - -This command is not meant to be run on its own. See list of available subcommands. - -### Options - - ---- - - - - - - - - - - -
-h, --help
help for kubelet
- - - -### Options inherited from parent commands - - ---- - - - - - - - - - - -
--rootfs string
[EXPERIMENTAL] The path to the 'real' host root filesystem.
- - - diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet_config.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet_config.md deleted file mode 100644 index 563d9fe227..0000000000 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet_config.md +++ /dev/null @@ -1,48 +0,0 @@ - -### Synopsis - - -This command is not meant to be run on its own. See list of available subcommands. - -### Options - - ---- - - - - - - - - - - -
-h, --help
help for config
- - - -### Options inherited from parent commands - - ---- - - - - - - - - - - -
--rootfs string
[EXPERIMENTAL] The path to the 'real' host root filesystem.
- - - diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet_config_enable-dynamic.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet_config_enable-dynamic.md deleted file mode 100644 index 278def1dd3..0000000000 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubelet_config_enable-dynamic.md +++ /dev/null @@ -1,87 +0,0 @@ - -### Synopsis - - -Enable or update dynamic kubelet configuration for a Node, against the kubelet-config-1.X ConfigMap in the cluster, where X is the minor version of the desired kubelet version. - -WARNING: This feature is still experimental, and disabled by default. Enable only if you know what you are doing, as it may have surprising side-effects at this stage. - -Alpha Disclaimer: this command is currently alpha. - -``` -kubeadm alpha kubelet config enable-dynamic [flags] -``` - -### Examples - -``` - # Enable dynamic kubelet configuration for a Node. - kubeadm alpha phase kubelet enable-dynamic-config --node-name node-1 --kubelet-version 1.18.0 - - WARNING: This feature is still experimental, and disabled by default. Enable only if you know what you are doing, as it - may have surprising side-effects at this stage. -``` - -### Options - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-h, --help
help for enable-dynamic
--kubeconfig string     Default: "/etc/kubernetes/admin.conf"
The kubeconfig file to use when talking to the cluster. If the flag is not set, a set of standard locations can be searched for an existing kubeconfig file.
--kubelet-version string
The desired version for the kubelet
--node-name string
Name of the node that should enable the dynamic kubelet configuration
- - - -### Options inherited from parent commands - - ---- - - - - - - - - - - -
--rootfs string
[EXPERIMENTAL] The path to the 'real' host root filesystem.
- - - diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_selfhosting.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_selfhosting.md deleted file mode 100644 index 77646b064b..0000000000 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_selfhosting.md +++ /dev/null @@ -1,48 +0,0 @@ - -### Synopsis - - -This command is not meant to be run on its own. See list of available subcommands. - -### Options - - ---- - - - - - - - - - - -
-h, --help
help for selfhosting
- - - -### Options inherited from parent commands - - ---- - - - - - - - - - - -
--rootfs string
[EXPERIMENTAL] The path to the 'real' host root filesystem.
- - - diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_selfhosting_pivot.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_selfhosting_pivot.md deleted file mode 100644 index 554b8fe4c6..0000000000 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_selfhosting_pivot.md +++ /dev/null @@ -1,99 +0,0 @@ - -### Synopsis - - -Convert static Pod files for control plane components into self-hosted DaemonSets configured via the Kubernetes API. - -See the documentation for self-hosting limitations. - -Alpha Disclaimer: this command is currently alpha. - -``` -kubeadm alpha selfhosting pivot [flags] -``` - -### Examples - -``` - # Convert a static Pod-hosted control plane into a self-hosted one. - - kubeadm alpha phase self-hosting convert-from-staticpods -``` - -### Options - - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
--cert-dir string     Default: "/etc/kubernetes/pki"
The path where certificates are stored
--config string
Path to a kubeadm configuration file.
-f, --force
Pivot the cluster without prompting for confirmation
-h, --help
help for pivot
--kubeconfig string     Default: "/etc/kubernetes/admin.conf"
The kubeconfig file to use when talking to the cluster. If the flag is not set, a set of standard locations can be searched for an existing kubeconfig file.
-s, --store-certs-in-secrets
Enable storing certs in secrets
- - - -### Options inherited from parent commands - - ---- - - - - - - - - - - -
--rootfs string
[EXPERIMENTAL] The path to the 'real' host root filesystem.
- - - diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubeconfig.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_kubeconfig.md similarity index 93% rename from content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubeconfig.md rename to content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_kubeconfig.md index 67f30bc3f8..67ee58fdd7 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubeconfig.md +++ b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_kubeconfig.md @@ -4,8 +4,6 @@ Kubeconfig file utilities. -Alpha Disclaimer: this command is currently alpha. - ### Options diff --git a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubeconfig_user.md b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_kubeconfig_user.md similarity index 92% rename from content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubeconfig_user.md rename to content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_kubeconfig_user.md index bdb246232f..8ff987503c 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_kubeconfig_user.md +++ b/content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_kubeconfig_user.md @@ -4,17 +4,16 @@ Output a kubeconfig file for an additional user. -Alpha Disclaimer: this command is currently alpha. ``` -kubeadm alpha kubeconfig user [flags] +kubeadm kubeconfig user [flags] ``` ### Examples ``` # Output a kubeconfig file for an additional user named foo using a kubeadm config file bar - kubeadm alpha kubeconfig user --client-name=foo --config=bar + kubeadm kubeconfig user --client-name=foo --config=bar ``` ### Options diff --git a/content/en/docs/reference/setup-tools/kubeadm/implementation-details.md b/content/en/docs/reference/setup-tools/kubeadm/implementation-details.md index 7159fc765d..cc7cef2543 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/implementation-details.md +++ b/content/en/docs/reference/setup-tools/kubeadm/implementation-details.md @@ -440,12 +440,14 @@ A ServiceAccount for `kube-proxy` is created in the `kube-system` namespace; the #### DNS -- In Kubernetes version 1.18 kube-dns usage with kubeadm is deprecated and will be removed in a future release - The CoreDNS service is named `kube-dns`. This is done to prevent any interruption - in service when the user is switching the cluster DNS from kube-dns to CoreDNS or vice-versa - the `--config` method described [here](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-addon) -- A ServiceAccount for CoreDNS/kube-dns is created in the `kube-system` namespace. -- The `kube-dns` ServiceAccount is bound to the privileges in the `system:kube-dns` ClusterRole + in service when the user is switching the cluster DNS from kube-dns to CoreDNS + the `--config` method described [here](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-addon). +- A ServiceAccount for CoreDNS is created in the `kube-system` namespace. +- The `coredns` ServiceAccount is bound to the privileges in the `system:coredns` ClusterRole + +In Kubernetes version 1.21, support for using `kube-dns` with kubeadm was removed. +You can use CoreDNS with kubeadm even when the related Service is named `kube-dns`. ## kubeadm join phases internal design diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-alpha.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-alpha.md index eaef0f5140..dd946c9737 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-alpha.md +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-alpha.md @@ -9,34 +9,7 @@ weight: 90 from the community. Please try it out and give us feedback! {{< /caution >}} -## kubeadm alpha kubeconfig user {#cmd-phase-kubeconfig} - -The `user` subcommand can be used for the creation of kubeconfig files for additional users. - -{{< tabs name="tab-kubeconfig" >}} -{{< tab name="kubeconfig" include="generated/kubeadm_alpha_kubeconfig.md" />}} -{{< tab name="user" include="generated/kubeadm_alpha_kubeconfig_user.md" />}} -{{< /tabs >}} - -## kubeadm alpha kubelet config {#cmd-phase-kubelet} - -Use the following command to enable the DynamicKubeletConfiguration feature. - -{{< tabs name="tab-kubelet" >}} -{{< tab name="kubelet" include="generated/kubeadm_alpha_kubelet.md" />}} -{{< tab name="enable-dynamic" include="generated/kubeadm_alpha_kubelet_config_enable-dynamic.md" />}} -{{< /tabs >}} - -## kubeadm alpha selfhosting pivot {#cmd-selfhosting} - -The subcommand `pivot` can be used to convert a static Pod-hosted control plane into a self-hosted one. - -[Documentation](/docs/setup/production-environment/tools/kubeadm/self-hosting/) - -{{< tabs name="selfhosting" >}} -{{< tab name="selfhosting" include="generated/kubeadm_alpha_selfhosting.md" />}} -{{< tab name="pivot" include="generated/kubeadm_alpha_selfhosting_pivot.md" />}} -{{< /tabs >}} +Currently there are no experimental commands under `kubeadm alpha`. ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-config.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-config.md index 23dff658e9..93f89c594b 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-config.md +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-config.md @@ -20,10 +20,6 @@ For more information navigate to [Using kubeadm init with a configuration file](/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file) or [Using kubeadm join with a configuration file](/docs/reference/setup-tools/kubeadm/kubeadm-join/#config-file). -In Kubernetes v1.13.0 and later to list/pull kube-dns images instead of the CoreDNS image -the `--config` method described [here](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-addon) -has to be used. - ## kubeadm config view {#cmd-config-view} diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init-phase.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init-phase.md index 21ab7a863d..2b6939bac6 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init-phase.md +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init-phase.md @@ -143,25 +143,6 @@ install them selectively. {{< tab name="kube-proxy" include="generated/kubeadm_init_phase_addon_kube-proxy.md" />}} {{< /tabs >}} -To use kube-dns instead of CoreDNS you have to pass a configuration file: - -```bash -# for installing a DNS addon only -kubeadm init phase addon coredns --config=someconfig.yaml -``` - -The file has to contain a [`dns`](https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2#DNS) field in[`ClusterConfiguration`](https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2#ClusterConfiguration) -and also a type for the addon - `kube-dns` (default value is `CoreDNS`). - -```yaml -apiVersion: kubeadm.k8s.io/v1beta2 -kind: ClusterConfiguration -dns: - type: "kube-dns" -``` - -Please note that kube-dns usage with kubeadm is deprecated as of v1.18 and will be removed in a future release. - For more details on each field in the `v1beta2` configuration you can navigate to our [API reference pages.] (https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2) diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md index c33a195120..2260c2ca22 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md @@ -66,12 +66,10 @@ following steps: 1. Installs a DNS server (CoreDNS) and the kube-proxy addon components via the API server. In Kubernetes version 1.11 and later CoreDNS is the default DNS server. - To install kube-dns instead of CoreDNS, the DNS addon has to be configured in the kubeadm `ClusterConfiguration`. - For more information about the configuration see the section `Using kubeadm init with a configuration file` below. Please note that although the DNS server is deployed, it will not be scheduled until CNI is installed. {{< warning >}} - kube-dns usage with kubeadm is deprecated as of v1.18 and will be removed in a future release. + kube-dns usage with kubeadm is deprecated as of v1.18 and is removed in v1.21. {{< /warning >}} ### Using init phases with kubeadm {#init-phases} diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md new file mode 100644 index 0000000000..f912285f7d --- /dev/null +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md @@ -0,0 +1,21 @@ +--- +title: kubeadm kubeconfig +content_type: concept +weight: 90 +--- + +`kubeadm kubeconfig` provides utilities for managing kubeconfig files. + +## kubeadm kubeconfig {#cmd-kubeconfig} + +{{< tabs name="tab-kubeconfig" >}} +{{< tab name="overview" include="generated/kubeadm_kubeconfig.md" />}} +{{< /tabs >}} + +## kubeadm kubeconfig user {#cmd-kubeconfig-user} + +This command can be used to output a kubeconfig file for an additional user. + +{{< tabs name="tab-kubeconfig-user" >}} +{{< tab name="user" include="generated/kubeadm_kubeconfig_user.md" />}} +{{< /tabs >}} \ No newline at end of file diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-upgrade.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-upgrade.md index 5796e7aec7..6a2c5f782f 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-upgrade.md +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-upgrade.md @@ -20,8 +20,6 @@ For older versions of kubeadm, please refer to older documentation sets of the K You can use `kubeadm upgrade diff` to see the changes that would be applied to static pod manifests. -To use kube-dns with upgrades in Kubernetes v1.13.0 and later please follow [this guide](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/#cmd-phase-addon). - In Kubernetes v1.15.0 and later, `kubeadm upgrade apply` and `kubeadm upgrade node` will also automatically renew the kubeadm managed certificates on this node, including those stored in kubeconfig files. To opt-out, it is possible to pass the flag `--certificate-renewal=false`. For more details about certificate diff --git a/content/en/docs/reference/using-api/deprecation-guide.md b/content/en/docs/reference/using-api/deprecation-guide.md index a8ad3494bd..7de71303d7 100755 --- a/content/en/docs/reference/using-api/deprecation-guide.md +++ b/content/en/docs/reference/using-api/deprecation-guide.md @@ -25,6 +25,17 @@ deprecated API versions to newer and more stable API versions. The **v1.25** release will stop serving the following deprecated API versions: +#### EndpointSlice {#endpointslice-v125} + +The **discovery.k8s.io/v1beta1** API version of EndpointSlice will no longer be served in v1.25. + +* Migrate manifests and API clients to use the **discovery.k8s.io/v1** API version, available since v1.21. +* All existing persisted objects are accessible via the new API +* Notable changes in **discovery.k8s.io/v1**: + * use per Endpoint `nodeName` field instead of deprecated `topology["kubernetes.io/hostname"]` field + * use per Endpoint `zone` field instead of deprecated `topology["topology.kubernetes.io/zone"]` field + * `topology` is replaced with the `deprecatedTopology` field which is not writable in v1 + #### Event {#event-v125} The **events.k8s.io/v1beta1** API version of Event will no longer be served in v1.25. diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index 4de09ee82a..eed4341628 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -301,7 +301,7 @@ Starting in Kubernetes v1.19, making an API request to a deprecated REST API end 1. Returns a `Warning` header (as defined in [RFC7234, Section 5.5](https://tools.ietf.org/html/rfc7234#section-5.5)) in the API response. 2. Adds a `"k8s.io/deprecated":"true"` annotation to the [audit event](/docs/tasks/debug-application-cluster/audit/) recorded for the request. -3. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver` +3. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver` process. The metric has labels for `group`, `version`, `resource`, `subresource` that can be joined to the `apiserver_request_total` metric, and a `removed_release` label that indicates the Kubernetes release in which the API will no longer be served. The following Prometheus query @@ -428,6 +428,46 @@ transitions a lifecycle stage as follows. Feature gates must function for no les is deprecated it must be documented in both in the release notes and the corresponding CLI help. Both warnings and documentation must indicate whether a feature gate is non-operational.** +## Deprecating a metric + +Each component of the Kubernetes control-plane exposes metrics (usually the +`/metrics` endpoint), which are typically ingested by cluster administrators. +Not all metrics are the same: some metrics are commonly used as SLIs or used +to determine SLOs, these tend to have greater import. Other metrics are more +experimental in nature or are used primarily in the Kubernetes development +process. + +Accordingly, metrics fall under two stability classes (`ALPHA` and `STABLE`); +this impacts removal of a metric during a Kubernetes release. These classes +are determined by the perceived importance of the metric. The rules for +deprecating and removing a metric are as follows: + +**Rule #9a: Metrics, for the corresponding stability class, must function for no less than:** + + * **STABLE: 4 releases or 12 months (whichever is longer)** + * **ALPHA: 0 releases** + +**Rule #9b: Metrics, after their _announced deprecation_, must function for no less than:** + + * **STABLE: 3 releases or 9 months (whichever is longer)** + * **ALPHA: 0 releases** + +Deprecated metrics will have their description text prefixed with a deprecation notice +string '(Deprecated from x.y)' and a warning log will be emitted during metric +registration. Like their stable undeprecated counterparts, deprecated metrics will +be automatically registered to the metrics endpoint and therefore visible. + +On a subsequent release (when the metric's `deprecatedVersion` is equal to +_current_kubernetes_version - 3_)), a deprecated metric will become a _hidden_ metric. +**_Unlike_** their deprecated counterparts, hidden metrics will _no longer_ be +automatically registered to the metrics endpoint (hence hidden). However, they +can be explicitly enabled through a command line flag on the binary +(`--show-hidden-metrics-for-version=`). This provides cluster admins an +escape hatch to properly migrate off of a deprecated metric, if they were not +able to react to the earlier deprecation warnings. Hidden metrics should be +deleted after one release. + + ## Exceptions No policy can cover every possible situation. This policy is a living @@ -438,4 +478,3 @@ leaders to find the best solutions for those specific cases, always bearing in mind that Kubernetes is committed to being a stable system that, as much as possible, never breaks users. Exceptions will always be announced in all relevant release notes. - diff --git a/content/en/docs/setup/production-environment/container-runtimes.md b/content/en/docs/setup/production-environment/container-runtimes.md index ba6827d833..b296636212 100644 --- a/content/en/docs/setup/production-environment/container-runtimes.md +++ b/content/en/docs/setup/production-environment/container-runtimes.md @@ -48,7 +48,7 @@ Changing the settings such that your container runtime and kubelet use `systemd` stabilized the system. To configure this for Docker, set `native.cgroupdriver=systemd`. {{< caution >}} -Changing the cgroup driver of a Node that has joined a cluster is strongly *not* recommended. +Changing the cgroup driver of a Node that has joined a cluster is a sensitive operation. If the kubelet has created Pods using the semantics of one cgroup driver, changing the container runtime to another cgroup driver can cause errors when trying to re-create the Pod sandbox for such existing Pods. Restarting the kubelet may not solve such errors. @@ -57,6 +57,11 @@ If you have automation that makes it feasible, replace the node with another usi configuration, or reinstall it using automation. {{< /caution >}} +### Migrating to the `systemd` driver in kubeadm managed clusters + +Follow this [Migration guide](/tasks/administer-cluster/kubeadm/configure-cgroup-driver) +if you wish to migrate to the `systemd` cgroup driver in existing kubeadm managed clusters. + ## Container runtimes {{% thirdparty-content %}} diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md b/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md index a5cdecafd7..0a394ad022 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md +++ b/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md @@ -187,6 +187,13 @@ Alternatively, if you are the `root` user, you can run: export KUBECONFIG=/etc/kubernetes/admin.conf ``` +{{< warning >}} +Kubeadm signs the certificate in the `admin.conf` to have `Subject: O = system:masters, CN = kubernetes-admin`. +`system:masters` is a break-glass, super user group that bypasses the authorization layer (e.g. RBAC). +Do not share the `admin.conf` file with anyone and instead grant users custom permissions by generating +them a kubeconfig file using the `kubeadm kubeconfig user` command. +{{< /warning >}} + Make a record of the `kubeadm join` command that `kubeadm init` outputs. You need this command to [join nodes to your cluster](#join-nodes). diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/dual-stack-support.md b/content/en/docs/setup/production-environment/tools/kubeadm/dual-stack-support.md new file mode 100644 index 0000000000..767787179c --- /dev/null +++ b/content/en/docs/setup/production-environment/tools/kubeadm/dual-stack-support.md @@ -0,0 +1,152 @@ +--- +title: Dual-stack support with kubeadm +content_type: task +weight: 110 +min-kubernetes-server-version: 1.21 +--- + + + +{{< feature-state for_k8s_version="v1.21" state="beta" >}} + +Your Kubernetes cluster can run in [dual-stack](/docs/concepts/services-networking/dual-stack/) networking mode, which means that cluster networking lets you use either address family. In a dual-stack cluster, the control plane can assign both an IPv4 address and an IPv6 address to a single {{< glossary_tooltip text="Pod" term_id="pod" >}} or a {{< glossary_tooltip text="Service" term_id="service" >}}. + + + +## {{% heading "prerequisites" %}} + +You need to have installed the {{< glossary_tooltip text="kubeadm" term_id="kubeadm" >}} tool, following the steps from [Installing kubeadm](/docs/setup/production-environment/tools/kubeadm/install-kubeadm/). + +For each server that you want to use as a {{< glossary_tooltip text="node" term_id="node" >}}, make sure it allows IPv6 forwarding. On Linux, you can set this by running run `sysctl -w net.ipv6.conf.all.forwarding=1` as the root user on each server. + +You need to have an IPv4 and and IPv6 address range to use. Cluster operators typically +use private address ranges for IPv4. For IPv6, a cluster operator typically chooses a global +unicast address block from within `2000::/3`, using a range that is assigned to the operator. +You don't have to route the cluster's IP address ranges to the public internet. + +The size of the IP address allocations should be suitable for the number of Pods and +Services that you are planning to run. + +{{< note >}} +If you are upgrading an existing cluster then, by default, the `kubeadm upgrade` command +changes the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +`IPv6DualStack` to `true` if that is not already enabled. +However, `kubeadm` does not support making modifications to the pod IP address range +(“cluster CIDR”) nor to the cluster's Service address range (“Service CIDR”). +{{< /note >}} + +### Create a dual-stack cluster + +To create a dual-stack cluster with `kubeadm init` you can pass command line arguments +similar to the following example: + +```shell +# These address ranges are examples +kubeadm init --pod-network-cidr=10.244.0.0/16,2001:db8:42:0::/56 --service-cidr=10.96.0.0/16,2001:db8:42:1::/112 +``` + +To make things clearer, here is an example kubeadm [configuration file](https://pkg.go.dev/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2) `kubeadm-config.yaml` for the primary dual-stack control plane node. + +```yaml +--- +apiVersion: kubeadm.k8s.io/v1beta2 +kind: ClusterConfiguration +featureGates: + IPv6DualStack: true +networking: + podSubnet: 10.244.0.0/16,2001:db8:42:0::/56 + serviceSubnet: 10.96.0.0/16,2001:db8:42:1::/112 +--- +apiVersion: kubeadm.k8s.io/v1beta2 +kind: InitConfiguration +localAPIEndpoint: + advertiseAddress: "10.100.0.1" + bindPort: 6443 +nodeRegistration: + kubeletExtraArgs: + node-ip: 10.100.0.2,fd00:1:2:3::2 +``` + +`advertiseAddress` in InitConfiguration specifies the IP address that the API Server will advertise it is listening on. The value of `advertiseAddress` equals the `--apiserver-advertise-address` flag of `kubeadm init` + +Run kubeadm to initiate the dual-stack control plane node: + +```shell +kubeadm init --config=kubeadm-config.yaml +``` + +Currently, the kube-controller-manager flags `--node-cidr-mask-size-ipv4|--node-cidr-mask-size-ipv6` are being left with default values. See [enable IPv4/IPv6 dual stack](/docs/concepts/services-networking/dual-stack#enable-ipv4ipv6-dual-stack). + +{{< note >}} +The `--apiserver-advertise-address` flag does not support dual-stack. +{{< /note >}} + +### Join a node to dual-stack cluster + +Before joining a node, make sure that the node has IPv6 routable network interface and allows IPv6 forwarding. + +Here is an example kubeadm [configuration file](https://pkg.go.dev/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2) `kubeadm-config.yaml` for joining a worker node to the cluster. + +```yaml +apiVersion: kubeadm.k8s.io/v1beta2 +kind: JoinConfiguration +discovery: + bootstrapToken: + apiServerEndpoint: 10.100.0.1:6443 +nodeRegistration: + kubeletExtraArgs: + node-ip: 10.100.0.3,fd00:1:2:3::3 +``` + +Also, here is an example kubeadm [configuration file](https://pkg.go.dev/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2) `kubeadm-config.yaml` for joining another control plane node to the cluster. +```yaml +apiVersion: kubeadm.k8s.io/v1beta2 +kind: JoinConfiguration +controlPlane: + localAPIEndpoint: + advertiseAddress: "10.100.0.2" + bindPort: 6443 +discovery: + bootstrapToken: + apiServerEndpoint: 10.100.0.1:6443 +nodeRegistration: + kubeletExtraArgs: + node-ip: 10.100.0.4,fd00:1:2:3::4 + +``` + +`advertiseAddress` in JoinConfiguration.controlPlane specifies the IP address that the API Server will advertise it is listening on. The value of `advertiseAddress` equals the `--apiserver-advertise-address` flag of `kubeadm join`. + +```shell +kubeadm join --config=kubeadm-config.yaml ... +``` + +### Create a single-stack cluster + +{{< note >}} +Enabling the dual-stack feature doesn't mean that you need to use dual-stack addressing. +You can deploy a single-stack cluster that has the dual-stack networking feature enabled. +{{< /note >}} + +In 1.21 the `IPv6DualStack` feature is Beta and the feature gate is defaulted to `true`. To disable the feature you must configure the feature gate to `false`. Note that once the feature is GA, the feature gate will be removed. + +```shell +kubeadm init --feature-gates IPv6DualStack=false +``` + +To make things more clear, here is an example kubeadm [configuration file](https://pkg.go.dev/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2) `kubeadm-config.yaml` for the single-stack control plane node. + +```yaml +apiVersion: kubeadm.k8s.io/v1beta2 +kind: ClusterConfiguration +featureGates: + IPv6DualStack: false +networking: + podSubnet: 10.244.0.0/16 + serviceSubnet: 10.96.0.0/16 +``` + +## {{% heading "whatsnext" %}} + +* [Validate IPv4/IPv6 dual-stack](/docs/tasks/network/validate-dual-stack) networking +* Read about [Dual-stack](/docs/concepts/services-networking/dual-stack/) cluster networking diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md b/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md index ea144e1dae..c997156827 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md +++ b/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md @@ -244,7 +244,7 @@ sudo mkdir -p /opt/cni/bin curl -L "https://github.com/containernetworking/plugins/releases/download/${CNI_VERSION}/cni-plugins-linux-amd64-${CNI_VERSION}.tgz" | sudo tar -C /opt/cni/bin -xz ``` -Define the directory to download command files +Define the directory to download command files {{< note >}} The `DOWNLOAD_DIR` variable must be set to a writable directory. @@ -295,33 +295,17 @@ See the [Kubeadm Troubleshooting guide](/docs/setup/production-environment/tools The kubelet is now restarting every few seconds, as it waits in a crashloop for kubeadm to tell it what to do. -## Configure cgroup driver used by kubelet on control-plane node +## Configuring a cgroup driver -When using Docker, kubeadm will automatically detect the cgroup driver for the kubelet -and set it in the `/var/lib/kubelet/config.yaml` file during runtime. +Both the container runtime and the kubelet have a property called +["cgroup driver"](/docs/setup/production-environment/container-runtimes/), which is important +for the management of cgroups on Linux machines. -If you are using a different CRI, you must pass your `cgroupDriver` value to `kubeadm init`, like so: +{{< warning >}} +Matching the container runtime and kubelet cgroup drivers is required or otherwise the kubelet process will fail. -```yaml -apiVersion: kubelet.config.k8s.io/v1beta1 -kind: KubeletConfiguration -cgroupDriver: -``` - -For further details, please read [Using kubeadm init with a configuration file](/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file) -and the [`KubeletConfiguration` reference](/docs/reference/config-api/kubelet-config.v1beta1/) - -Please mind, that you **only** have to do that if the cgroup driver of your CRI -is not `cgroupfs`, because that is the default value in the kubelet already. - -{{< note >}} -Since `--cgroup-driver` flag has been deprecated by the kubelet, if you have that in `/var/lib/kubelet/kubeadm-flags.env` -or `/etc/default/kubelet`(`/etc/sysconfig/kubelet` for RPMs), please remove it and use the KubeletConfiguration instead -(stored in `/var/lib/kubelet/config.yaml` by default). -{{< /note >}} - -The automatic detection of cgroup driver for other container runtimes -like CRI-O and containerd is work in progress. +See [Configuring a cgroup driver](/docs/tasks/administer-cluster/kubeadm/configure-cgroup-driver/) for more details. +{{< /warning >}} ## Troubleshooting diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/self-hosting.md b/content/en/docs/setup/production-environment/tools/kubeadm/self-hosting.md deleted file mode 100644 index d860a88bdd..0000000000 --- a/content/en/docs/setup/production-environment/tools/kubeadm/self-hosting.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -reviewers: -- sig-cluster-lifecycle -title: Configuring your kubernetes cluster to self-host the control plane -content_type: concept -weight: 100 ---- - - - -### Self-hosting the Kubernetes control plane {#self-hosting} - -kubeadm allows you to experimentally create a _self-hosted_ Kubernetes control -plane. This means that key components such as the API server, controller -manager, and scheduler run as [DaemonSet pods](/docs/concepts/workloads/controllers/daemonset/) -configured via the Kubernetes API instead of [static pods](/docs/tasks/configure-pod-container/static-pod/) -configured in the kubelet via static files. - -To create a self-hosted cluster see the -[kubeadm alpha selfhosting pivot](/docs/reference/setup-tools/kubeadm/kubeadm-alpha/#cmd-selfhosting) command. - - - -#### Caveats - -{{< caution >}} -This feature pivots your cluster into an unsupported state, rendering kubeadm unable -to manage you cluster any longer. This includes `kubeadm upgrade`. -{{< /caution >}} - -1. Self-hosting in 1.8 and later has some important limitations. In particular, a - self-hosted cluster _cannot recover from a reboot of the control-plane node_ - without manual intervention. - -1. By default, self-hosted control plane Pods rely on credentials loaded from - [`hostPath`](/docs/concepts/storage/volumes/#hostpath) - volumes. Except for initial creation, these credentials are not managed by - kubeadm. - -1. The self-hosted portion of the control plane does not include etcd, - which still runs as a static Pod. - -#### Process - -The self-hosting bootstrap process is documented in the [kubeadm design -document](https://github.com/kubernetes/kubeadm/blob/master/docs/design/design_v1.9.md#optional-self-hosting). - -In summary, `kubeadm alpha selfhosting` works as follows: - - 1. Waits for this bootstrap static control plane to be running and - healthy. This is identical to the `kubeadm init` process without self-hosting. - - 1. Uses the static control plane Pod manifests to construct a set of - DaemonSet manifests that will run the self-hosted control plane. - It also modifies these manifests where necessary, for example adding new volumes - for secrets. - - 1. Creates DaemonSets in the `kube-system` namespace and waits for the - resulting Pods to be running. - - 1. Once self-hosted Pods are operational, their associated static Pods are deleted - and kubeadm moves on to install the next component. This triggers kubelet to - stop those static Pods. - - 1. When the original static control plane stops, the new self-hosted control - plane is able to bind to listening ports and become active. - - diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm.md b/content/en/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm.md index 58f4f4652a..fc53228685 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm.md +++ b/content/en/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm.md @@ -153,7 +153,7 @@ Right after `kubeadm init` there should not be any pods in these states. MountFlags can interfere with volumes mounted by Kubernetes, and put the Pods in `CrashLoopBackOff` state. The error happens when Kubernetes does not find `var/run/secrets/kubernetes.io/serviceaccount` files. -## `coredns` (or `kube-dns`) is stuck in the `Pending` state +## `coredns` is stuck in the `Pending` state This is **expected** and part of the design. kubeadm is network provider-agnostic, so the admin should [install the pod network add-on](/docs/concepts/cluster-administration/addons/) diff --git a/content/en/docs/tasks/administer-cluster/controller-manager-leader-migration.md b/content/en/docs/tasks/administer-cluster/controller-manager-leader-migration.md new file mode 100644 index 0000000000..8b141f9da0 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/controller-manager-leader-migration.md @@ -0,0 +1,118 @@ +--- +reviewers: +- jpbetz +- cheftako +title: "Migrate Replicated Control Plane To Use Cloud Controller Manager" +linkTitle: "Migrate Replicated Control Plane To Use Cloud Controller Manager" +content_type: task +--- + + + + +{{< feature-state state="alpha" for_k8s_version="v1.21" >}} + +{{< glossary_definition term_id="cloud-controller-manager" length="all" prepend="The cloud-controller-manager is">}} + +## Background + +As part of the [cloud provider extraction effort](https://kubernetes.io/blog/2019/04/17/the-future-of-cloud-providers-in-kubernetes/), all cloud specific controllers must be moved out of the `kube-controller-manager`. All existing clusters that run cloud controllers in the `kube-controller-manager` must migrate to instead run the controllers in a cloud provider specific `cloud-controller-manager`. + +Leader Migration provides a mechanism in which HA clusters can safely migrate "cloud specific" controllers between the `kube-controller-manager` and the `cloud-controller-manager` via a shared resource lock between the two components while upgrading the replicated control plane. For a single-node control plane, or if unavailability of controller managers can be tolerated during the upgrade, Leader Migration is not needed and this guide can be ignored. + +Leader Migration is an alpha feature that is disabled by default and it requires `--enable-leader-migration` to be set on controller managers. It can be enabled by setting the feature gate `ControllerManagerLeaderMigration` plus `--enable-leader-migration` on `kube-controller-manager` or `cloud-controller-manager`. Leader Migration only applies during the upgrade and can be safely disabled or left enabled after the upgrade is complete. + +This guide walks you through the manual process of upgrading the control plane from `kube-controller-manager` with built-in cloud provider to running both `kube-controller-manager` and `cloud-controller-manager`. If you use a tool to administrator the cluster, please refer to the documentation of the tool and the cloud provider for more details. + +## {{% heading "prerequisites" %}} + +It is assumed that the control plane is running Kubernetes version N and to be upgraded to version N + 1. Although it is possible to migrate within the same version, ideally the migration should be performed as part of a upgrade so that changes of configuration can be aligned to releases. The exact versions of N and N + 1 depend on each cloud provider. For example, if a cloud provider builds a `cloud-controller-manager` to work with Kubernetes 1.22, then N can be 1.21 and N + 1 can be 1.22. + +The control plane nodes should run `kube-controller-manager` with Leader Election enabled through `--leader-elect=true`. As of version N, an in-tree cloud privider must be set with `--cloud-provider` flag and `cloud-controller-manager` should not yet be deployed. + +The out-of-tree cloud provider must have built a `cloud-controller-manager` with Leader Migration implmentation. If the cloud provider imports `k8s.io/cloud-provider` and `k8s.io/controller-manager` of version v0.21.0 or later, Leader Migration will be avaliable. + +This guide assumes that kubelet of each control plane node starts `kube-controller-manager` and `cloud-controller-manager` as static pods defined by their manifests. If the components run in a different setting, please adjust the steps accordingly. + +For authorization, this guide assumes that the cluser uses RBAC. If another authorization mode grants permissions to `kube-controller-manager` and `cloud-controller-manager` components, please grant the needed access in a way that matches the mode. + + + +### Grant access to Migration Lease + +The default permissions of the controller manager allow only accesses to their main Lease. In order for the migration to work, accesses to another Lease are required. + +You can grant `kube-controller-manager` full access to the leases API by modifying the `system::leader-locking-kube-controller-manager` role. This task guide assumes that the name of the migration lease is `cloud-provider-extraction-migration`. + +`kubectl patch -n kube-system role 'system::leader-locking-kube-controller-manager' -p '{"rules": [ {"apiGroups":[ "coordination.k8s.io"], "resources": ["leases"], "resourceNames": ["cloud-provider-extraction-migration"], "verbs": ["create", "list", "get", "update"] } ]}' --type=merge` + +Do the same to the `system::leader-locking-cloud-controller-manager` role. + +`kubectl patch -n kube-system role 'system::leader-locking-cloud-controller-manager' -p '{"rules": [ {"apiGroups":[ "coordination.k8s.io"], "resources": ["leases"], "resourceNames": ["cloud-provider-extraction-migration"], "verbs": ["create", "list", "get", "update"] } ]}' --type=merge` + +### Initial Leader Migration configuration + +Leader Migration requires a configuration file representing the state of controller-to-manager assignment. At this moment, with in-tree cloud provider, `kube-controller-manager` runs `route`, `service`, and `cloud-node-lifecycle`. The following example configuration shows the assignment. + +```yaml +kind: LeaderMigrationConfiguration +apiVersion: controllermanager.config.k8s.io/v1alpha1 +leaderName: cloud-provider-extraction-migration +resourceLock: leases +controllerLeaders: + - name: route + component: kube-controller-manager + - name: service + component: kube-controller-manager + - name: cloud-node-lifecycle + component: kube-controller-manager +``` + +On each control plane node, save the content to `/etc/leadermigration.conf`, and update the manifest of `kube-controller-manager` so that the file is mounted inside the container at the same location. Also, update the same manifest to add the following arguments: + +- `--feature-gates=ControllerManagerLeaderMigration=true` to enable Leader Migration which is an alpha feature +- `--enable-leader-migration` to enable Leader Migration on the controller manager +- `--leader-migration-config=/etc/leadermigration.conf` to set configuration file + +Restart `kube-controller-manager` on each node. At this moment, `kube-controller-manager` has leader migration enabled and is ready for the migration. + +### Deploy Cloud Controller Manager + +In version N + 1, the desired state of controller-to-manager assignment can be represented by a new configuration file, shown as follows. Please note `component` field of each `controllerLeaders` changing from `kube-controller-manager` to `cloud-controller-manager`. + +```yaml +kind: LeaderMigrationConfiguration +apiVersion: controllermanager.config.k8s.io/v1alpha1 +leaderName: cloud-provider-extraction-migration +resourceLock: leases +controllerLeaders: + - name: route + component: cloud-controller-manager + - name: service + component: cloud-controller-manager + - name: cloud-node-lifecycle + component: cloud-controller-manager +``` + +When creating control plane nodes of version N + 1, the content should be deploy to `/etc/leadermigration.conf`. The manifest of `cloud-controller-manager` should be updated to mount the configuration file in the same manner as `kube-controller-manager` of version N. Similarly, add `--feature-gates=ControllerManagerLeaderMigration=true`,`--enable-leader-migration`, and `--leader-migration-config=/etc/leadermigration.conf` to the arguments of `cloud-controller-manager`. + +Create a new control plane node of version N + 1 with the updated `cloud-controller-manager` manifest, and with the `--cloud-provider` flag unset for `kube-controller-manager`. `kube-controller-manager` of version N + 1 MUST NOT have Leader Migration enabled because, with an external cloud provider, it does not run the migrated controllers anymore and thus it is not involved in the migration. + +Please refer to [Cloud Controller Manager Administration](/docs/tasks/administer-cluster/running-cloud-controller/) for more detail on how to deploy `cloud-controller-manager`. + +### Upgrade Control Plane + +The control plane now contains nodes of both version N and N + 1. The nodes of version N run `kube-controller-manager` only, and these of version N + 1 run both `kube-controller-manager` and `cloud-controller-manager`. The migrated controllers, as specified in the configuration, are running under either `kube-controller-manager` of version N or `cloud-controller-manager` of version N + 1 depending on which controller manager holds the migration lease. No controller will ever be running under both controller managers at any time. + +In a rolling manner, create a new control plane node of version N + 1 and bring down one of version N + 1 until the control plane contains only nodes of version N + 1. +If a rollback from version N + 1 to N is required, add nodes of version N with Leader Migration enabled for `kube-controller-manager` back to the control plane, replacing one of version N + 1 each time until there are only nodes of version N. + +### (Optional) Disable Leader Migration {#disable-leader-migration} + +Now that the control plane has been upgraded to run both `kube-controller-manager` and `cloud-controller-manager` of version N + 1, Leader Migration has finished its job and can be safely disabled to save one Lease resource. It is safe to re-enable Leader Migration for the rollback in the future. + +In a rolling manager, update manifest of `cloud-controller-manager` to unset both `--enable-leader-migration` and `--leader-migration-config=` flag, also remove the mount of `/etc/leadermigration.conf`, and finally remove `/etc/leadermigration.conf`. To re-enable Leader Migration, recreate the configuration file and add its mount and the flags that enable Leader Migration back to `cloud-controller-manager`. + +## {{% heading "whatsnext" %}} + +- Read the [Controller Manager Leader Migration](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cloud-provider/2436-controller-manager-leader-migration) enhancement proposal diff --git a/content/en/docs/tasks/administer-cluster/coredns.md b/content/en/docs/tasks/administer-cluster/coredns.md index 32d4f7d7ec..54163058c8 100644 --- a/content/en/docs/tasks/administer-cluster/coredns.md +++ b/content/en/docs/tasks/administer-cluster/coredns.md @@ -36,7 +36,7 @@ For manual deployment or replacement of kube-dns, see the documentation at the In Kubernetes version 1.10 and later, you can also move to CoreDNS when you use `kubeadm` to upgrade a cluster that is using `kube-dns`. In this case, `kubeadm` will generate the CoreDNS configuration -("Corefile") based upon the `kube-dns` ConfigMap, preserving configurations for federation, +("Corefile") based upon the `kube-dns` ConfigMap, preserving configurations for stub domains, and upstream name server. If you are moving from kube-dns to CoreDNS, make sure to set the `CoreDNS` feature gate to `true` @@ -46,8 +46,7 @@ kubeadm upgrade apply v1.11.0 --feature-gates=CoreDNS=true ``` In Kubernetes version 1.13 and later the `CoreDNS` feature gate is removed and CoreDNS -is used by default. Follow the guide outlined [here](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase#cmd-phase-addon) if you want -your upgraded cluster to use kube-dns. +is used by default. In versions prior to 1.11 the Corefile will be **overwritten** by the one created during upgrade. **You should save your existing ConfigMap if you have customized it.** You may re-apply your @@ -56,26 +55,7 @@ customizations after the new ConfigMap is up and running. If you are running CoreDNS in Kubernetes version 1.11 and later, during upgrade, your existing Corefile will be retained. - -### Installing kube-dns instead of CoreDNS with kubeadm - -{{< note >}} -In Kubernetes 1.11, CoreDNS has graduated to General Availability (GA) -and is installed by default. -{{< /note >}} - -{{< warning >}} -In Kubernetes 1.18, kube-dns usage with kubeadm has been deprecated and will be removed in a future version. -{{< /warning >}} - -To install kube-dns on versions prior to 1.13, set the `CoreDNS` feature gate -value to `false`: - -``` -kubeadm init --feature-gates=CoreDNS=false -``` - -For versions 1.13 and later, follow the guide outlined [here](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase#cmd-phase-addon). +In Kubernetes version 1.21, support for `kube-dns` is removed from kubeadm. ## Upgrading CoreDNS diff --git a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md index 06de85b305..308b066651 100644 --- a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -34,7 +34,7 @@ As of Kubernetes v1.12, CoreDNS is the recommended DNS Server, replacing kube-dn originally used kube-dns, you may still have `kube-dns` deployed rather than CoreDNS. {{< note >}} -Both the CoreDNS and kube-dns Service are named `kube-dns` in the `metadata.name` field. +The CoreDNS Service is named `kube-dns` in the `metadata.name` field. This is so that there is greater interoperability with workloads that relied on the legacy `kube-dns` Service name to resolve addresses internal to the cluster. Using a Service named `kube-dns` abstracts away the implementation detail of which DNS provider is running behind that common name. {{< /note >}} @@ -179,17 +179,14 @@ During translation, all FQDN nameservers will be omitted from the CoreDNS config CoreDNS supports the features of kube-dns and more. A ConfigMap created for kube-dns to support `StubDomains`and `upstreamNameservers` translates to the `forward` plugin in CoreDNS. -Similarly, the `Federations` plugin in kube-dns translates to the `federation` plugin in CoreDNS. ### Example -This example ConfigMap for kube-dns specifies federations, stubdomains and upstreamnameservers: +This example ConfigMap for kube-dns specifies stubdomains and upstreamnameservers: ```yaml apiVersion: v1 data: - federations: | - {"foo" : "foo.feddomain.com"} stubDomains: | {"abc.com" : ["1.2.3.4"], "my.cluster.local" : ["2.3.4.5"]} upstreamNameservers: | @@ -199,13 +196,6 @@ kind: ConfigMap The equivalent configuration in CoreDNS creates a Corefile: -* For federations: -``` -federation cluster.local { - foo foo.feddomain.com -} -``` - * For stubDomains: ```yaml abc.com:53 { diff --git a/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md b/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md deleted file mode 100644 index d984652de8..0000000000 --- a/content/en/docs/tasks/administer-cluster/enabling-endpointslices.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -reviewers: -- bowei -- freehan -title: Enabling EndpointSlices -content_type: task ---- - - -This page provides an overview of enabling EndpointSlices in Kubernetes. - - - -## {{% heading "prerequisites" %}} - - {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - - - - -## Introduction - -EndpointSlices provide a scalable and extensible alternative to Endpoints in -Kubernetes. They build on top of the base of functionality provided by Endpoints -and extend that in a scalable way. When Services have a large number (>100) of -network endpoints, they will be split into multiple smaller EndpointSlice -resources instead of a single large Endpoints resource. - -## Enabling EndpointSlices - -{{< feature-state for_k8s_version="v1.17" state="beta" >}} - -{{< note >}} -The EndpointSlice resource was designed to address shortcomings in a earlier -resource: Endpoints. Some Kubernetes components and third-party applications -continue to use and rely on Endpoints. Whilst that remains the case, -EndpointSlices should be seen as an addition to Endpoints in a cluster, not as -an outright replacement. -{{< /note >}} - -EndpointSlice functionality in Kubernetes is made up of several different -components, most are enabled by default: -* _The EndpointSlice API_: EndpointSlices are part of the - `discovery.k8s.io/v1beta1` API. This is beta and enabled by default since - Kubernetes 1.17. All components listed below are dependent on this API being - enabled. -* _The EndpointSlice Controller_: This {{< glossary_tooltip text="controller" - term_id="controller" >}} maintains EndpointSlices for Services and the Pods - they reference. This is controlled by the `EndpointSlice` feature gate. It has - been enabled by default since Kubernetes 1.18. -* _The EndpointSliceMirroring Controller_: This {{< glossary_tooltip - text="controller" term_id="controller" >}} mirrors custom Endpoints to - EndpointSlices. This is controlled by the `EndpointSlice` feature gate. It has - been enabled by default since Kubernetes 1.19. -* _Kube-Proxy_: When {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy">}} - is configured to use EndpointSlices, it can support higher numbers of Service - endpoints. This is controlled by the `EndpointSliceProxying` feature gate on - Linux and `WindowsEndpointSliceProxying` on Windows. It has been enabled by - default on Linux since Kubernetes 1.19. It is not enabled by default for - Windows nodes. To configure kube-proxy to use EndpointSlices on Windows, you - can enable the `WindowsEndpointSliceProxying` [feature - gate](/docs/reference/command-line-tools-reference/feature-gates/) on - kube-proxy. - - -## API fields - -Some fields in the EndpointSlice API are feature-gated. - -- The `EndpointSliceNodeName` feature gate controls access to the `nodeName` - field. This is an alpha feature that is disabled by default. -- The `EndpointSliceTerminating` feature gate controls access to the `serving` - and `terminating` condition fields. This is an alpha feature that is disabled - by default. - -## Using EndpointSlices - -With EndpointSlices fully enabled in your cluster, you should see corresponding -EndpointSlice resources for each Endpoints resource. In addition to supporting -existing Endpoints functionality, EndpointSlices will allow for greater -scalability and extensibility of network endpoints in your cluster. - -## {{% heading "whatsnext" %}} - - -* Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) -* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) - - diff --git a/content/en/docs/tasks/administer-cluster/enabling-service-topology.md b/content/en/docs/tasks/administer-cluster/enabling-service-topology.md index 998bb8b2e5..8fd39a7e50 100644 --- a/content/en/docs/tasks/administer-cluster/enabling-service-topology.md +++ b/content/en/docs/tasks/administer-cluster/enabling-service-topology.md @@ -5,52 +5,51 @@ reviewers: - imroc title: Enabling Service Topology content_type: task +min-kubernetes-server-version: 1.17 --- -This page provides an overview of enabling Service Topology in Kubernetes. +{{< feature-state for_k8s_version="v1.21" state="deprecated" >}} +This feature, specifically the alpha `topologyKeys` field, is deprecated since +Kubernetes v1.21. +[Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), +introduced in Kubernetes v1.21, provide similar functionality. +_Service Topology_ enables a {{< glossary_tooltip term_id="service">}} to route traffic based upon the Node +topology of the cluster. For example, a service can specify that traffic be +preferentially routed to endpoints that are on the same Node as the client, or +in the same availability zone. ## {{% heading "prerequisites" %}} {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - - - -## Introduction - -_Service Topology_ enables a service to route traffic based upon the Node -topology of the cluster. For example, a service can specify that traffic be -preferentially routed to endpoints that are on the same Node as the client, or -in the same availability zone. - -## Prerequisites - The following prerequisites are needed in order to enable topology aware service routing: - * Kubernetes 1.17 or later - * {{< glossary_tooltip text="Kube-proxy" term_id="kube-proxy" >}} running in iptables mode or IPVS mode - * Enable [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/) + * Kubernetes v1.17 or later + * Configure {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to run in iptables mode or IPVS mode + + + ## Enable Service Topology -{{< feature-state for_k8s_version="v1.17" state="alpha" >}} +{{< feature-state for_k8s_version="v1.21" state="deprecated" >}} -To enable service topology, enable the `ServiceTopology` and `EndpointSlice` feature gate for all Kubernetes components: +To enable service topology, enable the `ServiceTopology` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) for all Kubernetes components: ``` ---feature-gates="ServiceTopology=true,EndpointSlice=true" +--feature-gates="ServiceTopology=true` ``` - ## {{% heading "whatsnext" %}} - -* Read about the [Service Topology](/docs/concepts/services-networking/service-topology) concept -* Read about [Endpoint Slices](/docs/concepts/services-networking/endpoint-slices) +* Read about [Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints/), the replacement for the `topologyKeys` field. +* Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) +* Read about the [Service Topology](/docs/concepts/services-networking/service-topology/) concept * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) diff --git a/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md b/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md new file mode 100644 index 0000000000..919f522c7c --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/enabling-topology-aware-hints.md @@ -0,0 +1,40 @@ +--- +reviewers: +- robscott +title: Enabling Topology Aware Hints +content_type: task +min-kubernetes-server-version: 1.21 +--- + + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +_Topology Aware Hints_ enable topology aware routing with topology hints +included in {{< glossary_tooltip text="EndpointSlices" term_id="endpoint-slice" >}}. +This approach tries to keep traffic close to where it originated from; +you might do this to reduce costs, or to improve network performance. + +## {{% heading "prerequisites" %}} + + {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +The following prerequisite is needed in order to enable topology aware hints: + +* Configure the {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}} to run in + iptables mode or IPVS mode +* Ensure that you have not disabled EndpointSlices + +## Enable Topology Aware Hints + +To enable service topology hints, enable the `TopologyAwareHints` [feature +gate](docs/reference/command-line-tools-reference/feature-gates/) for the +kube-apiserver, kube-controller-manager, and kube-proxy: + +``` +--feature-gates="TopologyAwareHints=true" +``` + +## {{% heading "whatsnext" %}} + +* Read about [Topology Aware Hints](/docs/concepts/services-networking/topology-aware-hints) for Services +* Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/configure-cgroup-driver.md b/content/en/docs/tasks/administer-cluster/kubeadm/configure-cgroup-driver.md new file mode 100644 index 0000000000..02fdc958fa --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/kubeadm/configure-cgroup-driver.md @@ -0,0 +1,127 @@ +--- +title: Configuring a cgroup driver +content_type: task +weight: 10 +--- + + + +This page explains how to configure the kubelet cgroup driver to match the container +runtime cgroup driver for kubeadm clusters. + +## {{% heading "prerequisites" %}} + +You should be familiar with the Kubernetes +[container runtime requirements](/docs/setup/production-environment/container-runtimes). + + + +## Configuring the container runtime cgroup driver + +The [Container runtimes](/docs/setup/production-environment/container-runtimes) page +explains that the `systemd` driver is recommended for kubeadm based setups instead +of the `cgroupfs` driver, because kubeadm manages the kubelet as a systemd service. + +The page also provides details on how to setup a number of different container runtimes with the +`systemd` driver by default. + +## Configuring the kubelet cgroup driver + +kubeadm allows you to pass a `KubeletConfiguration` structure during `kubeadm init`. +This `KubeletConfiguration` can include the `cgroupDriver` field which controls the cgroup +driver of the kubelet. + +{{< note >}} + +{{< feature-state for_k8s_version="v1.21" state="stable" >}} + +If the user is not setting the `cgroupDriver` field under `KubeletConfiguration`, +`kubeadm init` will default it to `systemd`. +{{< /note >}} + +A minimal example of configuring the field explicitly: + +```yaml +# kubeadm-config.yaml +kind: ClusterConfiguration +apiVersion: kubeadm.k8s.io/v1beta2 +kubernetesVersion: v1.21 +--- +kind: KubeletConfiguration +apiVersion: kubelet.config.k8s.io/v1beta1 +cgroupDriver: systemd +``` + +Such a configuration file can then be passed to the kubeadm command: + +```shell +kubeadm init --config kubeadm-config.yaml +``` + +{{< note >}} +Kubeadm uses the same `KubeletConfiguration` for all nodes in the cluster. +The `KubeletConfiguration` is stored in a [ConfigMap](docs/concepts/configuration/configmap) +object under the `kube-system` namespace. + +Executing the sub commands `init`, `join` and `upgrade` would result in kubeadm +writing the `KubeletConfiguration` as a file under `/var/lib/kubelet/config.yaml` +and passing it to the local node kubelet. +{{< /note >}} + +## Using the `cgroupfs` driver + +As this guide explains using the `cgroupfs` driver with kubeadm is not recommended. + +To continue using `cgroupfs` and to prevent `kubeadm upgrade` from modifying the +`KubeletConfiguration` cgroup driver on existing setups, you must be explicit +about its value. This applies to a case where you do not wish future versions +of kubeadm to apply the `systemd` driver by default. + +See the below section on "Modify the kubelet ConfigMap" for details on +how to be explicit about the value. + +If you wish to configure a container runtime to use the `cgroupfs` driver, +you must refer to the documentation of the container runtime of your choice. + +## Migrating to the `systemd` driver + +To change the cgroup driver of an existing kubeadm cluster to `systemd` in-place, +a similar procedure to a kubelet upgrade is required. This must include both +steps outlined below. + +{{< note >}} +Alternatively, it is possible to replace the old nodes in the cluster with new ones +that use the `systemd` driver. This requires executing only the first step below +before joining the new nodes and ensuring the workloads can safely move to the new +nodes before deleting the old nodes. +{{< /note >}} + +### Modify the kubelet ConfigMap + +- Find the kubelet ConfigMap name using `kubectl get cm -n kube-system | grep kubelet-config`. +- Call `kubectl edit cm kubelet-config-x.yy -n kube-system` (replace `x.yy` with +the Kubernetes version). +- Either modify the existing `cgroupDriver` value or add a new field that looks like this: + + ```yaml + cgroupDriver: systemd + ``` + This field must be present under the `kubelet:` section of the ConfigMap. + +### Update the cgroup driver on all nodes + +For each node in the cluster: + +- [Drain the node](/docs/tasks/administer-cluster/safely-drain-node) using `kubectl drain --ignore-daemonsets` +- Stop the kubelet using `systemctl stop kubelet` +- Stop the container runtime +- Modify the container runtime cgroup driver to `systemd` +- Set `cgroupDriver: systemd` in `/var/lib/kubelet/config.yaml` +- Start the container runtime +- Start the kubelet using `systemctl start kubelet` +- [Uncordon the node](/docs/tasks/administer-cluster/safely-drain-node) using `kubectl uncordon ` + +Execute these steps on nodes one at a time to ensure workloads +have sufficient time to schedule on different nodes. + +Once the process is complete ensure that all nodes and workloads are healthy. diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md index 47ea403e9a..da07ed672e 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md @@ -328,7 +328,7 @@ and post-upgrade manifest file for a certain component, a backup file for it wil - Makes sure the control plane images are available or available to pull to the machine. - Generates replacements and/or uses user supplied overwrites if component configs require version upgrades. - Upgrades the control plane components or rollbacks if any of them fails to come up. -- Applies the new `kube-dns` and `kube-proxy` manifests and makes sure that all necessary RBAC rules are created. +- Applies the new `CoreDNS` and `kube-proxy` manifests and makes sure that all necessary RBAC rules are created. - Creates new certificate and key files of the API server and backs up old files if they're about to expire in 180 days. `kubeadm upgrade node` does the following on additional control plane nodes: diff --git a/content/en/docs/tasks/administer-cluster/memory-manager.md b/content/en/docs/tasks/administer-cluster/memory-manager.md new file mode 100644 index 0000000000..60f2ded206 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/memory-manager.md @@ -0,0 +1,380 @@ +--- +title: Memory Manager + +reviewers: +- klueska +- derekwaynecarr + +content_type: task +min-kubernetes-server-version: v1.21 +--- + + + +{{< feature-state state="alpha" for_k8s_version="v1.21" >}} + +The Kubernetes *Memory Manager* enables the feature of guaranteed memory (and hugepages) allocation for pods in the `Guaranteed` {{< glossary_tooltip text="QoS class" term_id="qos-class" >}}. + +The Memory Manager employs hint generation protocol to yield the most suitable NUMA affinity for a pod. The Memory Manager feeds the central manager (*Topology Manager*) with these affinity hints. Based on both the hints and Topology Manager policy, the pod is rejected or admitted to the node. + +Moreover, the Memory Manager ensures that the memory which a pod requests is allocated from a minimum number of NUMA nodes. + +The Memory Manager is only pertinent to Linux based hosts. + +## {{% heading "prerequisites" %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +To align memory resources with other requested resources in a Pod Spec: +- the CPU Manager should be enabled and proper CPU Manager policy should be configured on a Node. See [control CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/); +- the Topology Manager should be enabled and proper Topology Manager policy should be configured on a Node. See [control Topology Management Policies](/docs/tasks/administer-cluster/topology-manager/). + +Support for the Memory Manager requires `MemoryManager` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. + +That is, the `kubelet` must be started with the following flag: + +`--feature-gates=MemoryManager=true` + +## How Memory Manager Operates? + +The Memory Manager currently offers the guaranteed memory (and hugepages) allocation for Pods in Guaranteed QoS class. To immediately put the Memory Manager into operation follow the guidelines in the section [Memory Manager configuration](#memory-manager-configuration), and subsequently, prepare and deploy a `Guaranteed` pod as illustrated in the section [Placing a Pod in the Guaranteed QoS class](#placing-a-pod-in-the-guaranteed-qos-class). + +The Memory Manager is a Hint Provider, and it provides topology hints for the Topology Manager which then aligns the requested resources according to these topology hints. It also enforces `cgroups` (i.e. `cpuset.mems`) for pods. The complete flow diagram concerning pod admission and deployment process is illustrated in [Memory Manager KEP: Design Overview][4] and below: + +![Memory Manager in the pod admission and deployment process](/images/docs/memory-manager-diagram.svg) + +During this process, the Memory Manager updates its internal counters stored in [Node Map and Memory Maps][2] to manage guaranteed memory allocation. + +The Memory Manager updates the Node Map during the startup and runtime as follows. + +### Startup + +This occurs once a node administrator employs `--reserved-memory` (section [Reserved memory flag](#reserved-memory-flag)). In this case, the Node Map becomes updated to reflect this reservation as illustrated in [Memory Manager KEP: Memory Maps at start-up (with examples)][5]. + +The administrator must provide `--reserved-memory` flag when `static` policy is configured. + +### Runtime + +Reference [Memory Manager KEP: Memory Maps at runtime (with examples)][6] illustrates how a successful pod deployment affects the Node Map, and it also relates to how potential Out-of-Memory (OOM) situations are handled further by Kubernetes or operating system. + +Important topic in the context of Memory Manager operation is the management of NUMA groups. Each time pod's memory request is in excess of single NUMA node capacity, the Memory Manager attempts to create a group that comprises several NUMA nodes and features extend memory capacity. The problem has been solved as elaborated in [Memory Manager KEP: How to enable the guaranteed memory allocation over many NUMA nodes?][3]. Also, reference [Memory Manager KEP: Simulation - how the Memory Manager works? (by examples)][1] illustrates how the management of groups occurs. + +## Memory Manager configuration + +Other Managers should be first pre-configured (section [Pre-configuration](#pre-configuration)). Next, the Memory Manger feature should be enabled (section [Enable the Memory Manager feature](#enable-the-memory-manager-feature)) and be run with `static` policy (section [static policy](#static-policy)). Optionally, some amount of memory can be reserved for system or kubelet processes to increase node stability (section [Reserved memory flag](#reserved-memory-flag)). + +### Policies + +Memory Manager supports two policies. You can select a policy via a `kubelet` flag `--memory-manager-policy`. + +Two policies can be selected: + +* `none` (default) +* `static` + +#### none policy {#policy-none} + +This is the default policy and does not affect the memory allocation in any way. +It acts the same as if the Memory Manager is not present at all. + +The `none` policy returns default topology hint. This special hint denotes that Hint Provider (Memory Manger in this case) has no preference for NUMA affinity with any resource. + +#### static policy {#policy-static} + +In the case of the `Guaranteed` pod, the `static` Memory Manger policy returns topology hints relating to the set of NUMA nodes where the memory can be guaranteed, and reserves the memory through updating the internal [NodeMap][2] object. + +In the case of the `BestEffort` or `Burstable` pod, the `static` Memory Manager policy sends back the default topology hint as there is no request for the guaranteed memory, and does not reserve the memory in the internal [NodeMap][2] object. + +### Reserved memory flag + +The [Node Allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/) mechanism is commonly used by node administrators to reserve K8S node system resources for the kubelet or operating system processes in order to enhance the node stability. A dedicated set of flags can be used for this purpose to set the total amount of reserved memory for a node. This pre-configured value is subsequently utilized to calculate the real amount of node's "allocatable" memory available to pods. + +The Kubernetes scheduler incorporates "allocatable" to optimise pod scheduling process. The foregoing flags include `--kube-reserved`, `--system-reserved` and `--eviction-threshold`. The sum of their values will account for the total amount of reserved memory. + + +A new `--reserved-memory` flag was added to Memory Manager to allow for this total reserved memory to be split (by a node administrator) and accordingly reserved across many NUMA nodes. + +The flag specifies a comma-separated list of memory reservations per NUMA node. +This parameter is only useful in the context of the Memory Manager feature. +The Memory Manager will not use this reserved memory for the allocation of container workloads. + +For example, if you have a NUMA node "NUMA0" with `10Gi` of memory available, and the `--reserved-memory` was specified to reserve `1Gi` of memory at "NUMA0", the Memory Manager assumes that only `9Gi` is available for containers. + +You can omit this parameter, however, you should be aware that the quantity of reserved memory from all NUMA nodes should be equal to the quantity of memory specified by the [Node Allocatable feature](/docs/tasks/administer-cluster/reserve-compute-resources/). If at least one node allocatable parameter is non-zero, you will need to specify `--reserved-memory` for at least one NUMA node. In fact, `eviction-hard` threshold value is equal to `100Mi` by default, so if `static` policy is used, `--reserved-memory` is obligatory. + +Also, avoid the following configurations: +1. duplicates, i.e. the same NUMA node or memory type, but with a different value; +2. setting zero limit for any of memory types; +3. NUMA node IDs that do not exist in the machine hardware; +4. memory type names different than `memory` or `hugepages-` (hugepages of particular `` should also exist). + +Syntax: + +`--reserved-memory N:memory-type1=value1,memory-type2=value2,...` +* `N` (integer) - NUMA node index, e.g. `0` +* `memory-type` (string) - represents memory type: + * `memory` - conventional memory + * `hugepages-2Mi` or `hugepages-1Gi` - hugepages +* `value` (string) - the quantity of reserved memory, e.g. `1Gi` + +Example usage: + +`--reserved-memory 0:memory=1Gi,hugepages-1Gi=2Gi` + +or + +`--reserved-memory 0:memory=1Gi --reserved-memory 1:memory=2Gi` + +When you specify values for `--reserved-memory` flag, you must comply with the setting that you prior provided via Node Allocatable Feature flags. That is, the following rule must be obeyed for each memory type: + +`sum(reserved-memory(i)) = kube-reserved + system-reserved + eviction-threshold`, + +where `i` is an index of a NUMA node. + +If you do not follow the formula above, the Memory Manager will show an error on startup. + +In other words, the example above illustrates that for the conventional memory (`type=memory`), we reserve `3Gi` in total, i.e.: + +`sum(reserved-memory(i)) = reserved-memory(0) + reserved-memory(1) = 1Gi + 2Gi = 3Gi` + +An example of kubelet command-line arguments relevant to the node Allocatable configuration: +* `--kube-reserved=cpu=500m,memory=50Mi` +* `--system-reserved=cpu=123m,memory=333Mi` +* `--eviction-hard=memory.available<500Mi` + +{{< note >}} +The default hard eviction threshold is 100MiB, and **not** zero. Remember to increase the quantity of memory that you reserve by setting `--reserved-memory` by that hard eviction threshold. Otherwise, the kubelet will not start Memory Manager and display an error. +{{< /note >}} + +Here is an example of a correct configuration: + +```shell +--feature-gates=MemoryManager=true +--kube-reserved=cpu=4,memory=4Gi +--system-reserved=cpu=1,memory=1Gi +--memory-manager-policy=static +--reserved-memory 0:memory=3Gi --reserved-memory 1:memory=2148Mi +``` +Let us validate the configuration above: +1. `kube-reserved + system-reserved + eviction-hard(default) = reserved-memory(0) + reserved-memory(1)` +2. `4GiB + 1GiB + 100MiB = 3GiB + 2148MiB` +3. `5120MiB + 100MiB = 3072MiB + 2148MiB` +4. `5220MiB = 5220MiB` (which is correct) + +## Placing a Pod in the Guaranteed QoS class + +If the selected policy is anything other than `none`, the Memory Manager identifies pods that are in the `Guaranteed` QoS class. The Memory Manager provides specific topology hints to the Topology Manager for each `Guaranteed` pod. For pods in a QoS class other than `Guaranteed`, the Memory Manager provides default topology hints to the Topology Manager. + +The following excerpts from pod manifests assign a pod to the `Guaranteed` QoS class. + +Pod with integer CPU(s) runs in the `Guaranteed` QoS class, when `requests` are equal to `limits`: + +```yaml +spec: + containers: + - name: nginx + image: nginx + resources: + limits: + memory: "200Mi" + cpu: "2" + example.com/device: "1" + requests: + memory: "200Mi" + cpu: "2" + example.com/device: "1" +``` + +Also, a pod sharing CPU(s) runs in the `Guaranteed` QoS class, when `requests` are equal to `limits`. + +```yaml +spec: + containers: + - name: nginx + image: nginx + resources: + limits: + memory: "200Mi" + cpu: "300m" + example.com/device: "1" + requests: + memory: "200Mi" + cpu: "300m" + example.com/device: "1" +``` + +Notice that both CPU and memory requests must be specified for a Pod to lend it to Guaranteed QoS class. + +## Troubleshooting + +The following means can be used to troubleshoot the reason why a pod could not be deployed or became rejected at a node: +- pod status - indicates topology affinity errors +- system logs - include valuable information for debugging, e.g., about generated hints +- state file - the dump of internal state of the Memory Manager (includes [Node Map and Memory Maps][2]) + +### Pod status (TopologyAffinityError) {#TopologyAffinityError} + +This error typically occurs in the following situations: +* a node has not enough resources available to satisfy the pod's request +* the pod's request is rejected due to particular Topology Manager policy constraints + +The error appears in the status of a pod: +```shell +# kubectl get pods +NAME READY STATUS RESTARTS AGE +guaranteed 0/1 TopologyAffinityError 0 113s +``` + +Use `kubectl describe pod ` or `kubectl get events` to obtain detailed error message: +```shell +Warning TopologyAffinityError 10m kubelet, dell8 Resources cannot be allocated with Topology locality +``` + +### System logs + +Search system logs with respect to a particular pod. + +The set of hints that Memory Manager generated for the pod can be found in the logs. +Also, the set of hints generated by CPU Manager should be present in the logs. + +Topology Manager merges these hints to calculate a single best hint. +The best hint should be also present in the logs. + +The best hint indicates where to allocate all the resources. Topology Manager tests this hint against its current policy, and based on the verdict, it either admits the pod to the node or rejects it. + +Also, search the logs for occurrences associated with the Memory Manager, e.g. to find out information about `cgroups` and `cpuset.mems` updates. + +### Examine the memory manager state on a node + +Let us first deploy a sample `Guaranteed` pod whose specification is as follows: +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: guaranteed +spec: + containers: + - name: guaranteed + image: consumer + imagePullPolicy: Never + resources: + limits: + cpu: "2" + memory: 150Gi + requests: + cpu: "2" + memory: 150Gi + command: ["sleep","infinity"] +``` + +Next, let us log into the node where it was deployed and examine the state file in `/var/lib/kubelet/memory_manager_state`: +```json +{ + "policyName":"static", + "machineState":{ + "0":{ + "numberOfAssignments":1, + "memoryMap":{ + "hugepages-1Gi":{ + "total":0, + "systemReserved":0, + "allocatable":0, + "reserved":0, + "free":0 + }, + "memory":{ + "total":134987354112, + "systemReserved":3221225472, + "allocatable":131766128640, + "reserved":131766128640, + "free":0 + } + }, + "nodes":[ + 0, + 1 + ] + }, + "1":{ + "numberOfAssignments":1, + "memoryMap":{ + "hugepages-1Gi":{ + "total":0, + "systemReserved":0, + "allocatable":0, + "reserved":0, + "free":0 + }, + "memory":{ + "total":135286722560, + "systemReserved":2252341248, + "allocatable":133034381312, + "reserved":29295144960, + "free":103739236352 + } + }, + "nodes":[ + 0, + 1 + ] + } + }, + "entries":{ + "fa9bdd38-6df9-4cf9-aa67-8c4814da37a8":{ + "guaranteed":[ + { + "numaAffinity":[ + 0, + 1 + ], + "type":"memory", + "size":161061273600 + } + ] + } + }, + "checksum":4142013182 +} +``` + +It can be deduced from the state file that the pod was pinned to both NUMA nodes, i.e.: + +```json +"numaAffinity":[ + 0, + 1 +], +``` + +Pinned term means that pod's memory consumption is constrained (through `cgroups` configuration) to these NUMA nodes. + +This automatically implies that Memory Manager instantiated a new group that comprises these two NUMA nodes, i.e. `0` and `1` indexed NUMA nodes. + +Notice that the management of groups is handled in a relatively complex manner, and further elaboration is provided in Memory Manager KEP in [this][1] and [this][3] sections. + +In order to analyse memory resources available in a group, the corresponding entries from NUMA nodes belonging to the group must be added up. + +For example, the total amount of free "conventional" memory in the group can be computed by adding up the free memory available at every NUMA node in the group, i.e., in the `"memory"` section of NUMA node `0` (`"free":0`) and NUMA node `1` (`"free":103739236352`). So, the total amount of free "conventional" memory in this group is equal to `0 + 103739236352` bytes. + +The line `"systemReserved":3221225472` indicates that the administrator of this node reserved `3221225472` bytes (i.e. `3Gi`) to serve kubelet and system processes at NUMA node `0`, by using `--reserved-memory` flag. + +## {{% heading "whatsnext" %}} + +- [Memory Manager KEP: Design Overview][4] + +- [Memory Manager KEP: Memory Maps at start-up (with examples)][5] + +- [Memory Manager KEP: Memory Maps at runtime (with examples)][6] + +- [Memory Manager KEP: Simulation - how the Memory Manager works? (by examples)][1] + +- [Memory Manager KEP: The Concept of Node Map and Memory Maps][2] + +- [Memory Manager KEP: How to enable the guaranteed memory allocation over many NUMA nodes?][3] + +[1]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/1769-memory-manager#simulation---how-the-memory-manager-works-by-examples +[2]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/1769-memory-manager#the-concept-of-node-map-and-memory-maps +[3]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/1769-memory-manager#how-to-enable-the-guaranteed-memory-allocation-over-many-numa-nodes +[4]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/1769-memory-manager#design-overview +[5]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/1769-memory-manager#memory-maps-at-start-up-with-examples +[6]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/1769-memory-manager#memory-maps-at-runtime-with-examples diff --git a/content/en/docs/tasks/administer-cluster/sysctl-cluster.md b/content/en/docs/tasks/administer-cluster/sysctl-cluster.md index 60af560e30..f81623982f 100644 --- a/content/en/docs/tasks/administer-cluster/sysctl-cluster.md +++ b/content/en/docs/tasks/administer-cluster/sysctl-cluster.md @@ -6,19 +6,20 @@ content_type: task --- -{{< feature-state for_k8s_version="v1.12" state="beta" >}} + +{{< feature-state for_k8s_version="v1.21" state="stable" >}} This document describes how to configure and use kernel parameters within a Kubernetes cluster using the {{< glossary_tooltip term_id="sysctl" >}} interface. - - ## {{% heading "prerequisites" %}} -{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} +{{< include "task-tutorial-prereqs.md" >}} +For some steps, you also need to be able to reconfigure the command line +options for the kubelets running on your cluster. @@ -166,6 +167,8 @@ to schedule those pods onto the right nodes. ## PodSecurityPolicy +{{< feature-state for_k8s_version="v1.21" state="deprecated" >}} + You can further control which sysctls can be set in pods by specifying lists of sysctls or sysctl patterns in the `forbiddenSysctls` and/or `allowedUnsafeSysctls` fields of the PodSecurityPolicy. A sysctl pattern ends diff --git a/content/en/docs/tasks/administer-cluster/topology-manager.md b/content/en/docs/tasks/administer-cluster/topology-manager.md index 7d3f017940..e8d2e7c19d 100644 --- a/content/en/docs/tasks/administer-cluster/topology-manager.md +++ b/content/en/docs/tasks/administer-cluster/topology-manager.md @@ -69,6 +69,10 @@ Details on the various `scopes` and `policies` available today can be found belo To align CPU resources with other requested resources in a Pod Spec, the CPU Manager should be enabled and proper CPU Manager policy should be configured on a Node. See [control CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/). {{< /note >}} +{{< note >}} +To align memory (and hugepages) resources with other requested resources in a Pod Spec, the Memory Manager should be enabled and proper Memory Manager policy should be configured on a Node. Examine [Memory Manager](/docs/tasks/administer-cluster/memory-manager/) documentation. +{{< /note >}} + ### Topology Manager Scopes The Topology Manager can deal with the alignment of resources in a couple of distinct scopes: @@ -263,8 +267,4 @@ Using this information the Topology Manager calculates the optimal hint for the ### Known Limitations 1. The maximum number of NUMA nodes that Topology Manager allows is 8. With more than 8 NUMA nodes there will be a state explosion when trying to enumerate the possible NUMA affinities and generating their hints. -2. The scheduler is not topology-aware, so it is possible to be scheduled on a node and then fail on the node due to the Topology Manager. - -3. The Device Manager and the CPU Manager are the only components to adopt the Topology Manager's HintProvider interface. This means that NUMA alignment can only be achieved for resources managed by the CPU Manager and the Device Manager. Memory or Hugepages are not considered by the Topology Manager for NUMA alignment. - - +2. The scheduler is not topology-aware, so it is possible to be scheduled on a node and then fail on the node due to the Topology Manager. \ No newline at end of file diff --git a/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md b/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md index 918a5bf33e..f8ebea0963 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md +++ b/content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md @@ -427,7 +427,48 @@ For a TCP probe, the kubelet makes the probe connection at the node, not in the means that you can not use a service name in the `host` parameter since the kubelet is unable to resolve it. +### Probe-level `terminationGracePeriodSeconds` +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + +Prior to release 1.21, the pod-level `terminationGracePeriodSeconds` was used +for terminating a container that failed its liveness or startup probe. This +coupling was unintended and may have resulted in failed containers taking an +unusually long time to restart when a pod-level `terminationGracePeriodSeconds` +was set. + +In 1.21, when the feature flag `ProbeTerminationGracePeriod` is enabled, users +can specify a probe-level `terminationGracePeriodSeconds` as part of the probe +specification. When the feature flag is enabled, and both a pod- and +probe-level `terminationGracePeriodSeconds` are set, the kubelet will use the +probe-level value. + +For example, + +```yaml +spec: + terminationGracePeriodSeconds: 3600 # pod-level + containers: + - name: test + image: ... + + ports: + - name: liveness-port + containerPort: 8080 + hostPort: 8080 + + livenessProbe: + httpGet: + path: /healthz + port: liveness-port + failureThreshold: 1 + periodSeconds: 60 + # Override pod-level terminationGracePeriodSeconds # + terminationGracePeriodSeconds: 60 +``` + +Probe-level `terminationGracePeriodSeconds` cannot be set for readiness probes. +It will be rejected by the API server. ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/tasks/configure-pod-container/configure-service-account.md b/content/en/docs/tasks/configure-pod-container/configure-service-account.md index d96a5c8270..23a76f3752 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-service-account.md +++ b/content/en/docs/tasks/configure-pod-container/configure-service-account.md @@ -323,11 +323,10 @@ The application is responsible for reloading the token when it rotates. Periodic ## Service Account Issuer Discovery -{{< feature-state for_k8s_version="v1.20" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} -The Service Account Issuer Discovery feature is enabled by enabling the -`ServiceAccountIssuerDiscovery` [feature gate](/docs/reference/command-line-tools-reference/feature-gates) -and then enabling the Service Account Token Projection feature as described +The Service Account Issuer Discovery feature is enabled when the Service Account +Token Projection feature is enabled, as described [above](#service-account-token-volume-projection). {{< note >}} @@ -349,8 +348,8 @@ Configuration document at `/.well-known/openid-configuration` and the associated JSON Web Key Set (JWKS) at `/openid/v1/jwks`. The OpenID Provider Configuration is sometimes referred to as the _discovery document_. -When enabled, the cluster is also configured with a default RBAC ClusterRole -called `system:service-account-issuer-discovery`. No role bindings are provided +Clusters include a default RBAC ClusterRole called +`system:service-account-issuer-discovery`. No role bindings are provided by default. Administrators may, for example, choose whether to bind the role to `system:authenticated` or `system:unauthenticated` depending on their security requirements and which external systems they intend to federate with. diff --git a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md index 693e730a09..26c7c91134 100644 --- a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md +++ b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md @@ -1,6 +1,6 @@ --- title: Running Automated Tasks with a CronJob -min-kubernetes-server-version: v1.8 +min-kubernetes-server-version: v1.21 reviewers: - chenopis content_type: task @@ -9,6 +9,10 @@ weight: 10 +CronJobs was promoted to general availability in Kubernetes v1.21. If you are using an older version of +Kubernetes, please refer to the documentation for the version of Kubernetes that you are using, +so that you see accurate information. Older Kubernetes versions do not support the `batch/v1` CronJob API. + You can use a {{< glossary_tooltip text="CronJob" term_id="cronjob" >}} to run {{< glossary_tooltip text="Jobs" term_id="job" >}} on a time-based schedule. These automated jobs run like [Cron](https://en.wikipedia.org/wiki/Cron) tasks on a Linux or UNIX system. @@ -170,13 +174,12 @@ After the deadline, the cron job does not start the job. Jobs that do not meet their deadline in this way count as failed jobs. If this field is not specified, the jobs have no deadline. -The CronJob controller counts how many missed schedules happen for a cron job. If there are more than 100 missed schedules, the cron job is no longer scheduled. When `.spec.startingDeadlineSeconds` is not set, the CronJob controller counts missed schedules from `status.lastScheduleTime` until now. +If the `.spec.startingDeadlineSeconds` field is set (not null), the CronJob +controller measures the time between when a job is expected to be created and +now. If the difference is higher than that limit, it will skip this execution. -For example, one cron job is supposed to run every minute, the `status.lastScheduleTime` of the cronjob is 5:00am, but now it's 7:00am. That means 120 schedules were missed, so the cron job is no longer scheduled. - -If the `.spec.startingDeadlineSeconds` field is set (not null), the CronJob controller counts how many missed jobs occurred from the value of `.spec.startingDeadlineSeconds` until now. - -For example, if it is set to `200`, it counts how many missed schedules occurred in the last 200 seconds. In that case, if there were more than 100 missed schedules in the last 200 seconds, the cron job is no longer scheduled. +For example, if it is set to `200`, it allows a job to be created for up to 200 +seconds after the actual schedule. ### Concurrency Policy diff --git a/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md b/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md index 62ddf56aab..2db5d3ecc3 100644 --- a/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md +++ b/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md @@ -2,7 +2,7 @@ title: Coarse Parallel Processing Using a Work Queue min-kubernetes-server-version: v1.8 content_type: task -weight: 30 +weight: 20 --- diff --git a/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md b/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md index 268eed7f9b..c5d1d0fa30 100644 --- a/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md +++ b/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md @@ -2,7 +2,7 @@ title: Fine Parallel Processing Using a Work Queue content_type: task min-kubernetes-server-version: v1.8 -weight: 40 +weight: 30 --- diff --git a/content/en/docs/tasks/job/indexed-parallel-processing-static.md b/content/en/docs/tasks/job/indexed-parallel-processing-static.md new file mode 100644 index 0000000000..08ada55471 --- /dev/null +++ b/content/en/docs/tasks/job/indexed-parallel-processing-static.md @@ -0,0 +1,190 @@ +--- +title: Indexed Job for Parallel Processing with Static Work Assignment +content_type: task +min-kubernetes-server-version: v1.21 +weight: 30 +--- + +{{< feature-state for_k8s_version="v1.21" state="alpha" >}} + + + + +In this example, you will run a Kubernetes Job that uses multiple parallel +worker processes. +Each worker is a different container running in its own Pod. The Pods have an +_index number_ that the control plane sets automatically, which allows each Pod +to identify which part of the overall task to work on. + +The pod index is available in the {{< glossary_tooltip text="annotation" term_id="annotation" >}} +`batch.kubernetes.io/job-completion-index` as a string representing its +decimal value. In order for the containerized task process to obtain this index, +you can publish the value of the annotation using the [downward API](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#the-downward-api) +mechanism. +For convenience, the control plane automatically sets the downward API to +expose the index in the `JOB_COMPLETION_INDEX` environment variable. + +Here is an overview of the steps in this example: + +1. **Define a Job manifest using indexed completion**. + The downward API allows you to pass the pod index annotation as an + environment variable or file to the container. +2. **Start an `Indexed` Job based on that manifest**. + +## {{% heading "prerequisites" %}} + +You should already be familiar with the basic, +non-parallel, use of [Job](/docs/concepts/workloads/controllers/job/). + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +To be able to create Indexed Jobs, make sure to enable the `IndexedJob` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +on the [API server](docs/reference/command-line-tools-reference/kube-apiserver/) +and the [controller manager](/docs/reference/command-line-tools-reference/kube-controller-manager/). + + + +## Choose an approach + +To access the work item from the worker program, you have a few options: + +1. Read the `JOB_COMPLETION_INDEX` environment variable. The Job + {{< glossary_tooltip text="controller" term_id="controller" >}} + automatically links this variable to the annotation containing the completion + index. +1. Read a file that contains the completion index. +1. Assuming that you can't modify the program, you can wrap it with a script + that reads the index using any of the methods above and converts it into + something that the program can use as input. + +For this example, imagine that you chose option 3 and you want to run the +[rev](https://man7.org/linux/man-pages/man1/rev.1.html) utility. This +program accepts a file as an argument and prints its content reversed. + +```shell +rev data.txt +``` + +You'll use the `rev` tool from the +[`busybox`](https://hub.docker.com/_/busybox) container image. + +As this is only an example, each Pod only does a tiny piece of work (reversing a short +string). In a real workload you might, for example, create a Job that represents + the +task of producing 60 seconds of video based on scene data. +Each work item in the video rendering Job would be to render a particular +frame of that video clip. Indexed completion would mean that each Pod in +the Job knows which frame to render and publish, by counting frames from +the start of the clip. + +## Define an Indexed Job + +Here is a sample Job manifest that uses `Indexed` completion mode: + +{{< codenew language="yaml" file="application/job/indexed-job.yaml" >}} + +In the example above, you use the builtin `JOB_COMPLETION_INDEX` environment +variable set by the Job controller for all containers. An [init container](/docs/concepts/workloads/pods/init-containers/) +maps the index to a static value and writes it to a file that is shared with the +container running the worker through an [emptyDir volume](/docs/concepts/storage/volumes/#emptydir). +Optionally, you can [define your own environment variable through the downward +API](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/) +to publish the index to containers. You can also choose to load a list of values +from a [ConfigMap as an environment variable or file](/docs/tasks/configure-pod-container/configure-pod-configmap/). + +Alternatively, you can directly [use the downward API to pass the annotation +value as a volume file](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#store-pod-fields), +like shown in the following example: + +{{< codenew language="yaml" file="application/job/indexed-job-vol.yaml" >}} + +## Running the Job + +Now run the Job: + +```shell +# This uses the first approach (relying on $JOB_COMPLETION_INDEX) +kubectl apply -f https://kubernetes.io/examples/application/job/indexed-job.yaml +``` + +When you create this Job, the control plane creates a series of Pods, one for each index you specified. The value of `.spec.parallelism` determines how many can run at once whereas `.spec.completions` determines how many Pods the Job creates in total. + +Because `.spec.parallelism` is less than `.spec.completions`, the control plane waits for some of the first Pods to complete before starting more of them. + +Once you have created the Job, wait a moment then check on progress: + +```shell +kubectl describe jobs/indexed-job +``` + +The output is similar to: + +``` +Name: indexed-job +Namespace: default +Selector: controller-uid=bf865e04-0b67-483b-9a90-74cfc4c3e756 +Labels: controller-uid=bf865e04-0b67-483b-9a90-74cfc4c3e756 + job-name=indexed-job +Annotations: +Parallelism: 3 +Completions: 5 +Start Time: Thu, 11 Mar 2021 15:47:34 +0000 +Pods Statuses: 2 Running / 3 Succeeded / 0 Failed +Completed Indexes: 0-2 +Pod Template: + Labels: controller-uid=bf865e04-0b67-483b-9a90-74cfc4c3e756 + job-name=indexed-job + Init Containers: + input: + Image: docker.io/library/bash + Port: + Host Port: + Command: + bash + -c + items=(foo bar baz qux xyz) + echo ${items[$JOB_COMPLETION_INDEX]} > /input/data.txt + + Environment: + Mounts: + /input from input (rw) + Containers: + worker: + Image: docker.io/library/busybox + Port: + Host Port: + Command: + rev + /input/data.txt + Environment: + Mounts: + /input from input (rw) + Volumes: + input: + Type: EmptyDir (a temporary directory that shares a pod's lifetime) + Medium: + SizeLimit: +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulCreate 4s job-controller Created pod: indexed-job-njkjj + Normal SuccessfulCreate 4s job-controller Created pod: indexed-job-9kd4h + Normal SuccessfulCreate 4s job-controller Created pod: indexed-job-qjwsz + Normal SuccessfulCreate 1s job-controller Created pod: indexed-job-fdhq5 + Normal SuccessfulCreate 1s job-controller Created pod: indexed-job-ncslj +``` + +In this example, you run the Job with custom values for each index. You can +inspect the output of one of the pods: + +```shell +kubectl logs indexed-job-fdhq5 # Change this to match the name of a Pod from that Job +``` + + +The output is similar to: + +``` +xuq +``` \ No newline at end of file diff --git a/content/en/docs/tasks/job/parallel-processing-expansion.md b/content/en/docs/tasks/job/parallel-processing-expansion.md index 8f5994929e..fdd309cafb 100644 --- a/content/en/docs/tasks/job/parallel-processing-expansion.md +++ b/content/en/docs/tasks/job/parallel-processing-expansion.md @@ -2,7 +2,7 @@ title: Parallel Processing using Expansions content_type: task min-kubernetes-server-version: v1.8 -weight: 20 +weight: 50 --- diff --git a/content/en/docs/tasks/run-application/configure-pdb.md b/content/en/docs/tasks/run-application/configure-pdb.md index 3823cac4ee..3110c2f807 100644 --- a/content/en/docs/tasks/run-application/configure-pdb.md +++ b/content/en/docs/tasks/run-application/configure-pdb.md @@ -2,11 +2,12 @@ title: Specifying a Disruption Budget for your Application content_type: task weight: 110 +min-kubernetes-server-version: v1.21 --- -{{< feature-state for_k8s_version="v1.5" state="beta" >}} +{{< feature-state for_k8s_version="v1.21" state="stable" >}} This page shows how to limit the number of concurrent disruptions that your application experiences, allowing for higher availability @@ -17,6 +18,8 @@ nodes. ## {{% heading "prerequisites" %}} +{{< version-check >}} + * You are the owner of an application running on a Kubernetes cluster that requires high availability. * You should know how to deploy [Replicated Stateless Applications](/docs/tasks/run-application/run-stateless-application-deployment/) @@ -112,9 +115,9 @@ of the number of pods from that set that can be unavailable after the eviction. It can be either an absolute number or a percentage. {{< note >}} -For versions 1.8 and earlier: When creating a `PodDisruptionBudget` -object using the `kubectl` command line tool, the `minAvailable` field has a -default value of 1 if neither `minAvailable` nor `maxUnavailable` is specified. +The behavior for an empty selector differs between the policy/v1beta1 and policy/v1 APIs for +PodDisruptionBudgets. For policy/v1beta1 an empty selector matches zero pods, while +for policy/v1 an empty selector matches every pod in the namespace. {{< /note >}} You can specify only one of `maxUnavailable` and `minAvailable` in a single `PodDisruptionBudget`. @@ -160,7 +163,7 @@ Example PDB Using minAvailable: {{< codenew file="policy/zookeeper-pod-disruption-budget-minavailable.yaml" >}} -Example PDB Using maxUnavailable (Kubernetes 1.7 or higher): +Example PDB Using maxUnavailable: {{< codenew file="policy/zookeeper-pod-disruption-budget-maxunavailable.yaml" >}} @@ -206,7 +209,7 @@ You can get more information about the status of a PDB with this command: kubectl get poddisruptionbudgets zk-pdb -o yaml ``` ```yaml -apiVersion: policy/v1beta1 +apiVersion: policy/v1 kind: PodDisruptionBudget metadata: annotations: diff --git a/content/en/examples/application/job/cronjob.yaml b/content/en/examples/application/job/cronjob.yaml index 816d682f28..da905a9048 100644 --- a/content/en/examples/application/job/cronjob.yaml +++ b/content/en/examples/application/job/cronjob.yaml @@ -1,4 +1,4 @@ -apiVersion: batch/v1beta1 +apiVersion: batch/v1 kind: CronJob metadata: name: hello diff --git a/content/en/examples/application/job/indexed-job-vol.yaml b/content/en/examples/application/job/indexed-job-vol.yaml new file mode 100644 index 0000000000..ed40e1cc44 --- /dev/null +++ b/content/en/examples/application/job/indexed-job-vol.yaml @@ -0,0 +1,27 @@ +apiVersion: batch/v1 +kind: Job +metadata: + name: 'indexed-job' +spec: + completions: 5 + parallelism: 3 + completionMode: Indexed + template: + spec: + restartPolicy: Never + containers: + - name: 'worker' + image: 'docker.io/library/busybox' + command: + - "rev" + - "/input/data.txt" + volumeMounts: + - mountPath: /input + name: input + volumes: + - name: input + downwardAPI: + items: + - path: "data.txt" + fieldRef: + fieldPath: metadata.annotations['batch.kubernetes.io/job-completion-index'] \ No newline at end of file diff --git a/content/en/examples/application/job/indexed-job.yaml b/content/en/examples/application/job/indexed-job.yaml new file mode 100644 index 0000000000..5b80d35264 --- /dev/null +++ b/content/en/examples/application/job/indexed-job.yaml @@ -0,0 +1,35 @@ +apiVersion: batch/v1 +kind: Job +metadata: + name: 'indexed-job' +spec: + completions: 5 + parallelism: 3 + completionMode: Indexed + template: + spec: + restartPolicy: Never + initContainers: + - name: 'input' + image: 'docker.io/library/bash' + command: + - "bash" + - "-c" + - | + items=(foo bar baz qux xyz) + echo ${items[$JOB_COMPLETION_INDEX]} > /input/data.txt + volumeMounts: + - mountPath: /input + name: input + containers: + - name: 'worker' + image: 'docker.io/library/busybox' + command: + - "rev" + - "/input/data.txt" + volumeMounts: + - mountPath: /input + name: input + volumes: + - name: input + emptyDir: {} diff --git a/content/en/examples/application/zookeeper/zookeeper.yaml b/content/en/examples/application/zookeeper/zookeeper.yaml index a858a72613..4d893b369b 100644 --- a/content/en/examples/application/zookeeper/zookeeper.yaml +++ b/content/en/examples/application/zookeeper/zookeeper.yaml @@ -27,7 +27,7 @@ spec: selector: app: zk --- -apiVersion: policy/v1beta1 +apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: zk-pdb diff --git a/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml b/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml index a62bef140f..ef0b8645ba 100644 --- a/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml +++ b/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml @@ -1,4 +1,4 @@ -apiVersion: policy/v1beta1 +apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: zk-pdb diff --git a/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml b/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml index c4776ad4c0..49a66ee669 100644 --- a/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml +++ b/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml @@ -1,4 +1,4 @@ -apiVersion: policy/v1beta1 +apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: zk-pdb diff --git a/content/en/examples/service/networking/namespaced-params.yaml b/content/en/examples/service/networking/namespaced-params.yaml new file mode 100644 index 0000000000..dd56724787 --- /dev/null +++ b/content/en/examples/service/networking/namespaced-params.yaml @@ -0,0 +1,12 @@ +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: external-lb +spec: + controller: example.com/ingress-controller + parameters: + apiGroup: k8s.example.com + kind: IngressParameters + name: external-lb + namespace: external-configuration + scope: Namespace diff --git a/content/zh/docs/reference/command-line-tools-reference/feature-gates.md b/content/zh/docs/reference/command-line-tools-reference/feature-gates.md index a8b2c35f9d..f2818820fb 100644 --- a/content/zh/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/zh/docs/reference/command-line-tools-reference/feature-gates.md @@ -214,6 +214,14 @@ different Kubernetes components. | `StorageVersionAPI` | `false` | Alpha | 1.20 | | | `StorageVersionHash` | `false` | Alpha | 1.14 | 1.14 | | `StorageVersionHash` | `true` | Beta | 1.15 | | +| `SupportNodePidsLimit` | `false` | Alpha | 1.14 | 1.14 | +| `SupportNodePidsLimit` | `true` | Beta | 1.15 | | +| `SupportPodPidsLimit` | `false` | Alpha | 1.10 | 1.13 | +| `SupportPodPidsLimit` | `true` | Beta | 1.14 | | +| `TokenRequest` | `false` | Alpha | 1.10 | 1.11 | +| `TokenRequest` | `true` | Beta | 1.12 | | +| `TokenRequestProjection` | `false` | Alpha | 1.11 | 1.11 | +| `TokenRequestProjection` | `true` | Beta | 1.12 | | | `Sysctls` | `true` | Beta | 1.11 | | | `TTLAfterFinished` | `false` | Alpha | 1.12 | | | `TopologyManager` | `false` | Alpha | 1.16 | 1.17 | @@ -380,12 +388,17 @@ different Kubernetes components. | `SupportIPVSProxyMode` | `false` | Beta | 1.9 | 1.9 | | `SupportIPVSProxyMode` | `true` | Beta | 1.10 | 1.10 | | `SupportIPVSProxyMode` | `true` | GA | 1.11 | - | +<<<<<<< HEAD +| `Sysctls` | `true` | Beta | 1.11 | 1.20 | +| `Sysctls` | `true` | GA | 1.21 | | +======= | `SupportNodePidsLimit` | `false` | Alpha | 1.14 | 1.14 | | `SupportNodePidsLimit` | `true` | Beta | 1.15 | 1.19 | | `SupportNodePidsLimit` | `true` | GA | 1.20 | - | | `SupportPodPidsLimit` | `false` | Alpha | 1.10 | 1.13 | | `SupportPodPidsLimit` | `true` | Beta | 1.14 | 1.19 | | `SupportPodPidsLimit` | `true` | GA | 1.20 | - | +>>>>>>> upstream/master | `TaintBasedEvictions` | `false` | Alpha | 1.6 | 1.12 | | `TaintBasedEvictions` | `true` | Beta | 1.13 | 1.17 | | `TaintBasedEvictions` | `true` | GA | 1.18 | - | diff --git a/content/zh/docs/reference/command-line-tools-reference/kubelet.md b/content/zh/docs/reference/command-line-tools-reference/kubelet.md index 317a3a581e..6d7d2e757a 100644 --- a/content/zh/docs/reference/command-line-tools-reference/kubelet.md +++ b/content/zh/docs/reference/command-line-tools-reference/kubelet.md @@ -584,19 +584,6 @@ kubelet 使用此目录来保存所下载的配置，跟踪配置运行状况。 - - - - - - - diff --git a/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md b/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md index b8bffbc61b..20e8cee3d8 100644 --- a/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md +++ b/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md @@ -12,7 +12,6 @@ content_type: task -{{< feature-state for_k8s_version="v1.12" state="beta" >}}
--enable-cadvisor-json-endpoints     Default: `false`
- -启用 cAdvisor JSON 数据的 /spec 和 /stats/* 端点。 -已弃用：未来版本将会移除此标志。 -
--enable-controller-attach-detach     默认值：true