[
https://issues.apache.org/jira/browse/SOLR-18160?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18065745#comment-18065745
]
David Smiley commented on SOLR-18160:
-------------------------------------
The above analysis was written by Claude Opus.
The scope of this issue is just deprecation {{@Deprecated}} with version
number. It can eventually be removed for 11 in a separate issue. The v2 API
is "experimental" and can be removed immediately. If a user invokes these
APIs, they should call the {{DeprecationLog}} to help inform the user. The
"major changes" .adoc refguide page should indicate their deprecation and to
use "node roles" (system properties) instead.
> 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
> Priority: Major
> Labels: newdev
>
> 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]
