Merge branch 'main' of https://github.com/kubernetes/website into dev1

2021-07-11 21:46:30 +08:00
parent 08a8887464 cfca8c2f89
commit adf0e0f9ff
696 changed files with 24489 additions and 3093 deletions
@@ -11,7 +11,7 @@
 For overall help on editing and submitting pull requests, visit:
  https://kubernetes.io/docs/contribute/start/#improve-existing-content

- Use the default base branch, “master”, if you're documenting existing
+ Use the default base branch, “main”, if you're documenting existing
 features in the English localization.

 If you're working on a different localization (not English), see
@@ -235,10 +235,12 @@ aliases:
    - parispittman
  # authoritative source: https://git.k8s.io/sig-release/OWNERS_ALIASES
  sig-release-leads:
+    - cpanato # SIG Technical Lead
    - hasheddan # SIG Technical Lead
    - jeremyrickard # SIG Technical Lead
    - justaugustus # SIG Chair
    - LappleApple # SIG Program Manager
+    - puerco # SIG Technical Lead
    - saschagrunert # SIG Chair
  release-engineering-approvers:
    - cpanato # Release Manager
@@ -4,7 +4,7 @@
 # The Kubernetes documentation
 -->

-[![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-master-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-main-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest)

 <!--
 This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad that you want to contribute!
@@ -1,6 +1,6 @@
 # The Kubernetes documentation

-[![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-master-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-main-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest)

 This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad that you want to contribute!

@@ -0,0 +1,61 @@
+---
+layout: blog
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+slug: <seo-friendly-version-of-title-separated-by-dashes>
+---
+
+**Author:** <your name> (<your organization name>), <another author's name> (<their organization>)
+
+<!--  
+Instructions:
+- Replace these instructions and the following text with your content.
+- Replace `<angle bracket placeholders>` with actual values. For example, you would update `date: <yyyy>-<mm>-<dd>` to look something like `date: 2021-10-21`.
+- For convenience, use third-party tools to author and collaborate on your content.
+- To save time and effort in reviews, check your content's spelling, grammar, and style before contributing.
+- Feel free to ask for assistance in the Kubernetes Slack channel, [#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J).
+-->
+
+Replace this first line of your content with one to three sentences that summarize the blog post.
+
+## This is a section heading
+
+To help the reader, organize your content into sections that contain about three to six paragraphs.
+
+If you're documenting commands, separate the commands from the outputs, like this:
+
+1. Verify that the Secret exists by running the following command:
+
+      ```shell
+      kubectl get secrets
+      ```
+
+      The response should be like this:
+
+      ```shell
+      NAME                    TYPE                                  DATA   AGE
+      mysql-pass-c57bb4t7mf   Opaque                                1      9s
+      ```
+
+You're free to create any sections you like. Below are a few common patterns we see at the end of blog posts.
+
+## What’s next?
+
+This optional section describes the future of the thing you've just described in the post.
+
+## How can I learn more?
+
+This optional section provides links to more information. Please avoid promoting and over-represent your organization.
+
+## How do I get involved?
+
+An optional section that links to resources for readers to get involved, and acknowledgments of individual contributors, such as:
+
+* [The name of a channel on Slack, #a-channel](https://<a-workspace>.slack.com/messages/<a-channel>)
+
+* [A link to a "contribute" page with more information](<https://github.com/kubernetes/community/blob/master/sig-storage/README.md#contact>).
+
+* Acknowledgements and thanks to the contributors. <person's name> ([<github id>](https://github.com/<github id>)) who did X, Y, and Z.
+
+* Those interested in getting involved with the design and development of <project>, join the [<name of the SIG>](https://github.com/project/community/tree/master/<sig-group>). We’re rapidly growing and always welcome new contributors.
@@ -7,6 +7,7 @@ timeout: 1200s
 options:
  substitution_option: ALLOW_LOOSE
 steps:
+    # It's fine to bump the tag to a recent version, as needed
  - name: "gcr.io/k8s-testimages/gcb-docker-gcloud:v20190906-745fed4"
    entrypoint: make
    env:
@@ -48,7 +48,7 @@ Kubernetes is open source giving you the freedom to take advantage of on-premise
        <br>
        <br>
        <br>
-        <a href="https://events.linuxfoundation.org/kubecon-cloudnativecon-europe/?utm_source=kubernetes.io&utm_medium=nav&utm_campaign=kccnceu21" button id="desktopKCButton">Revisit KubeCon EU 2021</a>
+        <a href="https://events.linuxfoundation.org/kubecon-cloudnativecon-europe-2022/?utm_source=kubernetes.io&utm_medium=nav&utm_campaign=kccnceu22" button id="desktopKCButton">Attend KubeCon Europe on May 17-20, 2022</a>
 </div>
 <div id="videoPlayer">
    <iframe data-url="https://www.youtube.com/embed/H06qrNmGqyE?autoplay=1" frameborder="0" allowfullscreen></iframe>
@@ -140,7 +140,7 @@ The local persistent volume beta feature is not complete by far. Some notable en

 ## Complementary features

-[Pod priority and preemption](/docs/concepts/configuration/pod-priority-preemption/) is another Kubernetes feature that is complementary to local persistent volumes. When your application uses local storage, it must be scheduled to the specific node where the local volume resides. You can give your local storage workload high priority so if that node ran out of room to run your workload, Kubernetes can preempt lower priority workloads to make room for it.
+[Pod priority and preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/) is another Kubernetes feature that is complementary to local persistent volumes. When your application uses local storage, it must be scheduled to the specific node where the local volume resides. You can give your local storage workload high priority so if that node ran out of room to run your workload, Kubernetes can preempt lower priority workloads to make room for it.

 [Pod disruption budget](/docs/concepts/workloads/pods/disruptions/) is also very important for those workloads that must maintain quorum. Setting a disruption budget for your workload ensures that it does not drop below quorum due to voluntary disruption events, such as node drains during upgrade.

@@ -94,7 +94,7 @@ JOSH BERKUS: That goes into release notes. I mean, keep in mind that one of the

 However, stuff happens, and we do occasionally have to do those. And so far, our main way to identify that to people actually is in the release notes. If you look at [the current release notes](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#no-really-you-must-do-this-before-you-upgrade), there are actually two things in there right now that are sort of breaking changes. 

-One of them is the bit with [priority and preemption](/docs/concepts/configuration/pod-priority-preemption/) in that preemption being on by default now allows badly behaved users of the system to cause trouble in new ways. I'd actually have to look at the release notes to see what the second one was...
+One of them is the bit with [priority and preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/) in that preemption being on by default now allows badly behaved users of the system to cause trouble in new ways. I'd actually have to look at the release notes to see what the second one was...

 TIM PEPPER: The [JSON capitalization case sensitivity](https://github.com/kubernetes/kubernetes/issues/64612). 

@@ -166,7 +166,7 @@ Some critical state is held outside etcd. Certificates, container images, and ot
 * Cloud provider specific account and configuration data

 ## Considerations for your production workloads
-Anti-affinity specifications can be used to split clustered services across backing hosts, but at this time the settings are used only when the pod is scheduled. This means that Kubernetes can restart a failed node of your clustered application, but does not have a native mechanism to rebalance after a fail back. This is a topic worthy of a separate blog, but supplemental logic might be useful to achieve optimal workload placements after host or worker node recoveries or expansions. The [Pod Priority and Preemption feature](/docs/concepts/configuration/pod-priority-preemption/) can be used to specify a preferred triage in the event of resource shortages caused by failures or bursting workloads.
+Anti-affinity specifications can be used to split clustered services across backing hosts, but at this time the settings are used only when the pod is scheduled. This means that Kubernetes can restart a failed node of your clustered application, but does not have a native mechanism to rebalance after a fail back. This is a topic worthy of a separate blog, but supplemental logic might be useful to achieve optimal workload placements after host or worker node recoveries or expansions. The [Pod Priority and Preemption feature](/docs/concepts/scheduling-eviction/pod-priority-preemption/) can be used to specify a preferred triage in the event of resource shortages caused by failures or bursting workloads.

 For stateful services, external attached volume mounts are the standard Kubernetes recommendation for a non-clustered service (e.g., a typical SQL database). At this time Kubernetes managed snapshots of these external volumes is in the category of a [roadmap feature request](https://docs.google.com/presentation/d/1dgxfnroRAu0aF67s-_bmeWpkM1h2LCxe6lB1l1oS0EQ/edit#slide=id.g3ca07c98c2_0_47), likely to align with the Container Storage Interface (CSI) integration. Thus performing backups of such a service would involve application specific, in-pod activity that is beyond the scope of this document. While awaiting better Kubernetes support for a snapshot and backup workflow, running your database service in a VM rather than a container, and exposing it to your Kubernetes workload may be worth considering.

@@ -8,7 +8,7 @@ date: 2019-04-16

 Kubernetes is well-known for running scalable workloads. It scales your workloads based on their resource usage. When a workload is scaled up, more instances of the application get created. When the application is critical for your product, you want to make sure that these new instances are scheduled even when your cluster is under resource pressure. One obvious solution to this problem is to over-provision your cluster resources to have some amount of slack resources available for scale-up situations. This approach often works, but costs more as you would have to pay for the resources that are idle most of the time.

-[Pod priority and preemption](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/) is a scheduler feature made generally available in Kubernetes 1.14 that allows you to achieve high levels of scheduling confidence for your critical workloads without overprovisioning your clusters. It also provides a way to improve resource utilization in your clusters without sacrificing the reliability of your essential workloads.
+[Pod priority and preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/) is a scheduler feature made generally available in Kubernetes 1.14 that allows you to achieve high levels of scheduling confidence for your critical workloads without overprovisioning your clusters. It also provides a way to improve resource utilization in your clusters without sacrificing the reliability of your essential workloads.

 ## Guaranteed scheduling with controlled cost

@@ -55,7 +55,7 @@ The team has made progress in the last few months that is well worth celebrating

 - The K8s-Infrastructure Working Group released an automated billing report that they start every meeting off by reviewing as a group. 
 - DNS for k8s.io and kubernetes.io are also fully [community-owned](https://groups.google.com/g/kubernetes-dev/c/LZTYJorGh7c/m/u-ydk-yNEgAJ), with community members able to [file issues](https://github.com/kubernetes/k8s.io/issues/new?assignees=&labels=wg%2Fk8s-infra&template=dns-request.md&title=DNS+REQUEST%3A+%3Cyour-dns-record%3E) to manage records.
- The container registry [k8s.gcr.io](https://github.com/kubernetes/k8s.io/tree/master/k8s.gcr.io) is also fully community-owned and available for all Kubernetes subprojects to use. 
+- The container registry [k8s.gcr.io](https://github.com/kubernetes/k8s.io/tree/main/k8s.gcr.io) is also fully community-owned and available for all Kubernetes subprojects to use. 
 - The Kubernetes [publishing-bot](https://github.com/kubernetes/publishing-bot) responsible for keeping k8s.io/kubernetes/staging repositories published to their own top-level repos (For example: [kubernetes/api](https://github.com/kubernetes/api)) runs on a community-owned cluster.
 - The gcsweb.k8s.io service used to provide anonymous access to GCS buckets for kubernetes artifacts runs on a community-owned cluster.
 - There is also an automated process of promoting all our container images. This includes a fully documented infrastructure, managed by the Kubernetes community, with automated processes for provisioning permissions. 
@@ -186,7 +186,7 @@ metadata:

 ### Role Oriented Design

-When you put it all together, you have a single load balancing infrastructure that can be safely shared by multiple teams. The Gateway API not only a more expressive API for advanced routing, but is also a role-oriented API, designed for multi-tenant infrastructure. Its extensibility ensures that it will evolve for future use-cases while preserving portability. Ultimately these characteristics will allow Gateway API to adapt to different organizational models and implementations well into the future.
+When you put it all together, you have a single load balancing infrastructure that can be safely shared by multiple teams. The Gateway API is not only a more expressive API for advanced routing, but is also a role-oriented API, designed for multi-tenant infrastructure. Its extensibility ensures that it will evolve for future use-cases while preserving portability. Ultimately these characteristics will allow the Gateway API to adapt to different organizational models and implementations well into the future.

 ### Try it out and get involved

@@ -194,4 +194,4 @@ There are many resources to check out to learn more.

 *   Check out the [user guides](https://gateway-api.sigs.k8s.io/guides/getting-started/) to see what use-cases can be addressed. 
 *   Try out one of the [existing Gateway controllers ](https://gateway-api.sigs.k8s.io/references/implementations/)
-*   Or [get involved](https://gateway-api.sigs.k8s.io/contributing/community/) and help design and influence the future of Kubernetes service networking!
+*   Or [get involved](https://gateway-api.sigs.k8s.io/contributing/community/) and help design and influence the future of Kubernetes service networking!
@@ -0,0 +1,49 @@
+---
+layout: blog
+title: "Announcing Kubernetes Community Group Annual Reports"
+description: >
+  Introducing brand new Kubernetes Community Group Annual Reports for
+  Special Interest Groups and Working Groups.
+date: 2021-06-28T10:00:00-08:00
+slug: Announcing-Kubernetes-Community-Group-Annual-Reports
+---
+
+**Authors:** Divya Mohan
+
+{{< figure src="k8s_annual_report_2020.svg" alt="Community annual report 2020" link="https://www.cncf.io/reports/kubernetes-community-annual-report-2020/" >}}
+
+Given the growth and scale of the Kubernetes project, the existing reporting mechanisms were proving to be inadequate and challenging.
+Kubernetes is a large open source project. With over 100000 commits just to the main k/kubernetes repository, hundreds of other code
+repositories in the project, and thousands of contributors, there's a lot going on. In fact, there are 37 contributor groups at the time of
+writing. We also value all forms of contribution and not just code changes.
+
+With that context in mind, the challenge of reporting on all this activity was a call to action for exploring better options. Therefore
+inspired by the Apache Software Foundation’s [open guide to PMC Reporting](https://www.apache.org/foundation/board/reporting) and the
+[CNCF project Annual Reporting](https://www.cncf.io/cncf-annual-report-2020/), the Kubernetes project is proud to announce the 
+**Kubernetes Community Group Annual Reports for Special Interest Groups (SIGs) and Working Groups (WGs)**. In its flagship edition, 
+the [2020 Summary report](https://www.cncf.io/reports/kubernetes-community-annual-report-2020/) focuses on bettering the 
+Kubernetes ecosystem by assessing and promoting the healthiness of the groups within the upstream community. 
+
+Previously, the mechanisms for the Kubernetes project overall to report on groups and their activities were 
+[devstats](https://k8s.devstats.cncf.io/), GitHub data, issues, to measure the healthiness of a given UG/WG/SIG/Committee. As a 
+project spanning several diverse communities, it was essential to have something that captured the human side of things. With 50,000+
+contributors, it’s easy to assume that the project has enough help and this report surfaces more information than /help-wanted and 
+/good-first-issue for end users. This is how we sustain the project. Paraphrasing one of the Steering Committee members, 
+[Paris Pittman](https://github.com/parispittman), “There was a requirement for tighter feedback loops - ones that involved more than just
+GitHub data and issues. Given that Kubernetes, as a project, has grown in scale and number of contributors over the years, we have 
+outgrown the existing reporting mechanisms."
+
+The existing communication channels between the Steering committee members and the folks leading the groups and committees were also required
+to be made as open and as bi-directional as possible. Towards achieving this very purpose, every group and committee has been assigned a
+liaison from among the steering committee members for kick off, help, or guidance needed throughout the process. According to 
+[Davanum Srinivas a.k.a. dims](https://github.com/dims), “... That was one of the main motivations behind this report. People (leading the
+groups/committees) know that they can reach out to us and there’s a vehicle for them to reach out to us… This is our way of setting up a
+two-way feedback for them." The progress on these action items would be updated and tracked on the monthly Steering Committee meetings
+ensuring that this is not a one-off activity. Quoting [Nikhita Raghunath](https://github.com/nikhita), one of the Steering Committee members,
+“... Once we have a base, the liaisons will work with these groups to ensure that the problems are resolved. When we have a report next year, 
+we’ll have a look at the progress made and how we could still do better. But the idea is definitely to not stop at the report.”
+
+With this report, we hope to empower our end user communities with information that they can use to identify ways in which they can support
+the project as well as a sneak peek into the roadmap for upcoming features. As a community, we thrive on feedback and would love to hear your
+views about the report. You can get in touch with the [Steering Committee](https://github.com/kubernetes/steering#contact) via 
+[Slack](https://kubernetes.slack.com/messages/steering-committee) or via the [mailing list](steering@kubernetes.io).
@@ -159,11 +159,12 @@ You can run your own controller as a set of Pods,
 or externally to Kubernetes. What fits best will depend on what that particular
 controller does.

-
-
 ## {{% heading "whatsnext" %}}

 * Read about the [Kubernetes control plane](/docs/concepts/overview/components/#control-plane-components)
 * Discover some of the basic [Kubernetes objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/)
 * Learn more about the [Kubernetes API](/docs/concepts/overview/kubernetes-api/)
-* If you want to write your own controller, see [Extension Patterns](/docs/concepts/extend-kubernetes/extend-cluster/#extension-patterns) in Extending Kubernetes.
+* If you want to write your own controller, see
+  [Extension Patterns](/docs/concepts/extend-kubernetes/#extension-patterns)
+  in Extending Kubernetes.
+
@@ -283,7 +283,7 @@ The node eviction behavior changes when a node in a given availability zone
 becomes unhealthy. The node controller checks what percentage of nodes in the zone
 are unhealthy (NodeReady condition is ConditionUnknown or ConditionFalse) at
 the same time:
- If the fraction of unhealthy nodes is at least `--unhealthy-zone-threshold` 
+- If the fraction of unhealthy nodes is at least `--unhealthy-zone-threshold`
  (default 0.55), then the eviction rate is reduced.
 - If the cluster is small (i.e. has less than or equal to
  `--large-cluster-size-threshold` nodes - default 50), then evictions are stopped.
@@ -377,6 +377,21 @@ For example, if `ShutdownGracePeriod=30s`, and
 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).

+{{< note >}}
+When pods were evicted during the graceful node shutdown, they are marked as failed.
+Running `kubectl get pods` shows the status of the the evicted pods as `Shutdown`.
+And `kubectl describe pod` indicates that the pod was evicted because of node shutdown:
+
+```
+Status:         Failed
+Reason:         Shutdown
+Message:        Node is shutting, evicting pods
+```
+
+Failed pod objects will be preserved until explicitly deleted or [cleaned up by the GC](/docs/concepts/workloads/pods/pod-lifecycle/#pod-garbage-collection).
+This is a change of behavior compared to abrupt node termination.
+{{< /note >}}
+
 ## {{% heading "whatsnext" %}}

 * Learn about the [components](/docs/concepts/overview/components/#node-components) that make up a node.
@@ -33,8 +33,6 @@ the `--max-requests-inflight` flag without the API Priority and
 Fairness feature enabled.
 {{< /caution >}}

-
-
 <!-- body -->

 ## Enabling/Disabling API Priority and Fairness
@@ -65,6 +63,7 @@ The command-line flag `--enable-priority-and-fairness=false` will disable the
 API Priority and Fairness feature, even if other flags have enabled it.

 ## Concepts
+
 There are several distinct features involved in the API Priority and Fairness
 feature. Incoming requests are classified by attributes of the request using
 _FlowSchemas_, and assigned to priority levels. Priority levels add a degree of
@@ -75,12 +74,13 @@ each other, and allows for requests to be queued to prevent bursty traffic from
 causing failed requests when the average load is acceptably low.

 ### Priority Levels
-Without APF enabled, overall concurrency in
-the API server is limited by the `kube-apiserver` flags
-`--max-requests-inflight` and `--max-mutating-requests-inflight`. With APF
-enabled, the concurrency limits defined by these flags are summed and then the sum is divided up
-among a configurable set of _priority levels_. Each incoming request is assigned
-to a single priority level, and each priority level will only dispatch as many
+
+Without APF enabled, overall concurrency in the API server is limited by the
+`kube-apiserver` flags `--max-requests-inflight` and
+`--max-mutating-requests-inflight`. With APF enabled, the concurrency limits
+defined by these flags are summed and then the sum is divided up among a
+configurable set of _priority levels_. Each incoming request is assigned to a
+single priority level, and each priority level will only dispatch as many
 concurrent requests as its configuration allows.

 The default configuration, for example, includes separate priority levels for
@@ -90,6 +90,7 @@ requests cannot prevent leader election or actions by the built-in controllers
 from succeeding.

 ### Queuing
+
 Even within a priority level there may be a large number of distinct sources of
 traffic. In an overload situation, it is valuable to prevent one stream of
 requests from starving others (in particular, in the relatively common case of a
@@ -114,15 +115,18 @@ independent flows will all make progress when total traffic exceeds capacity),
 tolerance for bursty traffic, and the added latency induced by queuing.

 ### Exempt requests
+
 Some requests are considered sufficiently important that they are not subject to
 any of the limitations imposed by this feature. These exemptions prevent an
 improperly-configured flow control configuration from totally disabling an API
 server.

 ## Defaults
+
 The Priority and Fairness feature ships with a suggested configuration that
 should suffice for experimentation; if your cluster is likely to
-experience heavy load then you should consider what configuration will work best. The suggested configuration groups requests into five priority
+experience heavy load then you should consider what configuration will work
+best. The suggested configuration groups requests into five priority
 classes:

 * The `system` priority level is for requests from the `system:nodes` group,
@@ -180,19 +184,18 @@ If you add the following additional FlowSchema, this exempts those
 requests from rate limiting.

 {{< caution >}}
-
 Making this change also allows any hostile party to then send
 health-check requests that match this FlowSchema, at any volume they
 like.  If you have a web traffic filter or similar external security
 mechanism to protect your cluster's API server from general internet
 traffic, you can configure rules to block any health check requests
 that originate from outside your cluster.
-
 {{< /caution >}}

 {{< codenew file="priority-and-fairness/health-for-strangers.yaml" >}}

 ## Resources
+
 The flow control API involves two kinds of resources.
 [PriorityLevelConfigurations](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#prioritylevelconfiguration-v1beta1-flowcontrol-apiserver-k8s-io)
 define the available isolation classes, the share of the available concurrency
@@ -204,6 +207,7 @@ of the same API group, and it has the same Kinds with the same syntax and
 semantics.

 ### PriorityLevelConfiguration
+
 A PriorityLevelConfiguration represents a single isolation class. Each
 PriorityLevelConfiguration has an independent limit on the number of outstanding
 requests, and limitations on the number of queued requests.
@@ -217,6 +221,7 @@ server by restarting `kube-apiserver` with a different value for
 `--max-requests-inflight` (or `--max-mutating-requests-inflight`), and all
 PriorityLevelConfigurations will see their maximum allowed concurrency go up (or
 down) by the same fraction.
+
 {{< caution >}}
 With the Priority and Fairness feature enabled, the total concurrency limit for
 the server is set to the sum of `--max-requests-inflight` and
@@ -235,8 +240,8 @@ above the threshold will be queued, with the shuffle sharding and fair queuing t
 to balance progress between request flows.

 The queuing configuration allows tuning the fair queuing algorithm for a
-priority level. Details of the algorithm can be read in the [enhancement
-proposal](#whats-next), but in short:
+priority level. Details of the algorithm can be read in the
+[enhancement proposal](#whats-next), but in short:

 * Increasing `queues` reduces the rate of collisions between different flows, at
  the cost of increased memory usage. A value of 1 here effectively disables the
@@ -249,15 +254,15 @@ proposal](#whats-next), but in short:
 * Changing `handSize` allows you to adjust the probability of collisions between
  different flows and the overall concurrency available to a single flow in an
  overload situation.
-    {{< note >}}
-    A larger `handSize` makes it less likely for two individual flows to collide
-    (and therefore for one to be able to starve the other), but more likely that
-    a small number of flows can dominate the apiserver. A larger `handSize` also
-    potentially increases the amount of latency that a single high-traffic flow
-    can cause. The maximum number of queued requests possible from a
-    single flow is `handSize * queueLengthLimit`.
-    {{< /note >}}

+  {{< note >}}
+  A larger `handSize` makes it less likely for two individual flows to collide
+  (and therefore for one to be able to starve the other), but more likely that
+  a small number of flows can dominate the apiserver. A larger `handSize` also
+  potentially increases the amount of latency that a single high-traffic flow
+  can cause. The maximum number of queued requests possible from a
+  single flow is `handSize * queueLengthLimit`.
+  {{< /note >}}

 Following is a table showing an interesting collection of shuffle
 sharding configurations, showing for each the probability that a
@@ -319,6 +324,7 @@ considered part of a single flow. The correct choice for a given FlowSchema
 depends on the resource and your particular environment.

 ## Diagnostics
+
 Every HTTP response from an API server with the priority and fairness feature
 enabled has two extra headers: `X-Kubernetes-PF-FlowSchema-UID` and
 `X-Kubernetes-PF-PriorityLevel-UID`, noting the flow schema that matched the request
@@ -356,13 +362,14 @@ poorly-behaved workloads that may be harming system health.
  matched the request), `priority_level` (indicating the one to which
  the request was assigned), and `reason`.  The `reason` label will be
  have one of the following values:
-    * `queue-full`, indicating that too many requests were already
-      queued,
-    * `concurrency-limit`, indicating that the
-      PriorityLevelConfiguration is configured to reject rather than
-      queue excess requests, or
-    * `time-out`, indicating that the request was still in the queue
-      when its queuing time limit expired.
+
+  * `queue-full`, indicating that too many requests were already
+    queued,
+  * `concurrency-limit`, indicating that the
+    PriorityLevelConfiguration is configured to reject rather than
+    queue excess requests, or
+  * `time-out`, indicating that the request was still in the queue
+    when its queuing time limit expired.

 * `apiserver_flowcontrol_dispatched_requests_total` is a counter
  vector (cumulative since server start) of requests that began
@@ -430,14 +437,15 @@ poorly-behaved workloads that may be harming system health.
  sample to its histogram, reporting the length of the queue immediately
  after the request was added.  Note that this produces different
  statistics than an unbiased survey would.
-    {{< note >}}
-    An outlier value in a histogram here means it is likely that a single flow
-    (i.e., requests by one user or for one namespace, depending on
-    configuration) is flooding the API server, and being throttled. By contrast,
-    if one priority level's histogram shows that all queues for that priority
-    level are longer than those for other priority levels, it may be appropriate
-    to increase that PriorityLevelConfiguration's concurrency shares.
-    {{< /note >}}
+
+  {{< note >}}
+  An outlier value in a histogram here means it is likely that a single flow
+  (i.e., requests by one user or for one namespace, depending on
+  configuration) is flooding the API server, and being throttled. By contrast,
+  if one priority level's histogram shows that all queues for that priority
+  level are longer than those for other priority levels, it may be appropriate
+  to increase that PriorityLevelConfiguration's concurrency shares.
+  {{< /note >}}

 * `apiserver_flowcontrol_request_concurrency_limit` is a gauge vector
  holding the computed concurrency limit (based on the API server's
@@ -450,12 +458,13 @@ poorly-behaved workloads that may be harming system health.
  `priority_level` (indicating the one to which the request was
  assigned), and `execute` (indicating whether the request started
  executing).
-    {{< note >}}
-    Since each FlowSchema always assigns requests to a single
-    PriorityLevelConfiguration, you can add the histograms for all the
-    FlowSchemas for one priority level to get the effective histogram for
-    requests assigned to that priority level.
-    {{< /note >}}
+
+  {{< note >}}
+  Since each FlowSchema always assigns requests to a single
+  PriorityLevelConfiguration, you can add the histograms for all the
+  FlowSchemas for one priority level to get the effective histogram for
+  requests assigned to that priority level.
+  {{< /note >}}

 * `apiserver_flowcontrol_request_execution_seconds` is a histogram
  vector of how long requests took to actually execute, broken down by
@@ -465,14 +474,19 @@ poorly-behaved workloads that may be harming system health.

 ### Debug endpoints

-When you enable the API Priority and Fairness feature, the kube-apiserver serves the following additional paths at its HTTP[S] ports.
+When you enable the API Priority and Fairness feature, the `kube-apiserver`
+serves the following additional paths at its HTTP[S] ports.
+
+- `/debug/api_priority_and_fairness/dump_priority_levels` - a listing of
+  all the priority levels and the current state of each.  You can fetch like this:

- `/debug/api_priority_and_fairness/dump_priority_levels` - a listing of all the priority levels and the current state of each.  You can fetch like this:
  ```shell
  kubectl get --raw /debug/api_priority_and_fairness/dump_priority_levels
  ```
+
  The output is similar to this:
-  ```
+
+  ```none
  PriorityLevelName, ActiveQueues, IsIdle, IsQuiescing, WaitingRequests, ExecutingRequests,
  workload-low,      0,            true,   false,       0,               0,
  global-default,    0,            true,   false,       0,               0,
@@ -483,12 +497,16 @@ When you enable the API Priority and Fairness feature, the kube-apiserver serves
  workload-high,     0,            true,   false,       0,               0,
  ```

- `/debug/api_priority_and_fairness/dump_queues` - a listing of all the queues and their current state.  You can fetch like this:
+- `/debug/api_priority_and_fairness/dump_queues` - a listing of all the
+  queues and their current state.  You can fetch like this:
+
  ```shell
  kubectl get --raw /debug/api_priority_and_fairness/dump_queues
  ```
+
  The output is similar to this:
-  ```
+
+  ```none
  PriorityLevelName, Index,  PendingRequests, ExecutingRequests, VirtualStart,
  workload-high,     0,      0,               0,                 0.0000,
  workload-high,     1,      0,               0,                 0.0000,
@@ -498,25 +516,33 @@ When you enable the API Priority and Fairness feature, the kube-apiserver serves
  leader-election,   15,     0,               0,                 0.0000,
  ```

- `/debug/api_priority_and_fairness/dump_requests` - a listing of all the requests that are currently waiting in a queue.  You can fetch like this:
+- `/debug/api_priority_and_fairness/dump_requests` - a listing of all the requests
+  that are currently waiting in a queue.  You can fetch like this:
+
  ```shell
  kubectl get --raw /debug/api_priority_and_fairness/dump_requests
  ```
+
  The output is similar to this:
-  ```
+
+  ```none
  PriorityLevelName, FlowSchemaName, QueueIndex, RequestIndexInQueue, FlowDistingsher,       ArriveTime,
  exempt,            <none>,         <none>,     <none>,              <none>,                <none>,
  system,            system-nodes,   12,         0,                   system:node:127.0.0.1, 2020-07-23T15:26:57.179170694Z,
  ```
  
-  In addition to the queued requests, the output includes one phantom line for each priority level that is exempt from limitation.
+  In addition to the queued requests, the output includes one phantom line
+  for each priority level that is exempt from limitation.

  You can get a more detailed listing with a command like this:
+
  ```shell
  kubectl get --raw '/debug/api_priority_and_fairness/dump_requests?includeRequestDetails=1'
  ```
+
  The output is similar to this:
-  ```
+
+  ```none
  PriorityLevelName, FlowSchemaName, QueueIndex, RequestIndexInQueue, FlowDistingsher,       ArriveTime,                     UserName,              Verb,   APIPath,                                                     Namespace, Name,   APIVersion, Resource, SubResource,
  system,            system-nodes,   12,         0,                   system:node:127.0.0.1, 2020-07-23T15:31:03.583823404Z, system:node:127.0.0.1, create, /api/v1/namespaces/scaletest/configmaps,
  system,            system-nodes,   12,         1,                   system:node:127.0.0.1, 2020-07-23T15:31:03.594555947Z, system:node:127.0.0.1, create, /api/v1/namespaces/scaletest/configmaps,
@@ -528,4 +554,4 @@ When you enable the API Priority and Fairness feature, the kube-apiserver serves
 For background information on design details for API priority and fairness, see
 the [enhancement proposal](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1040-priority-and-fairness).
 You can make suggestions and feature requests via [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery) 
-or the feature's [slack channel](http://kubernetes.slack.com/messages/api-priority-and-fairness).
+or the feature's [slack channel](https://kubernetes.slack.com/messages/api-priority-and-fairness).
@@ -1,5 +1,4 @@
 ---
-reviewers:
 title: Garbage collection for container images
 content_type: concept
 weight: 70
@@ -7,12 +6,13 @@ weight: 70

 <!-- overview -->

-Garbage collection is a helpful function of kubelet that will clean up unused [images](/docs/concepts/containers/#container-images) and unused [containers](/docs/concepts/containers/). Kubelet will perform garbage collection for containers every minute and garbage collection for images every five minutes.
-
-External garbage collection tools are not recommended as these tools can potentially break the behavior of kubelet by removing containers expected to exist.
-
-
+Garbage collection is a helpful function of kubelet that will clean up unused
+[images](/docs/concepts/containers/#container-images) and unused
+[containers](/docs/concepts/containers/). Kubelet will perform garbage collection
+for containers every minute and garbage collection for images every five minutes.

+External garbage collection tools are not recommended as these tools can potentially
+break the behavior of kubelet by removing containers expected to exist.

 <!-- body -->

@@ -28,10 +28,24 @@ threshold has been met.

 ## Container Collection

-The policy for garbage collecting containers considers three user-defined variables. `MinAge` is the minimum age at which a container can be garbage collected. `MaxPerPodContainer` is the maximum number of dead containers every single
-pod (UID, container name) pair is allowed to have. `MaxContainers` is the maximum number of total dead containers. These variables can be individually disabled by setting `MinAge` to zero and setting `MaxPerPodContainer` and `MaxContainers` respectively to less than zero.
+The policy for garbage collecting containers considers three user-defined variables.
+`MinAge` is the minimum age at which a container can be garbage collected.
+`MaxPerPodContainer` is the maximum number of dead containers every single
+pod (UID, container name) pair is allowed to have.
+`MaxContainers` is the maximum number of total dead containers.
+These variables can be individually disabled by setting `MinAge` to zero and
+setting `MaxPerPodContainer` and `MaxContainers` respectively to less than zero.

-Kubelet will act on containers that are unidentified, deleted, or outside of the boundaries set by the previously mentioned flags. The oldest containers will generally be removed first. `MaxPerPodContainer` and `MaxContainer` may potentially conflict with each other in situations where retaining the maximum number of containers per pod (`MaxPerPodContainer`) would go outside the allowable range of global dead containers (`MaxContainers`). `MaxPerPodContainer` would be adjusted in this situation: A worst case scenario would be to downgrade `MaxPerPodContainer` to 1 and evict the oldest containers. Additionally, containers owned by pods that have been deleted are removed once they are older than `MinAge`.
+Kubelet will act on containers that are unidentified, deleted, or outside of
+the boundaries set by the previously mentioned flags. The oldest containers
+will generally be removed first. `MaxPerPodContainer` and `MaxContainer` may
+potentially conflict with each other in situations where retaining the maximum
+number of containers per pod (`MaxPerPodContainer`) would go outside the
+allowable range of global dead containers (`MaxContainers`).
+`MaxPerPodContainer` would be adjusted in this situation: A worst case
+scenario would be to downgrade `MaxPerPodContainer` to 1 and evict the oldest
+containers. Additionally, containers owned by pods that have been deleted are
+removed once they are older than `MinAge`.

 Containers that are not managed by kubelet are not subject to container garbage collection.

@@ -40,18 +54,18 @@ Containers that are not managed by kubelet are not subject to container garbage
 You can adjust the following thresholds to tune image garbage collection with the following kubelet flags :

 1. `image-gc-high-threshold`, the percent of disk usage which triggers image garbage collection.
-Default is 85%.
+   Default is 85%.
 2. `image-gc-low-threshold`, the percent of disk usage to which image garbage collection attempts
-to free. Default is 80%.
+   to free. Default is 80%.

 You can customize the garbage collection policy through the following kubelet flags:

 1. `minimum-container-ttl-duration`, minimum age for a finished container before it is
-garbage collected. Default is 0 minute, which means every finished container will be garbage collected.
+   garbage collected. Default is 0 minute, which means every finished container will be garbage collected.
 2. `maximum-dead-containers-per-container`, maximum number of old instances to be retained
-per container. Default is 1.
+   per container. Default is 1.
 3. `maximum-dead-containers`, maximum number of old instances of containers to retain globally.
-Default is -1, which means there is no global limit.
+   Default is -1, which means there is no global limit.

 Containers can potentially be garbage collected before their usefulness has expired. These containers
 can contain logs and other data that can be useful for troubleshooting. A sufficiently large value for
@@ -77,10 +91,8 @@ Including:
 | `--low-diskspace-threshold-mb` | `--eviction-hard` or `eviction-soft` | eviction generalizes disk thresholds to other resources |
 | `--outofdisk-transition-frequency` | `--eviction-pressure-transition-period` | eviction generalizes disk pressure transition to other resources |

-
-
 ## {{% heading "whatsnext" %}}

-
-See [Configuring Out Of Resource Handling](/docs/tasks/administer-cluster/out-of-resource/) for more details.
+See [Configuring Out Of Resource Handling](/docs/concepts/scheduling-eviction/node-pressure-eviction/)
+for more details.

@@ -83,8 +83,11 @@ 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 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 parameters [`containerLogMaxSize` and `containerLogMaxFiles`](/docs/reference/config-api/kubelet-config.v1beta1/#kubelet-config-k8s-io-v1beta1-KubeletConfiguration)
+in [kubelet config file](/docs/tasks/administer-cluster/kubelet-config-file/)
+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
@@ -50,7 +50,7 @@ It is a recommended practice to put resources related to the same microservice o
 A URL can also be specified as a configuration source, which is handy for deploying directly from configuration files checked into GitHub:

 ```shell
-kubectl apply -f https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/application/nginx/nginx-deployment.yaml
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/nginx/nginx-deployment.yaml
 ```

 ```shell
@@ -17,6 +17,11 @@ a *kubeconfig file*. This is a generic way of referring to configuration files.
 It does not mean that there is a file named `kubeconfig`.
 {{< /note >}}

+{{< warning >}}
+Only use kubeconfig files from trusted sources. Using a specially-crafted kubeconfig file could result in malicious code execution or file exposure. 
+If you must use an untrusted kubeconfig file, inspect it carefully first, much as you would a shell script.
+{{< /warning>}}
+
 By default, `kubectl` looks for a file named `config` in the `$HOME/.kube` directory.
 You can specify other kubeconfig files by setting the `KUBECONFIG` environment
 variable or by setting the
@@ -154,4 +159,3 @@ are stored absolutely.



-
@@ -407,9 +407,9 @@ stringData:

 There are several options to create a Secret:

- [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/)
+- [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/)

 ## Editing a Secret

@@ -1235,15 +1235,11 @@ for secret data, so that the secrets are not stored in the clear into {{< glossa
 - A user who can create a Pod that uses a secret can also see the value of that secret. Even
   if the API server policy does not allow that user to read the Secret, the user could
   run a Pod which exposes the secret.
- - Currently, anyone with root permission on any node can read _any_ secret from the API server,
-   by impersonating the kubelet. It is a planned feature to only send secrets to
-   nodes that actually require them, to restrict the impact of a root exploit on a
-   single node.


 ## {{% heading "whatsnext" %}}

- 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/)
+- 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/)

@@ -77,6 +77,20 @@ the pull policy of any object after its initial creation.

 When `imagePullPolicy` is defined without a specific value, it is also set to `Always`.

+### ImagePullBackOff
+
+When a kubelet starts creating containers for a Pod using a container runtime,
+it might be possible the container is in [Waiting](/docs/concepts/workloads/pods/pod-lifecycle/#container-state-waiting)
+state because of `ImagePullBackOff`.
+
+The status `ImagePullBackOff` means that a container could not start because Kubernetes
+could not pull a container image (for reasons such as invalid image name, or pulling
+from a private registry without `imagePullSecret`). The `BackOff` part indicates
+that Kubernetes will keep trying to pull the image, with an increasing back-off delay.
+
+Kubernetes raises the delay between each attempt until it reaches a compiled-in limit,
+which is 300 seconds (5 minutes).
+
 ## Multi-architecture images with image indexes

 As well as providing binary images, a container registry can also serve a [container image index](https://github.com/opencontainers/image-spec/blob/master/image-index.md). An image index can point to multiple [image manifests](https://github.com/opencontainers/image-spec/blob/master/manifest.md) for architecture-specific versions of a container. The idea is that you can have a name for an image (for example: `pause`, `example/mycontainer`, `kube-apiserver`) and allow different systems to fetch the right binary image for the machine architecture they are using.
@@ -51,7 +51,7 @@ heterogeneous node configurations, see [Scheduling](#scheduling) below.
 {{< /note >}}

 The configurations have a corresponding `handler` name, referenced by the RuntimeClass. The
-handler must be a valid DNS 1123 label (alpha-numeric + `-` characters).
+handler must be a valid [DNS label name](/docs/concepts/overview/working-with-objects/names/#dns-label-names).

 ### 2. Create the corresponding RuntimeClass resources

@@ -135,7 +135,7 @@ table](https://github.com/cri-o/cri-o/blob/master/docs/crio.conf.5.md#crioruntim
  runtime_path = "${PATH_TO_BINARY}"
 ```

-See CRI-O's [config documentation](https://raw.githubusercontent.com/cri-o/cri-o/9f11d1d/docs/crio.conf.5.md) for more details.
+See CRI-O's [config documentation](https://github.com/cri-o/cri-o/blob/master/docs/crio.conf.5.md) for more details.

 ## Scheduling

@@ -179,4 +179,4 @@ are accounted for in Kubernetes.
 - [RuntimeClass Design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/585-runtime-class/README.md)
 - [RuntimeClass Scheduling Design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/585-runtime-class/README.md#runtimeclass-scheduling)
 - Read about the [Pod Overhead](/docs/concepts/scheduling-eviction/pod-overhead/) concept
- [PodOverhead Feature Design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/20190226-pod-overhead.md)
+- [PodOverhead Feature Design](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/688-pod-overhead)
@@ -51,8 +51,7 @@ Some of the things that you can use an operator to automate include:
 * choosing a leader for a distributed application without an internal
  member election process

-What might an Operator look like in more detail? Here's an example in more
-detail:
+What might an Operator look like in more detail? Here's an example:

 1. A custom resource named SampleDB, that you can configure into the cluster.
 2. A Deployment that makes sure a Pod is running that contains the
@@ -116,7 +115,7 @@ Operator.
 * [Charmed Operator Framework](https://juju.is/)
 * [kubebuilder](https://book.kubebuilder.io/)
 * [KUDO](https://kudo.dev/) (Kubernetes Universal Declarative Operator)
-* [Metacontroller](https://metacontroller.app/) along with WebHooks that
+* [Metacontroller](https://metacontroller.github.io/metacontroller/intro.html) along with WebHooks that
  you implement yourself
 * [Operator Framework](https://operatorframework.io)
 * [shell-operator](https://github.com/flant/shell-operator)
@@ -124,6 +123,7 @@ Operator.
 ## {{% heading "whatsnext" %}}


+* Read the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} [Operator White Paper](https://github.com/cncf/tag-app-delivery/blob/eece8f7307f2970f46f100f51932db106db46968/operator-wg/whitepaper/Operator-WhitePaper_v1-0.md).
 * Learn more about [Custom Resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
 * Find ready-made operators on [OperatorHub.io](https://operatorhub.io/) to suit your use case
 * [Publish](https://operatorhub.io/) your operator for other people to use
@@ -10,7 +10,8 @@ weight: 40

 {{< feature-state for_k8s_version="v1.20" state="stable" >}}

-Kubernetes allow you to limit the number of process IDs (PIDs) that a {{< glossary_tooltip term_id="Pod" text="Pod" >}} can use.
+Kubernetes allow you to limit the number of process IDs (PIDs) that a
+{{< glossary_tooltip term_id="Pod" text="Pod" >}} can use.
 You can also reserve a number of allocatable PIDs for each {{< glossary_tooltip term_id="node" text="node" >}}
 for use by the operating system and daemons (rather than by Pods).

@@ -84,7 +85,9 @@ gate](/docs/reference/command-line-tools-reference/feature-gates/)
 Kubernetes allows you to limit the number of processes running in a Pod. You
 specify this limit at the node level, rather than configuring it as a resource
 limit for a particular Pod. Each Node can have a different PID limit.  
-To configure the limit, you can specify the command line parameter `--pod-max-pids` to the kubelet, or set `PodPidsLimit` in the kubelet [configuration file](/docs/tasks/administer-cluster/kubelet-config-file/).
+To configure the limit, you can specify the command line parameter `--pod-max-pids`
+to the kubelet, or set `PodPidsLimit` in the kubelet
+[configuration file](/docs/tasks/administer-cluster/kubelet-config-file/).

 {{< note >}}
 Before Kubernetes version 1.20, PID resource limiting for Pods required enabling
@@ -95,9 +98,12 @@ the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
 ## PID based eviction

 You can configure kubelet to start terminating a Pod when it is misbehaving and consuming abnormal amount of resources.
-This feature is called eviction. You can [Configure Out of Resource Handling](/docs/tasks/administer-cluster/out-of-resource) for various eviction signals.
+This feature is called eviction. You can
+[Configure Out of Resource Handling](/docs/concepts/scheduling-eviction/node-pressure-eviction/)
+for various eviction signals.
 Use `pid.available` eviction signal to configure the threshold for number of PIDs used by Pod.
-You can set soft and hard eviction policies. However, even with the hard eviction policy, if the number of PIDs growing very fast,
+You can set soft and hard eviction policies.
+However, even with the hard eviction policy, if the number of PIDs growing very fast,
 node can still get into unstable state by hitting the node PIDs limit.
 Eviction signal value is calculated periodically and does NOT enforce the limit.

@@ -112,6 +118,7 @@ when one Pod is misbehaving.
 ## {{% heading "whatsnext" %}}

 - Refer to the [PID Limiting enhancement document](https://github.com/kubernetes/enhancements/blob/097b4d8276bc9564e56adf72505d43ce9bc5e9e8/keps/sig-node/20190129-pid-limiting.md) for more information.
- For historical context, read [Process ID Limiting for Stability Improvements in Kubernetes 1.14](/blog/2019/04/15/process-id-limiting-for-stability-improvements-in-kubernetes-1.14/).
+- For historical context, read
+  [Process ID Limiting for Stability Improvements in Kubernetes 1.14](/blog/2019/04/15/process-id-limiting-for-stability-improvements-in-kubernetes-1.14/).
 - Read [Managing Resources for Containers](/docs/concepts/configuration/manage-resources-containers/).
- Learn how to [Configure Out of Resource Handling](/docs/tasks/administer-cluster/out-of-resource).
+- Learn how to [Configure Out of Resource Handling](/docs/concepts/scheduling-eviction/node-pressure-eviction/).
@@ -11,7 +11,8 @@ weight: 30

 {{< feature-state for_k8s_version="v1.21" state="deprecated" >}}

-PodSecurityPolicy is deprecated as of Kubernetes v1.21, and will be removed in v1.25.
+PodSecurityPolicy is deprecated as of Kubernetes v1.21, and will be removed in v1.25. For more information on the deprecation,
+see [PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).

 Pod Security Policies enable fine-grained authorization of pod creation and
 updates.
@@ -48,13 +49,12 @@ administrator to control the following:

 ## Enabling Pod Security Policies

-Pod security policy control is implemented as an optional (but recommended)
-[admission
-controller](/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy). PodSecurityPolicies
-are enforced by [enabling the admission
+Pod security policy control is implemented as an optional [admission
+controller](/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy).
+PodSecurityPolicies are enforced by [enabling the admission
 controller](/docs/reference/access-authn-authz/admission-controllers/#how-do-i-turn-on-an-admission-control-plug-in),
-but doing so without authorizing any policies **will prevent any pods from being
-created** in the cluster.
+but doing so without authorizing any policies **will prevent any pods from being created** in the
+cluster.

 Since the pod security policy API (`policy/v1beta1/podsecuritypolicy`) is
 enabled independently of the admission controller, for existing clusters it is
@@ -110,7 +110,11 @@ roleRef:
  name: <role name>
  apiGroup: rbac.authorization.k8s.io
 subjects:
-# Authorize specific service accounts:
+# Authorize all service accounts in a namespace (recommended):
+- kind: Group
+  apiGroup: rbac.authorization.k8s.io
+  name: system:serviceaccounts:<authorized namespace>
+# Authorize specific service accounts (not recommended):
 - kind: ServiceAccount
  name: <authorized service account name>
  namespace: <authorized pod namespace>
@@ -139,6 +143,40 @@ Examples](/docs/reference/access-authn-authz/rbac#role-binding-examples).
 For a complete example of authorizing a PodSecurityPolicy, see
 [below](#example).

+### Recommended Practice
+
+PodSecurityPolicy is being replaced by a new, simplified `PodSecurity` {{< glossary_tooltip
+text="admission controller" term_id="admission-controller" >}}. For more details on this change, see
+[PodSecurityPolicy Deprecation: Past, Present, and
+Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/). Follow these
+guidelines to simplify migration from PodSecurityPolicy to the new admission controller:
+
+1. Limit your PodSecurityPolicies to the policies defined by the [Pod Security Standards](/docs/concepts/security/pod-security-standards):
+    - {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}}
+    - {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}}
+    - {{< example file="policy/restricted-psp.yaml" >}}Restricted{{< /example >}}
+
+2. Only bind PSPs to entire namespaces, by using the `system:serviceaccounts:<namespace>` group
+   (where `<namespace>` is the target namespace). For example:
+
+    ```yaml
+    apiVersion: rbac.authorization.k8s.io/v1
+    # This cluster role binding allows all pods in the "development" namespace to use the baseline PSP.
+    kind: ClusterRoleBinding
+    metadata:
+      name: psp-baseline-namespaces
+    roleRef:
+      kind: ClusterRole
+      name: psp-baseline
+      apiGroup: rbac.authorization.k8s.io
+    subjects:
+    - kind: Group
+      name: system:serviceaccounts:development
+      apiGroup: rbac.authorization.k8s.io
+    - kind: Group
+      name: system:serviceaccounts:canary
+      apiGroup: rbac.authorization.k8s.io
+    ```

 ### Troubleshooting

@@ -661,8 +699,10 @@ Refer to the [Sysctl documentation](

 ## {{% heading "whatsnext" %}}

+- See [PodSecurityPolicy Deprecation: Past, Present, and
+  Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/) to learn about
+  the future of pod security policy.
+
 - See [Pod Security Standards](/docs/concepts/security/pod-security-standards/) for policy recommendations.

 - Refer to [Pod Security Policy Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicy-v1beta1-policy) for the api details.
-
-
@@ -57,8 +57,9 @@ Neither contention nor changes to quota will affect already created resources.

 ## Enabling Resource Quota

-Resource Quota support is enabled by default for many Kubernetes distributions.  It is
-enabled when the {{< glossary_tooltip text="API server" term_id="kube-apiserver" >}} `--enable-admission-plugins=` flag has `ResourceQuota` as
+Resource Quota support is enabled by default for many Kubernetes distributions. It is
+enabled when the {{< glossary_tooltip text="API server" term_id="kube-apiserver" >}}
+`--enable-admission-plugins=` flag has `ResourceQuota` as
 one of its arguments.

 A resource quota is enforced in a particular namespace when there is a
@@ -66,7 +67,9 @@ ResourceQuota in that namespace.

 ## Compute Resource Quota

-You can limit the total sum of [compute resources](/docs/concepts/configuration/manage-resources-containers/) that can be requested in a given namespace.
+You can limit the total sum of
+[compute resources](/docs/concepts/configuration/manage-resources-containers/)
+that can be requested in a given namespace.

 The following resource types are supported:

@@ -125,7 +128,9 @@ In release 1.8, quota support for local ephemeral storage is added as an alpha f
 | `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.
+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
@@ -192,7 +197,7 @@ Resources specified on the quota outside of the allowed set results in a validat
 | `NotTerminating` | Match pods where `.spec.activeDeadlineSeconds is nil` |
 | `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). |
+| `PriorityClass` | Match pods that references the specified [priority class](/docs/concepts/scheduling-eviction/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:
@@ -248,13 +253,14 @@ specified.

 {{< feature-state for_k8s_version="v1.17" state="stable" >}}

-Pods can be created at a specific [priority](/docs/concepts/configuration/pod-priority-preemption/#pod-priority).
+Pods can be created at a specific [priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/#pod-priority).
 You can control a pod's consumption of system resources based on a pod's priority, by using the `scopeSelector`
 field in the quota spec.

 A quota is matched and consumed only if `scopeSelector` in the quota spec selects the pod.

-When quota is scoped for priority class using `scopeSelector` field, quota object is restricted to track only following resources:
+When quota is scoped for priority class using `scopeSelector` field, quota object
+is restricted to track only following resources:

 * `pods`
 * `cpu`
@@ -554,7 +560,7 @@ kubectl create -f ./object-counts.yaml --namespace=myspace
 kubectl get quota --namespace=myspace
 ```

-```
+```none
 NAME                    AGE
 compute-resources       30s
 object-counts           32s
@@ -564,7 +570,7 @@ object-counts           32s
 kubectl describe quota compute-resources --namespace=myspace
 ```

-```
+```none
 Name:                    compute-resources
 Namespace:               myspace
 Resource                 Used  Hard
@@ -580,7 +586,7 @@ requests.nvidia.com/gpu  0     4
 kubectl describe quota object-counts --namespace=myspace
 ```

-```
+```none
 Name:                   object-counts
 Namespace:              myspace
 Resource                Used    Hard
@@ -677,10 +683,10 @@ Then, create a resource quota object in the `kube-system` namespace:
 {{< codenew file="policy/priority-class-resourcequota.yaml" >}}

 ```shell
-$ kubectl apply -f https://k8s.io/examples/policy/priority-class-resourcequota.yaml -n kube-system
+kubectl apply -f https://k8s.io/examples/policy/priority-class-resourcequota.yaml -n kube-system
 ```

-```
+```none
 resourcequota/pods-cluster-services created
 ```

@@ -193,7 +193,7 @@ resources based on the filesystems on the node.
 If the node has a dedicated `imagefs` filesystem for container runtimes to use,
 the kubelet does the following:

-  * If the `nodefs` filesystem meets the eviction threshlds, the kubelet garbage collects
+  * If the `nodefs` filesystem meets the eviction thresholds, the kubelet garbage collects
    dead pods and containers. 
  * If the `imagefs` filesystem meets the eviction thresholds, the kubelet
    deletes all unused images. 
@@ -214,7 +214,7 @@ signal below the threshold, the kubelet begins to evict end-user pods.
 The kubelet uses the following parameters to determine pod eviction order:

 1. Whether the pod's resource usage exceeds requests
-1. [Pod Priority](/docs/concepts/configuration/pod-priority-preemption/)
+1. [Pod Priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/)
 1. The pod's resource usage relative to requests

 As a result, kubelet ranks and evicts pods in the following order:
@@ -252,12 +252,12 @@ Even so, the answer to the preceding question must be yes. If the answer is no,
 the Node is not considered for preemption.
 {{< /note >}}

-If a pending Pod has inter-pod affinity to one or more of the lower-priority
-Pods on the Node, the inter-Pod affinity rule cannot be satisfied in the absence
-of those lower-priority Pods. In this case, the scheduler does not preempt any
-Pods on the Node. Instead, it looks for another Node. The scheduler might find a
-suitable Node or it might not. There is no guarantee that the pending Pod can be
-scheduled.
+If a pending Pod has inter-pod {{< glossary_tooltip text="affinity" term_id="affinity" >}}
+to one or more of the lower-priority Pods on the Node, the inter-Pod affinity
+rule cannot be satisfied in the absence of those lower-priority Pods. In this case, 
+the scheduler does not preempt any Pods on the Node. Instead, it looks for another
+Node. The scheduler might find a suitable Node or it might not. There is no 
+guarantee that the pending Pod can be scheduled.

 Our recommended solution for this problem is to create inter-Pod affinity only
 towards equal or higher priority Pods.
@@ -266,9 +266,23 @@ This ensures that DaemonSet pods are never evicted due to these problems.

 ## Taint Nodes by Condition

-The node lifecycle controller automatically creates taints corresponding to
-Node conditions with `NoSchedule` effect.
-Similarly the scheduler does not check Node conditions; instead the scheduler checks taints. This assures that Node conditions don't affect what's scheduled onto the Node. The user can choose to ignore some of the Node's problems (represented as Node conditions) by adding appropriate Pod tolerations.
+The control plane, using the node {{<glossary_tooltip text="controller" term_id="controller">}},
+automatically creates taints with a `NoSchedule` effect for [node conditions](/docs/concepts/scheduling-eviction/pod-eviction#node-conditions).
+
+The scheduler checks taints, not node conditions, when it makes scheduling
+decisions. This ensures that node conditions don't directly affect scheduling.
+For example, if the `DiskPressure` node condition is active, the control plane
+adds the `node.kubernetes.io/disk-pressure` taint and does not schedule new pods
+onto the affected node. If the `MemoryPressure` node condition is active, the
+control plane adds the `node.kubernetes.io/memory-pressure` taint. 
+
+You can ignore node conditions for newly created pods by adding the corresponding
+Pod tolerations. The control plane also adds the `node.kubernetes.io/memory-pressure` 
+toleration on pods that have a {{< glossary_tooltip text="QoS class" term_id="qos-class" >}} 
+other than `BestEffort`. This is because Kubernetes treats pods in the `Guaranteed` 
+or `Burstable` QoS classes (even pods with no memory request set) as if they are
+able to cope with memory pressure, while new `BestEffort` pods are not scheduled
+onto the affected node. 

 The DaemonSet controller automatically adds the following `NoSchedule`
 tolerations to all daemons, to prevent DaemonSets from breaking.
@@ -282,10 +296,9 @@ tolerations to all daemons, to prevent DaemonSets from breaking.
 Adding these tolerations ensures backward compatibility. You can also add
 arbitrary tolerations to DaemonSets.

-
 ## {{% heading "whatsnext" %}}

-* Read about [out of resource handling](/docs/tasks/administer-cluster/out-of-resource/) and how you can configure it
-* Read about [pod priority](/docs/concepts/configuration/pod-priority-preemption/)
+* Read about [out of resource handling](/docs/concepts/scheduling-eviction/out-of-resource/) and how you can configure it
+* Read about [pod priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/)


@@ -86,7 +86,7 @@ enforced/disallowed:
 		<tr>
 			<td>Capabilities</td>
 			<td>
-				Adding additional capabilities beyond the <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">default set</a> must be disallowed.<br>
+				Adding <tt>NET_RAW</tt> or capabilities beyond the <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">default set</a> must be disallowed.<br>
 				<br><b>Restricted Fields:</b><br>
 				spec.containers[*].securityContext.capabilities.add<br>
 				spec.initContainers[*].securityContext.capabilities.add<br>
@@ -194,7 +194,7 @@ well as lower-trust users.The following listed controls should be enforced/disal
 		<tr>
 			<td>Volume Types</td>
 			<td>
-				In addition to restricting HostPath volumes, the restricted profile limits usage of non-core volume types to those defined through PersistentVolumes.<br>
+				In addition to restricting HostPath volumes, the restricted profile limits usage of non-ephemeral volume types to those defined through PersistentVolumes.<br>
 				<br><b>Restricted Fields:</b><br>
 				spec.volumes[*].hostPath<br>
 				spec.volumes[*].gcePersistentDisk<br>
@@ -216,7 +216,6 @@ well as lower-trust users.The following listed controls should be enforced/disal
 				spec.volumes[*].portworxVolume<br>
 				spec.volumes[*].scaleIO<br>
 				spec.volumes[*].storageos<br>
-				spec.volumes[*].csi<br>
 				<br><b>Allowed Values:</b> undefined/nil<br>
 			</td>
 		</tr>
@@ -283,9 +282,9 @@ of individual policies are not defined here.

 [**PodSecurityPolicy**](/docs/concepts/policy/pod-security-policy/)

- [Privileged](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/privileged-psp.yaml)
- [Baseline](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/baseline-psp.yaml)
- [Restricted](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/restricted-psp.yaml)
+- {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}}
+- {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}}
+- {{< example file="policy/restricted-psp.yaml" >}}Restricted{{< /example >}}

 ## FAQ

@@ -50,7 +50,7 @@ options ndots:5
 ```

 In summary, a pod in the _test_ namespace can successfully resolve either 
-`data.prod` or `data.prod.cluster.local`.
+`data.prod` or `data.prod.svc.cluster.local`.

 ### DNS Records

@@ -249,5 +249,4 @@ implementation in `kube-proxy`.

 ## {{% heading "whatsnext" %}}

-* Learn about [Enabling EndpointSlices](/docs/tasks/administer-cluster/enabling-endpointslices)
 * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/)
@@ -215,7 +215,7 @@ each Service port. The value of this field is mirrored by the corresponding
 Endpoints and EndpointSlice objects.

 This field follows standard Kubernetes label syntax. Values should either be
-[IANA standard service names](http://www.iana.org/assignments/service-names) or
+[IANA standard service names](https://www.iana.org/assignments/service-names) or
 domain prefixed names such as `mycompany.com/my-custom-protocol`.

 ## Virtual IPs and service proxies
@@ -189,7 +189,7 @@ and pre-created PVs, but you'll need to look at the documentation for a specific
 to see its supported topology keys and examples.

 {{< note >}}
-   If you choose to use `waitForFirstConsumer`, do not use `nodeName` in the Pod spec
+   If you choose to use `WaitForFirstConsumer`, do not use `nodeName` in the Pod spec
   to specify node affinity. If `nodeName` is used in this case, the scheduler will be bypassed and PVC will remain in `pending` state.

   Instead, you can use node selector for hostname in this case as shown below.
@@ -658,11 +658,11 @@ metadata:
 provisioner: kubernetes.io/azure-disk
 parameters:
  storageaccounttype: Standard_LRS
-  kind: Shared
+  kind: managed
 ```

 * `storageaccounttype`: Azure storage account Sku tier. Default is empty.
-* `kind`: Possible values are `shared` (default), `dedicated`, and `managed`.
+* `kind`: Possible values are `shared`, `dedicated`, and `managed` (default).
  When `kind` is `shared`, all unmanaged disks are created in a few shared
  storage accounts in the same resource group as the cluster. When `kind` is
  `dedicated`, a new dedicated storage account will be created for the new
@@ -529,6 +529,15 @@ See the [GlusterFS example](https://github.com/kubernetes/examples/tree/{{< para

 ### hostPath {#hostpath}

+{{< warning >}}
+HostPath volumes present many security risks, and it is a best practice to avoid the use of
+HostPaths when possible. When a HostPath volume must be used, it should be scoped to only the
+required file or directory, and mounted as ReadOnly.
+
+If restricting HostPath access to specific directories through AdmissionPolicy, `volumeMounts` MUST
+be required to use `readOnly` mounts for the policy to be effective.
+{{< /warning >}}
+
 A `hostPath` volume mounts a file or directory from the host node's filesystem
 into your Pod. This is not something that most Pods will need, but it offers a
 powerful escape hatch for some applications.
@@ -558,6 +567,9 @@ The supported values for field `type` are:

 Watch out when using this type of volume, because:

+* HostPaths can expose privileged system credentials (such as for the Kubelet) or privileged APIs
+  (such as container runtime socket), which can be used for container escape or to attack other
+  parts of the cluster.
 * Pods with identical configuration (such as created from a PodTemplate) may
  behave differently on different nodes due to different files on the nodes
 * The files or directories created on the underlying hosts are only writable by root. You
@@ -32,7 +32,8 @@ different flags and/or different memory and cpu requests for different hardware

 ### Create a DaemonSet

-You can describe a DaemonSet in a YAML file. For example, the `daemonset.yaml` file below describes a DaemonSet that runs the fluentd-elasticsearch Docker image:
+You can describe a DaemonSet in a YAML file. For example, the `daemonset.yaml` file below
+describes a DaemonSet that runs the fluentd-elasticsearch Docker image:

 {{< codenew file="controllers/daemonset.yaml" >}}

@@ -46,19 +47,23 @@ kubectl apply -f https://k8s.io/examples/controllers/daemonset.yaml

 As with all other Kubernetes config, a DaemonSet needs `apiVersion`, `kind`, and `metadata` fields.  For
 general information about working with config files, see
-[running stateless applications](/docs/tasks/run-application/run-stateless-application-deployment/),
-[configuring containers](/docs/tasks/), and [object management using kubectl](/docs/concepts/overview/working-with-objects/object-management/) documents.
+[running stateless applications](/docs/tasks/run-application/run-stateless-application-deployment/)
+and [object management using kubectl](/docs/concepts/overview/working-with-objects/object-management/).

 The name of a DaemonSet object must be a valid
 [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).

-A DaemonSet also needs a [`.spec`](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) section.
+A DaemonSet also needs a
+[`.spec`](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status)
+section.

 ### Pod Template

 The `.spec.template` is one of the required fields in `.spec`.

-The `.spec.template` is a [pod template](/docs/concepts/workloads/pods/#pod-templates). It has exactly the same schema as a {{< glossary_tooltip text="Pod" term_id="pod" >}}, except it is nested and does not have an `apiVersion` or `kind`.
+The `.spec.template` is a [pod template](/docs/concepts/workloads/pods/#pod-templates).
+It has exactly the same schema as a {{< glossary_tooltip text="Pod" term_id="pod" >}},
+except it is nested and does not have an `apiVersion` or `kind`.

 In addition to required fields for a Pod, a Pod template in a DaemonSet has to specify appropriate
 labels (see [pod selector](#pod-selector)).
@@ -79,20 +84,23 @@ unintentional orphaning of Pods, and it was found to be confusing to users.

 The `.spec.selector` is an object consisting of two fields:

-* `matchLabels` - works the same as the `.spec.selector` of a [ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/).
+* `matchLabels` - works the same as the `.spec.selector` of a
+  [ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/).
 * `matchExpressions` - allows to build more sophisticated selectors by specifying key,
  list of values and an operator that relates the key and values.

 When the two are specified the result is ANDed.

-If the `.spec.selector` is specified, it must match the `.spec.template.metadata.labels`. Config with these not matching will be rejected by the API.
+If the `.spec.selector` is specified, it must match the `.spec.template.metadata.labels`.
+Config with these not matching will be rejected by the API.

 ### Running Pods on select Nodes

 If you specify a `.spec.template.spec.nodeSelector`, then the DaemonSet controller will
-create Pods on nodes which match that [node
-selector](/docs/concepts/scheduling-eviction/assign-pod-node/). Likewise if you specify a `.spec.template.spec.affinity`,
-then DaemonSet controller will create Pods on nodes which match that [node affinity](/docs/concepts/scheduling-eviction/assign-pod-node/).
+create Pods on nodes which match that [node selector](/docs/concepts/scheduling-eviction/assign-pod-node/).
+Likewise if you specify a `.spec.template.spec.affinity`,
+then DaemonSet controller will create Pods on nodes which match that
+[node affinity](/docs/concepts/scheduling-eviction/assign-pod-node/).
 If you do not specify either, then the DaemonSet controller will create Pods on all nodes.

 ## How Daemon Pods are scheduled
@@ -106,18 +114,19 @@ node that a Pod runs on is selected by the Kubernetes scheduler. However,
 DaemonSet pods are created and scheduled by the DaemonSet controller instead.
 That introduces the following issues:

- * Inconsistent Pod behavior: Normal Pods waiting to be scheduled are created
-   and in `Pending` state, but DaemonSet pods are not created in `Pending`
-   state. This is confusing to the user.
- * [Pod preemption](/docs/concepts/configuration/pod-priority-preemption/)
-   is handled by default scheduler. When preemption is enabled, the DaemonSet controller
-   will make scheduling decisions without considering pod priority and preemption.
+* Inconsistent Pod behavior: Normal Pods waiting to be scheduled are created
+  and in `Pending` state, but DaemonSet pods are not created in `Pending`
+  state. This is confusing to the user.
+* [Pod preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/)
+  is handled by default scheduler. When preemption is enabled, the DaemonSet controller
+  will make scheduling decisions without considering pod priority and preemption.

 `ScheduleDaemonSetPods` allows you to schedule DaemonSets using the default
 scheduler instead of the DaemonSet controller, by adding the `NodeAffinity` term
 to the DaemonSet pods, instead of the `.spec.nodeName` term. The default
 scheduler is then used to bind the pod to the target host. If node affinity of
-the DaemonSet pod already exists, it is replaced (the original node affinity was taken into account before selecting the target host). The DaemonSet controller only
+the DaemonSet pod already exists, it is replaced (the original node affinity was
+taken into account before selecting the target host). The DaemonSet controller only
 performs these operations when creating or modifying DaemonSet pods, and no
 changes are made to the `spec.template` of the DaemonSet.

@@ -158,10 +167,12 @@ Some possible patterns for communicating with Pods in a DaemonSet are:

 - **Push**: Pods in the DaemonSet are configured to send updates to another service, such
  as a stats database.  They do not have clients.
- **NodeIP and Known Port**: Pods in the DaemonSet can use a `hostPort`, so that the pods are reachable via the node IPs.  Clients know the list of node IPs somehow, and know the port by convention.
- **DNS**: Create a [headless service](/docs/concepts/services-networking/service/#headless-services) with the same pod selector,
-  and then discover DaemonSets using the `endpoints` resource or retrieve multiple A records from
-  DNS.
+- **NodeIP and Known Port**: Pods in the DaemonSet can use a `hostPort`, so that the pods
+  are reachable via the node IPs.
+  Clients know the list of node IPs somehow, and know the port by convention.
+- **DNS**: Create a [headless service](/docs/concepts/services-networking/service/#headless-services)
+  with the same pod selector, and then discover DaemonSets using the `endpoints`
+  resource or retrieve multiple A records from DNS.
 - **Service**: Create a service with the same Pod selector, and use the service to reach a
  daemon on a random node. (No way to reach specific node.)

@@ -86,7 +86,7 @@ rolling out node software updates can cause voluntary disruptions. Also, some im
 of cluster (node) autoscaling may cause voluntary disruptions to defragment and compact nodes.
 Your cluster administrator or hosting provider should have documented what level of voluntary
 disruptions, if any, to expect. Certain configuration options, such as
-[using PriorityClasses](/docs/concepts/configuration/pod-priority-preemption/)
+[using PriorityClasses](/docs/concepts/scheduling-eviction/pod-priority-preemption/)
 in your pod spec can also cause voluntary (and involuntary) disruptions.


@@ -16,7 +16,7 @@ You can use _topology spread constraints_ to control how {{< glossary_tooltip te
 In versions of Kubernetes before v1.18, you must enable the `EvenPodsSpread`
 [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) on
 the [API server](/docs/concepts/overview/components/#kube-apiserver) and the
-[scheduler](/docs/reference/generated/kube-scheduler/) in order to use Pod
+[scheduler](/docs/reference/command-line-tools-reference/kube-scheduler/) in order to use Pod
 topology spread constraints.
 {{< /note >}}

@@ -82,12 +82,11 @@ spec:
 You can define one or multiple `topologySpreadConstraint` to instruct the kube-scheduler how to place each incoming Pod in relation to the existing Pods across your cluster. The fields are:

 - **maxSkew** describes the degree to which Pods may be unevenly distributed.
-  It's the maximum permitted difference between the number of matching Pods in
-  any two topology domains of a given topology type. It must be greater than
-  zero. Its semantics differs according to the value of `whenUnsatisfiable`:
+  It must be greater than zero. Its semantics differs according to the value of `whenUnsatisfiable`:
  - when `whenUnsatisfiable` equals to "DoNotSchedule", `maxSkew` is the maximum
    permitted difference between the number of matching pods in the target
-    topology and the global minimum.
+    topology and the global minimum 
+    (the minimum number of pods that match the label selector in a topology domain. For example, if you have 3 zones with 0, 2 and 3 matching pods respectively, The global minimum is 0).
  - when `whenUnsatisfiable` equals to "ScheduleAnyway", scheduler gives higher
    precedence to topologies that would help reduce the skew.
 - **topologyKey** is the key of node labels. If two Nodes are labelled with this key and have identical values for that label, the scheduler treats both Nodes as being in the same topology. The scheduler tries to place a balanced number of Pods into each topology domain.
@@ -96,6 +95,8 @@ You can define one or multiple `topologySpreadConstraint` to instruct the kube-s
  - `ScheduleAnyway` tells the scheduler to still schedule it while prioritizing nodes that minimize the skew.
 - **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. See [Label Selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors) for more details.

+When a Pod defines more than one `topologySpreadConstraint`, those constraints are ANDed: The kube-scheduler looks for a node for the incoming Pod that satisfies all the constraints.
+
 You can read more about this field by running `kubectl explain Pod.spec.topologySpreadConstraints`.

 ### Example: One TopologySpreadConstraint
@@ -387,7 +388,8 @@ for more details.

 ## Known Limitations

- Scaling down a Deployment may result in imbalanced Pods distribution.
+- There's no guarantee that the constraints remain satisfied when Pods are removed. For example, scaling down a Deployment may result in imbalanced Pods distribution. 
+You can use [Descheduler](https://github.com/kubernetes-sigs/descheduler) to rebalance the Pods distribution.
 - Pods matched on tainted nodes are respected. See [Issue 80921](https://github.com/kubernetes/kubernetes/issues/80921)

 ## {{% heading "whatsnext" %}}
@@ -18,8 +18,8 @@ the build setup and generates the reference documentation for a release.

 ## Getting the docs repository

-Make sure your `website` fork is up-to-date with the `kubernetes/website` master and clone
-your `website` fork.
+Make sure your `website` fork is up-to-date with the `kubernetes/website` remote on
+GitHub (`main` branch), and clone your `website` fork.

 ```shell
 mkdir github.com
@@ -171,7 +171,7 @@ For example:
 The `release.yml` configuration file contains instructions to fix relative links.
 To fix relative links within your imported files, set the`gen-absolute-links`
 property to `true`. You can find an example of this in
-[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml).
+[`release.yml`](https://github.com/kubernetes/website/blob/main/update-imported-docs/release.yml).

 ## Adding and committing changes in kubernetes/website

@@ -98,7 +98,7 @@ Once you've opened a localization PR, you can become members of the Kubernetes G

 ### Add your localization team in GitHub

-Next, add your Kubernetes localization team to [`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml). For an example of adding a localization team, see the PR to add the [Spanish localization team](https://github.com/kubernetes/org/pull/685).
+Next, add your Kubernetes localization team to [`sig-docs/teams.yaml`](https://github.com/kubernetes/org/blob/main/config/kubernetes/sig-docs/teams.yaml). For an example of adding a localization team, see the PR to add the [Spanish localization team](https://github.com/kubernetes/org/pull/685).

 Members of `@kubernetes/sig-docs-**-owners` can approve PRs that change content within (and only within) your localization directory: `/content/**/`.

@@ -117,7 +117,7 @@ For an example of adding a label, see the PR for adding the [Italian language la

 ### Modify the site configuration

-The Kubernetes website uses Hugo as its web framework. The website's Hugo configuration resides in the  [`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml) file. To support a new localization, you'll need to modify `config.toml`.
+The Kubernetes website uses Hugo as its web framework. The website's Hugo configuration resides in the  [`config.toml`](https://github.com/kubernetes/website/tree/main/config.toml) file. To support a new localization, you'll need to modify `config.toml`.

 Add a configuration block for the new language to `config.toml`, under the existing `[languages]` block. The German block, for example, looks like:

@@ -136,7 +136,7 @@ For more information about Hugo's multilingual support, see "[Multilingual Mode]

 ### Add a new localization directory

-Add a language-specific subdirectory to the [`content`](https://github.com/kubernetes/website/tree/master/content) folder in the repository. For example, the two-letter code for German is `de`:
+Add a language-specific subdirectory to the [`content`](https://github.com/kubernetes/website/tree/main/content) folder in the repository. For example, the two-letter code for German is `de`:

 ```shell
 mkdir content/de
@@ -219,7 +219,7 @@ For an example of adding a new localization, see the PR to enable [docs in Frenc

 ### Add a localized README file

-To guide other localization contributors, add a new [`README-**.md`](https://help.github.com/articles/about-readmes/) to the top level of k/website, where `**` is the two-letter language code. For example, a German README file would be `README-de.md`.
+To guide other localization contributors, add a new [`README-**.md`](https://help.github.com/articles/about-readmes/) to the top level of [k/website](https://github.com/kubernetes/website/), where `**` is the two-letter language code. For example, a German README file would be `README-de.md`.

 Provide guidance to localization contributors in the localized `README-**.md` file. Include the same information contained in `README.md` as well as:

@@ -276,15 +276,15 @@ To find source files for your target version:
 2. Select a branch for your target version from the following table:
    Target version | Branch
    -----|-----
-    Latest version | [`master`](https://github.com/kubernetes/website/tree/master)
+    Latest version | [`main`](https://github.com/kubernetes/website/tree/main)
    Previous version | [`release-{{< skew prevMinorVersion >}}`](https://github.com/kubernetes/website/tree/release-{{< skew prevMinorVersion >}})
    Next version | [`dev-{{< skew nextMinorVersion >}}`](https://github.com/kubernetes/website/tree/dev-{{< skew nextMinorVersion >}})

-The `master` branch holds content for the current release `{{< latest-version >}}`. The release team will create a `{{< release-branch >}}` branch before the next release: v{{< skew nextMinorVersion >}}.
+The `main` branch holds content for the current release `{{< latest-version >}}`. The release team will create a `{{< release-branch >}}` branch before the next release: v{{< skew nextMinorVersion >}}.

 ### Site strings in i18n

-Localizations must include the contents of [`data/i18n/en/en.toml`](https://github.com/kubernetes/website/blob/master/data/i18n/en/en.toml) in a new language-specific file. Using German as an example: `data/i18n/de/de.toml`.
+Localizations must include the contents of [`data/i18n/en/en.toml`](https://github.com/kubernetes/website/blob/main/data/i18n/en/en.toml) in a new language-specific file. Using German as an example: `data/i18n/de/de.toml`.

 Add a new localization directory and file to `data/i18n/`. For example, with German (`de`):

@@ -339,14 +339,14 @@ Repeat steps 1-4 as needed until the localization is complete. For example, subs
 Teams must merge localized content into the same branch from which the content was sourced.

 For example:
- a localization branch sourced from `master` must be merged into `master`.
- a localization branch sourced from `release-1.19` must be merged into `release-1.19`.
+- a localization branch sourced from `main` must be merged into `main`.
+- a localization branch sourced from `release-{{ skew "prevMinorVersion" }}` must be merged into `release-{{ skew "prevMinorVersion" }}`.

 {{< note >}}
-If your localization branch was created from `master` branch but it is not merged into `master` before new release branch `{{< release-branch >}}` created, merge it into both `master` and new release branch `{{< release-branch >}}`. To merge your localization branch into new release branch `{{< release-branch >}}`, you need to switch upstream branch of your localization branch to `{{< release-branch >}}`.
+If your localization branch was created from `main` branch but it is not merged into `main` before new release branch `{{< release-branch >}}` created, merge it into both `main` and new release branch `{{< release-branch >}}`. To merge your localization branch into new release branch `{{< release-branch >}}`, you need to switch upstream branch of your localization branch to `{{< release-branch >}}`.
 {{< /note >}}

-At the beginning of every team milestone, it's helpful to open an issue comparing upstream changes between the previous localization branch and the current localization branch. There are two scripts for comparing upstream changes. [`upstream_changes.py`](https://github.com/kubernetes/website/tree/master/scripts#upstream_changespy) is useful for checking the changes made to a specific file. And [`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/master/scripts#diff_l10n_branchespy) is useful for creating a list of outdated files for a specific localization branch.
+At the beginning of every team milestone, it's helpful to open an issue comparing upstream changes between the previous localization branch and the current localization branch. There are two scripts for comparing upstream changes. [`upstream_changes.py`](https://github.com/kubernetes/website/tree/main/scripts#upstream_changespy) is useful for checking the changes made to a specific file. And [`diff_l10n_branches.py`](https://github.com/kubernetes/website/tree/main/scripts#diff_l10n_branchespy) is useful for creating a list of outdated files for a specific localization branch.

 While only approvers can open a new localization branch and merge pull requests, anyone can open a pull request for a new localization branch. No special permissions are required.

@@ -40,7 +40,7 @@ Anyone can write a blog post and submit it for review.
    - Many CNCF projects have their own blog. These are often a better choice for posts. There are times of major feature or milestone for a CNCF project that users would be interested in reading on the Kubernetes blog.
 - Blog posts should be original content
  - The official blog is not for repurposing existing content from a third party as new content.
-  - The [license](https://github.com/kubernetes/website/blob/master/LICENSE) for the blog allows commercial use of the content for commercial purposes, but not the other way around.
+  - The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows commercial use of the content for commercial purposes, but not the other way around.
 - Blog posts should aim to be future proof
  - Given the development velocity of the project, we want evergreen content that won't require updates to stay accurate for the reader. 
  - It can be a better choice to add a tutorial or update official documentation than to write a high level overview as a blog post.
@@ -56,7 +56,7 @@ The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/mast

 To submit a blog post follow these directions:

- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts) directory.
+- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post. New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts) directory.

 - Ensure that your blog post follows the correct naming conventions and the following frontmatter (metadata) information:

@@ -90,6 +90,6 @@ Case studies highlight how organizations are using Kubernetes to solve
 real-world problems. The Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}} collaborate with you on all case studies.

 Have a look at the source for the
-[existing case studies](https://github.com/kubernetes/website/tree/master/content/en/case-studies).
+[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies).

 Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md) and submit your request as outlined in the guidelines.
@@ -127,7 +127,7 @@ Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installi
    upstream	https://github.com/kubernetes/website.git (push)
    ```

-6. Fetch commits from your fork's `origin/master` and `kubernetes/website`'s `upstream/master`:
+6. Fetch commits from your fork's `origin/main` and `kubernetes/website`'s `upstream/main`:

    ```bash
    git fetch origin
@@ -137,15 +137,15 @@ Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installi
    This makes sure your local repository is up to date before you start making changes.

    {{< note >}}
-    This workflow is different than the [Kubernetes Community GitHub Workflow](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md). You do not need to merge your local copy of `master` with `upstream/master` before pushing updates to your fork.
+    This workflow is different than the [Kubernetes Community GitHub Workflow](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md). You do not need to merge your local copy of `main` with `upstream/main` before pushing updates to your fork.
    {{< /note >}}

 ### Create a branch

 1. Decide which branch base to your work on:

-  - For improvements to existing content, use `upstream/master`.
-  - For new content about existing features, use `upstream/master`.
+  - For improvements to existing content, use `upstream/main`.
+  - For new content about existing features, use `upstream/main`.
  - For localized content, use the localization's conventions. For more information, see [localizing Kubernetes documentation](/docs/contribute/localization/).
  - For new features in an upcoming Kubernetes release, use the feature branch. For more information, see [documenting for a release](/docs/contribute/new-content/new-features/).
  - For long-running efforts that multiple SIG Docs contributors collaborate on,
@@ -154,10 +154,10 @@ Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installi

    If you need help choosing a branch, ask in the `#sig-docs` Slack channel.

-2. Create a new branch based on the branch identified in step 1. This example assumes the base branch is `upstream/master`:
+2. Create a new branch based on the branch identified in step 1. This example assumes the base branch is `upstream/main`:

    ```bash
-    git checkout -b <my_new_branch> upstream/master
+    git checkout -b <my_new_branch> upstream/main
    ```

 3.  Make your changes using a text editor.
@@ -262,7 +262,7 @@ The commands below use Docker as default container engine. Set the `CONTAINER_EN

 Alternately, install and use the `hugo` command on your computer:

-1.  Install the [Hugo](https://gohugo.io/getting-started/installing/) version specified in [`website/netlify.toml`](https://raw.githubusercontent.com/kubernetes/website/master/netlify.toml).
+1.  Install the [Hugo](https://gohugo.io/getting-started/installing/) version specified in [`website/netlify.toml`](https://raw.githubusercontent.com/kubernetes/website/main/netlify.toml).

 2.  If you have not updated your website repository, the `website/themes/docsy` directory is empty.
    The site cannot build without a local copy of the theme. To update the website theme, run:
@@ -370,11 +370,11 @@ If another contributor commits changes to the same file in another PR, it can cr
    git push --force-with-lease origin <your-branch-name>
    ```

-2. Fetch changes from `kubernetes/website`'s `upstream/master` and rebase your branch:
+2. Fetch changes from `kubernetes/website`'s `upstream/main` and rebase your branch:

    ```bash
    git fetch upstream
-    git rebase upstream/master
+    git rebase upstream/main
    ```

 3. Inspect the results of the rebase:
@@ -42,7 +42,7 @@ When opening a pull request, you need to know in advance which branch to base yo

 Scenario | Branch
 :---------|:------------
-Existing or new English language content for the current release | `master`
+Existing or new English language content for the current release | `main`
 Content for a feature change release | The branch which corresponds to the major and minor version the feature change is in, using the pattern `dev-<version>`. For example, if a feature changes in the `v{{< skew nextMinorVersion >}}` release, then add documentation changes to the ``dev-{{< skew nextMinorVersion >}}`` branch.
 Content in other languages (localizations) | Use the localization's convention. See the [Localization branching strategy](/docs/contribute/localization/#branching-strategy) for more information.

@@ -60,6 +60,6 @@ Limit pull requests to one language per PR. If you need to make an identical cha

 ## Tools for contributors

-The [doc contributors tools](https://github.com/kubernetes/website/tree/master/content/en/docs/doc-contributor-tools) directory in the `kubernetes/website` repository contains tools to help your contribution journey go more smoothly.
+The [doc contributors tools](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools) directory in the `kubernetes/website` repository contains tools to help your contribution journey go more smoothly.


@@ -73,8 +73,8 @@ two [prow plugins](https://github.com/kubernetes/test-infra/tree/master/prow/plu
 - approve

 These two plugins use the
-[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) and
-[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES)
+[OWNERS](https://github.com/kubernetes/website/blob/main/OWNERS) and
+[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS_ALIASES)
 files in the top level of the `kubernetes/website` GitHub repository to control
 how prow works within the repository.

@@ -44,8 +44,8 @@ These queries exclude localization PRs. All queries are against the main branch
  Lists PRs that need an LGTM from a member. If the PR needs technical review, loop in one of the reviewers suggested by the bot. If the content needs work, add suggestions and feedback in-line.
 - [Has LGTM, needs docs approval](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+-label%3Ado-not-merge%2Fwork-in-progress+-label%3Ado-not-merge%2Fhold+label%3Alanguage%2Fen+label%3Algtm+):
  Lists PRs that need an `/approve` comment to merge.
- [Quick Wins](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+base%3Amaster+-label%3A%22do-not-merge%2Fwork-in-progress%22+-label%3A%22do-not-merge%2Fhold%22+label%3A%22cncf-cla%3A+yes%22+label%3A%22size%2FXS%22+label%3A%22language%2Fen%22): Lists PRs against the main branch with no clear blockers. (change "XS" in the size label as you work through the PRs [XS, S, M, L, XL, XXL]).
- [Not against the main branch](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3Alanguage%2Fen+-base%3Amaster): If the PR is against a `dev-` branch, it's for an upcoming release. Assign the [docs release manager](https://github.com/kubernetes/sig-release/tree/master/release-team#kubernetes-release-team-roles) using: `/assign @<manager's_github-username>`. If the PR is against an old branch, help the author figure out whether it's targeted against the best branch.
+- [Quick Wins](https://github.com/kubernetes/website/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+base%3Amain+-label%3A%22do-not-merge%2Fwork-in-progress%22+-label%3A%22do-not-merge%2Fhold%22+label%3A%22cncf-cla%3A+yes%22+label%3A%22size%2FXS%22+label%3A%22language%2Fen%22): Lists PRs against the main branch with no clear blockers. (change "XS" in the size label as you work through the PRs [XS, S, M, L, XL, XXL]).
+- [Not against the primary branch](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3Alanguage%2Fen+-base%3Amain): If the PR is against a `dev-` branch, it's for an upcoming release. Assign the [docs release manager](https://github.com/kubernetes/sig-release/tree/master/release-team#kubernetes-release-team-roles) using: `/assign @<manager's_github-username>`. If the PR is against an old branch, help the author figure out whether it's targeted against the best branch.

 ### Helpful Prow commands for wranglers

@@ -147,7 +147,7 @@ separately for reviewer status in SIG Docs.
 To apply:

 1. Open a pull request that adds your GitHub user name to a section of the
-   [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file
+   [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS) file
   in the `kubernetes/website` repository.

   {{< note >}}
@@ -219,7 +219,7 @@ separately for approver status in SIG Docs.
 To apply:

 1. Open a pull request adding yourself to a section of the
-   [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS)
+   [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/main/OWNERS)
   file in the `kubernetes/website` repository.

    {{< note >}}
@@ -55,7 +55,7 @@ You can reference glossary terms with an inclusion that automatically updates an
 As well as inclusions with tooltips, you can reuse the definitions from the glossary in
 page content.

-The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term.
+The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary), with a content file for each glossary term.

 ### Glossary demo

@@ -30,7 +30,7 @@ glossary entries, tabs, and representing feature state.
 ## Language

 Kubernetes documentation has been translated into multiple languages
-(see [Localization READMEs](https://github.com/kubernetes/website/blob/master/README.md#localization-readmemds)).
+(see [Localization READMEs](https://github.com/kubernetes/website/blob/main/README.md#localization-readmemds)).

 The way of localizing the docs for a different language is described in [Localizing Kubernetes Documentation](/docs/contribute/localization/).

@@ -79,6 +79,10 @@ operator to use or manage a cluster.
 * [Client authentication API (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)
 * [WebhookAdmission configuration (v1)](/docs/reference/config-api/apiserver-webhookadmission.v1/)

+## Config API for kubeadm
+
+* [v1beta2](/docs/reference/config-api/kubeadm-config.v1beta2/)
+
 ## Design Docs

 An archive of the design docs for Kubernetes functionality. Good starting points are
@@ -698,6 +698,8 @@ admission plugin, which allows preventing pods from running on specifically tain

 ### PodSecurityPolicy {#podsecuritypolicy}

+{{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
+
 This admission controller acts on creation and modification of the pod and determines if it should be admitted
 based on the requested security context and the available Pod Security Policies.

@@ -56,11 +56,11 @@ state for some duration:

 * Approved requests: automatically deleted after 1 hour
 * Denied requests: automatically deleted after 1 hour
-* Pending requests: automatically deleted after 1 hour
+* Pending requests: automatically deleted after 24 hours

 ## Signers

-All signers should provide information about how they work so that clients can predict what will happen to their CSRs.
+Custom signerNames can also be specified. All signers should provide information about how they work so that clients can predict what will happen to their CSRs.
 This includes:

 1. **Trust distribution**: how trust (CA bundles) are distributed.
@@ -282,7 +282,7 @@ Of course you need to set up the webhook server to handle these authentications.

 ### Request

-Webhooks are sent a POST request, with `Content-Type: application/json`,
+Webhooks are sent as POST requests, with `Content-Type: application/json`,
 with an `AdmissionReview` API object in the `admission.k8s.io` API group
 serialized to JSON as the body.

@@ -61,6 +61,7 @@ different Kubernetes components.
 | `BalanceAttachedNodeVolumes` | `false` | Alpha | 1.11 | |
 | `BoundServiceAccountTokenVolume` | `false` | Alpha | 1.13 | 1.20 |
 | `BoundServiceAccountTokenVolume` | `true` | Beta | 1.21 | |
+| `ControllerManagerLeaderMigration` | `false` | Alpha | 1.21 | |
 | `CPUManager` | `false` | Alpha | 1.8 | 1.9 |
 | `CPUManager` | `true` | Beta | 1.10 | |
 | `CSIInlineVolume` | `false` | Alpha | 1.15 | 1.15 |
@@ -152,7 +153,8 @@ different Kubernetes components.
 | `ProbeTerminationGracePeriod` | `false` | Alpha | 1.21 | |
 | `ProcMountType` | `false` | Alpha | 1.12 | |
 | `QOSReserved` | `false` | Alpha | 1.11 | |
-| `RemainingItemCount` | `false` | Alpha | 1.15 | |
+| `RemainingItemCount` | `false` | Alpha | 1.15 | 1.15 |
+| `RemainingItemCount` | `true` | Beta | 1.16 | |
 | `RemoveSelfLink` | `false` | Alpha | 1.16 | 1.19 |
 | `RemoveSelfLink` | `true` | Beta | 1.20 | |
 | `RotateKubeletServerCertificate` | `false` | Alpha | 1.7 | 1.11 |
@@ -477,6 +479,11 @@ Each feature gate is designed for enabling/disabling a specific feature:
  extended tokens by starting `kube-apiserver` with flag `--service-account-extend-token-expiration=false`.
  Check [Bound Service Account Tokens](https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/1205-bound-service-account-tokens/README.md)
   for more details.
+- `ControllerManagerLeaderMigration`: Enables Leader Migration for 
+  [kube-controller-manager](/docs/tasks/administer-cluster/controller-manager-leader-migration/#initial-leader-migration-configuration) and 
+  [cloud-controller-manager](/docs/tasks/administer-cluster/controller-manager-leader-migration/#deploy-cloud-controller-manager) which allows a cluster operator to live migrate 
+  controllers from the kube-controller-manager into an external controller-manager 
+  (e.g. the cloud-controller-manager) in an HA cluster without downtime.
 - `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. The default max size of a log file is 10MB and the
@@ -726,7 +733,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `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
-  [priorities](/docs/concepts/configuration/pod-priority-preemption/).
+  [priorities](/docs/concepts/scheduling-eviction/pod-priority-preemption/).
 - `PodReadinessGates`: Enable the setting of `PodReadinessGate` field for extending
  Pod readiness evaluation.  See [Pod readiness gate](/docs/concepts/workloads/pods/pod-lifecycle/#pod-readiness-gate)
  for more details.
@@ -14,6 +14,48 @@ auto_generated: true
  
    

+## `LoggingConfiguration`     {#LoggingConfiguration}
+    
+
+
+
+**Appears in:**
+
+- [KubeletConfiguration](#kubelet-config-k8s-io-v1beta1-KubeletConfiguration)
+
+
+LoggingConfiguration contains logging options
+Refer [Logs Options](https://github.com/kubernetes/component-base/blob/master/logs/options.go) for more information.
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+    
+
+  
+<tr><td><code>format</code> <B>[Required]</B><br/>
+<code>string</code>
+</td>
+<td>
+   Format Flag specifies the structure of log messages.
+default value of format is `text`</td>
+</tr>
+    
+  
+<tr><td><code>sanitization</code> <B>[Required]</B><br/>
+<code>bool</code>
+</td>
+<td>
+   [Experimental] When enabled prevents logging of fields tagged as sensitive (passwords, keys, tokens).
+Runtime log sanitization may introduce significant computation overhead and therefore should not be enabled in production.`)</td>
+</tr>
+    
+  
+</tbody>
+</table>
+  
+    
+

 ## `KubeletConfiguration`     {#kubelet-config-k8s-io-v1beta1-KubeletConfiguration}
    
@@ -445,10 +487,10 @@ Default: "10s"</td>
 status to master if node status does not change. Kubelet will ignore this
 frequency and post node status immediately if any change is detected. It is
 only used when node lease feature is enabled. nodeStatusReportFrequency's
-default value is 1m. But if nodeStatusUpdateFrequency is set explicitly,
+default value is 5m. But if nodeStatusUpdateFrequency is set explicitly,
 nodeStatusReportFrequency's default value will be set to
 nodeStatusUpdateFrequency for backward compatibility.
-Default: "1m"</td>
+Default: "5m"</td>
 </tr>
    
  
@@ -590,7 +632,7 @@ Default: "cgroupfs"</td>
 Requires the CPUManager feature gate to be enabled.
 Dynamic Kubelet Config (beta): This field should not be updated without a full node
 reboot. It is safest to keep this value the same as the local config.
-Default: "none"</td>
+Default: "None"</td>
 </tr>
    
  
@@ -606,6 +648,18 @@ Default: "10s"</td>
 </tr>
    
  
+<tr><td><code>memoryManagerPolicy</code><br/>
+<code>string</code>
+</td>
+<td>
+   MemoryManagerPolicy is the name of the policy to use by memory manager.
+Requires the MemoryManager feature gate to be enabled.
+Dynamic Kubelet Config (beta): This field should not be updated without a full node
+reboot. It is safest to keep this value the same as the local config.
+Default: "none"</td>
+</tr>
+    
+  
 <tr><td><code>topologyManagerPolicy</code><br/>
 <code>string</code>
 </td>
@@ -1231,7 +1285,7 @@ Default: true</td>
 </td>
 <td>
   ShutdownGracePeriod specifies the total duration that the node should delay the shutdown and total grace period for pod termination during a node shutdown.
-Default: "30s"</td>
+Default: "0s"</td>
 </tr>
    
  
@@ -1241,7 +1295,46 @@ Default: "30s"</td>
 <td>
   ShutdownGracePeriodCriticalPods specifies the duration used to terminate critical pods during a node shutdown. This should be less than ShutdownGracePeriod.
 For example, if ShutdownGracePeriod=30s, and ShutdownGracePeriodCriticalPods=10s, during a node shutdown the first 20 seconds would be reserved for gracefully terminating normal pods, and the last 10 seconds would be reserved for terminating critical pods.
-Default: "10s"</td>
+Default: "0s"</td>
+</tr>
+    
+  
+<tr><td><code>reservedMemory</code><br/>
+<a href="#kubelet-config-k8s-io-v1beta1-MemoryReservation"><code>[]MemoryReservation</code></a>
+</td>
+<td>
+   ReservedMemory specifies a comma-separated list of memory reservations for NUMA nodes.
+The parameter makes sense only in the context of the memory manager feature. The memory manager will not allocate reserved memory for container workloads.
+For example, if you have a NUMA0 with 10Gi of memory and the ReservedMemory was specified to reserve 1Gi of memory at NUMA0,
+the memory manager will assume that only 9Gi is available for allocation.
+You can specify a different amount of NUMA node and memory types.
+You can omit this parameter at all, but you should be aware that the amount of reserved memory from all NUMA nodes
+should be equal to the amount of memory specified by the node allocatable features(https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable).
+If at least one node allocatable parameter has a non-zero value, you will need to specify at least one NUMA node.
+Also, avoid specifying:
+1. Duplicates, the same NUMA node, and memory type, but with a different value.
+2. zero limits for any memory type.
+3. NUMAs nodes IDs that do not exist under the machine.
+4. memory types except for memory and hugepages-<size>
+Default: nil</td>
+</tr>
+    
+  
+<tr><td><code>enableProfilingHandler</code><br/>
+<code>bool</code>
+</td>
+<td>
+   enableProfilingHandler enables profiling via web interface host:port/debug/pprof/
+Default: true</td>
+</tr>
+    
+  
+<tr><td><code>enableDebugFlagsHandler</code><br/>
+<code>bool</code>
+</td>
+<td>
+   enableDebugFlagsHandler enables flags endpoint via web interface host:port/debug/flags/v
+Default: true</td>
 </tr>
    
  
@@ -1544,6 +1637,47 @@ and groups corresponding to the Organization in the client certificate.</td>
    


+## `MemoryReservation`     {#kubelet-config-k8s-io-v1beta1-MemoryReservation}
+    
+
+
+
+**Appears in:**
+
+- [KubeletConfiguration](#kubelet-config-k8s-io-v1beta1-KubeletConfiguration)
+
+
+MemoryReservation specifies the memory reservation of different types for each NUMA node
+
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+    
+
+  
+<tr><td><code>numaNode</code> <B>[Required]</B><br/>
+<code>int32</code>
+</td>
+<td>
+   <span class="text-muted">No description provided.</span>
+   </td>
+</tr>
+    
+  
+<tr><td><code>limits</code> <B>[Required]</B><br/>
+<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcelist-v1-core"><code>core/v1.ResourceList</code></a>
+</td>
+<td>
+   <span class="text-muted">No description provided.</span>
+   </td>
+</tr>
+    
+  
+</tbody>
+</table>
+    
+
+
 ## `ResourceChangeDetectionStrategy`     {#kubelet-config-k8s-io-v1beta1-ResourceChangeDetectionStrategy}
    
 (Alias of `string`)
@@ -1560,45 +1694,3 @@ managers (secret, configmap) are discovering object changes.

    
  
-  
-    
-
-## `LoggingConfiguration`     {#LoggingConfiguration}
-    
-
-
-
-**Appears in:**
-
- [KubeletConfiguration](#kubelet-config-k8s-io-v1beta1-KubeletConfiguration)
-
-
-LoggingConfiguration contains logging options
-Refer [Logs Options](https://github.com/kubernetes/component-base/blob/master/logs/options.go) for more information.
-
-<table class="table">
-<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
-<tbody>
-    
-
-  
-<tr><td><code>format</code> <B>[Required]</B><br/>
-<code>string</code>
-</td>
-<td>
-   Format Flag specifies the structure of log messages.
-default value of format is `text`</td>
-</tr>
-    
-  
-<tr><td><code>sanitization</code> <B>[Required]</B><br/>
-<code>bool</code>
-</td>
-<td>
-   [Experimental] When enabled prevents logging of fields tagged as sensitive (passwords, keys, tokens).
-Runtime log sanitization may introduce significant computation overhead and therefore should not be enabled in production.`)</td>
-</tr>
-    
-  
-</tbody>
-</table>
@@ -0,0 +1,22 @@
+---
+title: Affinity
+id: affinity
+date: 2019-01-11
+full_link: /docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
+short_description: >
+     Rules used by the scheduler to determine where to place pods
+aka:
+tags:
+- fundamental
+---
+
+In Kubernetes, _affinity_ is a set of rules that give hints to the scheduler about where to place pods.
+
+<!--more-->
+There are two kinds of affinity:
+* [node affinity](/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity)
+* [pod-to-pod affinity](/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity)
+
+The rules are defined using the Kubernetes {{< glossary_tooltip term_id="label" text="labels">}},
+and {{< glossary_tooltip term_id="selector" text="selectors">}} specified in {{< glossary_tooltip term_id="pod" text="pods" >}}, 
+and they can be either required or preferred, depending on how strictly you want the scheduler to enforce them.
--- a/Show More
+++ b/Show More