Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replaced all references to "master" #21815

Closed
wants to merge 2 commits into from
Closed

Replaced all references to "master" #21815

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
943cb2b
Replaced all references to "master"
punkdata Jun 16, 2020
215344b
Resolved merge conflict
punkdata Jul 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions content/en/docs/concepts/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,61 @@ 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 Primary** is a collection of three processes that run on a single node in your cluster, which is designated as the primary 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-primary node in your cluster runs two processes:
Comment on lines +22 to +23
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs a bit more rewording (see issue #21800): these processes don't actually have to run on a single host.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is primary the preferred term to replace master elsewhere in the docs?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is primary the preferred term to replace master elsewhere in the docs?

“It depends”. primary pairs well with replica, but sometimes it is better to replace master with control plane, or other wording (“leader” if it's the result of an election, for example).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well ... IMHO, "Kubernetes Control Plane" is the term we use elsewhere and the preferred replacement.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other places throughout the documentation, the Master (I'll refer to this as the Primary down below) is discussed as one piece of the Kubernetes Control Plane, not a direct 1-to-1 replacement. The Kubelet is also part of the Control Plane but is not part of the Master.

If we were simply to replace the word "master" with the word "Kubernetes Control Plane", then we end up with awkward descriptions such as this at https://kubernetes.io/docs/concepts/#kubernetes-control-plane

The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes

becomes the following, which doesn't make any sense:

The various parts of the Kubernetes Control Plane, such as the Kubernetes Control Plane and kubelet processes

We can of course re-word this to merge the Primary & CP concepts, but we need to be careful not to erase this architectural distinction. The Kubernetes documentation already has a lot of inconsistencies which are frustrating & confusing for new users. See #21755 for a similar example.

In that case, replacing "Master" with "Primary" would be the easy fix, as long the term "Primary" is the agreed-upon term and is used consistently throughout the documentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, I don't count the kubelet as part of the control plane - see for example the diagram at https://kubernetes.io/docs/concepts/overview/components/#editPageButton

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'm going to rewrite https://kubernetes.io/docs/concepts/#kubernetes-control-plane anyway.

* **[kubelet](/docs/admin/kubelet/)**, which communicates with the Kubernetes Primary.
* **[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 Primary

The Kubernetes primary 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 primary.

> The "primary" 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 primary. The primary 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 primary 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/home/contribute/style/page-content-types/#concept)
for information about the concept page types.