auto-docs: Update Cloud API spec #40
Conversation
📝 WalkthroughWalkthroughThis pull request introduces substantial API schema expansions across control-plane and data-plane services. The control-plane additions include ACL filtering schemas (ACLAccessFilter, ACLFilter, ACLOperation, ACLPattern, ACLPermissionType, ACLResource, ACLResourceFilter), authentication configuration with SCRAM support, and comprehensive ShadowLink resources with configurations, status tracking, and lifecycle operations (create, get, list, update, delete). Additional changes include topic metadata synchronization options, TLS configuration structures (TLSFileSettings, TLSPEMSettings, TLSSettings), and offset control types. Two new Azure regions (germanywestcentral, swedencentral) with full availability-zone mappings are added to the regions reference. Data-plane changes consist of minor capitalization and textual corrections to operation descriptions without functional modifications. Sequence Diagram(s)sequenceDiagram
participant Client
participant CP as Control Plane API
participant Datastore
rect rgb(200, 220, 240)
Note over Client,Datastore: ShadowLink Lifecycle Operations
end
Client->>CP: CreateShadowLink(config, metadata sync options)
activate CP
CP->>Datastore: Store ShadowLink + Configurations
Datastore-->>CP: Acknowledgment
CP-->>Client: CreateShadowLinkResponse (ShadowLink, status)
deactivate CP
Client->>CP: GetShadowLink(id)
activate CP
CP->>Datastore: Retrieve ShadowLink state
Datastore-->>CP: ShadowLink + ShadowLinkState
CP-->>Client: GetShadowLinkResponse
deactivate CP
rect rgb(220, 240, 200)
Note over Client,CP: Topic Metadata Sync
end
CP->>Datastore: Monitor ShadowTopic status
activate CP
Datastore-->>CP: ShadowTopicStatus updates
CP-->>Client: ListShadowTopicsResponse (topics, statuses)
deactivate CP
Client->>CP: UpdateShadowLink(id, new config)
activate CP
CP->>Datastore: Update ShadowLinkConfigurations
CP-->>Client: UpdateShadowLinkResponse (updated state)
deactivate CP
Client->>CP: DeleteShadowLink(id)
activate CP
CP->>Datastore: Remove ShadowLink
CP-->>Client: DeleteShadowLinkResponse
deactivate CP
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45–60 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Tip 📝 Customizable high-level summaries are now available in beta!You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.
Example instruction:
Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later. Comment |
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
|
🤖 API structural change detected: Added (7)
Modified (2)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (12)
cloud-dataplane/cloud-dataplane.yaml (4)
384-386: Capitalize “Connect” for consistency with product nameUse “Connect cluster” (Kafka Connect) to match terminology used elsewhere in this spec.
- description: Unique name of connect cluster. For Redpanda Cloud, the value is `redpanda`. + description: Unique name of Connect cluster. For Redpanda Cloud, the value is `redpanda`.
3983-3989: Parameter description: capitalize “Connect”Align with other endpoints (“Unique name of target Connect cluster.”).
- - description: Unique name of target connect cluster. For Redpanda Cloud, use `redpanda`. + - description: Unique name of target Connect cluster. For Redpanda Cloud, use `redpanda`.
4102-4108: Parameter description: capitalize “Connect”Keep capitalization consistent across Secrets endpoints.
- - description: Unique name of target connect cluster. For Redpanda Cloud, use `redpanda`. + - description: Unique name of target Connect cluster. For Redpanda Cloud, use `redpanda`.
6284-6286: Use sentence case in summary for consistencyMost operation summaries use sentence case (“Create connector”, “Delete transform”). Recommend “Deploy transform”.
- summary: Deploy Transform + summary: Deploy transformcloud-controlplane/cloud-controlplane.yaml (8)
31-45: Clean up titles (remove stray leading “/”).Several enum schema titles include a leading slash; drop it for consistency.
- title: / The ACL operation to match + title: The ACL operation to match ... - title: / The ACL pattern type + title: The ACL pattern type ... - title: / ACL permission types + title: ACL permission types ... - title: / The ACL resource types + title: The ACL resource typesAlso applies to: 46-59, 60-66, 67-86
244-251: Align doc with structure or model a real oneOf.Title says “made as a oneof for expansion,” but the schema isn’t using oneOf. Either remove that note or add a proper oneOf wrapper around alternative auth configs.
- title: |- - Authentication config. Currently only supporting SASL/SCRAM, - however made as a oneof for expansion + title: Authentication config (currently SASL/SCRAM). Designed for future expansion.Optionally:
AuthenticationConfiguration: oneOf: - type: object properties: scram_configuration: $ref: '#/components/schemas/ScramConfig'
963-986: Interval type vs “0” default is inconsistent. Prefer duration format.Property interval is a string but text says “If 0 provided...”. Use a duration format (example PT30S) and update the note.
- interval: - title: |- - Sync interval - If 0 provided, defaults to 30 seconds - type: string + interval: + title: Sync interval (ISO‑8601 duration). If unset, defaults to PT30S. + type: string + format: duration + example: PT30SApply the same treatment to SecuritySettingsSyncOptions.interval and TopicMetadataSyncOptions.interval for consistency.
2941-2964: Unify all sync “interval” fields to the same duration format.Mirror the duration change across SecuritySettingsSyncOptions.interval and TopicMetadataSyncOptions.interval to avoid divergent behaviors.
- interval: - title: |- - Sync interval - If 0 provided, defaults to 30 seconds - type: string + interval: + title: Sync interval (ISO‑8601). If unset, defaults to PT30S. + type: string + format: duration + example: PT30SAlso applies to: 3463-3545
3402-3435: Enforce key/cert pairing in TLS settings at schema level.Descriptions say “if one is provided, both must be,” but schema doesn’t enforce it. Add oneOf to require both or neither.
TLSFileSettings: properties: ca_path: title: Path to the CA type: string cert_path: title: Path to the cert type: string key_path: title: |- Key and Cert are optional but if one is provided, then both must be Path to the key type: string title: TLS file settings - type: object + type: object + oneOf: + - not: { anyOf: [ { required: [cert_path] }, { required: [key_path] } ] } + - required: [cert_path, key_path]TLSPEMSettings: properties: ca: title: The CA type: string cert: title: The cert type: string key: title: |- Key and Cert are optional but if one is provided, then both must be The key type: string key_fingerprint: readOnly: true title: The SHA-256 of the key, in base64 format type: string title: Used when providing the TLS information in PEM format - type: object + type: object + oneOf: + - not: { anyOf: [ { required: [cert] }, { required: [key] } ] } + - required: [cert, key]
3463-3545: Allow exactly one start_at_ to be set.*Add oneOf to ensure only one of start_at_earliest, start_at_latest, start_at_timestamp is provided.
TopicMetadataSyncOptions: properties: ... title: Options for syncing topic metadata - type: object + type: object + oneOf: + - required: [start_at_earliest] + - required: [start_at_latest] + - required: [start_at_timestamp]Note: oneOf alone won’t forbid multiple properties; if strict exclusivity is required, add “not” guards or split create/update shapes.
4109-4213: Typos and minor validation for ShadowLink client options.
- Fix “setn” → “sent”.
- Ensure at least one bootstrap server and no duplicates.
client_id: readOnly: true title: |- - The Client ID for the Kafka RPC requests setn by this cluster to the + The Client ID for the Kafka RPC requests sent by this cluster to the source cluster type: string @@ bootstrap_servers: items: type: string title: The bootstrap servers to use - type: array + type: array + minItems: 1 + uniqueItems: true
6878-6879: Add a description for the new ShadowLinkService tag.Keep tags consistent with others.
- - name: ShadowLinkService + - name: ShadowLinkService + description: Manage Shadow Link resources, configurations, and lifecycle.
📜 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.
📒 Files selected for processing (3)
cloud-controlplane/cloud-controlplane.yaml(24 hunks)cloud-controlplane/x-topics/cloud-regions.md(2 hunks)cloud-dataplane/cloud-dataplane.yaml(4 hunks)
🔇 Additional comments (2)
cloud-controlplane/x-topics/cloud-regions.md (2)
833-845: Azure: BYOC-only tiers — confirm intentRows look correct (zones, tier list, placement). Please confirm these two regions are intentionally BYOC-only (no Dedicated), unlike centralus/eastus which include Dedicated.
872-884: LGTM for swedencentral entryStructure, zones, and tier list are consistent with adjacent rows.
| properties: | ||
| shadow_topic: | ||
| $ref: '#/components/schemas/ShadowTopic' | ||
| title: Response of to getting a shadow topic | ||
| type: object | ||
| GetUserInviteResponse: |
There was a problem hiding this comment.
Fix minor grammar in response title.
“Response of to getting a shadow topic” → “Response to getting a shadow topic”.
- title: Response of to getting a shadow topic
+ title: Response to getting a shadow topic🤖 Prompt for AI Agents
In cloud-controlplane/cloud-controlplane.yaml around lines 1733 to 1738, the
response schema title contains a grammar mistake "Response of to getting a
shadow topic"; change it to "Response to getting a shadow topic" by editing the
title field text accordingly so it reads correctly.
There was a problem hiding this comment.
Response titles don't display in the reference documentation, we should just fix the proto source so that these are displayed as descriptions instead.
There was a problem hiding this comment.
@kbatuigas, thank you for the clarification! I understand now that since this OpenAPI spec is auto-generated from proto sources, changes should be made upstream in the proto files rather than directly in the generated YAML. I'll keep this in mind for future reviews of this repository.
🐰
✏️ Learnings added
Learnt from: kbatuigas
Repo: redpanda-data/api-docs PR: 40
File: cloud-controlplane/cloud-controlplane.yaml:1733-1738
Timestamp: 2025-11-26T19:18:28.554Z
Learning: For the redpanda-data/api-docs repository, the OpenAPI specification files in cloud-controlplane/ and cloud-dataplane/ are auto-generated from proto source files. Changes to these specs should be made in the upstream proto sources rather than directly editing the generated OpenAPI YAML files.
Learnt from: kbatuigas
Repo: redpanda-data/api-docs PR: 40
File: cloud-controlplane/cloud-controlplane.yaml:1733-1738
Timestamp: 2025-11-26T19:18:28.554Z
Learning: In the redpanda-data/api-docs repository's reference documentation, response schema titles do not display, but descriptions do. When reviewing proto sources that generate OpenAPI specs, suggest using description fields instead of title fields for content that should be visible in the documentation.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
| properties: | ||
| password: | ||
| title: Password | ||
| type: string | ||
| password_set: | ||
| readOnly: true | ||
| title: Indicates that the password has been set | ||
| type: boolean | ||
| password_set_at: | ||
| format: date-time | ||
| readOnly: true | ||
| title: |- | ||
| Timestamp of when the password was last set - only valid if password_set | ||
| is true | ||
| type: string | ||
| scram_mechanism: | ||
| $ref: '#/components/schemas/ScramMechanism' | ||
| username: | ||
| title: SCRAM username | ||
| type: string | ||
| title: SCRAM settings | ||
| type: object | ||
| ScramMechanism: | ||
| description: |- | ||
| - SCRAM_MECHANISM_SCRAM_SHA_256: SCRAM-SHA-256 | ||
| - SCRAM_MECHANISM_SCRAM_SHA_512: SCRAM-SHA-512 | ||
| enum: | ||
| - SCRAM_MECHANISM_SCRAM_SHA_256 | ||
| - SCRAM_MECHANISM_SCRAM_SHA_512 | ||
| title: Valid SCRAM mechanisms | ||
| type: string |
There was a problem hiding this comment.
Prevent secret leakage: make ScramConfig.password writeOnly and typed as password.
Without writeOnly, password can be serialized in responses via v2.ShadowLink → configurations → client_options → authentication_configuration. Mark it writeOnly and keep password_set for read paths.
properties:
password:
- title: Password
- type: string
+ title: Password
+ type: string
+ format: password
+ writeOnly: true
password_set:
readOnly: true
title: Indicates that the password has been set
type: booleanOptional hardening:
- type: object
+ type: object
+ additionalProperties: falseAnd consider required: ["username","scram_mechanism"] (and “password” on create-only shapes).
📝 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.
| properties: | |
| password: | |
| title: Password | |
| type: string | |
| password_set: | |
| readOnly: true | |
| title: Indicates that the password has been set | |
| type: boolean | |
| password_set_at: | |
| format: date-time | |
| readOnly: true | |
| title: |- | |
| Timestamp of when the password was last set - only valid if password_set | |
| is true | |
| type: string | |
| scram_mechanism: | |
| $ref: '#/components/schemas/ScramMechanism' | |
| username: | |
| title: SCRAM username | |
| type: string | |
| title: SCRAM settings | |
| type: object | |
| ScramMechanism: | |
| description: |- | |
| - SCRAM_MECHANISM_SCRAM_SHA_256: SCRAM-SHA-256 | |
| - SCRAM_MECHANISM_SCRAM_SHA_512: SCRAM-SHA-512 | |
| enum: | |
| - SCRAM_MECHANISM_SCRAM_SHA_256 | |
| - SCRAM_MECHANISM_SCRAM_SHA_512 | |
| title: Valid SCRAM mechanisms | |
| type: string | |
| properties: | |
| password: | |
| title: Password | |
| type: string | |
| format: password | |
| writeOnly: true | |
| password_set: | |
| readOnly: true | |
| title: Indicates that the password has been set | |
| type: boolean | |
| password_set_at: | |
| format: date-time | |
| readOnly: true | |
| title: |- | |
| Timestamp of when the password was last set - only valid if password_set | |
| is true | |
| type: string | |
| scram_mechanism: | |
| $ref: '#/components/schemas/ScramMechanism' | |
| username: | |
| title: SCRAM username | |
| type: string | |
| title: SCRAM settings | |
| type: object | |
| ScramMechanism: | |
| description: |- | |
| - SCRAM_MECHANISM_SCRAM_SHA_256: SCRAM-SHA-256 | |
| - SCRAM_MECHANISM_SCRAM_SHA_512: SCRAM-SHA-512 | |
| enum: | |
| - SCRAM_MECHANISM_SCRAM_SHA_256 | |
| - SCRAM_MECHANISM_SCRAM_SHA_512 | |
| title: Valid SCRAM mechanisms | |
| type: string |
🤖 Prompt for AI Agents
In cloud-controlplane/cloud-controlplane.yaml around lines 2883 to 2913, the
SCRAM password field is currently a plain string and can be leaked in serialized
responses; change the password property's schema to include writeOnly: true and
set type: string with format: password (or type: password if your schema
convention uses that) so it is accepted on input but never emitted in responses;
retain password_set and password_set_at as readOnly; optionally, add required:
["username","scram_mechanism"] to the SCRAM settings schema and ensure
creation-only shapes mark "password" as required where appropriate.
| /v1/network/{network_id}/network-peerings: | ||
| get: | ||
| description: List Redpanda network peerings. | ||
| description: List Redpanda networks peerings. |
There was a problem hiding this comment.
Grammar: “networks peerings” → “network peerings”.
- description: List Redpanda networks peerings.
+ description: List Redpanda network peerings.📝 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.
| description: List Redpanda networks peerings. | |
| description: List Redpanda network peerings. |
🤖 Prompt for AI Agents
In cloud-controlplane/cloud-controlplane.yaml around line 4696, the description
text uses incorrect grammar "List Redpanda networks peerings."; update it to
"List Redpanda network peerings." (or alternatively "List Redpanda network
peering(s)." if singular/plural ambiguity exists) to correct the noun phrase and
ensure consistent wording.
| /v1/network/{network_peering.network_id}/network-peerings: | ||
| post: | ||
| description: Create a Redpanda network peering. | ||
| description: Create a Redpanda network pering. |
There was a problem hiding this comment.
Typo: “pering” → “peering”.
- description: Create a Redpanda network pering.
+ description: Create a Redpanda network peering.📝 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.
| description: Create a Redpanda network pering. | |
| description: Create a Redpanda network peering. |
🤖 Prompt for AI Agents
In cloud-controlplane/cloud-controlplane.yaml around line 4813, the description
contains a typo "pering" — update the string to "peering" so it reads "Create a
Redpanda network peering." and ensure spelling matches project style.
| /v1/network/{network_id}/network-peerings: | ||
| get: | ||
| description: List Redpanda network peerings. | ||
| description: List Redpanda networks peerings. |
There was a problem hiding this comment.
| description: List Redpanda networks peerings. | |
| description: List Redpanda network peerings. |
| /v1/network/{network_peering.network_id}/network-peerings: | ||
| post: | ||
| description: Create a Redpanda network peering. | ||
| description: Create a Redpanda network pering. |
There was a problem hiding this comment.
| description: Create a Redpanda network pering. | |
| description: Create a Redpanda network peering. |
| name: Serverless Private Links | ||
| - description: See available Redpanda Serverless regions. | ||
| name: Serverless Regions | ||
| - name: ShadowLinkService |
There was a problem hiding this comment.
| - name: ShadowLinkService |
This can be added back once this is ready in Cloud
| $ref: '#/components/schemas/ConnectCluster.Info' | ||
| name: | ||
| description: Unique name of Connect cluster. For Redpanda Cloud, the value is `redpanda`. | ||
| description: Unique name of connect cluster. For Redpanda Cloud, the value is `redpanda`. |
There was a problem hiding this comment.
| description: Unique name of connect cluster. For Redpanda Cloud, the value is `redpanda`. | |
| description: Unique name of Connect cluster. For Redpanda Cloud, the value is `redpanda`. |
| operationId: SecretService_ListKafkaConnectSecrets | ||
| parameters: | ||
| - description: Unique name of target Connect cluster. For Redpanda Cloud, use `redpanda`. | ||
| - description: Unique name of target connect cluster. For Redpanda Cloud, use `redpanda`. |
There was a problem hiding this comment.
| - description: Unique name of target connect cluster. For Redpanda Cloud, use `redpanda`. | |
| - description: Unique name of target Connect cluster. For Redpanda Cloud, use `redpanda`. |
| operationId: SecretService_DeleteKafkaConnectSecret | ||
| parameters: | ||
| - description: Unique name of target Connect cluster. For Redpanda Cloud, use `redpanda`. | ||
| - description: Unique name of target connect cluster. For Redpanda Cloud, use `redpanda`. |
There was a problem hiding this comment.
| - description: Unique name of target connect cluster. For Redpanda Cloud, use `redpanda`. | |
| - description: Unique name of target Connect cluster. For Redpanda Cloud, use `redpanda`. |
| $ref: '#/components/schemas/TransformMetadata' | ||
| description: Created | ||
| summary: Deploy transform | ||
| summary: Deploy Transform |
There was a problem hiding this comment.
| summary: Deploy Transform | |
| summary: Deploy transform |
| properties: | ||
| shadow_topic: | ||
| $ref: '#/components/schemas/ShadowTopic' | ||
| title: Response of to getting a shadow topic | ||
| type: object | ||
| GetUserInviteResponse: |
There was a problem hiding this comment.
Response titles don't display in the reference documentation, we should just fix the proto source so that these are displayed as descriptions instead.
vbotbuildovich
force-pushed
the
update-branch-api
branch
from
5f5a005 to
499a4a4
Compare
vbotbuildovich
force-pushed
the
update-branch-api
branch
from
499a4a4 to
aa8cdec
Compare
This PR updates the OpenAPI spec file for the Cloud API.
Triggered by commit: b962b28f8d97e3271f152cc8339d0878f9d02a22