Migrate org.apache.solr.cli tools from V1 to V2 APIs by epugh · Pull Request #4154 · apache/solr

epugh · 2026-02-22T00:13:50Z

Replaces legacy V1 admin API calls (CollectionAdminRequest, CoreAdminRequest) in the bin/solr CLI tools with generated V2 OpenAPI SolrJ classes. Also adds a new proper SolrJ V2 endpoint for GET /cluster/nodes that was previously missing, eliminating the need for a GenericV2SolrRequest workaround.

I used Copilot for this, and here is the agent chat: https://github.com/epugh/solr/tasks/3c2f15c6-c0c7-4e39-b6b6-1cd51f8e7aa4

Migrated calls

Class	Method	Before → After
`CLIUtils`	`safeCheckCollectionExists`	`CollectionAdminRequest.List` → `CollectionsApi.ListCollections`
`CreateTool`	`createCore`	`CoreAdminRequest.createCore` → `CoresApi.CreateCore`
`CreateTool`	`createCollection`	`CollectionAdminRequest.createCollection` → `CollectionsApi.CreateCollection`
`DeleteTool`	`deleteCollection`	`CollectionAdminRequest.deleteCollection` → `CollectionsApi.DeleteCollection`
`DeleteTool`	`deleteCore`	`CoreAdminRequest.Unload` → `CoresApi.UnloadCore`
`StatusTool`	`getCloudStatus`	`CollectionAdminRequest.ClusterStatus` → `ClusterApi.ListClusterNodes` + `CollectionsApi.ListCollections`

Verbose output restored via Jackson

The old V1 code serialized NamedList responses with noggit's JSONWriter. V2 response POJOs are Jackson-annotated, so verbose output now uses JacksonContentWriter.DEFAULT_MAPPER.writerWithDefaultPrettyPrinter() — actually cleaner output since the responses are already proper JSON objects:

// CreateTool, DeleteTool — after req.process():
if (isVerbose() && response != null) {
  echo(JacksonContentWriter.DEFAULT_MAPPER
      .writerWithDefaultPrettyPrinter()
      .writeValueAsString(response));
}

New `GET /cluster/nodes` V2 API (SolrJ support)

StatusTool previously fell back to GenericV2SolrRequest because SolrJ had no typed class for this endpoint. The full API pipeline was wired up:

ListClusterNodesResponse — new model with Set<String> nodes
ListClusterNodesApi — new endpoint interface at @Path("/cluster/nodes")
ListClusterNodes — new Jersey implementation registered in CollectionsHandler
ClusterApi.ListClusterNodes — generated SolrJ request class (replaces GenericV2SolrRequest)

// Before
NamedList<Object> resp = solrClient.request(
    new GenericV2SolrRequest(SolrRequest.METHOD.GET, "/cluster/nodes", SolrRequestType.ADMIN));
var liveNodes = (Collection<?>) resp.get("nodes");

// After
var resp = new ClusterApi.ListClusterNodes().process(solrClient);
var liveNodes = resp.nodes; // Set<String>

Not migrated

Snapshot tools (SnapshotCreateTool, SnapshotDeleteTool, etc.) are intentionally excluded as candidates for removal.

In fact, we may just remove them...?

Tests

Existing tests + bats tests all pass.

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…r/nodes + /collections APIs Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

… POJOs Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…pache

dsmiley

looks good; just some minor feedback

solr/core/src/java/org/apache/solr/cli/DeleteTool.java

solr/core/src/java/org/apache/solr/cli/StatusTool.java

gerlowskija · 2026-02-26T14:59:49Z

Right now, Solr allows users to disable the v2 APIs with a boolean sysprop: disable.v2.api

I'm 100% in favor of using the v2 APIs in more places - we desperately need that dog-fooding on them and this is a great way to do that. But if we're going to do this then we need to rip out that sysprop.

Ideally that'd happen before this PR gets merged, just to make sure we don't forget about it and accidentally release something where the bin/solr tools could be effectively bricked on any Solr deploys that use the sysprop. But I'd also be OK with filing a "Blocker" JIRA ticket, or a promise to tackle it soon, or something similar.

epugh · 2026-02-26T15:05:31Z

Right now, Solr allows users to disable the v2 APIs with a boolean sysprop: disable.v2.api

I'm 100% in favor of using the v2 APIs in more places - we desperately need that dog-fooding on them and this is a great way to do that. But if we're going to do this then we need to rip out that sysprop.

Ideally that'd happen before this PR gets merged, just to make sure we don't forget about it and accidentally release something where the bin/solr tools could be effectively bricked on any Solr deploys that use the sysprop. But I'd also be OK with filing a "Blocker" JIRA ticket, or a promise to tackle it soon, or something similar.

