Merge remote-tracking branch 'upstream/master' into dev-1.20

2020-12-07 10:39:57 -06:00
parent 72d21d074c b905af1f34
commit 7f43aceddb
167 changed files with 8101 additions and 4131 deletions
@@ -7,7 +7,7 @@ aliases: [ '/dockershim' ]
 ---

 This document goes over some frequently asked questions regarding the Dockershim
-depreaction announced as a part of the Kubernetes v1.20 release. For more detail
+deprecation announced as a part of the Kubernetes v1.20 release. For more detail
 on the deprecation of Docker as a container runtime for Kubernetes kubelets, and
 what that means, check out the blog post
 [Don't Panic: Kubernetes and Docker](/blog/2020/12/02/dont-panic-kubernetes-and-docker/).
@@ -101,7 +101,7 @@ in the form of [runc], which is the underlying default runtime for both
 [containerd] and [CRI-O]. The CRI builds on these low-level specifications to
 provide an end-to-end standard for managing containers.

-[Open Container Initative]: https://opencontainers.org/about/overview/
+[Open Container Initiative]: https://opencontainers.org/about/overview/
 [runc]: https://github.com/opencontainers/runc
 [containerd]: https://containerd.io/

@@ -0,0 +1,92 @@
+---
+layout: blog
+title: "GSoD 2020: Improving the API Reference Experience"
+date: 2020-12-04
+slug: gsod-2020-improving-api-reference-experience
+---
+
+**Author**: [Philippe Martin](https://github.com/feloy)
+
+_Editor's note: Better API references have been my goal since I joined Kubernetes docs three and a half years ago. Philippe has succeeded fantastically. More than a better API reference, though, Philippe embodied the best of the Kubernetes community in this project: excellence through collaboration, and a process that made the community itself better. Thanks, Google Season of Docs, for making Philippe's work possible. —Zach Corleissen_
+
+## Introduction
+
+The [Google Season of Docs](https://developers.google.com/season-of-docs) project brings open source organizations and technical writers together to work closely on a specific documentation project.
+
+I was selected by the CNCF to work on Kubernetes documentation, specifically to make the API Reference documentation more accessible.
+
+I'm a software developer with a great interest in documentation systems. In the late 90's I started translating Linux-HOWTO documents into French. From one thing to another, I learned about documentation systems. Eventually, I wrote a Linux-HOWTO to help documentarians learn the language used at that time for writing documents, LinuxDoc/SGML.
+
+Shortly afterward, Linux documentation adopted the DocBook language. I helped some writers rewrite their documents in this format; for example, the Advanced Bash-Scripting Guide. I also worked on the GNU `makeinfo` program to add DocBook output, making it possible to transform *GNU Info* documentation into Docbook format.
+
+## Background
+
+The [Kubernetes website](https://kubernetes.io/docs/home/) is built with Hugo from documentation written in Markdown format in the [website repository](https://github.com/kubernetes/website), using the [Docsy Hugo theme](https://www.docsy.dev/about/).
+
+The existing API reference documentation is a large HTML file generated from the Kubernetes OpenAPI specification.
+
+On my side, I wanted for some time to make the API Reference more accessible, by:
+- building individual and autonomous pages for each Kubernetes resource
+- adapting the format to mobile reading
+- reusing the website's assets and theme to build, integrate, and display the reference pages
+- allowing the search engines to reference the content of the pages
+
+Around one year ago, I started to work on the generator building the current unique HTML page, to add a DocBook output, so the API Reference could be generated first in DocBook format, and after that in PDF or other formats supported by DocBook processors. The first result has been some [Ebook files for the API Reference](https://github.com/feloy/kubernetes-resources-reference/releases) and an auto-edited paper book.
+
+I decided later to add another output to this generator, to generate Markdown files and create [a website with the API Reference](https://web.archive.org/web/20201022201911/https://www.k8sref.io/docs/workloads/).
+
+When the CNCF proposed a project for the Google Season of Docs to work on the API Reference, I applied, and the match occurred.
+
+## The Project
+
+### swagger-ui
+
+The first idea of the CNCF members that proposed this project was to test the [`swagger-ui` tool](https://swagger.io/tools/swagger-ui/), to try and document the Kubernetes API Reference with this standard tool. 
+
+Because the Kubernetes API is much larger than many other APIs, it has been necessary to write a tool to split the complete API Reference by API Groups, and insert in the Documentation website several `swagger-ui` components, one for each API Group.
+
+Generally, APIs are used by developers by calling endpoints with a specific HTTP verb, with specific parameters and waiting for a response. The `swagger-ui` interface is built for this usage: the interface displays a list of endpoints and their associated verbs, and for each the parameters and responses formats. 
+
+The Kubernetes API is most of the time used differently: users create manifest files containing resources definitions in YAML format, and use the `kubectl` CLI to *apply* these manifests to the cluster. In this case, the most important information is the description of the structures used as parameters and responses (the Kubernetes Resources).
+
+Because of this specificity, we realized that it would be difficult to adapt the `swagger-ui` interface to satisfy the users of the Kubernetes API and this direction has been abandoned.
+
+### Markdown pages
+
+The second stage of the project has been to adapt the work I had done to create the k8sref.io website, to include it in the official documentation website.
+
+The main changes have been to:
+- use go-templates to represent the output pages, so non-developers can adapt the generated pages without having to edit the generator code
+- create a new custom [shortcode](https://gohugo.io/content-management/shortcodes/), to easily create links from inside the website to specific pages of the API reference
+- improve the navigation between the sections of the API reference
+- add the code of the generator to the Kubernetes GitHub repository containing the different reference generators
+
+All the discussions and work done can be found in website [pull request #23294](https://github.com/kubernetes/website/pull/23294).
+
+Adding the generator code to the Kubernetes project happened in [kubernetes-sigs/reference-docs#179](https://github.com/kubernetes-sigs/reference-docs/pull/179).
+
+Here are the features of the new API Reference to be included in the official documentation website:
+
+- the resources are categorized, in the categories Workloads, Services, Config & Storage, Authentication, Authorization, Policies, Extend, Cluster. This structure is configurable with a simple [`toc.yaml` file](https://github.com/kubernetes-sigs/reference-docs/blob/master/gen-resourcesdocs/config/v1.20/toc.yaml)
+- each page displays associated resources at the first level ; for example: Pod, PodSpec, PodStatus, PodList
+- most resource pages inline relevant definitions ; the exceptions are when those definitions are common to several resources, or are too complex to be displayed inline. With the old approach, you had to follow a hyperlink to read each extra detail.
+- some widely used definitions, such as `ObjectMeta`, are documented in a specific page
+- required fields are indicated, and placed first
+- fields of a resource can be categorized and ordered, with the help of a [`fields.yaml` file](https://github.com/kubernetes-sigs/reference-docs/blob/master/gen-resourcesdocs/config/v1.20/fields.yaml)
+- `map` fields are indicated. For example the `.spec.nodeSelector` for a `Pod` is `map[string]string`, instead of `object`, using the value of `x-kubernetes-list-type`
+- patch strategies are indicated
+- `apiVersion` and `kind` display the value, not the `string` type
+- At the top of a reference page, the page displays the Go import necessary to use these resources from a Go program.
+
+The work is currently on hold pending the 1.20 release. When the release finishes and the work is integrated, the API reference will be available at https://kubernetes.io/docs/reference/.
+
+### Future Work
+
+There are points to improve, particularly:
+
+- Some Kubernetes resources are deeply nested. Inlining the definition of these resources makes them difficult to understand.
+- The created `shortcode` uses the URL of the page to reference a Resource page. It would be easier for documentarians if they could reference a Resource by its group and name.
+
+## Appreciation
+
+I would like to thank my mentor [Zach Corleissen](https://github.com/zacharysarah) and the lead writers [Karen Bradshaw](https://github.com/kbhawkey), [Celeste Horgan](https://github.com/celestehorgan), [Tim Bannister](https://github.com/sftim) and [Qiming Teng](https://github.com/tengqm) who supervised me during all the season. They all have been very encouraging and gave me tons of great advice.
@@ -80,7 +80,7 @@ default rotation is configured to take place when log file exceeds 10MB.

 As an example, you can find detailed information about how `kube-up.sh` sets
 up logging for COS image on GCP in the corresponding
-[script](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh)
+[script](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh).

 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
@@ -58,10 +58,11 @@ to containers.  If your job previously ran in a VM, your VM had an IP and could
 talk to other VMs in your project.  This is the same basic model.

 Kubernetes IP addresses exist at the `Pod` scope - containers within a `Pod`
-share their network namespaces - including their IP address.  This means that
-containers within a `Pod` can all reach each other's ports on `localhost`. This
-also means that containers within a `Pod` must coordinate port usage, but this
-is no different from processes in a VM.  This is called the "IP-per-pod" model.
+share their network namespaces - including their IP address and MAC address.
+This means that containers within a `Pod` can all reach each other's ports on
+`localhost`. This also means that containers within a `Pod` must coordinate port
+usage, but this is no different from processes in a VM.  This is called the
+"IP-per-pod" model.

 How this is implemented is a detail of the particular container runtime in use.

@@ -308,28 +308,37 @@ If expanding underlying storage fails, the cluster administrator can manually re

 ## Types of Persistent Volumes

-PersistentVolume types are implemented as plugins.  Kubernetes currently supports the following plugins:
+PersistentVolume types are implemented as plugins. Kubernetes currently supports the following plugins:

-* GCEPersistentDisk
-* AWSElasticBlockStore
-* AzureFile
-* AzureDisk
-* CSI
-* FC (Fibre Channel)
-* FlexVolume
-* Flocker
-* NFS
-* iSCSI
-* RBD (Ceph Block Device)
-* CephFS
-* Cinder (OpenStack block storage)
-* Glusterfs
-* VsphereVolume
-* Quobyte Volumes
-* HostPath (Single node testing only -- local storage is not supported in any way and WILL NOT WORK in a multi-node cluster)
-* Portworx Volumes
-* ScaleIO Volumes
-* StorageOS
+* [`awsElasticBlockStore`](/docs/concepts/storage/volumes/#awselasticblockstore) - AWS Elastic Block Store (EBS)
+* [`azureDisk`](/docs/concepts/sotrage/volumes/#azuredisk) - Azure Disk
+* [`azureFile`](/docs/concepts/storage/volumes/#azurefile) - Azure File
+* [`cephfs`](/docs/concepts/storage/volumes/#cephfs) - CephFS volume
+* [`cinder`](/docs/concepts/storage/volumes/#cinder) - Cinder (OpenStack block storage)
+  (**deprecated**)
+* [`csi`](/docs/concepts/storage/volumes/#csi) - Container Storage Interface (CSI)
+* [`fc`](/docs/concepts/storage/volumes/#fc) - Fibre Channel (FC) storage
+* [`flexVolume`](/docs/concepts/storage/volumes/#flexVolume) - FlexVolume
+* [`flocker`](/docs/concepts/storage/volumes/#flocker) - Flocker storage
+* [`gcePersistentDisk`](/docs/concepts/storage/volumes/#gcepersistentdisk) - GCE Persistent Disk
+* [`glusterfs`](/docs/concepts/storage/volumes/#glusterfs) - Glusterfs volume
+* [`hostPath`](/docs/concepts/storage/volumes/#hostpath) - HostPath volume
+  (for single node testing only; WILL NOT WORK in a multi-node cluster;
+  consider using `local` volume instead)
+* [`iscsi`](/docs/concepts/storage/volumes/#iscsi) - iSCSI (SCSI over IP) storage
+* [`local`](/docs/concepts/storage/volumes/#local) - local storage devices
+  mounted on nodes.
+* [`nfs`](/docs/concepts/storage/volumes/#nfs) - Network File System (NFS) storage
+* `photonPersistentDisk` - Photon controller persistent disk.
+  (This volume type no longer works since the removal of the corresponding
+  cloud provider.)
+* [`portworxVolume`](/docs/concepts/storage/volumes/#portworxvolume) - Portworx volume
+* [`quobyte`](/docs/concepts/storage/volumes/#quobyte) - Quobyte volume
+* [`rbd`](/docs/concepts/storage/volumes/#rbd) - Rados Block Device (RBD) volume
+* [`scaleIO`](/docs/concepts/storage/volumes/#scaleio) - ScaleIO volume
+  (**deprecated**)
+* [`storageos`](/docs/concepts/storage/volumes/#storageos) - StorageOS volume
+* [`vsphereVolume`](/docs/concepts/storage/volumes/#vspherevolume) - vSphere VMDK volume

 ## Persistent Volumes

@@ -87,12 +87,6 @@ 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.

-Also you should not normally create any Pods whose labels match this selector, either directly, via
-another DaemonSet, or via another workload resource such as ReplicaSet.  Otherwise, the DaemonSet
-{{< glossary_tooltip term_id="controller" >}} will think that those Pods were created by it.
-Kubernetes will not stop you from doing this. One case where you might want to do this is manually
-create a Pod with a different value on a node for testing.
-
 ### Running Pods on select Nodes

 If you specify a `.spec.template.spec.nodeSelector`, then the DaemonSet controller will
@@ -419,8 +419,10 @@ Each feature gate is designed for enabling/disabling a specific feature:
   See [Raw Block Volume Support](/docs/concepts/storage/persistent-volumes/#raw-block-volume-support)
   for more details.
 - `BoundServiceAccountTokenVolume`: Migrate ServiceAccount volumes to use a projected volume consisting of a
-   ServiceAccountTokenVolumeProjection.
-   Check [Service Account Token Volumes](https://git.k8s.io/community/contributors/design-proposals/storage/svcacct-token-volume-source.md)
+   ServiceAccountTokenVolumeProjection. Cluster admins can use metric `serviceaccount_stale_tokens_total` to
+   monitor workloads that are depending on the extended tokens. If there are no such workloads, turn off
+   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.
 - `ConfigurableFSGroupPolicy`: Allows user to configure volume permission change policy for fsGroups when mounting a volume in a Pod. See [Configure volume permission and ownership change policy for Pods](/docs/tasks/configure-pod-container/security-context/#configure-volume-permission-and-ownership-change-policy-for-pods) for more details.
 - `CronJobControllerV2`: Use an alternative implementation of the {{< glossary_tooltip text="CronJob" term_id="cronjob" >}} controller. Otherwise, version 1 of the same controller is selected. The version 2 controller provides experimental performance improvements.
@@ -415,6 +415,17 @@ approve node _serving_ certificates for [security
 reasons](https://github.com/kubernetes/community/pull/1982). To use
 `RotateKubeletServerCertificate` operators need to run a custom approving
 controller, or manually approve the serving certificate requests.
+
+A deployment-specific approval process for kubelet serving certificates should typically only approve CSRs which:
+
+1. are requested by nodes (ensure the `spec.username` field is of the form 
+   `system:node:<nodeName>` and `spec.groups` contains `system:nodes`) 
+2. request usages for a serving certificate (ensure `spec.usages` contains `server auth`, 
+   optionally contains `digital signature` and `key encipherment`, and contains no other usages)
+3. only have IP and DNS subjectAltNames that belong to the requesting node, 
+   and have no URI and Email subjectAltNames (parse the x509 Certificate Signing Request 
+   in `spec.request` to verify `subjectAltNames`)
+
 {{< /note >}}

 ## Other authenticating components
@@ -311,6 +311,7 @@ kubectl run nginx --image=nginx                     # Run pod nginx and write it
 kubectl attach my-pod -i                            # Attach to Running Container
 kubectl port-forward my-pod 5000:6000               # Listen on port 5000 on the local machine and forward to port 6000 on my-pod
 kubectl exec my-pod -- ls /                         # Run command in existing pod (1 container case)
+kubectl exec --stdin --tty my-pod -- /bin/sh        # Interactive shell access to a running pod (1 container case) 
 kubectl exec my-pod -c my-container -- ls /         # Run command in existing pod (multi-container case)
 kubectl top pod POD_NAME --containers               # Show metrics for a given pod and its containers
 ```
@@ -122,7 +122,7 @@ sudo apt-get update && sudo apt-get install -y containerd.io
 ```shell
 # Configure containerd
 sudo mkdir -p /etc/containerd
-sudo containerd config default > /etc/containerd/config.toml
+sudo containerd config default | sudo tee /etc/containerd/config.toml
 ```

 ```shell
@@ -200,6 +200,19 @@ If the access URLs of the restored cluster is changed from the previous cluster,

 If the majority of etcd members have permanently failed, the etcd cluster is considered failed. In this scenario, Kubernetes cannot make any changes to its current state. Although the scheduled pods might continue to run, no new pods can be scheduled. In such cases, recover the etcd cluster and potentially reconfigure Kubernetes API server to fix the issue.

+{{< note >}}
+If any API servers are running in your cluster, you should not attempt to restore instances of etcd.
+Instead, follow these steps to restore etcd:
+
+- stop *all* kube-apiserver instances
+- restore state in all etcd instances
+- restart all kube-apiserver instances
+
+We also recommend restarting any components (e.g. kube-scheduler, kube-controller-manager, kubelet) to ensure that they don't
+rely on some stale data. Note that in practice, the restore takes a bit of time.
+During the restoration, critical components will lose leader lock and restart themselves.
+{{< /note >}}
+
 ## Upgrading and rolling back etcd clusters

 As of Kubernetes v1.13.0, etcd2 is no longer supported as a storage backend for
@@ -105,8 +105,8 @@ Type:            Opaque

 Data
 ====
-password.txt:    12 bytes
-username.txt:    5 bytes
+password:    12 bytes
+username:    5 bytes
 ```

 The commands `kubectl get` and `kubectl describe` avoid showing the contents