Admin API: edits for 25.3 beta

[kbatuigas]

This pull request updates the Redpanda Admin API v2 specification, introducing new features for syncing Schema Registry data, enhancing topic metadata sync options, and improving the Kafka connections listing endpoint. It also clarifies and expands documentation across several files. The main changes are grouped below:

Documentation and Tag Updates:

• Improved the main API descriptions in both admin.yaml and the v2 overlay, adding details about authentication requirements and links to relevant documentation. [1] [2]
• Updated and expanded tag descriptions, including a new ClusterService tag to reflect the new cluster-wide endpoints. [1] [2]

Other:

• Updated the OpenAPI spec metadata to reflect the latest generation date.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

The changes update the Redpanda Admin API v2 specification with structural and documentation enhancements. Key modifications include adding effectiveInterval fields to options schemas, introducing new SchemaRegistrySyncOptions and SchemaRegistrySyncOptions.ShadowSchemaRegistryTopic schemas for Schema Registry shadowing configuration, expanding TopicMetadataSyncOptions with auto-create filters and offset start configurations via EarliestOffset and LatestOffset subtypes, and adding effective parameter fields to ShadowLinkClientOptions. Additionally, ListKafkaConnections is moved from BrokerService to ClusterService with updated descriptions, and a new ClusterService tag is introduced. Documentation descriptions are enhanced across multiple API specification files.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~40 minutes

The changes span multiple interconnected files with heterogeneous modifications: schema additions and structural expansions in admin-v2.yaml, documentation refinements across overlay files, service reorganization (endpoint migration from BrokerService to ClusterService), and introduction of multiple new types. The variety of changes requires separate reasoning for schema additions, documentation updates, and endpoint reorganization, combined with moderate logic density in understanding the API surface implications.

Possibly related PRs

• PR Add servers and tags objects with overlays #26: Modifies the same admin v2 overlay tag definitions and updates service/tag names for Admin API endpoints.
• PR Add Admin v2 spec file #29: Introduces the Admin v2 OpenAPI specification structure that this PR extends with new schemas and endpoint reorganizations.

Suggested reviewers

• JakeSCahill
• paulohtb6
• Feediver1

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The linked issue DOC-1770 focuses on ensuring operations have summaries/descriptions and updating overlays to clarify v2 versioning through the version switcher. However, the PR also introduces substantial schema-level additions that extend beyond these objectives, including new public types (SchemaRegistrySyncOptions, SchemaRegistrySyncOptions.ShadowSchemaRegistryTopic), expanded TopicMetadataSyncOptions with multiple new fields (autoCreateShadowTopicFilters, excludeDefault, syncedShadowTopicProperties) and nested types (EarliestOffset, LatestOffset), and multiple effectiveInterval and effective-parameter fields (effectiveConnectionTimeoutMs, effectiveFetchMaxBytes, etc.). While these changes are documented in the PR objectives as feature additions, they are not explicitly required by DOC-1770 and represent new API enhancements beyond the scope of documentation and tag cleanup work.	The PR combines two distinct types of work: (1) documentation cleanup and overlay updates for DOC-1770, and (2) schema additions for new feature support (Schema Registry syncing, enhanced topic metadata options). Consider separating these into two PRs—one focused on the documentation/tag cleanup required by DOC-1770, and another for the schema/feature additions. This will make it easier to track which changes address specific issues and simplify the review process.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Title Check	❓ Inconclusive	The pull request title "Admin API: edits for 25.3 beta" is directly related to the changeset, as the PR updates the Admin API specification for version 25.3 beta. The title accurately identifies the target version and scope (Admin API). However, the term "edits" is quite generic and doesn't convey what specific aspects are being modified—such as the schema additions, documentation improvements, or tag updates. A teammate scanning the commit history would understand this is about Admin API changes but wouldn't immediately recognize the main areas affected (Schema Registry features, topic metadata options, or documentation clarifications).	Consider using a more specific title that conveys the primary changes, such as "Admin API: add Schema Registry sync options and clarify v2 versioning for 25.3 beta" or "Admin API: schema additions and documentation cleanup for 25.3 beta". This would help future reviewers understand the scope at a glance without the generic term "edits".

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	The pull request description provides a clear, structured overview of the changes grouped into meaningful categories: schema and feature additions, documentation and tag updates, and miscellaneous updates. The description directly relates to the changeset and conveys meaningful information about what is being modified, including references to Schema Registry syncing, topic metadata enhancements, and authentication documentation. The description is neither vague nor off-topic; it accurately describes real changes present in the PR.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

ℹ️ API content change detected:

No structural change, nothing to display.

Preview documentation

Powered by Bump.sh

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8377a80 and b4ee9f0.

📒 Files selected for processing (4)

• admin/admin-v2.yaml (12 hunks)
• admin/admin.yaml (1 hunks)
• admin/v2-overlays/add-external-docs.yaml (1 hunks)
• admin/v2-overlays/create-and-update-tags.yaml (2 hunks)

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Clarify cluster-wide scope in request description.

The request description still talks about a single broker even though the RPC was moved under ClusterService and now aggregates connections across the cluster. Please update the wording so it matches the new behavior.

-      description: |-
-        ListKafkaConnectionsRequest return information about the broker's Kafka
-         connections.
+      description: |-
+        ListKafkaConnectionsRequest returns information about the cluster's Kafka
+         connections, aggregated across all brokers.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	ListKafkaConnectionsRequest return information about the broker's Kafka
	connections.
	properties:
	description: |-
	ListKafkaConnectionsRequest returns information about the cluster's Kafka
	connections, aggregated across all brokers.
	properties:

🤖 Prompt for AI Agents

In admin/admin-v2.yaml around lines 985 to 987, the description for
ListKafkaConnectionsRequest refers to a single broker but the RPC now lives
under ClusterService and returns connections aggregated across the cluster;
update the text to say it returns cluster-wide Kafka connection information (or
connections across all brokers in the cluster) to reflect the new scope, keeping
the wording concise and consistent with other ClusterService request
descriptions.