Good find! Yeah, I had forgotten about that setting. We could just commit these to main but I do worry about how much pain we set our selves up for in branch_10x.

For various v2 api's that we want to have flexiblity on, can we keep them as "experimental" for a little longer, so we don't have to worry about back compat, with the idea that internal to solr consumers, like the CLI (or maybe internal APIS) wouldn't care that we are changing them over time...

gerlowskija · 2026-02-26T16:16:01Z

I used Copilot for this, and here is the agent chat: ...

FYI that these links are "private" AFAIK - I get a 404 when trying to click through.

can we keep them as "experimental" for a little longer

I started out writing a reply to this that said essentially: "Sure, why not. Solr offers plenty of feature flags, and there's no clear correlation between those and 'experimental'-ness. Lots of non-experimental features have flags. And there are plenty of other 'experimental' features that don't have a feature flag. No reason to tie these things together."

But in writing that and reading it over I find I've unconvinced myself 😦

The problem here is security. I don't know of any security issues specific to the v2 API, but it's a whole new attack surface. While we're signaling that it's not ready for prime time then I think a subset of users are going to want to be able to disable it. Telling them: "here's this thing that's not quite ready yet, pray it doesn't expose you in some way" is not a great message.

This feels like a much larger discussion and I don't want it to hold up this PR. Would you be OK making this "main"-only for now, and I'll file a JIRA ticket or dev@ thread to figure out a path forward here? The dust may settle on that discussion in a few weeks and we decide we're OK with this hitting branch_10x, but keeping it "main" only for the moment helps you stay unblocked while we figure out the larger question...

epugh · 2026-02-26T16:18:51Z

I used Copilot for this, and here is the agent chat: ...

FYI that these links are "private" AFAIK - I get a 404 when trying to click through.

can we keep them as "experimental" for a little longer

I started out writing a reply to this that said essentially: "Sure, why not. Solr offers plenty of feature flags, and there's no clear correlation between those and 'experimental'-ness. Lots of non-experimental features have flags. And there are plenty of other 'experimental' features that don't have a feature flag. No reason to tie these things together."

But in writing that and reading it over I find I've unconvinced myself 😦

The problem here is security. I don't know of any security issues specific to the v2 API, but it's a whole new attack surface. While we're signaling that it's not ready for prime time then I think a subset of users are going to want to be able to disable it. Telling them: "here's this thing that's not quite ready yet, pray it doesn't expose you in some way" is not a great message.

This feels like a much larger discussion and I don't want it to hold up this PR. Would you be OK making this "main"-only for now, and I'll file a JIRA ticket or dev@ thread to figure out a path forward here? The dust may settle on that discussion in a few weeks and we decide we're OK with this hitting branch_10x, but keeping it "main" only for the moment helps you stay unblocked while we figure out the larger question...

I love a suggestion that keeps me unblocked ;-). I think main works, and then we can back port later as we decide we want this.

Interesting, I think of these as experimental not because of security but because we aren't sure we have the right flavour of API. Somethign I've noticed lately is that when I build APIs, that then, later, when I use them "for real" I find a lot of issues with them not being "quite right" yet. Not because of security or performacnce, but maybe because of too much paylard returned or not enough filters or what not. So yeah, please do move forward, and I'll merge this to main only.

gerlowskija

Found one bug in your code I think; see comments inline.

Also, this PR adds a whole new API (ListClusterNodes), so it probably deserves a changelog entry and some tests that use the generated v2 request.

gerlowskija · 2026-02-27T11:37:13Z

solr/core/src/java/org/apache/solr/cli/CLIUtils.java

-      @SuppressWarnings("unchecked")
-      List<String> collections = (List<String>) existsCheckResult.get("collections");
-      exists = collections != null && collections.contains(collection);
+      var response = new CollectionsApi.ListCollections().process(solrClient);


[0] I may be out of date, but as of one point at least these generated v2 request/response objects didn't throw exception on errors the way everything else in SolrJ does.

Assuming this is still true, users are responsible for inspecting the .responseHeader.status field to make sure that the operation succeeded. Hopefully I'm wrong, but if not you'll need to add that checking here and elsewhere.

solr/core/src/java/org/apache/solr/cli/StatusTool.java

gerlowskija · 2026-02-27T11:51:06Z

solr/core/src/java/org/apache/solr/handler/admin/api/ListClusterNodes.java

