kubespray should stop using the wording "master"

[neolit123]

What would you like to be added

a few years back the Kubernetes projected created a working group called "WG naming" backed by CNCF members which established that words like "master" are offensive in Kubernetes. the whole documentation at k8s.io. was revamped, a number areas of kubernetes/kubernetes were changed, kubeadm and other SIG Cluster Lifecycle subprojects changed too.
there was a kubeadm master -> control plane taint migration if you recall.

as much as i like kubepray, it seems that often it ends up on a bit of an island, where it seems isolated from what's going on in the top level SIG and the K8s ecosystem. i was recently pinged on this issue #11350 where i saw kubespray logs such as "Upgrade first master...".

https://github.com/search?q=repo%3Akubernetes-sigs%2Fkubespray+master&type=code

kubespray should stop using the wording "master" and you can execute on this action in a few steps:

• user facing non breaking changes such as log lines and documentation
• user facing breaking changes with deprecation periods and careful planning
• documenting impossible to change areas

please let me know if you have any questions.

/priority important-longterm

Why is this needed

compliance with the rest of the Kubernetes project

[neolit123]

@cristicalin
@floryut
@liupeng0518
@mzaian
@oomichi
@yankay
@ant31

taken from
https://github.com/kubernetes-sigs/kubespray/blob/master/OWNERS_ALIASES

PTAL

[tico88612]

/help
/good-first-issue

[k8s-ci-robot]

@tico88612:
This request has been marked as suitable for new contributors.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-good-first-issue command.

In response to this:

/help
/good-first-issue

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[floryut]

Indeed at least this occurrence was forgotten

kubespray/roles/kubernetes/control-plane/tasks/kubeadm-upgrade.yml

Line 12 in 1ebd860

- name: Kubeadm | Upgrade first master

[tico88612]

Some documents are still written master, and we must check them thoroughly.

https://kubespray.io/#/docs/CNI/kube-router?id=verifying-kube-router-install

[edgarzzc]

how should we help with this? Shall we check the codes contain the master and fix it?

[yankay]

Thanks @neolit123

The kubespray needs to fix it . :-)

[nicolas-goudry]

I’d like to work on this if nobody started it already.

However, I have a few questions after having reviewed the current state of the repository regarding usages of the master term:

1. at several places, the term is used as an ansible tag:
   • https://github.com/kubernetes-sigs/kubespray/blob/master/extra_playbooks/upgrade-only-k8s.yml#L47
   • https://github.com/kubernetes-sigs/kubespray/blob/master/playbooks/cluster.yml#L38
   • https://github.com/kubernetes-sigs/kubespray/blob/master/playbooks/cluster.yml#L71
   • https://github.com/kubernetes-sigs/kubespray/blob/master/playbooks/upgrade_cluster.yml#L55
   • https://github.com/kubernetes-sigs/kubespray/blob/master/playbooks/upgrade_cluster.yml#L101
   • https://github.com/kubernetes-sigs/kubespray/blob/master/roles/etcd/tasks/main.yml#L42
   • https://github.com/kubernetes-sigs/kubespray/blob/master/roles/etcd/tasks/main.yml#L53
   • https://github.com/kubernetes-sigs/kubespray/blob/master/roles/kubernetes/preinstall/tasks/0050-create_directories.yml#L18
   • https://github.com/kubernetes-sigs/kubespray/blob/master/roles/kubernetes/preinstall/tasks/0050-create_directories.yml#L42
2. should compatibility with old style group names be kept? (ie. kube-master group was renamed to kube_control_plane)
3. what about the kube_master_* ansible variables?
4. does the « master » term renaming should also be applied to etcd (eg. is_etcd_master)? I guess not, but I’m still wondering.
5. should the « worker » term also be taken into account? If so, should it be renamed to just « node »? Or something else?

For (1), should we keep the tag as-is? Add a new control-plane tag and keep the master tag around? For how long though? I think that straightly replacing the master tag with control-plane would be a breaking change for people relying on it.

