David Smiley created SOLR-18160:
-----------------------------------
Summary: Deprecate ADDROLE / REMOVEROLE Collection API in favor of
Node Roles
Key: SOLR-18160
URL: https://issues.apache.org/jira/browse/SOLR-18160
Project: Solr
Issue Type: Task
Components: SolrCloud
Reporter: David Smiley
The {{ADDROLE}} and {{REMOVEROLE}} Collection API commands should be deprecated
in favor of the newer [Node
Roles|https://solr.apache.org/guide/solr/latest/deployment-guide/node-roles.html]
system ({{-Dsolr.node.roles}}), which was added later and fully subsumes their
functionality.
h2. Background
SolrCloud has two overlapping mechanisms for designating overseer nodes:
h3. Old: ADDROLE / REMOVEROLE (Collection API)
* *APIs*:
[ADDROLE|https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-node-management.html#addrole]
and
[REMOVEROLE|https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-node-management.html#removerole]
** V1: {{?action=ADDROLE&role=overseer&node=...}}
** V2: {{POST /api/cluster}} with {{add-role}} / {{remove-role}} commands
* Only supports the {{overseer}} role.
* Stores assignments persistently in {{/roles.json}} in ZooKeeper.
* Triggers {{OverseerNodePrioritizer}} to reshuffle the overseer election queue.
* Already a *no-op* when distributed Collection API is enabled
({{OverseerRoleCmd}} lines 59-66 silently returns).
h3. New: Node Roles ({{-Dsolr.node.roles}})
* *APIs*: [Node
Roles|https://solr.apache.org/guide/solr/latest/deployment-guide/node-roles.html]
** {{GET /api/cluster/node-roles}} — list all role assignments
** {{GET /api/cluster/node-roles/supported}} — list supported roles and modes
** {{GET /api/cluster/node-roles/role/\{role\}}} — list by role
** {{GET /api/cluster/node-roles/node/\{node\}}} — list by node
* Supports multiple roles: {{data}}, {{overseer}}, {{coordinator}}.
* Configured at startup via {{-Dsolr.node.roles=data:on,overseer:preferred}}.
* Uses ephemeral ZK nodes under {{/node_roles/\{role\}/\{mode\}/\{nodeName\}}}
— auto-cleaned on node shutdown.
* Controls replica placement ({{data:off}} prevents a node from hosting
replicas) — functionality ADDROLE never had.
* Works regardless of whether the Collection API is distributed or
Overseer-based.
h2. How they overlap today
{{OverseerNodePrioritizer.prioritizeOverseerNodes()}} currently *merges both
sources*: it reads {{/roles.json}} (old) and {{/node_roles/overseer/preferred}}
(new), combines the lists, and uses the result to prioritize the overseer
election queue.
If a node appears in both, the code already logs a warning:
{quote}
Node \{X\} has been configured to be a preferred overseer using both ADDROLE
API command as well as using Node Roles (i.e. -Dsolr.node.roles start up
property). Only the latter is recommended.
{quote}
h2. Does ADDROLE do anything NodeRoles cannot?
*No.* The only arguable difference is that ADDROLE is a dynamic API (change at
runtime without restart) whereas NodeRoles requires {{-Dsolr.node.roles}} at
JVM startup. However:
* The Overseer itself is being phased out (distributed Collection API makes it
unnecessary), so adding dynamic overseer designation to NodeRoles seems
unwarranted.
* Dynamic runtime role assignment could be added to NodeRoles separately if
ever needed.
h2. Comparison
||Aspect||ADDROLE / REMOVEROLE||Node Roles||
|Scope|Only {{overseer}}|{{data}}, {{overseer}}, {{coordinator}}|
|Configuration|Dynamic API call|JVM startup property|
|ZK storage|Persistent {{/roles.json}}|Ephemeral {{/node_roles/}} znodes|
|Replica placement|No effect|{{data:off}} prevents replicas on a node|
|Node lifecycle|Must explicitly REMOVEROLE|Auto-removed when node stops|
|Distributed Collection API|No-op (silently ignored)|Works regardless|
h2. Proposed work
# Mark {{ADDROLE}} and {{REMOVEROLE}} as deprecated in code and ref guide.
# Mark the related V2 API commands ({{add-role}} / {{remove-role}} on
{{/api/cluster}}) as deprecated.
# Mark the {{roles}} field in {{CLUSTERSTATUS}} response as deprecated.
# Add deprecation warnings in {{OverseerRoleCmd}} when the APIs are actually
invoked.
# Update the
[ADDROLE|https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-node-management.html#addrole]
and
[REMOVEROLE|https://solr.apache.org/guide/solr/latest/deployment-guide/cluster-node-management.html#removerole]
ref guide sections to note deprecation and point users to [Node
Roles|https://solr.apache.org/guide/solr/latest/deployment-guide/node-roles.html].
h2. Key source files
*
[OverseerRoleCmd.java|https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cloud/api/collections/OverseerRoleCmd.java]
— ADDROLE/REMOVEROLE implementation
*
[OverseerNodePrioritizer.java|https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cloud/OverseerNodePrioritizer.java]
— merges both role sources for overseer election prioritization
*
[NodeRoles.java|https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/core/NodeRoles.java]
— Node Roles system
*
[CollectionAdminRequest.java|https://github.com/apache/solr/blob/main/solr/solrj/src/java/org/apache/solr/client/solrj/request/CollectionAdminRequest.java]
— {{addRole()}} / {{removeRole()}} client API
*
[ClusterAPI.java|https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/handler/ClusterAPI.java]
— V2 API endpoints for both systems
*
[CollectionParams.java|https://github.com/apache/solr/blob/main/solr/solrj/src/java/org/apache/solr/common/params/CollectionParams.java]
— {{ADDROLE}} / {{REMOVEROLE}} action enum definitions
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