+/**
+ * V2 API for listing the live nodes in the SolrCloud cluster.
+ *
+ * <p>This API (GET /v2/cluster/nodes) is equivalent to the v1 CLUSTERSTATUS action filtered to


[0] IMO the API comparison is a bit clearer if you put the verbatim v1 request here that you're comparing the v2 API to, rather than trying to describe it.

i.e. /admin/collections?action=CLUSTERSTATUS&liveNodes=true&includeAll=false

@gerlowskija should this API return filtered data? I am now thinking that if this is the new /cluster/nodes api, then it should take in params like liveNodes or includeAll? Should this be /cluster/nodes/live and we also support /cluster/nodes which would return all?

Ugh, I dug a bit more, and so yeah, in V1 CLUSTERSTATUS command returns collection and cluster data mixed up.

What I have implemented only returns cluster data. But don't quite understand how what I have written overlaps with the existing V2 code that I found in org.apache.solr.handler.ClusterAPI. --> I think ClusterAPI is the old way of doing V2 apis, so if I want nice pretty SolrJ objects, I have to use the new way, or accept a Generic response... I think what I've written may be not even be used or is overlapping with the existing ClusterAPI's implementation of /cluster/nodes...

don't quite understand how what I have written overlaps with the existing V2 code that I found in org.apache.solr.handler.ClusterAPI

My understanding is:

Long ago Noble or someone added an old-style "/api/nodes/cluster" implementation in ClusterAPI.

Both implementations, old and new, seem to be returning roughly the same information and be roughly equivalent.

Your new implementation uses the desired framework and auto-generates a SolrJ binding, so it's definitely worth keeping.

That means this PR should probably delete the "old" API definition (i.e. ClusterAPI.getNodes() )

should this API return filtered data? I am now thinking that if this is the new /cluster/nodes api, then it should take in params like liveNodes or includeAll? Should this be /cluster/nodes/live and we also support /cluster/nodes which would return all?

I'm not really sure what you mean by this. In SolrCloud, there's no real notion of "dead" nodes. Either you've registered yourself in ZK and you're a "live" part of the cluster, or you're not in the cluster at all. Right? Am I missing something?

I am going to be tackling ClusterAPI migration soon, so I may leave the old definition for that big effort...

As far as live/dead, I notice that if a node is no longer avialable, it still shows up in our ZK nodes page as red "down"...

I am hoping if you are onboard with my plan to delete apis in ClusterAPI that we can go ahead and merge this one now?

epugh · 2026-02-27T15:38:07Z

Found one bug in your code I think; see comments inline.

Also, this PR adds a whole new API (ListClusterNodes), so it probably deserves a changelog entry and some tests that use the generated v2 request.

I am a bit fuzzy on did I ADD a whole new API? Or did I just complete what already existed? Checking

Also, I think it can't be retunring just live nodes if its supposed to return all nodes?

… back to old style V2 api creation

epugh · 2026-02-22T00:17:15Z

solr/api/src/java/org/apache/solr/client/api/endpoint/ListClusterNodesApi.java

+import org.apache.solr.client.api.model.ListClusterNodesResponse;
+
+/** V2 API definition for listing the live nodes in the SolrCloud cluster. */
+@Path("/cluster/nodes")


I am still very fuzzy on how all this magic works! @gerlowskija I would really appreciate your reivewing the new endpoint. One thing I want to confirm is that we already HAVE a v2 /cluster/nodes. However, it was not (I believe) using the annotaitons os it meant the V2 wasn't in solrJ due to no openapi specs. Hence I had a GenericSolrRequest until I created this. (I being copilot).

epugh · 2026-02-22T00:17:49Z

solr/api/src/java/org/apache/solr/client/api/model/ListClusterNodesResponse.java

