From 3ff7312cff367e4321aedf6010bbb8b4a75b3163 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Mon, 22 Jun 2020 23:01:16 +0100 Subject: [PATCH] Add descriptions to Concept sections Each section directly beneath Concepts gains a description. --- content/en/docs/concepts/_index.md | 58 ------------------- .../en/docs/concepts/architecture/_index.md | 2 + .../concepts/cluster-administration/_index.md | 2 + .../en/docs/concepts/configuration/_index.md | 2 + content/en/docs/concepts/containers/_index.md | 5 ++ .../docs/concepts/extend-kubernetes/_index.md | 1 + content/en/docs/concepts/overview/_index.md | 3 +- .../en/docs/concepts/overview/components.md | 3 + .../docs/concepts/overview/kubernetes-api.md | 3 + .../overview/working-with-objects/_index.md | 4 +- content/en/docs/concepts/policy/_index.md | 3 +- .../concepts/scheduling-eviction/_index.md | 3 + content/en/docs/concepts/security/_index.md | 2 + .../concepts/services-networking/_index.md | 7 +++ content/en/docs/concepts/storage/_index.md | 2 + content/en/docs/concepts/workloads/_index.md | 2 + 16 files changed, 41 insertions(+), 61 deletions(-) diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index 27c23bfe4d65e..8165a3a1f45cb 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -12,61 +12,3 @@ The Concepts section helps you learn about the parts of the Kubernetes system an - -## 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. - - diff --git a/content/en/docs/concepts/architecture/_index.md b/content/en/docs/concepts/architecture/_index.md index 3a17d1b08ecbf..61fb48e7142b7 100755 --- a/content/en/docs/concepts/architecture/_index.md +++ b/content/en/docs/concepts/architecture/_index.md @@ -1,5 +1,7 @@ --- title: "Cluster Architecture" weight: 30 +description: > + The architectural concepts behind Kubernetes. --- diff --git a/content/en/docs/concepts/cluster-administration/_index.md b/content/en/docs/concepts/cluster-administration/_index.md index 72af40feecca1..42723fb10ae87 100755 --- a/content/en/docs/concepts/cluster-administration/_index.md +++ b/content/en/docs/concepts/cluster-administration/_index.md @@ -1,5 +1,7 @@ --- title: "Cluster Administration" weight: 100 +description: > + Lower-level detail relevant to creating or administering a Kubernetes cluster. --- diff --git a/content/en/docs/concepts/configuration/_index.md b/content/en/docs/concepts/configuration/_index.md index 1635c2a5bfb11..2ed10d601d63f 100755 --- a/content/en/docs/concepts/configuration/_index.md +++ b/content/en/docs/concepts/configuration/_index.md @@ -1,5 +1,7 @@ --- title: "Configuration" weight: 80 +description: > + Resources that Kubernetes provides for configuring Pods. --- diff --git a/content/en/docs/concepts/containers/_index.md b/content/en/docs/concepts/containers/_index.md index ad442f3ab36e4..432e7459c00b5 100755 --- a/content/en/docs/concepts/containers/_index.md +++ b/content/en/docs/concepts/containers/_index.md @@ -1,5 +1,10 @@ --- title: "Containers" weight: 40 +description: Technology for packaging an application along with its runtime dependencies. +reviewers: +- erictune +- thockin +content_type: concept --- diff --git a/content/en/docs/concepts/extend-kubernetes/_index.md b/content/en/docs/concepts/extend-kubernetes/_index.md index 93d955441d6b7..11cb3f46e0a60 100644 --- a/content/en/docs/concepts/extend-kubernetes/_index.md +++ b/content/en/docs/concepts/extend-kubernetes/_index.md @@ -1,4 +1,5 @@ --- title: Extending Kubernetes weight: 110 +description: Different ways to change the behavior of your Kubernetes cluster. --- diff --git a/content/en/docs/concepts/overview/_index.md b/content/en/docs/concepts/overview/_index.md index ec86980c4b5da..a52c47044685f 100755 --- a/content/en/docs/concepts/overview/_index.md +++ b/content/en/docs/concepts/overview/_index.md @@ -1,4 +1,5 @@ --- title: "Overview" weight: 20 ---- \ No newline at end of file +description: Get a high-level outline of Kubernetes and the components it is built from. +--- diff --git a/content/en/docs/concepts/overview/components.md b/content/en/docs/concepts/overview/components.md index f83f00683e227..53e6b84c16179 100644 --- a/content/en/docs/concepts/overview/components.md +++ b/content/en/docs/concepts/overview/components.md @@ -3,6 +3,9 @@ reviewers: - lavalamp title: Kubernetes Components content_type: concept +description: > + A Kubernetes cluster consists of the components that represent the control plane + and a set of machines called nodes. weight: 20 card: name: concepts diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index dd69fb6ccbf5a..b3b696035817d 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -4,6 +4,9 @@ reviewers: title: The Kubernetes API content_type: concept weight: 30 +description: > + The Kubernetes API lets you query and manipulate the state of objects in Kubernetes. + The core of Kubernetes' control plane is the API server and the HTTP API that it exposes. Users, the different parts of your cluster, and external components all communicate with one another through the API server. card: name: concepts weight: 30 diff --git a/content/en/docs/concepts/overview/working-with-objects/_index.md b/content/en/docs/concepts/overview/working-with-objects/_index.md index 8661349a3fbc4..f872c20697238 100755 --- a/content/en/docs/concepts/overview/working-with-objects/_index.md +++ b/content/en/docs/concepts/overview/working-with-objects/_index.md @@ -1,5 +1,7 @@ --- title: "Working with Kubernetes Objects" weight: 40 +description: > + Kubernetes objects are persistent entities in the Kubernetes system. Kubernetes uses these entities to represent the state of your cluster. + Learn about the Kubernetes object model and how to work with these objects. --- - diff --git a/content/en/docs/concepts/policy/_index.md b/content/en/docs/concepts/policy/_index.md index 41d91de546fc5..d2b42bc4cd74d 100755 --- a/content/en/docs/concepts/policy/_index.md +++ b/content/en/docs/concepts/policy/_index.md @@ -1,5 +1,6 @@ --- title: "Policies" weight: 90 +description: > + Policies you can configure that apply to groups of resources. --- - diff --git a/content/en/docs/concepts/scheduling-eviction/_index.md b/content/en/docs/concepts/scheduling-eviction/_index.md index a30a80a451a15..3a2bf9359f1e9 100644 --- a/content/en/docs/concepts/scheduling-eviction/_index.md +++ b/content/en/docs/concepts/scheduling-eviction/_index.md @@ -1,5 +1,8 @@ --- title: "Scheduling and Eviction" weight: 90 +description: > + In Kubernetes, scheduling refers to making sure that Pods are matched to Nodes so that the kubelet can run them. + Eviction is the process of proactively failing one or more Pods on resource-starved Nodes. --- diff --git a/content/en/docs/concepts/security/_index.md b/content/en/docs/concepts/security/_index.md index aecc16eee7a1d..3dfb62fe48253 100644 --- a/content/en/docs/concepts/security/_index.md +++ b/content/en/docs/concepts/security/_index.md @@ -1,4 +1,6 @@ --- title: "Security" weight: 81 +description: > + Concepts for keeping your cloud-native workload secure. --- diff --git a/content/en/docs/concepts/services-networking/_index.md b/content/en/docs/concepts/services-networking/_index.md index eea2c65b33e01..2e7d91427e6c6 100755 --- a/content/en/docs/concepts/services-networking/_index.md +++ b/content/en/docs/concepts/services-networking/_index.md @@ -1,5 +1,12 @@ --- title: "Services, Load Balancing, and Networking" weight: 60 +description: > + Concepts and resources behind networking in Kubernetes. --- +Kubernetes networking addresses four concerns: +- Containers within a Pod use networking to communicate via loopback. +- Cluster networking provides communication between different Pods. +- The Service resource lets you expose an application running in Pods to be reachable from outside your cluster. +- You can also use Services to publish services only for consumption inside your cluster. diff --git a/content/en/docs/concepts/storage/_index.md b/content/en/docs/concepts/storage/_index.md index 7e0dd19b1251a..a6aeac77348c8 100755 --- a/content/en/docs/concepts/storage/_index.md +++ b/content/en/docs/concepts/storage/_index.md @@ -1,5 +1,7 @@ --- title: "Storage" weight: 70 +description: > + Ways to provide both long-term and temporary storage to Pods in your cluster. --- diff --git a/content/en/docs/concepts/workloads/_index.md b/content/en/docs/concepts/workloads/_index.md index ca394ebd0029d..1aac095cb5d2c 100644 --- a/content/en/docs/concepts/workloads/_index.md +++ b/content/en/docs/concepts/workloads/_index.md @@ -1,5 +1,7 @@ --- title: "Workloads" weight: 50 +description: > + Understand Pods, the smallest deployable compute object in Kubernetes, and the higher-level abstractions that help you to run them. ---