whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge master into dev-1.21 to keep in sync, plus latest API reference

Browse Source 
This sync merge includes API reference updates.
This commit is contained in:
Tim Bannister
2021-04-06 20:53:30 +01:00
parent 8dbf6671db d2bf43be4d 41f8e9da78
commit 965aa51daf
266 changed files with 72690 additions and 4933 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/architecture/nodes.md
+10 -1
View File
@@ -67,6 +67,16 @@ delete the Node object to stop that health checking.
The name of a Node object must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
### Node name uniqueness
The [name](/docs/concepts/overview/working-with-objects/names#names) identifies a Node. Two Nodes
cannot have the same name at the same time. Kubernetes also assumes that a resource with the same
name is the same object. In case of a Node, it is implicitly assumed that an instance using the
same name will have the same state (e.g. network settings, root disk contents). This may lead to
inconsistencies if an instance was modified without changing its name. If the Node needs to be
replaced or updated significantly, the existing Node object needs to be removed from API server
first and re-added after the update.
### Self-registration of Nodes
When the kubelet flag `--register-node` is true (the default), the kubelet will attempt to
@@ -381,4 +391,3 @@ reserved for terminating [critical pods](/docs/tasks/administer-cluster/guarante
* Read the [Node](https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#the-kubernetes-node)
section of the architecture design document.
* Read about [taints and tolerations](/docs/concepts/scheduling-eviction/taint-and-toleration/).
content/en/docs/concepts/cluster-administration/addons.md
+1
View File
@@ -16,6 +16,7 @@ This page lists some of the available add-ons and links to their respective inst
## Networking and Network Policy
* [ACI](https://www.github.com/noironetworks/aci-containers) provides integrated container networking and network security with Cisco ACI.
* [Antrea](https://antrea.io/) operates at Layer 3/4 to provide networking and security services for Kubernetes, leveraging Open vSwitch as the networking data plane.
* [Calico](https://docs.projectcalico.org/latest/introduction/) is a networking and network policy provider. Calico supports a flexible set of networking options so you can choose the most efficient option for your situation, including non-overlay and overlay networks, with or without BGP. Calico uses the same engine to enforce network policy for hosts, pods, and (if using Istio & Envoy) applications at the service mesh layer.
* [Canal](https://github.com/tigera/canal/tree/master/k8s-install) unites Flannel and Calico, providing networking and network policy.
* [Cilium](https://github.com/cilium/cilium) is a L3 network and network policy plugin that can enforce HTTP/API/L7 policies transparently. Both routing and overlay/encapsulation mode are supported, and it can work on top of other CNI plugins.
content/en/docs/concepts/configuration/configmap.md
+2 -1
View File
@@ -224,7 +224,7 @@ When a ConfigMap currently consumed in a volume is updated, projected keys are e
The kubelet checks whether the mounted ConfigMap is fresh on every periodic sync.
However, the kubelet uses its local cache for getting the current value of the ConfigMap.
The type of the cache is configurable using the `ConfigMapAndSecretChangeDetectionStrategy` field in
the [KubeletConfiguration struct](https://github.com/kubernetes/kubernetes/blob/{{< param "docsbranch" >}}/staging/src/k8s.io/kubelet/config/v1beta1/types.go).
the [KubeletConfiguration struct](/docs/reference/config-api/kubelet-config.v1beta1/)).
A ConfigMap can be either propagated by watch (default), ttl-based, or by redirecting
all requests directly to the API server.
As a result, the total delay from the moment when the ConfigMap is updated to the moment
@@ -233,6 +233,7 @@ propagation delay, where the cache propagation delay depends on the chosen cache
(it equals to watch propagation delay, ttl of cache, or zero correspondingly).
ConfigMaps consumed as environment variables are not updated automatically and require a pod restart.
## Immutable ConfigMaps {#configmap-immutable}
{{< feature-state for_k8s_version="v1.21" state="stable" >}}
content/en/docs/concepts/configuration/manage-resources-containers.md
+7 -17
View File
@@ -21,9 +21,6 @@ allowed to use more of that resource than the limit you set. The kubelet also re
at least the _request_ amount of that system resource specifically for that container
to use.
<!-- body -->
## Requests and limits
@@ -442,12 +439,15 @@ If you want to use project quotas, you should:
* Enable the `LocalStorageCapacityIsolationFSQuotaMonitoring=true`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
in the kubelet configuration.
using the `featureGates` field in the
[kubelet configuration](/docs/reference/config-api/kubelet-config.v1beta1/)
or the `--feature-gates` command line flag.
* Ensure that the root filesystem (or optional runtime filesystem)
has project quotas enabled. All XFS filesystems support project quotas.
For ext4 filesystems, you need to enable the project quota tracking feature
while the filesystem is not mounted.
```bash
# For ext4, with /dev/block-device not mounted
sudo tune2fs -O project -Q prjquota /dev/block-device
@@ -518,8 +518,7 @@ Cluster-level extended resources are not tied to nodes. They are usually managed
by scheduler extenders, which handle the resource consumption and resource quota.
You can specify the extended resources that are handled by scheduler extenders
in [scheduler policy
configuration](https://github.com/kubernetes/kubernetes/blob/release-1.10/pkg/scheduler/api/v1/types.go#L31).
in [scheduler policy configuration](/docs/reference/config-api/kube-scheduler-policy-config.v1/)
**Example:**
@@ -742,23 +741,14 @@ LastState: map[terminated:map[exitCode:137 reason:OOM Killed startedAt:2015-07-0
You can see that the Container was terminated because of `reason:OOM Killed`, where `OOM` stands for Out Of Memory.
## {{% heading "whatsnext" %}}
* Get hands-on experience [assigning Memory resources to Containers and Pods](/docs/tasks/configure-pod-container/assign-memory-resource/).
* Get hands-on experience [assigning CPU resources to Containers and Pods](/docs/tasks/configure-pod-container/assign-cpu-resource/).
* For more details about the difference between requests and limits, see
[Resource QoS](https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md).
* Read the [Container](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#container-v1-core) API reference
* Read the [ResourceRequirements](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcerequirements-v1-core) API reference
* Read about [project quotas](https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-quotas.html) in XFS
* Read more about the [kube-scheduler Policy reference (v1)](/docs/reference/config-api/kube-scheduler-policy-config.v1/)
content/en/docs/concepts/configuration/secret.md
+8 -8
View File
@@ -668,7 +668,7 @@ When a secret currently consumed in a volume is updated, projected keys are even
The kubelet checks whether the mounted secret is fresh on every periodic sync.
However, the kubelet uses its local cache for getting the current value of the Secret.
The type of the cache is configurable using the `ConfigMapAndSecretChangeDetectionStrategy` field in
the [KubeletConfiguration struct](https://github.com/kubernetes/kubernetes/blob/{{< param "docsbranch" >}}/staging/src/k8s.io/kubelet/config/v1beta1/types.go).
the [KubeletConfiguration struct](/docs/reference/config-api/kubelet-config.v1beta1/).
A Secret can be either propagated by watch (default), ttl-based, or by redirecting
all requests directly to the API server.
As a result, the total delay from the moment when the Secret is updated to the moment
@@ -760,8 +760,8 @@ data has the following advantages:
- improves performance of your cluster by significantly reducing load on kube-apiserver, by
closing watches for secrets marked as immutable.
This feature is controlled by the `ImmutableEphemeralVolumes` [feature
gate](/docs/reference/command-line-tools-reference/feature-gates/),
This feature is controlled by the `ImmutableEphemeralVolumes`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/),
which is enabled by default since v1.19. You can create an immutable
Secret by setting the `immutable` field to `true`. For example,
```yaml
@@ -865,6 +865,7 @@ start until all the Pod's volumes are mounted.
### Use-Case: As container environment variables
Create a secret
```yaml
apiVersion: v1
kind: Secret
@@ -877,6 +878,7 @@ data:
```
Create the Secret:
```shell
kubectl apply -f mysecret.yaml
```
@@ -992,7 +994,7 @@ For example, if your actual password is `S!B\*d$zDsb=`, you should execute the c
kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password='S!B\*d$zDsb='
```
You do not need to escape special characters in passwords from files (`--from-file`).
You do not need to escape special characters in passwords from files (`--from-file`).
{{< /note >}}
Now make the Pods:
@@ -1173,14 +1175,12 @@ privileged, system-level components.
Applications that need to access the Secret API should perform `get` requests on
the secrets they need. This lets administrators restrict access to all secrets
while [white-listing access to individual instances](
/docs/reference/access-authn-authz/rbac/#referring-to-resources) that
while [white-listing access to individual instances](/docs/reference/access-authn-authz/rbac/#referring-to-resources) that
the app needs.
For improved performance over a looping `get`, clients can design resources that
reference a secret then `watch` the resource, re-requesting the secret when the
reference changes. Additionally, a ["bulk watch" API](
https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/bulk_watch.md)
reference changes. Additionally, a ["bulk watch" API](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/bulk_watch.md)
to let clients `watch` individual resources has also been proposed, and will likely
be available in future releases of Kubernetes.
content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md
+1 -1
View File
@@ -44,7 +44,7 @@ desired state, and continually maintains this state.
You can deploy and update a custom controller on a running cluster, independently
of the cluster's lifecycle. Custom controllers can work with any kind of resource,
but they are especially effective when combined with custom resources. The
[Operator pattern](https://coreos.com/blog/introducing-operators.html) combines custom
[Operator pattern](/docs/concepts/extend-kubernetes/operator/) combines custom
resources and custom controllers. You can use custom controllers to encode domain knowledge
for specific applications into an extension of the Kubernetes API.
content/en/docs/concepts/overview/components.md
+2 -2
View File
@@ -33,7 +33,8 @@ The control plane's components make global decisions about the cluster (for exam
Control plane components can be run on any machine in the cluster. However,
for simplicity, set up scripts typically start all control plane components on
the same machine, and do not run user containers on this machine. See
[Building High-Availability Clusters](/docs/admin/high-availability/) for an example multi-master-VM setup.
[Creating Highly Available clusters with kubeadm](/docs/setup/production-environment/tools/kubeadm/high-availability/)
for an example control plane setup that runs across multiple VMs.
### kube-apiserver
@@ -132,4 +133,3 @@ saving container logs to a central log store with search/browsing interface.
* Learn about [Controllers](/docs/concepts/architecture/controller/)
* Learn about [kube-scheduler](/docs/concepts/scheduling-eviction/kube-scheduler/)
* Read etcd's official [documentation](https://etcd.io/docs/)
content/en/docs/concepts/overview/working-with-objects/names.md
+4 -1
View File
@@ -24,6 +24,10 @@ For non-unique user-provided attributes, Kubernetes provides [labels](/docs/conc
{{< glossary_definition term_id="name" length="all" >}}
{{< note >}}
In cases when objects represent a physical entity, like a Node representing a physical host, when the host is re-created under the same name without deleting and re-creating the Node, Kubernetes treats the new host as the old one, which may lead to inconsistencies.
{{< /note >}}
Below are three types of commonly used name constraints for resources.
### DNS Subdomain Names
@@ -86,4 +90,3 @@ UUIDs are standardized as ISO/IEC 9834-8 and as ITU-T X.667.
* Read about [labels](/docs/concepts/overview/working-with-objects/labels/) in Kubernetes.
* See the [Identifiers and Names in Kubernetes](https://git.k8s.io/community/contributors/design-proposals/architecture/identifiers.md) design document.
content/en/docs/concepts/scheduling-eviction/assign-pod-node.md
+6 -7
View File
@@ -11,18 +11,17 @@ weight: 20
<!-- overview -->
You can constrain a {{< glossary_tooltip text="Pod" term_id="pod" >}} to only be able to run on particular
{{< glossary_tooltip text="Node(s)" term_id="node" >}}, or to prefer to run on particular nodes.
There are several ways to do this, and the recommended approaches all use
[label selectors](/docs/concepts/overview/working-with-objects/labels/) to make the selection.
You can constrain a {{< glossary_tooltip text="Pod" term_id="pod" >}} so that it can only run on particular set of
{{< glossary_tooltip text="Node(s)" term_id="node" >}}.
There are several ways to do this and the recommended approaches all use
[label selectors](/docs/concepts/overview/working-with-objects/labels/) to facilitate the selection.
Generally such constraints are unnecessary, as the scheduler will automatically do a reasonable placement
(e.g. spread your pods across nodes, not place the pod on a node with insufficient free resources, etc.)
but there are some circumstances where you may want more control on a node where a pod lands, for example to ensure
(e.g. spread your pods across nodes so as not place the pod on a node with insufficient free resources, etc.)
but there are some circumstances where you may want to control which node the pod deploys to - for example to ensure
that a pod ends up on a machine with an SSD attached to it, or to co-locate pods from two different
services that communicate a lot into the same availability zone.
<!-- body -->
## nodeSelector
content/en/docs/concepts/scheduling-eviction/kube-scheduler.md
+2
View File
@@ -87,6 +87,7 @@ of the scheduler:
* Read about [scheduler performance tuning](/docs/concepts/scheduling-eviction/scheduler-perf-tuning/)
* Read about [Pod topology spread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/)
* Read the [reference documentation](/docs/reference/command-line-tools-reference/kube-scheduler/) for kube-scheduler
* Read the [kube-scheduler config (v1beta1)](/docs/reference/config-api/kube-scheduler-config.v1beta1/) reference
* Learn about [configuring multiple schedulers](/docs/tasks/extend-kubernetes/configure-multiple-schedulers/)
* Learn about [topology management policies](/docs/tasks/administer-cluster/topology-manager/)
* Learn about [Pod Overhead](/docs/concepts/scheduling-eviction/pod-overhead/)
@@ -94,3 +95,4 @@ of the scheduler:
* [Volume Topology Support](/docs/concepts/storage/storage-classes/#volume-binding-mode)
* [Storage Capacity Tracking](/docs/concepts/storage/storage-capacity/)
* [Node-specific Volume Limits](/docs/concepts/storage/storage-limits/)
content/en/docs/concepts/scheduling-eviction/scheduler-perf-tuning.md
+7 -5
View File
@@ -24,8 +24,6 @@ in a process called _Binding_.
This page explains performance tuning optimizations that are relevant for
large Kubernetes clusters.
<!-- body -->
In large clusters, you can tune the scheduler's behaviour balancing
@@ -44,8 +42,10 @@ should use its compiled-in default.
If you set `percentageOfNodesToScore` above 100, kube-scheduler acts as if you
had set a value of 100.
To change the value, edit the kube-scheduler configuration file (this is likely
to be `/etc/kubernetes/config/kube-scheduler.yaml`), then restart the scheduler.
To change the value, edit the
[kube-scheduler configuration file](/docs/reference/config-api/kube-scheduler-config.v1beta1/)
and then restart the scheduler.
In many cases, the configuration file can be found at `/etc/kubernetes/config/kube-scheduler.yaml`.
After you have made this change, you can run
@@ -99,7 +99,6 @@ algorithmSource:
percentageOfNodesToScore: 50
```
## Tuning percentageOfNodesToScore
`percentageOfNodesToScore` must be a value between 1 and 100 with the default
@@ -160,4 +159,7 @@ Node 1, Node 5, Node 2, Node 6, Node 3, Node 4
After going over all the Nodes, it goes back to Node 1.
## {{% heading "whatsnext" %}}
* Check the [kube-scheduler configuration reference (v1beta1)](/docs/reference/config-api/kube-scheduler-config.v1beta1/)
content/en/docs/concepts/services-networking/service.md
+10 -3
View File
@@ -518,8 +518,13 @@ allocates a port from a range specified by `--service-node-port-range` flag (def
Each node proxies that port (the same port number on every Node) into your Service.
Your Service reports the allocated port in its `.spec.ports[*].nodePort` field.
If you want to specify particular IP(s) to proxy the port, you can set the `--nodeport-addresses` flag in kube-proxy to particular IP block(s); this is supported since Kubernetes v1.10.
This flag takes a comma-delimited list of IP blocks (e.g. 10.0.0.0/8, 192.0.2.0/25) to specify IP address ranges that kube-proxy should consider as local to this node.
If you want to specify particular IP(s) to proxy the port, you can set the
`--nodeport-addresses` flag for kube-proxy or the equivalent `nodePortAddresses`
field of the
[kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/)
to particular IP block(s).
This flag takes a comma-delimited list of IP blocks (e.g. `10.0.0.0/8`, `192.0.2.0/25`) to specify IP address ranges that kube-proxy should consider as local to this node.
For example, if you start kube-proxy with the `--nodeport-addresses=127.0.0.0/8` flag, kube-proxy only selects the loopback interface for NodePort Services. The default for `--nodeport-addresses` is an empty list. This means that kube-proxy should consider all available network interfaces for NodePort. (That's also compatible with earlier Kubernetes releases).
@@ -535,7 +540,9 @@ to configure environments that are not fully supported by Kubernetes, or even
to expose one or more nodes' IPs directly.
Note that this Service is visible as `<NodeIP>:spec.ports[*].nodePort`
and `.spec.clusterIP:spec.ports[*].port`. (If the `--nodeport-addresses` flag in kube-proxy is set, <NodeIP> would be filtered NodeIP(s).)
and `.spec.clusterIP:spec.ports[*].port`.
If the `--nodeport-addresses` flag for kube-proxy or the equivalent field
in the kube-proxy configuration file is set, `<NodeIP>` would be filtered node IP(s).
For example:
content/en/docs/concepts/storage/volumes.md
+1 -1
View File
@@ -937,7 +937,7 @@ GitHub project has [instructions](https://github.com/quobyte/quobyte-csi#quobyte
### rbd
An `rbd` volume allows a
[Rados Block Device](https://ceph.com/docs/master/rbd/rbd/) (RBD) volume to mount into your
[Rados Block Device](https://docs.ceph.com/en/latest/rbd/) (RBD) volume to mount into your
Pod. Unlike `emptyDir`, which is erased when a pod is removed, the contents of
an `rbd` volume are preserved and the volume is unmounted. This
means that a RBD volume can be pre-populated with data, and that data can
content/en/docs/concepts/workloads/controllers/replicationcontroller.md
+10 -9
View File
@@ -54,7 +54,9 @@ Run the example job by downloading the example file and then running this comman
```shell
kubectl apply -f https://k8s.io/examples/controllers/replication.yaml
```
The output is similar to this:
```
replicationcontroller/nginx created
```
@@ -64,7 +66,9 @@ Check on the status of the ReplicationController using this command:
```shell
kubectl describe replicationcontrollers/nginx
```
The output is similar to this:
```
Name: nginx
Namespace: default
@@ -103,7 +107,9 @@ To list all the pods that belong to the ReplicationController in a machine reada
pods=$(kubectl get pods --selector=app=nginx --output=jsonpath={.items..metadata.name})
echo $pods
```
The output is similar to this:
```
nginx-3ntk0 nginx-4ok8v nginx-qrm3m
```
@@ -117,7 +123,7 @@ specifies an expression with the name from each pod in the returned list.
As with all other Kubernetes config, a ReplicationController needs `apiVersion`, `kind`, and `metadata` fields.
The name of a ReplicationController object must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
For general information about working with config files, see [object management ](/docs/concepts/overview/working-with-objects/object-management/).
For general information about working with configuration files, see [object management](/docs/concepts/overview/working-with-objects/object-management/).
A ReplicationController also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
@@ -139,7 +145,7 @@ for example the [Kubelet](/docs/reference/command-line-tools-reference/kubelet/)
The ReplicationController can itself have labels (`.metadata.labels`). Typically, you
would set these the same as the `.spec.template.metadata.labels`; if `.metadata.labels` is not specified
then it defaults to `.spec.template.metadata.labels`. However, they are allowed to be
then it defaults to `.spec.template.metadata.labels`. However, they are allowed to be
different, and the `.metadata.labels` do not affect the behavior of the ReplicationController.
### Pod Selector
@@ -197,7 +203,7 @@ To update pods to a new spec in a controlled way, use a [rolling update](#rollin
### Isolating pods from a ReplicationController
Pods may be removed from a ReplicationController's target set by changing their labels. This technique may be used to remove pods from service for debugging, data recovery, etc. Pods that are removed in this way will be replaced automatically (assuming that the number of replicas is not also changed).
Pods may be removed from a ReplicationController's target set by changing their labels. This technique may be used to remove pods from service for debugging and data recovery. Pods that are removed in this way will be replaced automatically (assuming that the number of replicas is not also changed).
## Common usage patterns
@@ -207,8 +213,7 @@ As mentioned above, whether you have 1 pod you want to keep running, or 1000, a
### Scaling
The ReplicationController scales the number of replicas up or down by setting the `replicas` field.
You can configure the ReplicationController to manage the replicas manually or by an auto-scaling control agent.
The ReplicationController enables scaling the number of replicas up or down, either manually or by an auto-scaling control agent, by updating the `replicas` field.
### Rolling updates
@@ -245,7 +250,6 @@ The ReplicationController is forever constrained to this narrow responsibility.
The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, scale) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](https://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.
## API Object
Replication controller is a top-level resource in the Kubernetes REST API. More details about the
@@ -260,7 +264,6 @@ API object can be found at:
It's mainly used by [Deployment](/docs/concepts/workloads/controllers/deployment/) as a mechanism to orchestrate pod creation, deletion and updates.
Note that we recommend using Deployments instead of directly using Replica Sets, unless you require custom update orchestration or don't require updates at all.
### Deployment (Recommended)
[`Deployment`](/docs/concepts/workloads/controllers/deployment/) is a higher-level API object that updates its underlying Replica Sets and their Pods. Deployments are recommended if you want this rolling update functionality because, they are declarative, server-side, and have additional features.
@@ -284,5 +287,3 @@ safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
## For more information
Read [Run Stateless Application Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
content/en/docs/concepts/workloads/pods/init-containers.md
+4 -4
View File
@@ -313,16 +313,16 @@ limit, the same as the scheduler.
A Pod can restart, causing re-execution of init containers, for the following
reasons:
* A user updates the Pod specification, causing the init container image to change.
Any changes to the init container image restarts the Pod. App container image
changes only restart the app container.
* The Pod infrastructure container is restarted. This is uncommon and would
have to be done by someone with root access to nodes.
* All containers in a Pod are terminated while `restartPolicy` is set to Always,
forcing a restart, and the init container completion record has been lost due
to garbage collection.
The Pod will not be restarted when the init container image is changed, or the
init container completion record has been lost due to garbage collection. This
applies for Kubernetes v1.20 and later. If you are using an earlier version of
Kubernetes, consult the documentation for the version you are using.
## {{% heading "whatsnext" %}}