+/** Response for the v2 "list cluster nodes" API */
+public class ListClusterNodesResponse extends SolrJerseyResponse {
+
+  @Schema(description = "The live nodes in the cluster.")


I also want to confirm that this api is for "live nodes" and not "all nodes" including dead ones?

and it is..

epugh · 2026-02-22T00:20:51Z

solr/core/src/java/org/apache/solr/cli/StatusTool.java

-    // TODO get this as a metric from the metrics API instead, or something else.
-    var collections = (Map<String, Object>) json._get(List.of("cluster", "collections"), null);
+    var collectionsResponse = new CollectionsApi.ListCollections().process(solrClient);
+    var collections =


I don't love all these != null checks...

epugh · 2026-02-22T00:22:04Z

solr/core/src/java/org/apache/solr/handler/admin/api/ListClusterNodes.java

+
+  @Override
+  @PermissionName(COLL_READ_PERM)
+  public ListClusterNodesResponse listClusterNodes() {


@gerlowskija would love confirmation here on how we frame up the logic...

epugh · 2026-02-22T00:22:20Z

solr/core/src/java/org/apache/solr/handler/admin/CollectionsHandler.java

        DeleteNode.class,
        ListAliases.class,
        AliasProperty.class,
+        ListClusterNodes.class,


@gerlowskija and this is how we add v2 apis?

solr/core/src/java/org/apache/solr/cli/StatusTool.java

epugh · 2026-02-27T15:31:17Z

solr/core/src/java/org/apache/solr/handler/admin/api/ListClusterNodes.java

+/**
+ * V2 API for listing the live nodes in the SolrCloud cluster.
+ *
+ * <p>This API (GET /v2/cluster/nodes) is equivalent to the v1 CLUSTERSTATUS action filtered to


solr/core/src/java/org/apache/solr/cli/StatusTool.java

epugh · 2026-02-27T16:10:40Z

solr/core/src/java/org/apache/solr/handler/admin/api/ListClusterNodes.java

+/**
+ * V2 API for listing the live nodes in the SolrCloud cluster.
+ *
+ * <p>This API (GET /v2/cluster/nodes) is equivalent to the v1 CLUSTERSTATUS action filtered to


@gerlowskija should this API return filtered data? I am now thinking that if this is the new /cluster/nodes api, then it should take in params like liveNodes or includeAll? Should this be /cluster/nodes/live and we also support /cluster/nodes which would return all?

Ugh, I dug a bit more, and so yeah, in V1 CLUSTERSTATUS command returns collection and cluster data mixed up.

What I have implemented only returns cluster data. But don't quite understand how what I have written overlaps with the existing V2 code that I found in org.apache.solr.handler.ClusterAPI. --> I think ClusterAPI is the old way of doing V2 apis, so if I want nice pretty SolrJ objects, I have to use the new way, or accept a Generic response... I think what I've written may be not even be used or is overlapping with the existing ClusterAPI's implementation of /cluster/nodes...

epugh · 2026-02-27T16:34:04Z

solr/core/src/java/org/apache/solr/handler/ClusterAPI.java


  @EndPoint(method = GET, path = "/cluster/nodes", permission = COLL_READ_PERM)
  public void getNodes(SolrQueryRequest req, SolrQueryResponse rsp) {
+    System.out.println("\n\nHI THERE I AM IN CLUSTERAPI\n\n");


@gerlowskija this is what I used to prove to myself that ClusterAPI is being used instead of the code that I wrote... Does this change anything on the "Lets write more tests or changelog?"

Copilot AI and others added 5 commits February 21, 2026 19:10

Initial plan

3a1d553

Migrate CLI tools from V1 to V2 APIs: CLIUtils, CreateTool, DeleteTool

ee032f9

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Migrate StatusTool.getCloudStatus from V1 ClusterStatus to V2 /cluste…

5b9c8f7

…r/nodes + /collections APIs Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Restore verbose JSON output in CreateTool and DeleteTool using V2 API…

93c1717

… POJOs Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Add SolrJ V2 API support for GET /cluster/nodes (ListClusterNodes)

4f5f0d4

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

github-actions bot added cat:cli cat:api labels Feb 22, 2026

epugh added the no-changelog label Feb 23, 2026

epugh requested review from gerlowskija and malliaridis February 23, 2026 21:50

Merge remote-tracking branch 'upstream/main' into migrate-cli-to-v2-a…

93ed8ca

…pache

dsmiley reviewed Feb 26, 2026

View reviewed changes

solr/core/src/java/org/apache/solr/cli/DeleteTool.java Outdated Show resolved Hide resolved

solr/core/src/java/org/apache/solr/cli/StatusTool.java Outdated Show resolved Hide resolved

epugh added 2 commits February 26, 2026 17:12

Refactor echo message

c8fdd3f

more modern usage

13c4bcc

gerlowskija requested changes Feb 27, 2026

View reviewed changes

Demonstrates that the annotations appear to create the SolrJ but call…

eb58b9a

… back to old style V2 api creation

epugh commented Feb 27, 2026

View reviewed changes

doc the change

76e05ee

Conversation

epugh commented Feb 22, 2026

Migrated calls

Verbose output restored via Jackson

New GET /cluster/nodes V2 API (SolrJ support)

Not migrated

Tests

Uh oh!

dsmiley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gerlowskija commented Feb 26, 2026

Uh oh!

epugh commented Feb 26, 2026

Uh oh!

gerlowskija commented Feb 26, 2026

Uh oh!

epugh commented Feb 26, 2026

Uh oh!

gerlowskija left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epugh commented Feb 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

New `GET /cluster/nodes` V2 API (SolrJ support)