Change the "Master" nomenclature

[Jon-AtAWS]

Is your feature request related to a problem? Please describe.
Coming from #2589.

Describe the solution you'd like
Change all code, parameters, APIs, and documentation to refer to "leader" nodes instead of "master" nodes.

The goal is to have a consistent term to refer to this node function, while avoiding offensive language.

Describe alternatives you've considered
Other possible terminology
Manager (Keeps the"M" for abbreviations and existing diagrams)
Controller

---

Added on 04/18/2022:
Workitems in Plugins

• Deprecate the "Master" nomenclature alerting#320
• Deprecate the "Master" nomenclature anomaly-detection#397
• Deprecate the "Master" nomenclature index-management#285
• Deprecate the "Master" nomenclature k-NN#307
• Change the "Master" nomenclature sql#463
• Change the "Master" nomenclature asynchronous-search#99
• Change the "Master" nomenclature  cross-cluster-replication#319
• Deprecate the "Master" nomenclature performance-analyzer#152
• Deprecate the "Master" nomenclature performance-analyzer-rca#139
• Deprecate the "Master" nomenclature security#1664

In Other Projects

• [FEATURE] Change the "master" nomenclature documentation-website#450
• Deprecate the "Master" nomenclature OpenSearch-Dashboards#1318

[dgomesbr]

Suggesting Main instead of Leader as standard following https://github.com/github/renaming

[sharp-pixel]

I believe the context is very different between master/main branch in a repo and master/leader node. Master nodes are not the main nodes in the cluster.

[sharp-pixel]

@Jon-AtAWS , you mention code and parameters, should we update cluster settings and APIs as well (e.g. /_cat/master)?

[Jon-AtAWS]

Ideally, we would change from master/(slave - implied) terminology across the board. So, yes, changing the _cat APIs as well.

Also, I agree "main" doesn't really fit for me. The function of the nodes is to hold and broadcast state, so "manager" is a close second for me.

[morsik]

@Jon-AtAWS words are not offensive by themselves! It's time to start learn that finally!
There is nothing offensive in word "master" which here refers only to software. Don't change things that work. Don't bring stupid naming, because someone told you so.

Eh, this talk again…

Simple example: If I shout at friend in a friendly-laughy-way: "hey, stupid! ;)" it won't be offensive. But If I should: "Hey You! Stupid!" to someone else - it is offensive. It's not words, it's context. And software context has nothing to do with offense at all.

Changing words like that is very bad and not helpful with your "real world" (I mean slavery) problem as it more like sweeping it under the rug. You're just pretending there's no anything like master-slave relation - while here - in software - it is! Let alone, we don't have slavery right now here in our countries and you're trying to wash your hands by doing such change (like something like that never happened in your country). This is just pure madness and world is broken.

Good luck with project because I'm looking into it, but please leave stupid ideas behind and do something that is really meaningful to us - users - which is actual software.

