Merge pull request #21997 from sftim/20200622_tidy_concepts_section_p…

…ost_docsy

Tidy concepts section post-Docsy

content/en/docs/concepts/_index.md

@@ -12,61 +12,3 @@ The Concepts section helps you learn about the parts of the Kubernetes system an
 
 
 <!-- body -->
-
-## Overview
-
-To work with Kubernetes, you use *Kubernetes API objects* to describe your cluster's *desired state*: what applications or other workloads you want to run, what container images they use, the number of replicas, what network and disk resources you want to make available, and more. You set your desired state by creating objects using the Kubernetes API, typically via the command-line interface, `kubectl`. You can also use the Kubernetes API directly to interact with the cluster and set or modify your desired state.
-
-Once you've set your desired state, the *Kubernetes Control Plane* makes the cluster's current state match the desired state via the Pod Lifecycle Event Generator ([PLEG](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/pod-lifecycle-event-generator.md)). To do so, Kubernetes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of a collection of processes running on your cluster:
-
-* The **Kubernetes Master** is a collection of three processes that run on a single node in your cluster, which is designated as the master node. Those processes are: [kube-apiserver](/docs/admin/kube-apiserver/), [kube-controller-manager](/docs/admin/kube-controller-manager/) and [kube-scheduler](/docs/admin/kube-scheduler/).
-* Each individual non-master node in your cluster runs two processes:
-  * **[kubelet](/docs/admin/kubelet/)**, which communicates with the Kubernetes Master.
-  * **[kube-proxy](/docs/admin/kube-proxy/)**, a network proxy which reflects Kubernetes networking services on each node.
-
-## Kubernetes objects
-
-Kubernetes contains a number of abstractions that represent the state of your system: deployed containerized applications and workloads, their associated network and disk resources, and other information about what your cluster is doing. These abstractions are represented by objects in the Kubernetes API. See [Understanding Kubernetes objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/#kubernetes-objects) for more details.
-
-The basic Kubernetes objects include:
-
-* [Pod](/docs/concepts/workloads/pods/pod-overview/)
-* [Service](/docs/concepts/services-networking/service/)
-* [Volume](/docs/concepts/storage/volumes/)
-* [Namespace](/docs/concepts/overview/working-with-objects/namespaces/)
-
-Kubernetes also contains higher-level abstractions that rely on [controllers](/docs/concepts/architecture/controller/) to build upon the basic objects, and provide additional functionality and convenience features. These include:
-
-* [Deployment](/docs/concepts/workloads/controllers/deployment/)
-* [DaemonSet](/docs/concepts/workloads/controllers/daemonset/)
-* [StatefulSet](/docs/concepts/workloads/controllers/statefulset/)
-* [ReplicaSet](/docs/concepts/workloads/controllers/replicaset/)
-* [Job](/docs/concepts/workloads/controllers/job/)
-
-## Kubernetes Control Plane
-
-The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will respond to changes in the cluster and work to make the actual state of all the objects in the system match the desired state that you provided.
-
-For example, when you use the Kubernetes API to create a Deployment, you provide a new desired state for the system. The Kubernetes Control Plane records that object creation, and carries out your instructions by starting the required applications and scheduling them to cluster nodes--thus making the cluster's actual state match the desired state.
-
-### Kubernetes Master
-
-The Kubernetes master is responsible for maintaining the desired state for your cluster. When you interact with Kubernetes, such as by using the `kubectl` command-line interface, you're communicating with your cluster's Kubernetes master.
-
-> The "master" refers to a collection of processes managing the cluster state.  Typically all these processes run on a single node in the cluster, and this node is also referred to as the master. The master can also be replicated for availability and redundancy.
-
-### Kubernetes Nodes
-
-The nodes in a cluster are the machines (VMs, physical servers, etc) that run your applications and cloud workflows. The Kubernetes master controls each node; you'll rarely interact with nodes directly.
-
-
-
-
-## {{% heading "whatsnext" %}}
-
-
-If you would like to write a concept page, see
-[Page Content Types](/docs/contribute/style/page-content-types/#concept)
-for information about the concept page types.
-
-

content/en/docs/concepts/architecture/_index.md

@@ -1,5 +1,7 @@
 ---
 title: "Cluster Architecture"
 weight: 30
+description: >
+  The architectural concepts behind Kubernetes.
 ---
 

content/en/docs/concepts/cluster-administration/_index.md

@@ -1,5 +1,74 @@
 ---
-title: "Cluster Administration"
+title: Cluster Administration
+reviewers:
+- davidopp
+- lavalamp
 weight: 100
+content_type: concept
+description: >
+  Lower-level detail relevant to creating or administering a Kubernetes cluster.
 ---
 
+<!-- overview -->
+The cluster administration overview is for anyone creating or administering a Kubernetes cluster.
+It assumes some familiarity with core Kubernetes [concepts](/docs/concepts/).
+
+
+<!-- body -->
+## Planning a cluster
+
+See the guides in [Setup](/docs/setup/) for examples of how to plan, set up, and configure Kubernetes clusters. The solutions listed in this article are called *distros*.
+
+   {{< note  >}}
+   Not all distros are actively maintained. Choose distros which have been tested with a recent version of Kubernetes.
+   {{< /note >}}
+
+Before choosing a guide, here are some considerations:
+
+ - Do you just want to try out Kubernetes on your computer, or do you want to build a high-availability, multi-node cluster? Choose distros best suited for your needs.
+ - Will you be using **a hosted Kubernetes cluster**, such as [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/), or **hosting your own cluster**?
+ - Will your cluster be **on-premises**, or **in the cloud (IaaS)**? Kubernetes does not directly support hybrid clusters. Instead, you can set up multiple clusters.
+ - **If you are configuring Kubernetes on-premises**, consider which [networking model](/docs/concepts/cluster-administration/networking/) fits best.
+ - Will you be running Kubernetes on **"bare metal" hardware** or on **virtual machines (VMs)**?
+ - Do you **just want to run a cluster**, or do you expect to do **active development of Kubernetes project code**? If the
+   latter, choose an actively-developed distro. Some distros only use binary releases, but
+   offer a greater variety of choices.
+ - Familiarize yourself with the [components](/docs/admin/cluster-components/) needed to run a cluster.
+
+
+## Managing a cluster
+
+* [Managing a cluster](/docs/tasks/administer-cluster/cluster-management/) describes several topics related to the lifecycle of a cluster: creating a new cluster, upgrading your cluster’s master and worker nodes, performing node maintenance (e.g. kernel upgrades), and upgrading the Kubernetes API version of a running cluster.
+
+* Learn how to [manage nodes](/docs/concepts/nodes/node/).
+
+* Learn how to set up and manage the [resource quota](/docs/concepts/policy/resource-quotas/) for shared clusters.
+
+## Securing a cluster
+
+* [Certificates](/docs/concepts/cluster-administration/certificates/) describes the steps to generate certificates using different tool chains.
+
+* [Kubernetes Container Environment](/docs/concepts/containers/container-environment/) describes the environment for Kubelet managed containers on a Kubernetes node.
+
+* [Controlling Access to the Kubernetes API](/docs/reference/access-authn-authz/controlling-access/) describes how to set up permissions for users and service accounts.
+
+* [Authenticating](/docs/reference/access-authn-authz/authentication/) explains authentication in Kubernetes, including the various authentication options.
+
+* [Authorization](/docs/reference/access-authn-authz/authorization/) is separate from authentication, and controls how HTTP calls are handled.
+
+* [Using Admission Controllers](/docs/reference/access-authn-authz/admission-controllers/) explains plug-ins which intercepts requests to the Kubernetes API server after authentication and authorization.
+
+* [Using Sysctls in a Kubernetes Cluster](/docs/concepts/cluster-administration/sysctl-cluster/) describes to an administrator how to use the `sysctl` command-line tool to set kernel parameters .
+
+* [Auditing](/docs/tasks/debug-application-cluster/audit/) describes how to interact with Kubernetes' audit logs.
+
+### Securing the kubelet
+  * [Master-Node communication](/docs/concepts/architecture/master-node-communication/)
+  * [TLS bootstrapping](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/)
+  * [Kubelet authentication/authorization](/docs/admin/kubelet-authentication-authorization/)
+
+## Optional Cluster Services
+
+* [DNS Integration](/docs/concepts/services-networking/dns-pod-service/) describes how to resolve a DNS name directly to a Kubernetes service.
+
+* [Logging and Monitoring Cluster Activity](/docs/concepts/cluster-administration/logging/) explains how logging in Kubernetes works and how to implement it.

content/en/docs/concepts/configuration/_index.md

@@ -1,5 +1,7 @@
 ---
 title: "Configuration"
 weight: 80
+description: >
+  Resources that Kubernetes provides for configuring Pods.
 ---
 

content/en/docs/concepts/containers/_index.md

@@ -1,5 +1,44 @@
 ---
-title: "Containers"
+title: Containers
 weight: 40
+description: Technology for packaging an application along with its runtime dependencies.
+reviewers:
+- erictune
+- thockin
+content_type: concept
 ---
 
+<!-- overview -->
+
+Each container that you run is repeatable; the standardization from having
+dependencies included means that you get the same behavior wherever you
+run it.
+
+Containers decouple applications from underlying host infrastructure.
+This makes deployment easier in different cloud or OS environments.
+
+
+
+
+<!-- body -->
+
+## Container images
+A [container image](/docs/concepts/containers/images/) is a ready-to-run
+software package, containing everything needed to run an application:
+the code and any runtime it requires, application and system libraries,
+and default values for any essential settings.
+
+By design, a container is immutable: you cannot change the code of a
+container that is already running. If you have a containerized application
+and want to make changes, you need to build a new container that includes
+the change, then recreate the container to start from the updated image.
+
+## Container runtimes
+
+{{< glossary_definition term_id="container-runtime" length="all" >}}
+
+## {{% heading "whatsnext" %}}
+
+* Read about [container images](/docs/concepts/containers/images/)
+* Read about [Pods](/docs/concepts/workloads/pods/)
+