For (2), most of the comments mentioning the backward compatibility bit are from around 3 years ago, so I guess it would be safe to completely remove them (and effectively breaking backward compatibility, but since it’s been years, it shouldn’t bother anyone).

For (3), I think this is the most dangerous part about this tree-wide renaming since it touches directly to how Kubespray is configured. My thoughts are to add new control_plane_* variables which take the same default value as their kube_master_* siblings and keep supporting both for a bit. Compatibility could be achieved by a specific task, but ATM it seems this task may not be trivial to implement when thinking about the multiple possible scenarios and rules to define and respect in order to choose which one should be used (eg. kube_master_memory_reserved and control_plane_memory_reserved are both set and different, which one should be used and why?).

IMO this issue should be addressed by several PRs:

• tasks names (easy and trivial, no breaking changes)
• file names (easy, very low chances of breaking anything)
• old-style group kube-master (easy, expected breaking changes for people stuck 3y ago)
• tags (may require some thinking and attention to details to avoid breaking anything, no breaking change to expect if backward compatibility is kept)
• variables (hard, very high chances of breaking something)
• documentation (easy but must be done after all changes are done, no breaking changes)

[bogd]

Since I seem to have triggered this (with the kubespray issue ), I would like to help. As @nicolas-goudry pointed out, this is not a trivial task, since it touches many kubespray internals - at a quick search, there are 1486 references to "master" in 331 files across the project.

And after performing the search, I actually came here to say something similar - while some of the search results are not relevant (references to master branches in git repos) and some fixes are simple (like the task name mentioned above), others are not (the variable names, handler names, etc. have a high risk of breaking stuff).

As for the documentation, I believe that needs to be done at the same time as the changes in the code. It will already be confusing if we have two sets of variables doing the same thing (kube_master_* vs kube_control_plane_*) - if the documentation is not also up to date, it will be painful....

[ Edited to add a quick note regarding item 4: the usage of etcd_master seems... inconsistent in the code. Unless I'm misunderstanding something:

• is_etcd_master: "{{ inventory_hostname in groups['etcd'] }}" - so is_etcd_master would basically be is_etcd_node. But...
• in other contexts, etcd_master is just etcd_first_node:

- name: Gen_certs | Gather etcd member/admin and kube_control_plane client certs from first etcd node
  register: etcd_master_certs
...
  delegate_to: "{{ groups['etcd'][0] }}"

]

[bogd]

I started on the "low hanging fruit" (descriptions, comments, task names, etc) here . I am not touching any "sensitive" stuff (like variable names) yet.

A couple more things I noticed while going through the files:

• as mentioned above, variables will be a problem. I have not touched them yet, but probably they will require some "compatibility tasks" (setting kube_control_plane_cpu_reserved from kube_master_cpu_reserved if the former is not defined, but the latter is). Similar to what we have now with the compatibility tasks for the kube-master group, for example, or what we have with KUBE_MASTERS in the inventory builder.
• some references to master are coming from other places in the ecosystem, and most likely will not go away very soon - see here for one simple example (which still references the node-role.kubernetes.io/master label :) )

[VannTen]

I think if you are offended at a common word used in tech, your time can be better spent elsewhere.

This has been discussed at length, in the kubernetes project as well as elsewhere.

Please refrain from discussing the why any further, this is about the how.

[ant31]

@bogd Thank you for taking the time to looking at it.
can you please make a "WIP PR" from your fork so it's easier to follow progress and comment along the way.

[bogd]

@ant31 - Thank you for the suggestion! I was looking for a way to get input from the team while working on this, and this seems like the best way to proceed.

Opened WIP PR #11394 . Looking forward to guidance on the more... "troublesome" steps of the process (see previous comments for some examples).

[bogd]

/assign

[yankay]

There is no reason to change branch name, word master in context of repository is not offensive repository is not a person so calling it master is not wrong, This change will bring a lot of problems not only to the code but also to users, please test first upgrading working production cluster after this change.

Agree with you