Merge pull request #29153 from PI-Victor/merged-main-dev-1.22

k8s-ci-robot · web-flow · commit 6b0351333e31 · 2021-07-29T08:14:19.000-07:00
Merge main into dev 1.22 to sync and fix conflicts
diff --git a/content/en/docs/concepts/cluster-administration/flow-control.md b/content/en/docs/concepts/cluster-administration/flow-control.md
@@ -412,6 +412,10 @@ poorly-behaved workloads that may be harming system health.
   queue) requests, broken down by the labels `priority_level` and
   `flow_schema`.
 
+* `apiserver_flowcontrol_request_concurrency_in_use` is a gauge vector
+  holding the instantaneous number of occupied seats, broken down by
+  the labels `priority_level` and `flow_schema`.
+
 * `apiserver_flowcontrol_priority_level_request_count_samples` is a
   histogram vector of observations of the then-current number of
   requests broken down by the labels `phase` (which takes on the
diff --git a/content/en/docs/concepts/configuration/manage-resources-containers.md b/content/en/docs/concepts/configuration/manage-resources-containers.md
@@ -115,7 +115,7 @@ CPU is always requested as an absolute quantity, never as a relative quantity;
 
 Limits and requests for `memory` are measured in bytes. You can express memory as
 a plain integer or as a fixed-point number using one of these suffixes:
-E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi,
+E, P, T, G, M, k. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi,
 Mi, Ki. For example, the following represent roughly the same value:
 
 ```shell
diff --git a/content/en/docs/concepts/configuration/secret.md b/content/en/docs/concepts/configuration/secret.md
@@ -12,26 +12,33 @@ weight: 30
 
 <!-- overview -->
 
-Kubernetes Secrets let you store and manage sensitive information, such
-as passwords, OAuth tokens, and ssh keys. Storing confidential information in a Secret
-is safer and more flexible than putting it verbatim in a
-{{< glossary_tooltip term_id="pod" >}} definition or in a
-{{< glossary_tooltip text="container image" term_id="image" >}}.
-See [Secrets design document](https://git.k8s.io/community/contributors/design-proposals/auth/secrets.md) for more information.
-
 A Secret is an object that contains a small amount of sensitive data such as
 a password, a token, or a key. Such information might otherwise be put in a
-Pod specification or in an image. Users can create Secrets and the system
-also creates some Secrets.
+{{< glossary_tooltip term_id="pod" >}} specification or in a
+{{< glossary_tooltip text="container image" term_id="image" >}}. Using a
+Secret means that you don't need to include confidential data in your
+application code.
+
+Because Secrets can be created independently of the Pods that use them, there
+is less risk of the Secret (and its data) being exposed during the workflow of
+creating, viewing, and editing Pods. Kubernetes, and applications that run in
+your cluster, can also take additional precautions with Secrets, such as
+avoiding writing confidential data to nonvolatile storage.
+
+Secrets are similar to {{< glossary_tooltip text="ConfigMaps" term_id="configmap" >}}
+but are specifically intended to hold confidential data.
 
 {{< caution >}}
-Kubernetes Secrets are, by default, stored as unencrypted base64-encoded
-strings. By default they can be retrieved - as plain text - by anyone with API
-access, or anyone with access to Kubernetes' underlying data store, etcd. In
-order to safely use Secrets, it is recommended you (at a minimum):
+Kubernetes Secrets are, by default, stored unencrypted in the API server's underlying data store (etcd). Anyone with API access can retrieve or modify a Secret, and so can anyone with access to etcd.
+Additionally, anyone who is authorized to create a Pod in a namespace can use that access to read any Secret in that namespace; this includes indirect access such as the ability to create a Deployment.
+
+In order to safely use Secrets, take at least the following steps:
 
 1. [Enable Encryption at Rest](/docs/tasks/administer-cluster/encrypt-data/) for Secrets.
-2. [Enable or configure RBAC rules](/docs/reference/access-authn-authz/authorization/) that restrict reading and writing the Secret. Be aware that secrets can be obtained implicitly by anyone with the permission to create a Pod.
+2. Enable or configure [RBAC rules](/docs/reference/access-authn-authz/authorization/) that
+   restrict reading data in Secrets (including via indirect means).
+3. Where appropriate, also use mechanisms such as RBAC to limit which principals are allowed to create new Secrets or replace existing ones.
+
 {{< /caution >}}
 
 <!-- body -->
@@ -47,6 +54,10 @@ A Secret can be used with a Pod in three ways:
 - As [container environment variable](#using-secrets-as-environment-variables).
 - By the [kubelet when pulling images](#using-imagepullsecrets) for the Pod.
 
+The Kubernetes control plane also uses Secrets; for example,
+[bootstrap token Secrets](#bootstrap-token-secrets) are a mechanism to
+help automate node registration.
+
 The name of a Secret object must be a valid
 [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
 You can specify the `data` and/or the `stringData` field when creating a
@@ -407,9 +418,9 @@ stringData:
 
 There are several options to create a Secret:
 
-- [create Secrets using `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
-- [create Secrets from config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
-- [create Secrets using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
+- [create Secret using `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
+- [create Secret from config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
+- [create Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
 
 ## Editing a Secret
 
@@ -1164,7 +1175,7 @@ limit access using [authorization policies](
 Secrets often hold values that span a spectrum of importance, many of which can
 cause escalations within Kubernetes (e.g. service account tokens) and to
 external systems. Even if an individual app can reason about the power of the
-secrets it expects to interact with, other apps within the same namespace can
+Secrets it expects to interact with, other apps within the same namespace can
 render those assumptions invalid.
 
 For these reasons `watch` and `list` requests for secrets within a namespace are
@@ -1236,10 +1247,8 @@ for secret data, so that the secrets are not stored in the clear into {{< glossa
    if the API server policy does not allow that user to read the Secret, the user could
    run a Pod which exposes the secret.
 
-
 ## {{% heading "whatsnext" %}}
 
-- Learn how to [manage Secrets using `kubectl`](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
-- Learn how to [manage Secrets using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
-- Learn how to [manage Secrets using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
-
+- Learn how to [manage Secret using `kubectl`](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
+- Learn how to [manage Secret using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
+- Learn how to [manage Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
diff --git a/content/en/docs/concepts/overview/working-with-objects/annotations.md b/content/en/docs/concepts/overview/working-with-objects/annotations.md
@@ -30,6 +30,11 @@ Annotations, like labels, are key/value maps:
 }
 ```
 
+{{<note>}}
+The keys and the values in the map must be strings. In other words, you cannot use
+numeric, boolean, list or other types for either the keys or the values.
+{{</note>}}
+
 Here are some examples of information that could be recorded in annotations:
 
 * Fields managed by a declarative configuration layer. Attaching these fields
diff --git a/content/en/docs/concepts/workloads/controllers/daemonset.md b/content/en/docs/concepts/workloads/controllers/daemonset.md
@@ -230,6 +230,8 @@ storage servers).
 Use a Deployment for stateless services, like frontends, where scaling up and down the
 number of replicas and rolling out updates are more important than controlling exactly which host
 the Pod runs on.  Use a DaemonSet when it is important that a copy of a Pod always run on
-all or certain hosts, and when it needs to start before other Pods.
+all or certain hosts, if the DaemonSet provides node-level functionality that allows other Pods to run correctly on that particular node.
+
+For example, [network plugins](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) often include a component that runs as a DaemonSet. The DaemonSet component makes sure that the node where it's running has working cluster networking.
 
 
diff --git a/content/en/docs/concepts/workloads/pods/init-containers.md b/content/en/docs/concepts/workloads/pods/init-containers.md
@@ -291,7 +291,8 @@ Given the ordering and execution for init containers, the following rules
 for resource usage apply:
 
 * The highest of any particular resource request or limit defined on all init
-  containers is the *effective init request/limit*
+  containers is the *effective init request/limit*. If any resource has no
+  resource limit specified this is considered as the highest limit.
 * The Pod's *effective request/limit* for a resource is the higher of:
   * the sum of all app containers request/limit for a resource
   * the effective init request/limit for a resource
diff --git a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md b/content/en/docs/concepts/workloads/pods/pod-lifecycle.md
@@ -379,7 +379,7 @@ An example flow:
    as terminating (a graceful shutdown duration has been set), the kubelet begins the local Pod
    shutdown process.
    1. If one of the Pod's containers has defined a `preStop`
-      [hook](/docs/concepts/containers/container-lifecycle-hooks/#hook-details), the kubelet
+      [hook](/docs/concepts/containers/container-lifecycle-hooks), the kubelet
       runs that hook inside of the container. If the `preStop` hook is still running after the
       grace period expires, the kubelet requests a small, one-off grace period extension of 2
       seconds.
diff --git a/content/en/docs/contribute/generate-ref-docs/quickstart.md b/content/en/docs/contribute/generate-ref-docs/quickstart.md
@@ -6,7 +6,7 @@ weight: 40
 
 <!-- overview -->
 
-This page shows how to use the `update-imported-docs` script to generate
+This page shows how to use the `update-imported-docs.py` script to generate
 the Kubernetes reference documentation. The script automates
 the build setup and generates the reference documentation for a release.
 
@@ -39,7 +39,7 @@ see the [contributing upstream guide](/docs/contribute/generate-ref-docs/contrib
 
 ## Overview of update-imported-docs
 
-The `update-imported-docs` script is located in the `<web-base>/update-imported-docs/`
+The `update-imported-docs.py` script is located in the `<web-base>/update-imported-docs/`
 directory.
 
 The script builds the following references:
@@ -48,7 +48,7 @@ The script builds the following references:
 * The `kubectl` command reference
 * The Kubernetes API reference
 
-The `update-imported-docs` script generates the Kubernetes reference documentation
+The `update-imported-docs.py` script generates the Kubernetes reference documentation
 from the Kubernetes source code. The script creates a temporary directory
 under `/tmp` on your machine and clones the required repositories: `kubernetes/kubernetes` and
 `kubernetes-sigs/reference-docs` into this directory.
@@ -69,7 +69,7 @@ The `generate-command` field defines a series of build instructions
 from `kubernetes-sigs/reference-docs/Makefile`. The `K8S_RELEASE` variable
 determines the version of the release.
 
-The `update-imported-docs` script performs the following steps:
+The `update-imported-docs.py` script performs the following steps:
 
 1. Clones the related repositories specified in a configuration file. For the
    purpose of generating reference docs, the repository that is cloned by
@@ -152,17 +152,17 @@ For example:
 
 ## Running the update-imported-docs tool
 
-You can run the `update-imported-docs` tool as follows:
+You can run the `update-imported-docs.py` tool as follows:
 
 ```shell
 cd <web-base>/update-imported-docs
-./update-imported-docs <configuration-file.yml> <release-version>
+./update-imported-docs.py <configuration-file.yml> <release-version>
 ```
 
 For example:
 
 ```shell
-./update-imported-docs reference.yml 1.17
+./update-imported-docs.py reference.yml 1.17
 ```
 
 <!-- Revisit: is the release configuration used -->
@@ -254,4 +254,3 @@ running the build targets, see the following guides:
 * [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
 * [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
 
-
diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md
@@ -39,7 +39,7 @@ client libraries:
 - [Kubernetes Java client library](https://github.com/kubernetes-client/java)
 - [Kubernetes JavaScript client library](https://github.com/kubernetes-client/javascript)
 - [Kubernetes C# client library](https://github.com/kubernetes-client/csharp)
-- [Kubernetes Haskell Client library](https://github.com/kubernetes-client/haskell)
+- [Kubernetes Haskell client library](https://github.com/kubernetes-client/haskell)
 
 ## CLI
 
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
@@ -2,6 +2,9 @@
 title: Feature Gates
 weight: 10
 content_type: concept
+card:
+  name: reference
+  weight: 60
 ---
 
 <!-- overview -->
diff --git a/content/en/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping.md b/content/en/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping.md
@@ -10,7 +10,7 @@ content_type: concept
 
 <!-- overview -->
 
-In a Kubernetes cluster, the components on the worker nodes - kubelet and kube-proxy - need to communicate with Kubernetes master components, specifically kube-apiserver.
+In a Kubernetes cluster, the components on the worker nodes - kubelet and kube-proxy - need to communicate with Kubernetes control plane components, specifically kube-apiserver.
 In order to ensure that communication is kept private, not interfered with, and ensure that each component of the cluster is talking to another trusted component, we strongly
 recommend using client TLS certificates on nodes.
 
@@ -44,7 +44,7 @@ Note that the above process depends upon:
 All of the following are responsibilities of whoever sets up and manages the cluster:
 
 1. Creating the CA key and certificate
-2. Distributing the CA certificate to the master nodes, where kube-apiserver is running
+2. Distributing the CA certificate to the control plane nodes, where kube-apiserver is running
 3. Creating a key and certificate for each kubelet; strongly recommended to have a unique one, with a unique CN, for each kubelet
 4. Signing the kubelet certificate using the CA key
 5. Distributing the kubelet key and signed certificate to the specific node on which the kubelet is running
@@ -90,9 +90,9 @@ In addition, you need your Kubernetes Certificate Authority (CA).
 ## Certificate Authority
 
 As without bootstrapping, you will need a Certificate Authority (CA) key and certificate. As without bootstrapping, these will be used
-to sign the kubelet certificate. As before, it is your responsibility to distribute them to master nodes.
+to sign the kubelet certificate. As before, it is your responsibility to distribute them to control plane nodes.
 
-For the purposes of this document, we will assume these have been distributed to master nodes at `/var/lib/kubernetes/ca.pem` (certificate) and `/var/lib/kubernetes/ca-key.pem` (key).
+For the purposes of this document, we will assume these have been distributed to control plane nodes at `/var/lib/kubernetes/ca.pem` (certificate) and `/var/lib/kubernetes/ca-key.pem` (key).
 We will refer to these as "Kubernetes CA certificate and key".
 
 All Kubernetes components that use these certificates - kubelet, kube-apiserver, kube-controller-manager - assume the key and certificate to be PEM-encoded.
@@ -234,7 +234,7 @@ In order for the controller-manager to sign certificates, it needs the following
 
 ### Access to key and certificate
 
-As described earlier, you need to create a Kubernetes CA key and certificate, and distribute it to the master nodes.
+As described earlier, you need to create a Kubernetes CA key and certificate, and distribute it to the control plane nodes.
 These will be used by the controller-manager to sign the kubelet certificates.
 
 Since these signed certificates will, in turn, be used by the kubelet to authenticate as a regular kubelet to kube-apiserver, it is important that the CA
@@ -319,7 +319,7 @@ collection.
 
 ## kubelet configuration
 
-Finally, with the master nodes properly set up and all of the necessary authentication and authorization in place, we can configure the kubelet.
+Finally, with the control plane nodes properly set up and all of the necessary authentication and authorization in place, we can configure the kubelet.
 
 The kubelet requires the following configuration to bootstrap:
 
diff --git a/content/en/docs/reference/tools/_index.md b/content/en/docs/reference/tools/_index.md
@@ -8,7 +8,7 @@ no_list: true
 ---
 
 <!-- overview -->
-Kubernetes contains several built-in tools to help you work with the Kubernetes system.
+Kubernetes contains several built-in tools and external tools that are commonly used or relevant that may as well be seen as required for Kubernetes to function.
 
 
 <!-- body -->
diff --git a/content/en/docs/reference/using-api/health-checks.md b/content/en/docs/reference/using-api/health-checks.md
@@ -25,7 +25,7 @@ The more verbose options shown below are intended to be used by human operators
 The following examples will show how you can interact with the health API endpoints.
 
 For all endpoints you can use the `verbose` parameter to print out the checks and their status.
-This can be useful for a human operator to debug the current status of the Api server, it is not intended to be consumed by a machine:
+This can be useful for a human operator to debug the current status of the API server, it is not intended to be consumed by a machine:
 
 ```shell
 curl -k https://localhost:6443/livez?verbose
@@ -93,7 +93,7 @@ The output show that the `etcd` check is excluded:
 
 {{< feature-state state="alpha" >}}
 
-Each individual health check exposes an http endpoint and could can be checked individually.
+Each individual health check exposes an HTTP endpoint and could can be checked individually.
 The schema for the individual health checks is `/livez/<healthcheck-name>` where `livez` and `readyz` and be used to indicate if you want to check the liveness or the readiness of the API server.
 The `<healthcheck-name>` path can be discovered using the `verbose` flag from above and take the path between `[+]` and `ok`.
 These individual health checks should not be consumed by machines but can be helpful for a human operator to debug a system:
diff --git a/content/en/docs/setup/best-practices/cluster-large.md b/content/en/docs/setup/best-practices/cluster-large.md
@@ -124,3 +124,6 @@ components, including cluster-critical addons.
 The [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler#readme)
 integrates with a number of cloud providers to help you run the right number of
 nodes for the level of resource demand in your cluster.
+
+The [addon resizer](https://github.com/kubernetes/autoscaler/tree/master/addon-resizer#readme)
+helps you in resizing the addons automatically as your cluster's scale changes.
diff --git a/content/en/docs/tasks/administer-cluster/encrypt-data.md b/content/en/docs/tasks/administer-cluster/encrypt-data.md
@@ -157,7 +157,7 @@ program to retrieve the contents of your secret.
    kubectl describe secret secret1 -n default
    ```
 
-   should match `mykey: bXlkYXRh`, mydata is encoded, check [decoding a secret](/docs/concepts/configuration/secret#decoding-a-secret) to
+   should match `mykey: bXlkYXRh`, mydata is encoded, check [decoding a secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret) to
    completely decode the secret.
 
 
diff --git a/content/en/docs/tasks/administer-cluster/kubelet-config-file.md b/content/en/docs/tasks/administer-cluster/kubelet-config-file.md
@@ -30,11 +30,15 @@ Here is an example of what this file might look like:
 ```
 apiVersion: kubelet.config.k8s.io/v1beta1
 kind: KubeletConfiguration
+address: "192.168.0.8",
+port: 20250,
+serializeImagePulls: false,
 evictionHard:
     memory.available:  "200Mi"
 ```
 
-In the example, the Kubelet is configured to evict Pods when available memory drops below 200Mi.
+In the example, the Kubelet is configured to serve on IP address 192.168.0.8 and port 20250, pull images in parallel,
+and evict Pods when available memory drops below 200Mi.
 All other Kubelet configuration values are left at their built-in defaults, unless overridden
 by flags. Command line flags which target the same value as a config file will override that value.
 
diff --git a/content/en/docs/tasks/extend-kubernetes/configure-aggregation-layer.md b/content/en/docs/tasks/extend-kubernetes/configure-aggregation-layer.md
@@ -17,7 +17,7 @@ Configuring the [aggregation layer](/docs/concepts/extend-kubernetes/api-extensi
 {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
 
 {{< note >}}
-There are a few setup requirements for getting the aggregation layer working in your environment to support mutual TLS auth between the proxy and extension apiservers. Kubernetes and the kube-apiserver have multiple CAs, so make sure that the proxy is signed by the aggregation layer CA and not by something else, like the master CA.
+There are a few setup requirements for getting the aggregation layer working in your environment to support mutual TLS auth between the proxy and extension apiservers. Kubernetes and the kube-apiserver have multiple CAs, so make sure that the proxy is signed by the aggregation layer CA and not by something else, like the Kubernetes general CA.
 {{< /note >}}
 
 {{< caution >}}
diff --git a/content/en/docs/tutorials/stateful-application/cassandra.md b/content/en/docs/tutorials/stateful-application/cassandra.md
diff --git a/content/en/docs/tutorials/stateless-application/guestbook.md b/content/en/docs/tutorials/stateless-application/guestbook.md
diff --git a/content/it/docs/concepts/cluster-administration/addons.md b/content/it/docs/concepts/cluster-administration/addons.md
diff --git a/content/zh/docs/concepts/configuration/manage-resources-containers.md b/content/zh/docs/concepts/configuration/manage-resources-containers.md
diff --git a/content/zh/docs/tasks/debug-application-cluster/debug-application.md b/content/zh/docs/tasks/debug-application-cluster/debug-application.md
