Merge master into dev-1.20 to keep in sync

2020-10-07 15:36:49 -07:00
parent 5e7cb3f9ca 3d23e421d2
commit 59cf7a42b4
82 changed files with 3337 additions and 779 deletions
@@ -6,7 +6,7 @@ cid: home

 {{< blocks/section id="oceanNodes" >}}
 {{% blocks/feature image="flower" %}}
-### [Kubernetes (K8s)]({{< relref "/docs/concepts/overview/what-is-kubernetes" >}}) is an open-source system for automating deployment, scaling, and management of containerized applications.
+[Kubernetes (K8s)]({{< relref "/docs/concepts/overview/what-is-kubernetes" >}}) is an open-source system for automating deployment, scaling, and management of containerized applications.

 It groups containers that make up an application into logical units for easy management and discovery. Kubernetes builds upon [15 years of experience of running production workloads at Google](http://queue.acm.org/detail.cfm?id=2898444), combined with best-of-breed ideas and practices from the community.
 {{% /blocks/feature %}}
@@ -89,7 +89,7 @@ Volume cloning enables users to specify another PVC as a "DataSource" when provi
 - ExecutionHook API [designed to trigger hook commands](https://github.com/kubernetes/enhancements/issues/962) in the containers for different use cases is now Alpha.
 - Continued deprecation of extensions/v1beta1, apps/v1beta1, and apps/v1beta2 APIs; these extensions will be retired in 1.16!

-Check the [release notes](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.15.md#kubernetes-v115-release-notes) for a complete list of notable features and fixes.
+Check the [release notes](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.15.md#kubernetes-v115-release-notes) for a complete list of notable features and fixes.

 **Availability**

@@ -0,0 +1,107 @@
+---
+title: "Contributing to the Development Guide"
+linkTitle: "Contributing to the Development Guide"
+Author: Erik L. Arneson
+Description: "A new contributor describes the experience of writing and submitting changes to the Kubernetes Development Guide."
+date: 2020-10-01
+canonicalUrl: https://www.kubernetes.dev/blog/2020/09/28/contributing-to-the-development-guide/
+resources:
+- src: "jorge-castro-code-of-conduct.jpg"
+  title: "Jorge Castro announcing the Kubernetes Code of Conduct during a weekly SIG ContribEx meeting."
+---
+
+When most people think of contributing to an open source project, I suspect they probably think of
+contributing code changes, new features, and bug fixes. As a software engineer and a long-time open
+source user and contributor, that's certainly what I thought. Although I have written a good quantity
+of documentation in different workflows, the massive size of the Kubernetes community was a new kind 
+of "client." I just didn't know what to expect when Google asked my compatriots and me at
+[Lion's Way](https://lionswaycontent.com/) to make much-needed updates to the Kubernetes Development Guide.
+
+*This article originally appeared on the [Kubernetes Contributor Community blog](https://www.kubernetes.dev/blog/2020/09/28/contributing-to-the-development-guide/).*
+
+## The Delights of Working With a Community
+
+As professional writers, we are used to being hired to write very specific pieces. We specialize in
+marketing, training, and documentation for technical services and products, which can range anywhere from relatively fluffy marketing emails to deeply technical white papers targeted at IT and developers. With 
+this kind of professional service, every deliverable tends to have a measurable return on investment. 
+I knew this metric wouldn't be present when working on open source documentation, but I couldn't
+predict how it would change my relationship with the project.
+
+One of the primary traits of the relationship between our writing and our traditional clients is that we
+always have one or two primary points of contact inside a company. These contacts are responsible
+for reviewing our writing and making sure it matches the voice of the company and targets the
+audience they're looking for. It can be stressful -- which is why I'm so glad that my writing
+partner, eagle-eyed reviewer, and bloodthirsty editor [Joel](https://twitter.com/JoelByronBarker)
+handles most of the client contact.
+
+I was surprised and delighted that all of the stress of client contact went out the window when
+working with the Kubernetes community.
+
+"How delicate do I have to be? What if I screw up? What if I make a developer angry? What if I make
+enemies?" These were all questions that raced through my mind and made me feel like I was
+approaching a field of eggshells when I first joined the `#sig-contribex` channel on the Kubernetes
+Slack and announced that I would be working on the
+[Development Guide](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md).
+
+{{< imgproc jorge-castro-code-of-conduct Fit "800x450" >}}
+"The Kubernetes Code of Conduct is in effect, so please be excellent to each other." &mdash; Jorge
+Castro, SIG ContribEx co-chair
+{{< /imgproc >}}
+
+My fears were unfounded. Immediately, I felt welcome. I like to think this isn't just because I was
+working on a much needed task, but rather because the Kubernetes community is filled
+with friendly, welcoming people. During the weekly SIG ContribEx meetings, our reports on progress
+with the Development Guide were included immediately. In addition, the leader of the meeting would
+always stress that the [Kubernetes Code of Conduct](https://www.kubernetes.dev/resources/code-of-conduct/) was in
+effect, and that we should, like Bill and Ted, be excellent to each other.
+
+## This Doesn't Mean It's All Easy
+
+The Development Guide needed a pretty serious overhaul. When we got our hands on it, it was already
+packed with information and lots of steps for new developers to go through, but it was getting dusty
+with age and neglect. Documentation can really require a global look, not just point fixes.
+As a result, I ended up submitting a gargantuan pull request to the
+[Community repo](https://github.com/kubernetes/community): 267 additions and 88 deletions.
+
+The life cycle of a pull request requires a certain number of Kubernetes organization members to review and approve changes
+before they can be merged. This is a great practice, as it keeps both documentation and code in
+pretty good shape, but it can be tough to cajole the right people into taking the time for such a hefty
+review. As a result, that massive PR took 26 days from my first submission to final merge. But in
+the end, [it was successful](https://github.com/kubernetes/community/pull/5003).
+
+Since Kubernetes is a pretty fast-moving project, and since developers typically aren't really
+excited about writing documentation, I also ran into the problem that sometimes, the secret jewels
+that describe the workings of a Kubernetes subsystem are buried deep within the [labyrinthine mind of
+a brilliant engineer](https://github.com/amwat), and not in plain English in a Markdown file. I ran headlong into this issue
+when it came time to update the getting started documentation for end-to-end (e2e) testing. 
+
+This portion of my journey took me out of documentation-writing territory and into the role of a
+brand new user of some unfinished software. I ended up working with one of the developers of the new
+[`kubetest2` framework](https://github.com/kubernetes-sigs/kubetest2) to document the latest process of
+getting up-and-running for e2e testing, but it required a lot of head scratching on my part. You can
+judge the results for yourself by checking out my
+[completed pull request](https://github.com/kubernetes/community/pull/5045).
+
+## Nobody Is the Boss, and Everybody Gives Feedback
+
+But while I secretly expected chaos, the process of contributing to the Kubernetes Development Guide
+and interacting with the amazing Kubernetes community went incredibly smoothly. There was no
+contention. I made no enemies. Everybody was incredibly friendly and welcoming. It was *enjoyable*.
+
+With an open source project, there is no one boss. The Kubernetes project, which approaches being
+gargantuan, is split into many different special interest groups (SIGs), working groups, and
+communities. Each has its own regularly scheduled meetings, assigned duties, and elected
+chairpersons. My work intersected with the efforts of both SIG ContribEx (who watch over and seek to
+improve the contributor experience) and SIG Testing (who are in charge of testing). Both of these
+SIGs proved easy to work with, eager for contributions, and populated with incredibly friendly and
+welcoming people.
+
+In an active, living project like Kubernetes, documentation continues to need maintenance, revision,
+and testing alongside the code base. The Development Guide will continue to be crucial to onboarding
+new contributors to the Kubernetes code base, and as our efforts have shown, it is important that
+this guide keeps pace with the evolution of the Kubernetes project.
+
+Joel and I really enjoy interacting with the Kubernetes community and contributing to
+the Development Guide. I really look forward to continuing to not only contributing more, but to
+continuing to build the new friendships I've made in this vast open source community over the past
+few months.
@@ -438,7 +438,7 @@ If you want to use project quotas, you should:
  [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
  in the kubelet configuration.

-* Ensure that the the root filesystem (or optional runtime filesystem)
+* Ensure that the root filesystem (or optional runtime filesystem)
  has project quotas enabled. All XFS filesystems support project quotas.
  For ext4 filesystems, you need to enable the project quota tracking feature
  while the filesystem is not mounted.
@@ -181,8 +181,8 @@ are accounted for in Kubernetes.
 ## {{% heading "whatsnext" %}}


- [RuntimeClass Design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/runtime-class.md)
- [RuntimeClass Scheduling Design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/runtime-class-scheduling.md)
+- [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/configuration/pod-overhead/) concept
 - [PodOverhead Feature Design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/20190226-pod-overhead.md)

@@ -44,9 +44,9 @@ Kubernetes as a project currently supports and maintains [GCE](https://git.k8s.i
 * [NGINX, Inc.](https://www.nginx.com/) offers support and maintenance for the
  [NGINX Ingress Controller for Kubernetes](https://www.nginx.com/products/nginx/kubernetes-ingress-controller).
 * [Skipper](https://opensource.zalando.com/skipper/kubernetes/ingress-controller/) HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress, designed as a library to build your custom proxy
-* [Traefik](https://github.com/containous/traefik) is a fully featured ingress controller
+* [Traefik](https://github.com/traefik/traefik) is a fully featured ingress controller
  ([Let's Encrypt](https://letsencrypt.org), secrets, http2, websocket), and it also comes with commercial
-  support by [Containous](https://containo.us/services).
+  support by [Traefik Labs](https://traefik.io).

 ## Using multiple Ingress controllers

@@ -411,7 +411,7 @@ type: kubernetes.io/tls
 Referencing this secret in an Ingress tells the Ingress controller to
 secure the channel from the client to the load balancer using TLS. You need to make
 sure the TLS secret you created came from a certificate that contains a Common
-Name (CN), also known as a Fully Qualified Domain Name (FQDN) for `sslexample.foo.com`.
+Name (CN), also known as a Fully Qualified Domain Name (FQDN) for `https-example.foo.com`.

 {{< codenew file="service/networking/tls-example-ingress.yaml" >}}

@@ -28,8 +28,8 @@ Init containers are exactly like regular containers, except:
 * Init containers always run to completion.
 * Each init container must complete successfully before the next one starts.

-If a Pod's init container fails, Kubernetes repeatedly restarts the Pod until the init container
-succeeds. However, if the Pod has a `restartPolicy` of Never, Kubernetes does not restart the Pod.
+If a Pod's init container fails, the kubelet repeatedly restarts that init container until it succeeds. 
+However, if the Pod has a `restartPolicy` of Never, and an init container fails during startup of that Pod, Kubernetes treats the overall Pod as failed.

 To specify an init container for a Pod, add the `initContainers` field into
 the Pod specification, as an array of objects of type
@@ -342,7 +342,9 @@ place, the {{< glossary_tooltip text="kubelet" term_id="kubelet" >}} attempts gr
 shutdown.

 Typically, the container runtime sends a TERM signal to the main process in each
-container. Once the grace period has expired, the KILL signal is sent to any remaining
+container. Many container runtimes respect the `STOPSIGNAL` value defined in the container
+image and send this instead of TERM.
+Once the grace period has expired, the KILL signal is sent to any remaining
 processes, and the Pod is then deleted from the
 {{< glossary_tooltip text="API Server" term_id="kube-apiserver" >}}. If the kubelet or the
 container runtime's management service is restarted while waiting for processes to terminate, the
@@ -353,9 +355,9 @@ An example flow:
 1. You use the `kubectl` tool to manually delete a specific Pod, with the default grace period
   (30 seconds).
 1. The Pod in the API server is updated with the time beyond which the Pod is considered "dead"
-   along with the grace period.  
+   along with the grace period.
   If you use `kubectl describe` to check on the Pod you're deleting, that Pod shows up as
-   "Terminating".  
+   "Terminating".
   On the node where the Pod is running: as soon as the kubelet sees that a Pod has been marked
   as terminating (a graceful shutdown duration has been set), the kubelet begins the local Pod
   shutdown process.
@@ -386,7 +388,7 @@ An example flow:
   `SIGKILL` to any processes still running in any container in the Pod.
   The kubelet also cleans up a hidden `pause` container if that container runtime uses one.
 1. The kubelet triggers forcible removal of Pod object from the API server, by setting grace period
-   to 0 (immediate deletion).  
+   to 0 (immediate deletion).
 1. The API server deletes the Pod's API object, which is then no longer visible from any client.

 ### Forced Pod termination {#pod-termination-forced}
@@ -190,7 +190,7 @@ close the issue without fixing.

 Some docs issues are actually issues with the underlying code, or requests for
 assistance when something, for example a tutorial, doesn't work.
-For issues unrelated to docs, close the issue with the `triage/support` label and a comment
+For issues unrelated to docs, close the issue with the `kind/support` label and a comment
 directing the requester to support venues (Slack, Stack Overflow) and, if
 relevant, the repository to file an issue for bugs with features (`kubernetes/kubernetes`
 is a great place to start).
@@ -31,6 +31,7 @@ be issued, based on a signing request.
 The CertificateSigningRequest object includes a PEM-encoded PKCS#10 signing request in
 the `spec.request` field. The CertificateSigningRequest denotes the _signer_ (the
 recipient that the request is being made to) using the `spec.signerName` field.
+Note that `spec.signerName` is a required key after api version `certificates.k8s.io/v1`.

 Once created, a CertificateSigningRequest must be approved before it can be signed.
 Depending on the signer selected, a CertificateSigningRequest may be automatically approved
@@ -106,8 +107,9 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
    1. Expiration/certificate lifetime - minimum of CSR signer or request.
    1. CA bit allowed/disallowed - not allowed.

-1. `kubernetes.io/legacy-unknown`:  has no guarantees for trust at all. Some distributions may honor these as client
-  certs, but that behavior is not standard Kubernetes behavior.
+1. `kubernetes.io/legacy-unknown`:  has no guarantees for trust at all. Some third-party distributions of Kubernetes
+  may honor client certificates signed by it. The stable CertificateSigningRequest API (version `certificates.k8s.io/v1` and later)
+  does not allow to set the `signerName` as `kubernetes.io/legacy-unknown`.
  Never auto-approved by {{< glossary_tooltip term_id="kube-controller-manager" >}}.
    1. Trust distribution: None.  There is no standard trust or distribution for this signer in a Kubernetes cluster.
    1. Permitted subjects - any
@@ -227,7 +229,7 @@ rules:

 ## Normal User

-There are a few steps are required in order to get normal user to be able to authenticate and invoke API. First, this user must have certificate issued by the Kubernetes Cluster, and then present that Certificate into the API call as the Certificate Header, or through the kubectl.
+A few steps are required in order to get normal user to be able to authenticate and invoke an API. First, this user must have certificate issued by the Kubernetes Cluster, and then present that Certificate to the API call as the Certificate Header or through the kubectl.

 ### Create Private Key

@@ -1096,37 +1096,37 @@ In order from most secure to least secure, the approaches are:

 2. Grant a role to the "default" service account in a namespace

-If an application does not specify a `serviceAccountName`, it uses the "default" service account.
+    If an application does not specify a `serviceAccountName`, it uses the "default" service account.

-{{< note >}}
-Permissions given to the "default" service account are available to any pod
-in the namespace that does not specify a `serviceAccountName`.
-{{< /note >}}
+    {{< note >}}
+    Permissions given to the "default" service account are available to any pod
+    in the namespace that does not specify a `serviceAccountName`.
+    {{< /note >}}

-For example, grant read-only permission within "my-namespace" to the "default" service account:
+    For example, grant read-only permission within "my-namespace" to the "default" service account:

-```shell
-kubectl create rolebinding default-view \
-  --clusterrole=view \
-  --serviceaccount=my-namespace:default \
-  --namespace=my-namespace
-```
+    ```shell
+    kubectl create rolebinding default-view \
+      --clusterrole=view \
+      --serviceaccount=my-namespace:default \
+      --namespace=my-namespace
+    ```

-Many [add-ons](/docs/concepts/cluster-administration/addons/) run as the
-"default" service account in the `kube-system` namespace.
-To allow those add-ons to run with super-user access, grant cluster-admin
-permissions to the "default" service account in the `kube-system` namespace.
+    Many [add-ons](/docs/concepts/cluster-administration/addons/) run as the
+    "default" service account in the `kube-system` namespace.
+    To allow those add-ons to run with super-user access, grant cluster-admin
+    permissions to the "default" service account in the `kube-system` namespace.

-{{< caution >}}
-Enabling this means the `kube-system` namespace contains Secrets
-that grant super-user access to your cluster's API.
-{{< /caution >}}
+    {{< caution >}}
+    Enabling this means the `kube-system` namespace contains Secrets
+    that grant super-user access to your cluster's API.
+    {{< /caution >}}

-```shell
-kubectl create clusterrolebinding add-on-cluster-admin \
-  --clusterrole=cluster-admin \
-  --serviceaccount=kube-system:default
-```
+    ```shell
+    kubectl create clusterrolebinding add-on-cluster-admin \
+      --clusterrole=cluster-admin \
+      --serviceaccount=kube-system:default
+    ```

 3. Grant a role to all service accounts in a namespace

@@ -1193,7 +1193,7 @@ the [legacy ABAC policy](/docs/reference/access-authn-authz/abac/#policy-file-fo
 ```

 To explain that first command line option in detail: if earlier authorizers, such as Node,
-deny a request, then the the RBAC authorizer attempts to authorize the API request. If RBAC
+deny a request, then the RBAC authorizer attempts to authorize the API request. If RBAC
 also denies that API request, the ABAC authorizer is then run. This means that any request
 allowed by *either* the RBAC or ABAC policies is allowed.

@@ -9,7 +9,6 @@ short_description: >
 aka:
 tags:
 - fundamental
- core-object
 ---
 An agent that runs on each {{< glossary_tooltip text="node" term_id="node" >}} in the cluster. It makes sure that {{< glossary_tooltip text="containers" term_id="container" >}} are running in a {{< glossary_tooltip text="Pod" term_id="pod" >}}.

@@ -19,7 +19,7 @@ The `healthz` endpoint is deprecated (since Kubernetes v1.16), and you should us
 The `livez` endpoint can be used with the `--livez-grace-period` [flag](/docs/reference/command-line-tools-reference/kube-apiserver) to specify the startup duration.
 For a graceful shutdown you can specify the `--shutdown-delay-duration` [flag](/docs/reference/command-line-tools-reference/kube-apiserver) with the `/readyz` endpoint.
 Machines that check the `health`/`livez`/`readyz` of the API server should rely on the HTTP status code.
-A status code `200` indicates the the API server is `healthy`/`live`/`ready`, depending of the called endpoint.
+A status code `200` indicates the API server is `healthy`/`live`/`ready`, depending of the called endpoint.
 The more verbose options shown below are intended to be used by human operators to debug their cluster or specially the state of the API server.

 The following examples will show how you can interact with the health API endpoints.
@@ -573,7 +573,7 @@ Your main source of help for troubleshooting your Kubernetes cluster should star
    Get-NetAdapter | ? Name -Like "vEthernet (Ethernet*"
    ```

-    Often it is worthwhile to modify the [InterfaceName](https://github.com/microsoft/SDN/blob/master/Kubernetes/flannel/start.ps1#L6) parameter of the start.ps1 script, in cases where the host's network adapter isn't "Ethernet". Otherwise, consult the output of the `start-kubelet.ps1` script to see if there are errors during virtual network creation.
+    Often it is worthwhile to modify the [InterfaceName](https://github.com/microsoft/SDN/blob/master/Kubernetes/flannel/start.ps1#L7) parameter of the start.ps1 script, in cases where the host's network adapter isn't "Ethernet". Otherwise, consult the output of the `start-kubelet.ps1` script to see if there are errors during virtual network creation.

 1. My Pods are stuck at "Container Creating" or restarting over and over

@@ -41,7 +41,7 @@ like `free -m`. This is important because `free -m` does not work in a
 container, and if users use the [node
 allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) feature, out of resource decisions
 are made local to the end user Pod part of the cgroup hierarchy as well as the
-root node. This [script](/docs/tasks/administer-cluster/memory-available.sh)
+root node. This [script](/examples/admin/resource/memory-available.sh)
 reproduces the same set of steps that the `kubelet` performs to calculate
 `memory.available`. The `kubelet` excludes inactive_file (i.e. # of bytes of
 file-backed memory on inactive LRU list) from its calculation as it assumes that
@@ -153,7 +153,7 @@ An older kubectl plugin mechanism provided environment variables such as `KUBECT
 kubectl plugins must parse and validate all of the arguments passed to them.
 See [using the command line runtime package](#using-the-command-line-runtime-package) for details of a Go library aimed at plugin authors.

-Here are some additional cases where users invoke your plugin while providing additional flags and arguments. This builds upon the the `kubectl-foo-bar-baz` plugin from the scenario above.
+Here are some additional cases where users invoke your plugin while providing additional flags and arguments. This builds upon the `kubectl-foo-bar-baz` plugin from the scenario above.

 If you run `kubectl foo bar baz arg1 --flag=value arg2`, kubectl's plugin mechanism will first try to find the plugin with the longest possible name, which in this case
 would be `kubectl-foo-bar-baz-arg1`. Upon not finding that plugin, kubectl then treats the last dash-separated value as an argument (`arg1` in this case), and attempts to find the next longest possible name, `kubectl-foo-bar-baz`.
@@ -405,8 +405,8 @@ behavior:
      periodSeconds: 60
 ```

-To allow a final drop of 5 pods, another policy can be added and a selection
-strategy of minimum:
+To allow a final drop of 5 pods, another policy can be added with a selection
+strategy of maximum:

 ```yaml
 behavior:
@@ -39,7 +39,7 @@ helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com
 Check to make sure that it installed successfully by executing the following command:

 ```shell
-helm search service-catalog
+helm search repo service-catalog
 ```

 If the installation was successful, the command should output the following:
@@ -65,7 +65,7 @@ Using the latest version of kubectl helps avoid unforeseen issues.

 {{< tabs name="kubectl_install" >}}
 {{< tab name="Ubuntu, Debian or HypriotOS" codelang="bash" >}}
-sudo apt-get update && sudo apt-get install -y apt-transport-https gnupg2
+sudo apt-get update && sudo apt-get install -y apt-transport-https gnupg2 curl
 curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
 echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee -a /etc/apt/sources.list.d/kubernetes.list
 sudo apt-get update