kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
community/sig-architecture/naming/recommendations/001-master-control-plane.md

5.8 KiB
Raw Blame History

Recommendation: master -> control plane

Last Updated: 2020-10-16

Status: Accepted

Recommendation

Within the Kubernetes codebase, the term “master” is often used in reference to the kubernetes control plane, either as a whole or to some subset of the components within. We recommend control plane to refer to the set of components as a whole. We recommend context-specific alternatives when talking about individual components or the roles they serve.

Suggested Alternatives

Control Plane

  • e.g. "The control plane is the set of all components responsible for controlling a kubernetes cluster"
  • e.g. "The control plane is the thing that can be communicated with in order to control a kubernetes cluster"
  • If it matters which specific component(s) or component instance is being communicated with, be specific:
    • endpoint, e.g. "we don't care whether a load balancer, apiserver, or other component is behind this endpoint; we will talk only to this endpoint and no other"
    • instance, e.g. "we are going to create multiple control plane apiserver instances; we will talk only to this specific instance"
    • , e.g. "we will simulate an etcd fault by running this command on instances where etcd is hosted"

Control Plane Node

Leader

  • e.g. "The leader is the winner of a leader election"
  • When using an adjective instead of a noun to describe this concept, there is likely a more specific term:
    • active/passive, e.g. "The active controller-manager process is the one that wins its leader election"
    • primary/replica

Other Considerations

  • if the api field, flag, code, command etc. uses the literal word 'master' and cannot be immediately changed or has no alternative available, use this word only in direct reference to the code item
    • master branch being renamed to main branch falls under this
  • there are no strict guarantees about how and where control plane components can and will run, e.g.
    • they may run on machines that are not registered as Nodes for the Kubernetes cluster they control
    • they may run alongside user workloads on Nodes in the Kubernetes cluster they control
    • there may be one to many instances of each control plane component
  • When using terminology that could be seen as generic, consider whether there is enough context available to disambiguate potential meanings for the reader. e.g.
    • "instance" - an instance of what?
    • "apiserver" - is this a generic apiserver? is this a kubernetes apiserver? is this an apiserver that has been configured to be part of the kubernetes control plane?
    • "endpoint" - what's at the other end of this endpoint?

Context

Master raises first-order concerns according to our language evaluation framework:

Master also raises third-order concerns:

  • within kubernetes it is used to represent a variety of overlapping or unrelated concepts (see the variety of suggested alternatives)
  • one class of usage represents a set of false assumptions:
    • there is exactly one instance of each control plane component
    • there is exactly one kubernetes node that hosts all of these components
    • these components are guaranteed to run in a specific manner (systemd units, on certain ports, etc.)

Prior discussions:

Consequences

TODO