And don't get me wrong - I'm from Poland - we didn't have slavery and stuff like that, I'm just looking at all that crap from outside of America region and I may be not aware of your internal problems (but it's still your internal problems, not rest of the world!) - but from my point of view it's like: You are just trying to wash your hands from history by removing those words. And I know that because I live in country which was occupied in WW2 by Germany (not Nazis! Nazis was a political party in Germany country!) and they are trying to wash that history too in their country by forbiding telling anything about WW2 and by changing "Germany" to "Nazis" like it is another country so people can forget that Germans did (quite similar to your word changing, isn't it?).

@YtFI apart from my personal opinion regarding this change - "Control Plane" in Kubernetes is different thing from "master"/"manager" - so definitely big no for "control plane" in ES. Especially that "Control Plane" is general term for all set of services that makes kubernetes master, database and other tools needed to operate Kube cluster - while here in ElasticSearch it's just single application (I mean: ElasticSearch; or here called: OpenSearch).

[sercasti]

I think this issue should be closed and ignored.

[Redacted]

Every minute we spend with this stupid nonsense is a waste of time. Jon, nobody is forcing you to use this product, if you don't like it, you're free to use a different one. Period.

Note: This comment was edited to remove content the that was in volition of the project code of conduct. Comment was flagged by @stockholmux.

[stockholmux]

On behalf of the maintainers of the project I agree that the term 'master' may be offensive to some people. This project is committed to being a community where everyone can join and contribute. This means using inclusive and welcoming language. The repo defaults to main for the branch and, in a similar vein, supporting inclusive language should extend to the API and the rest of the software as long as it can be made in a backward compatible way.

[dblock]

Thanks @stockholmux. I would kindly ask for future comments to please be limited to technical arguments, and we really appreciate all your suggestions and thoughts and contributions.

[Jon-AtAWS]

Thanks for the replies, folks. I appreciate that this is a possibly difficult, and politicized discussion. I want to encourage everyone to stick with the technical. And I want to +1 @stockholmux's comment above on a commitment to inclusivity.

[morsik]

@Jon-AtAWS sorry, but I just don't see how "inclusivity" connects with some people's personal problems with wrong understanding of word in this context. And @sercasti has point here. Any word can be offensive to anyone. If "world" decides one day that >any other word< is offensive, will we go with this nonsense over and over again?

You can't make everyone's happy - that's unwritten rule to this world. And inclusivity doesn't mean changing words - inclusivity means we welcome all people to commit to project, we welcome everybody to be part of community no matter who they are. And this I can just write in very simple Code of Conduct rules:

Be human, not asshole.

That's all. So, be human, be welcome to other people, be nice and I encourage everyone to take part of this (and any other projects) - but please don't change real inclusivity into some political war (like even you mentioned) or some day this will turn to those people who didn't wanted such "offensive" words (which - they are just not offensive, let's be honest - and there's even prove to that because you ignored @sercasti's comment here who makes good point here).

I just try to understand all of this "political correctness", but I simply can't.

[rursprung]

disclaimer: this is very much my personal opinion (anything not 100% technical will always be my personal opinion and not reflect any opinion of an employer or other 3rd party if not explicitly mentioned).

i very much try not to be pulled into a political discussion here (you can only lose if you try to be part of such a discussion), but: i agree that changing words in a software (which has nothing to do with slavery) does not change anything in the real world. want to end modern-day slavery or increase equality in society? then work on that, rather than doing virtue signaling.

with that out of the way, i have a simple technical reason why this renaming shouldn't be done: this nomenclature is part of various APIs (e.g. in the cluster API). changing this would change the API. besides this being a breaking change (and you should break as little as possible) it'd also break compatibility with elasticsearch 7.10. and the statement was that you want to be compatible with ES 7.10 for as long as possible.

[stockholmux]

@rursprung I don't think an API change like this would happen in a disorderly fashion - like any API change, it would go through a deprecation period on a major version change.

[beejeebus]

👋 what's the best way to proceed? I'm happy to work on this with a bit of direction on how to chunk up the changes.

[CEHENKLE]

I added the 2.0 release (when we'd want to fix this) and removed "help wanted" as it's not a good starting issue for someone.

[tlfeng]

This is the plan to resolve the issue.

Goal of the enhancement

Replace non-inclusive terminology "master" throughout this repository with inclusive one.

Context

What is "inclusive language"?

Inclusive language is designed to avoid excluding people on the basis of gender, sexual preference, age, race, ability, etc. By using language that avoids expressions which imply or express ideas that have prejudice to any particular group of people, we aim to create a more equitable community.

Why using "inclusive language" is important?

Using inclusive language helps build an inclusive environment, which accepts diversity and ensures any individuals and groups feel welcome, respected, and safe. Diversity does contribute to create a fair and strong organization, and also leads to diversity of ideas, which change into creativity and innovation.

How to apply "inclusive language" in a software program?

Replace objectionable language in code bases and documentation. It involves assessing existing code bases and documentation, identifying potentially problematic language, then replacing terms with more preferable language.

Solution

Overview

To solve the issue, breaking changes will be introduced to OpenSearch, which requires backwards compatibility. The exclusionary terms exist in APIs and configurations, which will impact the compatibility with previous versions of OpenSearch and its third-party clients and tools.
We will support both and new APIs or configurations for a period of time, to let users get used to the breaking changes gradually. Considering OpenSearch follows Semantic Versioning, we are going to include the new API and configuration in current minor versions, while continuing to provide support for the previous APIs and configurations for a period of time, then remove support for the old ones in a next major version.

Substitute for the exclusionary terminology

Our proposed preferable terminologies to replace "master" (when referring to a role of node): leader, primary, manager, ClusterManager, ClusterCoordinator

Location for the terminology:

• "master branch" in documents
• code comments
• internal variable, method and class names
• log messages
• documentation (md file)
• field, method, class and package names that are exposed as API in Java libraries (renaming will impact clients and plugins that depend on OpenSearch code base)
• setting names and values (including definition, yml configuration files)
• REST APIs (including endpoint, path parameter, request parameter and response field)
• tests

Versions to introduce the change

• Add the new usages with inclusive terminology and deprecation notice for the old usages in minor versions of 1.x.
• Remove the support for the old usages (APIs and settings) in a major version, it could be either 2.0 or 3.0.

Explanation:

1. The ideal case is to apply inclusive naming to replace the exclusionary terminology as soon as possible, but the backwards compatibility is a key aspect to be considered, so with new usages added soon, the old usages will be kept for a while before removal to keep the compatibility.
2. Considering OpenSearch follows Semantic Versioning, deprecation notice MUST come at a minor version, and the breaking change, such as API removal MUST come at a major version.
3. Update in March 2022: In practice, new usages will be added in version 2.0, and old usages will be removed in at least version 3.0.

Procedure for the replacement

1. Replace the exclusionary words that won’t impact the compatibility.

(source of the idea)
In the following location:

• Documents (but keep the content for the existing API and configuration usages)
• code comments
• Internal variable, method and class names

2. Deprecate old usages that having exclusionary words and impact the compatibility, then create alternative usages with the inclusive terms.

(source of the idea)
This step includes the following effort:

1. Deprecate the REST APIs and settings which contains exclusionary words.
2. Add proper form of deprecation notice for every REST API and setting changes, including in code (such as adding @Deprecated annotation), console output and logs.
3. Create alternative REST APIs and settings where having name change, so that calls to the new names can have the same effect with the old names.
4. For settings, adding fallback logic to fallback to the existing setting with old name, when the corresponding new setting is not configured.

The location that will impact the compatibility when changed:

• Configuration, including setting name and value.
• REST API, including endpoint, path parameter, request parameter and response field.

3. Add tests to check both old and new usages - REST APIs and settings.

(source of the idea)
Adding new unit tests to check the both old and new names have got the same functionality.

4. Replace the exclusionary words in log messages and update documentation.

This step includes the following effort:

1. Replace the exclusionary words in log messages and console outputs.
2. Update the user and developer documents to introduce the new usages, and notice the deprecation of old usages.

5. Replace the exclusionary words that will impact software programs depend on OpenSearch Java libraries - in Java APIs.

Replace the exclusionary words in all Java APIs, including field, method, class, and package names.
The "Java APIs" refers to those packaged in Java libraries and are published to Maven (https://search.maven.org/search?q=g:org.opensearch https://mvnrepository.com/artifact/org.opensearch)
Impact of this step:
All plugins, clients and tools that use OpenSearch Java APIs from OpenSearch Java libraries which contain non-inclusive terminologies have to make corresponding changes to call new APIs, if they want to upgrade the dependency to a future major version of OpenSearch.

6. Remove the deprecated configurations and REST APIs in a future major version.

Sub-issues

• Replace "master" terminology in code comments, and internal variable, method and class names #1548
• Add alternative usages for the REST APIs and configurations that contain "master" terminology #1549
• Replace "master" terminology in Log message #2539
• Replace "master" terminology in documentation #2694
• Replace "master" terminology in Java APIs #1684
• Remove the usages with non-inclusive language.

Appendix

Location that contains the exclusionary term and will impact the compatibility when changed

Setting names
1 Discovery and cluster formation settings
cluster.initial_master_nodes (static)
cluster.no_master_block (dynamic)
discovery.zen.no_master_block
discovery.zen.minimum_master_nodes
discovery.zen.master_election.*
Note: discovery.zen.* settings are already deprecated in Elasticsearch 7.0, but code remains to be removed. Update: they have been removed in OpenSearch 2.0 by the commit 4db97aa)

2 Local gateway settings
gateway.expected_master_nodes
gateway.recover_after_master_nodes
Note: the above 2 settings are already deprecated in Elasticsearch 7.7, but code remains to be removed.

3 Miscellaneous
cluster.service.slow_master_task_logging_threshold (dynamic)
Code: https://github.com/opensearch-project/OpenSearch/blob/1.0.0/server/src/main/java/org/opensearch/cluster/service/MasterService.java#L90

Setting values
1 Node roles
node.roles: [ master ] (static)

REST API endpoints
1 cat master
GET _cat/master

REST API path parameters
1 "node filters" used in some cluster-level APIs. The APIs are usually in the format: GET /_nodes/<node_id>, where <node_id> can be set as _master or master:true or master:false to filter the master nodes.
Nodes Info API API - GET /_nodes/<node_id>
Nodes stats API - GET /_nodes/<node_id>/stats , GET/_nodes/<node_id>/stats/<metric> , GET /_nodes/<node_id>/stats/<metric>/<index_metric>
Nodes feature usage API - GET /_nodes/<node_id>/usage , GET /_nodes/<node_id>/usage/<metric>
Nodes hot threads API - GET /_nodes/<node_id>/hot_threads
Nodes reload secure settings API - POST /_nodes/<node_id>/reload_secure_settings
Task management API - GET _tasks?nodes=<node_id>

REST API request parameter names
1 master_timeout (used in multiple APIs)

• In CAT API:
  CAT Allocation API https://opensearch.org/docs/opensearch/rest-api/cat/cat-allocation/
  CAT Indices API https://opensearch.org/docs/opensearch/rest-api/cat/cat-indices/
  CAT Master API https://opensearch.org/docs/opensearch/rest-api/cat/cat-master/
  CAT Nodeattrs API https://opensearch.org/docs/opensearch/rest-api/cat/cat-nodeattrs/
  CAT Nodes API https://opensearch.org/docs/latest/opensearch/rest-api/cat/cat-nodes/
  CAT Pending tasks API https://opensearch.org/docs/opensearch/rest-api/cat/cat-pending-tasks/
  CAT Plugins API https://opensearch.org/docs/opensearch/rest-api/cat/cat-plugins/
  CAT Repositories API https://opensearch.org/docs/opensearch/rest-api/cat/cat-repositories/
  CAT Shards API https://opensearch.org/docs/opensearch/rest-api/cat/cat-shards/
  CAT Snapshots API https://opensearch.org/docs/opensearch/rest-api/cat/cat-snapshots/
  CAT Templates API https://opensearch.org/docs/opensearch/rest-api/cat/cat-templates/
  CAT Thread pool API https://opensearch.org/docs/opensearch/rest-api/cat/cat-thread-pool/
  CAT Segment API https://opensearch.org/docs/latest/opensearch/rest-api/cat/cat-segments/
• In Cluster API:
  Cluster health API https://opensearch.org/docs/opensearch/rest-api/cluster-health/
  Cluster reroute API - POST /_cluster/reroute
  Cluster state API - GET /_cluster/state/<metrics>/<target>
  Cluster get settings API https://opensearch.org/docs/latest/opensearch/rest-api/cluster-settings/
  Cluster update settings API https://opensearch.org/docs/latest/opensearch/rest-api/cluster-settings/
  Pending cluster tasks API - GET /_cluster/pending_tasks
• In Index API:
  Index management:
  Create index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/create-index/
  Delete index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/delete-index/
  Get index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/get-index/
  Open index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/open-index/
  Close index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/close-index/
  Clone index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/clone/
  Shrink index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/shrink-index/
  Split index API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/split/
  Rollover index API POST /<rollover-target>/_rollover/<target-index>
  Alias management:
  Add index alias API https://opensearch.org/docs/latest/opensearch/rest-api/alias/
  Delete index alias API DELETE /<index>/_alias/<alias>
  Mapping management:
  Get mapping API
  Put mapping API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/put-mapping/
  Index settings:
  Get Index Settings API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/get-settings/
  Update index settings API https://opensearch.org/docs/latest/opensearch/rest-api/index-apis/update-settings/
  Index templates:
  Get (Legacy) Index Template API GET /_template/<index-template>
  Delete (Legacy) Index Template API DELETE /_template/<index-template>
  Put (Legacy) Index Template API PUT /_template/<index-template>
  Get (Composable) Index Template API GET /_index_template/<index-template>
  Delete (Composable) Index Template API
  Put (Composable) Index Template API
  Get Component Template API GET /_component_template/<index-template>
  Delete Component Template API
  Put Component Template API
  Simulate index API POST /_index_template/_simulate_index/{name}
  Simulate index template API POST /_index_template/_simulate
  Dangling indices:
  Delete Dangling Index API
  Import Dangling Index API POST /_dangling/<index-uuid>
  Other:
  Add index block API PUT /<index>/_block/<block>
• In Snapshot API:
  Put snapshot repository API PUT /_snapshot/<repository>, POST /_snapshot/<repository>
  Get snapshot repository API
  Delete snapshot repository API
  Clean up snapshot repository API POST /_snapshot/<repository>/_cleanup
  Verify snapshot repository API POST /_snapshot/<repository>/_verify
  Create snapshot API
  Get snapshot API
  Delete snapshot API
  Restore snapshot API POST /_snapshot/<repository>/<snapshot>/_restore
  Clone snapshot API
  Get snapshot status API GET _snapshot/<repository>/<snapshot>/_status
• In Ingest API:
  Put pipeline API https://opensearch.org/docs/latest/opensearch/rest-api/ingest-apis/create-update-ingest/
  Get pipeline API https://opensearch.org/docs/latest/opensearch/rest-api/ingest-apis/get-ingest/
  Delete pipeline API https://opensearch.org/docs/latest/opensearch/rest-api/ingest-apis/delete-ingest/
• In Script API:
  Get stored script API GET _scripts/<script-id>
  Put stored script API
  Delete stored script API

REST API request parameter values
1 metric=master_node
Cluster reroute API - POST /_cluster/reroute
Cluster state API - GET /_cluster/state/<metrics>/<target>

REST API response fields
1 discovered_master
Response of GET _cluster/health
doc: https://opensearch.org/docs/latest/opensearch/rest-api/cluster-health/#response
code: https://github.com/opensearch-project/OpenSearch/blob/1.1.0/server/src/main/java/org/opensearch/action/admin/cluster/health/ClusterHealthResponse.java#L69
Response of GET _cat/health (in the header of table)
doc: https://opensearch.org/docs/latest/opensearch/rest-api/cat/cat-health/#response
code: https://github.com/opensearch-project/OpenSearch/blob/1.2.4/server/src/main/java/org/opensearch/rest/action/cat/RestHealthAction.java#L91

2 cat nodes
Response of GET _cat/nodes

Location that contains the exclusionary terms and will impact software programs depend on OpenSearch Java libraries

API of Java library
These libraries have been published to Maven. (Links: https://mvnrepository.com/artifact/org.opensearch https://search.maven.org/search?q=g:org.opensearch)
Java Low Level REST Client
1 field org.opensearch.client.NodeSelector.SKIP_DEDICATED_MASTERS
https://opensearch.org/javadocs/1.1.0/OpenSearch/client/rest/build/docs/javadoc/org/opensearch/client/NodeSelector.html#SKIP_DEDICATED_MASTERS
2 method org.opensearch.client.Node.Roles.isMasterEligible()
https://opensearch.org/javadocs/1.1.0/OpenSearch/client/rest/build/docs/javadoc/org/opensearch/client/Node.Roles.html#isMasterEligible()

Java High Level REST Client
1 field org.opensearch.client.TimedRequest.DEFAULT_MASTER_NODE_TIMEOUT
https://opensearch.org/javadocs/1.1.0/OpenSearch/client/rest-high-level/build/docs/javadoc/org/opensearch/client/TimedRequest.html#DEFAULT_MASTER_NODE_TIMEOUT
2 method org.opensearch.client.TimedRequest.masterNodeTimeout()
3 org.opensearch.client.indices.GetComponentTemplatesRequest.getMasterNodeTimeout()
https://opensearch.org/javadocs/1.1.0/OpenSearch/client/rest-high-level/build/docs/javadoc/org/opensearch/client/indices/GetComponentTemplatesRequest.html#getMasterNodeTimeout()
4 org.opensearch.client.indices.GetComponentTemplatesRequest.setMasterNodeTimeout()
... (and a few other getMasterNodeTimeout() and setMasterNodeTimeout())

server
1 package org.opensearch.action.support.master
https://opensearch.org/javadocs/1.1.0/OpenSearch/server/build/docs/javadoc/org/opensearch/action/support/master/package-summary.html
2 class org.opensearch.cluster.MasterNodeChangePredicate
https://opensearch.org/javadocs/1.1.0/OpenSearch/server/build/docs/javadoc/org/opensearch/cluster/MasterNodeChangePredicate.html
3 field org.opensearch.action.support.master.MasterNodeRequest.DEFAULT_MASTER_NODE_TIMEOUT
https://opensearch.org/javadocs/1.1.0/OpenSearch/server/build/docs/javadoc/org/opensearch/action/support/master/MasterNodeRequest.html#DEFAULT_MASTER_NODE_TIMEOUT
4 org.opensearch.discovery.zen.MasterFaultDetection.masterNode()
https://opensearch.org/javadocs/1.1.0/OpenSearch/server/build/docs/javadoc/org/opensearch/discovery/zen/MasterFaultDetection.html#masterNode()
... (totally about 210 items)

Related issues and PRs

Existing PR before the issue created: #564

[peternied]

@tlfeng Thanks for driving this effort, I would strongly recommend adding a mechanism to ensure we have removed all of these terms. By onboarding a separate check style workflow that can be created and run automatically by plugins it ensure compliance and lets you capture metrics charting the progress to zero.

I've created a couple of checkstyle rules in this PR for the security plugin opensearch-project/security#1782

[tlfeng]

@peternied Thank you for your suggestion! I knew this campaign lack a mechanism to validate the achievement, it looks like a feasible solution. 😄

[flavienbwk]

Strange for Amazon engineers to take a decision implying dozens of hours of refactoring (just highly political without any impact on the real world) instead of focusing on real features improving the software and asked by your community.

Just saying "this is inclusive" and "this solves a problem" doesn't mean it is nor it does...

How much time are you going to loose on this ? Is this even estimated ?

[peternied]

@flavienbwk I appreciate your desire to improve OpenSearch, please open an issue or create a pull request in areas you'd to see updated/enhanced.

[peternied]

I've created an issue to track a centralized mechanism, opensearch-project/opensearch-plugins#147

[cliu123]

There are multiple APIs in OpenSearch core still have master terminology, so security plugin cannot remove all of them: node.master, ClusterChangedEvent.localNodeMaster(), org.opensearch.action.support.master,MasterNodeOperationRequestBuilder.

[saratvemulapalli]

@tlfeng looks like we do have few changes reverted, so is it safe to assume we will not ship in 2.1.0?
I'll slap 2.2.0 label, let me know if you think otherwise.

[anasalkouz]

With 2.4 release, we have deprecated all non-inclusive usages (i.e. master, blacklist and whitelist) and we are planning to remove those deprecated usages on 3.0 release.

[morsik]

all non-inclusive usages (i.e. master, blacklist and whitelist)

@anasalkouz after all this talk being on the other side of Ocean, I still don't see what's "non-inclusive" in those terms. Sorry. The world is just broken and you're doing wrong thing here.

[anasalkouz]

Closing the issue.