You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by Matteo Merli <ma...@gmail.com> on 2026/02/27 17:49:38 UTC
[DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
https://github.com/apache/pulsar/pull/25275
# PIP-457: Remove support for V1 topic names and V1 Admin API
## Background knowledge
Apache Pulsar historically supported two topic naming formats:
- **V1 format**: `persistent://tenant/cluster/namespace/topic` —
includes the cluster name in the topic path
- **V2 format**: `persistent://tenant/namespace/topic` — omits the
cluster name, making all namespaces implicitly "global"
The V1 format was the original naming convention from Pulsar's early
days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
2018) by removing the cluster component, and PIP-11 further simplified
naming with short topic names defaulting to
`persistent://public/default/`. V1 topic names have been deprecated
since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
The V1 naming format also implied a separate set of Admin REST API
endpoints, Lookup endpoints, and WebSocket paths that include
`{property}/{cluster}/{namespace}` in their URL structure, as opposed
to the V2 paths using `{tenant}/{namespace}`.
These V1 APIs have been deprecated and hidden from the API
documentation for many years. The V2 format has been the recommended
and default format since Pulsar 2.0.
## Motivation
The continued presence of V1 topic name support imposes several costs
on the project:
1. **Maintenance burden**: Every Admin API operation must be
duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
`v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
their V2 counterparts). Bug fixes and new features touching admin APIs
must account for both code paths.
2. **Increased attack surface**: The V1 endpoints are hidden from
documentation but still active and routable, creating undocumented API
surface area that must be secured, tested, and maintained.
3. **Code complexity in TopicName parsing**: The `TopicName` class
must handle both 3-part (V2) and 4-part (V1) name parsing, and the
`isV2()` check propagates throughout the broker, lookup, and client
code.
4. **WebSocket handler complexity**: WebSocket paths must support both
`/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
(V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
(V2).
5. **Confusion for new contributors and operators**: The existence of
two naming schemes and two sets of admin APIs creates unnecessary
confusion and cognitive overhead.
6. **Test matrix expansion**: V1 paths must be covered by integration
and unit tests, expanding the test matrix without providing value to
modern deployments.
V1 topics have been deprecated since Pulsar 2.0, released in June
2018. With nearly 8 years having passed and the project now on the 4.x
release line, it is time to complete this deprecation and remove V1
support entirely.
## Goals
### In Scope
- Remove all V1 Admin REST API endpoint classes and their registrations:
- `org.apache.pulsar.broker.admin.v1.PersistentTopics`
- `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
- `org.apache.pulsar.broker.admin.v1.Namespaces`
- `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
- Remove V1 topic lookup endpoint:
- `org.apache.pulsar.broker.lookup.v1.TopicLookup`
- Remove V1 WebSocket handler paths
- Remove V1 (4-part) topic name parsing from `TopicName` and related classes
- Remove `isV2()` method and all conditional branching based on V1 vs
V2 topic format
- Remove `LOOKUP_PATH_V1` constant and related redirect logic
- Remove or update all tests that exercise V1 code paths
- Update CLI tools that may still reference V1 format
- Log a clear error message if a client attempts to use a V1-style
topic name, to aid migration
### Out of Scope
- Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
- Changes to the binary protocol wire format
- Metadata store migration of existing V1 topic metadata (this PIP
covers code removal; data migration would be addressed separately if
needed)
## High Level Design
The removal will be executed in a single coordinated change:
1. **Admin API**: Delete the `v1` package under
`pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
remove the registration of V1 REST resources from the broker's web
server initialization.
2. **Lookup**: Delete
`pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
and remove its registration.
3. **TopicName parsing**: Simplify `TopicName` to only accept the
3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
name is provided, throw a clear `IllegalArgumentException` with a
message explaining V1 names are no longer supported and how to
convert.
4. **WebSocket**: Remove V1 URI parsing paths from
`AbstractWebSocketHandler` and related classes.
5. **Tests**: Remove or convert all V1-specific test cases. Tests that
coincidentally use V1 names should be updated to V2 format.
## Detailed Design
### Admin API Removal
The following classes will be deleted:
- `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
- `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
- `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
Their registration in the broker's Jersey/JAX-RS application
configuration will be removed.
### TopicName Simplification
In `pulsar-common`, the `TopicName` class will be modified:
```java
// Before: accepts both V1 (4 parts) and V2 (3 parts)
// After: only accepts V2 (3 parts)
private TopicName(String completeTopicName) {
// ... parse domain://
String[] parts = rest.split("/", 3); // tenant/namespace/localName
if (parts.length != 3) {
throw new IllegalArgumentException(
"Invalid topic name '" + completeTopicName + "'. "
+ "Expected format: 'persistent://tenant/namespace/topic'. "
+ "V1 topic names (with cluster component) are no longer
supported. "
+ "Please use the V2 format without the cluster name.");
}
this.tenant = parts[0];
this.namespace = parts[1];
this.localName = parts[2];
// cluster field removed entirely
}
```
The `isV2()` method and `cluster` field will be removed from
`TopicName`. All call sites that branch on `isV2()` will be
simplified.
The `NamespaceName` class will similarly be simplified to remove V1 support.
### Lookup Simplification
The `LOOKUP_PATH_V1` constant and any conditional logic choosing
between V1/V2 redirect paths will be removed. Lookups will only use V2
paths.
### WebSocket Simplification
The `getTopic()` method in WebSocket handler classes will be
simplified to only parse V2-style URIs (`/ws/v2/...`).
## Public-facing Changes
### REST API
The following REST API paths will be **removed**:
**Persistent Topics (V1)**:
- `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
- `GET/PUT/DELETE
/admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
topic operations
- `GET/PUT/DELETE
/admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
partitioned topic operations
**Non-Persistent Topics (V1)**:
- `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list topics
- `GET/PUT/DELETE
/admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
all topic operations
**Namespaces (V1)**:
- `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
— all namespace operations
**Lookup (V1)**:
- `GET /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
— topic lookup
### Binary Protocol
No changes to the binary protocol.
### Configuration
No new configuration. The broker configuration key `allowV1Topics` may
be considered for a transitional release but is **not** proposed here
— the removal is clean and complete.
### CLI
`pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
names. Passing a V1 topic name will produce a clear error message with
migration guidance.
### Metrics
No metrics changes.
## Monitoring
Operators should monitor for client errors after the upgrade. Clients
attempting to use V1 topic names will receive clear error responses
(HTTP 404 for V1 admin paths, or client-side
`IllegalArgumentException` for V1 topic names).
## Security Considerations
This change reduces the API attack surface by removing undocumented
but active REST endpoints. No new security considerations are
introduced.
## Backward & Forward Compatibility
### Upgrade
This is a **breaking change** for any deployment still using V1 topic
names or V1 Admin API paths.
Before upgrading to the version containing this change, operators must:
1. Ensure all topic names in use follow the V2 format
(`persistent://tenant/namespace/topic`)
2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
The V1 format has been deprecated since Pulsar 2.0, released in June
2018 — nearly 8 years ago. Any deployment that has been maintained on
a supported Pulsar version should already be using V2 format
exclusively.
### Downgrade / Rollback
Rolling back to a prior version that supports V1 topic names will work
without issues, as no data format changes are involved.
### Geo-Replication
No impact. Geo-replication already uses V2 topic names. The cluster
component in V1 topic names was originally related to replication
configuration but has been decoupled since V2 was introduced.
## General Notes
### Related PIPs
- PIP-10: Remove cluster from topic name (introduced V2 naming)
- PIP-11: Short topic name (further simplified topic naming)
- PIP-48: Proposed V4 admin API (future direction for admin APIs)
### Migration Guide
For any users who may still be using V1 topic names, the migration is
straightforward:
| V1 Format | V2 Format |
|---|---|
| `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
`persistent://my-tenant/my-namespace/my-topic` |
| `/admin/persistent/my-tenant/my-cluster/my-namespace` |
`/admin/v2/persistent/my-tenant/my-namespace` |
| `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
`/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
Simply remove the cluster component from the topic name path.
--
Matteo Merli
<ma...@gmail.com>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Lari Hotari <lh...@apache.org>.
Sounds good!
-Lari
On 2026/02/27 17:49:38 Matteo Merli wrote:
> https://github.com/apache/pulsar/pull/25275
>
>
> # PIP-457: Remove support for V1 topic names and V1 Admin API
>
> ## Background knowledge
>
> Apache Pulsar historically supported two topic naming formats:
>
> - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> includes the cluster name in the topic path
> - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> cluster name, making all namespaces implicitly "global"
>
> The V1 format was the original naming convention from Pulsar's early
> days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> 2018) by removing the cluster component, and PIP-11 further simplified
> naming with short topic names defaulting to
> `persistent://public/default/`. V1 topic names have been deprecated
> since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
>
> The V1 naming format also implied a separate set of Admin REST API
> endpoints, Lookup endpoints, and WebSocket paths that include
> `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> to the V2 paths using `{tenant}/{namespace}`.
>
> These V1 APIs have been deprecated and hidden from the API
> documentation for many years. The V2 format has been the recommended
> and default format since Pulsar 2.0.
>
> ## Motivation
>
> The continued presence of V1 topic name support imposes several costs
> on the project:
>
> 1. **Maintenance burden**: Every Admin API operation must be
> duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> their V2 counterparts). Bug fixes and new features touching admin APIs
> must account for both code paths.
>
> 2. **Increased attack surface**: The V1 endpoints are hidden from
> documentation but still active and routable, creating undocumented API
> surface area that must be secured, tested, and maintained.
>
> 3. **Code complexity in TopicName parsing**: The `TopicName` class
> must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> `isV2()` check propagates throughout the broker, lookup, and client
> code.
>
> 4. **WebSocket handler complexity**: WebSocket paths must support both
> `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> (V2).
>
> 5. **Confusion for new contributors and operators**: The existence of
> two naming schemes and two sets of admin APIs creates unnecessary
> confusion and cognitive overhead.
>
> 6. **Test matrix expansion**: V1 paths must be covered by integration
> and unit tests, expanding the test matrix without providing value to
> modern deployments.
>
> V1 topics have been deprecated since Pulsar 2.0, released in June
> 2018. With nearly 8 years having passed and the project now on the 4.x
> release line, it is time to complete this deprecation and remove V1
> support entirely.
>
> ## Goals
>
> ### In Scope
>
> - Remove all V1 Admin REST API endpoint classes and their registrations:
> - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.Namespaces`
> - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> - Remove V1 topic lookup endpoint:
> - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> - Remove V1 WebSocket handler paths
> - Remove V1 (4-part) topic name parsing from `TopicName` and related classes
> - Remove `isV2()` method and all conditional branching based on V1 vs
> V2 topic format
> - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> - Remove or update all tests that exercise V1 code paths
> - Update CLI tools that may still reference V1 format
> - Log a clear error message if a client attempts to use a V1-style
> topic name, to aid migration
>
> ### Out of Scope
>
> - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
> - Changes to the binary protocol wire format
> - Metadata store migration of existing V1 topic metadata (this PIP
> covers code removal; data migration would be addressed separately if
> needed)
>
> ## High Level Design
>
> The removal will be executed in a single coordinated change:
>
> 1. **Admin API**: Delete the `v1` package under
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> remove the registration of V1 REST resources from the broker's web
> server initialization.
>
> 2. **Lookup**: Delete
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> and remove its registration.
>
> 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> name is provided, throw a clear `IllegalArgumentException` with a
> message explaining V1 names are no longer supported and how to
> convert.
>
> 4. **WebSocket**: Remove V1 URI parsing paths from
> `AbstractWebSocketHandler` and related classes.
>
> 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> coincidentally use V1 names should be updated to V2 format.
>
> ## Detailed Design
>
> ### Admin API Removal
>
> The following classes will be deleted:
> - `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> - `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> - `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
>
> Their registration in the broker's Jersey/JAX-RS application
> configuration will be removed.
>
> ### TopicName Simplification
>
> In `pulsar-common`, the `TopicName` class will be modified:
>
> ```java
> // Before: accepts both V1 (4 parts) and V2 (3 parts)
> // After: only accepts V2 (3 parts)
> private TopicName(String completeTopicName) {
> // ... parse domain://
> String[] parts = rest.split("/", 3); // tenant/namespace/localName
> if (parts.length != 3) {
> throw new IllegalArgumentException(
> "Invalid topic name '" + completeTopicName + "'. "
> + "Expected format: 'persistent://tenant/namespace/topic'. "
> + "V1 topic names (with cluster component) are no longer
> supported. "
> + "Please use the V2 format without the cluster name.");
> }
> this.tenant = parts[0];
> this.namespace = parts[1];
> this.localName = parts[2];
> // cluster field removed entirely
> }
> ```
>
> The `isV2()` method and `cluster` field will be removed from
> `TopicName`. All call sites that branch on `isV2()` will be
> simplified.
>
> The `NamespaceName` class will similarly be simplified to remove V1 support.
>
> ### Lookup Simplification
>
> The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> between V1/V2 redirect paths will be removed. Lookups will only use V2
> paths.
>
> ### WebSocket Simplification
>
> The `getTopic()` method in WebSocket handler classes will be
> simplified to only parse V2-style URIs (`/ws/v2/...`).
>
> ## Public-facing Changes
>
> ### REST API
>
> The following REST API paths will be **removed**:
>
> **Persistent Topics (V1)**:
> - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> topic operations
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> partitioned topic operations
>
> **Non-Persistent Topics (V1)**:
> - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list topics
> - `GET/PUT/DELETE
> /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> all topic operations
>
> **Namespaces (V1)**:
> - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> — all namespace operations
>
> **Lookup (V1)**:
> - `GET /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> — topic lookup
>
> ### Binary Protocol
>
> No changes to the binary protocol.
>
> ### Configuration
>
> No new configuration. The broker configuration key `allowV1Topics` may
> be considered for a transitional release but is **not** proposed here
> — the removal is clean and complete.
>
> ### CLI
>
> `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> names. Passing a V1 topic name will produce a clear error message with
> migration guidance.
>
> ### Metrics
>
> No metrics changes.
>
> ## Monitoring
>
> Operators should monitor for client errors after the upgrade. Clients
> attempting to use V1 topic names will receive clear error responses
> (HTTP 404 for V1 admin paths, or client-side
> `IllegalArgumentException` for V1 topic names).
>
> ## Security Considerations
>
> This change reduces the API attack surface by removing undocumented
> but active REST endpoints. No new security considerations are
> introduced.
>
> ## Backward & Forward Compatibility
>
> ### Upgrade
>
> This is a **breaking change** for any deployment still using V1 topic
> names or V1 Admin API paths.
>
> Before upgrading to the version containing this change, operators must:
> 1. Ensure all topic names in use follow the V2 format
> (`persistent://tenant/namespace/topic`)
> 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
>
> The V1 format has been deprecated since Pulsar 2.0, released in June
> 2018 — nearly 8 years ago. Any deployment that has been maintained on
> a supported Pulsar version should already be using V2 format
> exclusively.
>
> ### Downgrade / Rollback
>
> Rolling back to a prior version that supports V1 topic names will work
> without issues, as no data format changes are involved.
>
> ### Geo-Replication
>
> No impact. Geo-replication already uses V2 topic names. The cluster
> component in V1 topic names was originally related to replication
> configuration but has been decoupled since V2 was introduced.
>
> ## General Notes
>
> ### Related PIPs
> - PIP-10: Remove cluster from topic name (introduced V2 naming)
> - PIP-11: Short topic name (further simplified topic naming)
> - PIP-48: Proposed V4 admin API (future direction for admin APIs)
>
> ### Migration Guide
>
> For any users who may still be using V1 topic names, the migration is
> straightforward:
>
> | V1 Format | V2 Format |
> |---|---|
> | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> `persistent://my-tenant/my-namespace/my-topic` |
> | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> `/admin/v2/persistent/my-tenant/my-namespace` |
> | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
>
> Simply remove the cluster component from the topic name path.
>
>
>
>
>
> --
> Matteo Merli
> <ma...@gmail.com>
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by mattison chao <ma...@apache.org>.
+1
On Sat, 28 Feb 2026 at 09:23, Jie crossover <cr...@gmail.com> wrote:
> +1
> --
> Best Regards!
> crossoverJie
>
>
> Matteo Merli <ma...@gmail.com> 于2026年2月28日周六 05:39写道:
>
> > I too understand your point of view, although I don’t completely agree :)
> >
> > I believe 8 years of deprecation have already been an abundance of
> heads-up
> > time.
> >
> > I don't agree to tie this proposal with another proposal for a migration
> > strategy.
> >
> > I would like to see the effort for such a migration strategy/tool coming
> > from the *actual* users of v1 topics. I don't believe it's fair to expect
> > the rest of the community to carry the cost of this long
> delayed/neglected
> > migration.
> > I reassert that I'm willing to work with you (or anyone else) to help
> such
> > an effort.
> >
> > Matteo
> >
> > --
> > Matteo Merli
> > <ma...@gmail.com>
> >
> >
> > On Fri, Feb 27, 2026 at 11:07 AM Rajan Dhabalia <rd...@apache.org>
> > wrote:
> >
> > > I totally understand the intent and I agree with the changes as well.
> > > However, removing V1 support would prevent legacy systems from
> upgrading
> > > Pulsar, which is a significant risk. At the moment, there is no
> practical
> > > way to migrate V1 topics to Vn topics without requiring changes in
> client
> > > applications, and that does not seem feasible.
> > >
> > > I suggest linking this PIP with a dependent PIP that enables seamless
> > > migration from V1 topics to Vn. Establishing a migration path now will
> > also
> > > make it possible to deprecate other Vx topic versions safely in the
> > future.
> > >
> > > Thanks,
> > >
> > > Rajan
> > >
> > > On Fri, Feb 27, 2026 at 10:39 AM Matteo Merli <ma...@gmail.com>
> > > wrote:
> > >
> > > > Hi Rajan,
> > > >
> > > > existing deployment using v1 era topics already had 8 years to start
> a
> > > > migration. I don't see how waiting more time will help here.
> > > >
> > > > These deployments can keep staying on the 4.0.x LTS version which is
> > > > still going to be maintained for significant time.
> > > >
> > > > I'm not against a migration mechanism, though that would require
> > > > significant effort. I'm happy to help out whoever wants to work on
> > > > that.
> > > >
> > > > Right now, I think the complexity throughout the code base required
> to
> > > > support v1/v2 greatly overweights the benefits and it severely
> hinders
> > > > the ability to further evolve and push Pulsar forward.
> > > >
> > > > Thanks,
> > > > Matteo
> > > >
> > > > --
> > > > Matteo Merli
> > > > <ma...@gmail.com>
> > > >
> > > > On Fri, Feb 27, 2026 at 10:31 AM Rajan Dhabalia <
> dhabalia.me@gmail.com
> > >
> > > > wrote:
> > > > >
> > > > > Hi Matteo,
> > > > >
> > > > > I completely understand your concern and the motivation behind
> this.
> > > > >
> > > > > However, there are still large scale Pulsar deployments with a
> > > > significant
> > > > > number of V1 topic names. Removing V1 topic support would
> effectively
> > > > > require those systems to stop using Pulsar, which does not seem
> like
> > > the
> > > > > right approach.
> > > > >
> > > > > We should introduce a migration mechanism to move V1 topics to the
> > > newer
> > > > > version so legacy systems have a clear transition path. I would not
> > > > > recommend removing V1 topic support without first defining and
> > agreeing
> > > > on
> > > > > a migration strategy.
> > > > >
> > > > > Thanks,
> > > > > Rajan
> > > > >
> > > > > On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <
> matteo.merli@gmail.com
> > >
> > > > wrote:
> > > > >
> > > > > > https://github.com/apache/pulsar/pull/25275
> > > > > >
> > > > > >
> > > > > > # PIP-457: Remove support for V1 topic names and V1 Admin API
> > > > > >
> > > > > > ## Background knowledge
> > > > > >
> > > > > > Apache Pulsar historically supported two topic naming formats:
> > > > > >
> > > > > > - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> > > > > > includes the cluster name in the topic path
> > > > > > - **V2 format**: `persistent://tenant/namespace/topic` — omits
> the
> > > > > > cluster name, making all namespaces implicitly "global"
> > > > > >
> > > > > > The V1 format was the original naming convention from Pulsar's
> > early
> > > > > > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released
> June
> > > > > > 2018) by removing the cluster component, and PIP-11 further
> > > simplified
> > > > > > naming with short topic names defaulting to
> > > > > > `persistent://public/default/`. V1 topic names have been
> deprecated
> > > > > > since Pulsar 2.0 — nearly 8 years ago at the time of this
> proposal.
> > > > > >
> > > > > > The V1 naming format also implied a separate set of Admin REST
> API
> > > > > > endpoints, Lookup endpoints, and WebSocket paths that include
> > > > > > `{property}/{cluster}/{namespace}` in their URL structure, as
> > opposed
> > > > > > to the V2 paths using `{tenant}/{namespace}`.
> > > > > >
> > > > > > These V1 APIs have been deprecated and hidden from the API
> > > > > > documentation for many years. The V2 format has been the
> > recommended
> > > > > > and default format since Pulsar 2.0.
> > > > > >
> > > > > > ## Motivation
> > > > > >
> > > > > > The continued presence of V1 topic name support imposes several
> > costs
> > > > > > on the project:
> > > > > >
> > > > > > 1. **Maintenance burden**: Every Admin API operation must be
> > > > > > duplicated across V1 and V2 endpoint classes
> > (`v1.PersistentTopics`,
> > > > > > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup`
> > alongside
> > > > > > their V2 counterparts). Bug fixes and new features touching admin
> > > APIs
> > > > > > must account for both code paths.
> > > > > >
> > > > > > 2. **Increased attack surface**: The V1 endpoints are hidden from
> > > > > > documentation but still active and routable, creating
> undocumented
> > > API
> > > > > > surface area that must be secured, tested, and maintained.
> > > > > >
> > > > > > 3. **Code complexity in TopicName parsing**: The `TopicName`
> class
> > > > > > must handle both 3-part (V2) and 4-part (V1) name parsing, and
> the
> > > > > > `isV2()` check propagates throughout the broker, lookup, and
> client
> > > > > > code.
> > > > > >
> > > > > > 4. **WebSocket handler complexity**: WebSocket paths must support
> > > both
> > > > > >
> `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> > > > > > (V1) and
> `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> > > > > > (V2).
> > > > > >
> > > > > > 5. **Confusion for new contributors and operators**: The
> existence
> > of
> > > > > > two naming schemes and two sets of admin APIs creates unnecessary
> > > > > > confusion and cognitive overhead.
> > > > > >
> > > > > > 6. **Test matrix expansion**: V1 paths must be covered by
> > integration
> > > > > > and unit tests, expanding the test matrix without providing value
> > to
> > > > > > modern deployments.
> > > > > >
> > > > > > V1 topics have been deprecated since Pulsar 2.0, released in June
> > > > > > 2018. With nearly 8 years having passed and the project now on
> the
> > > 4.x
> > > > > > release line, it is time to complete this deprecation and remove
> V1
> > > > > > support entirely.
> > > > > >
> > > > > > ## Goals
> > > > > >
> > > > > > ### In Scope
> > > > > >
> > > > > > - Remove all V1 Admin REST API endpoint classes and their
> > > > registrations:
> > > > > > - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> > > > > > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> > > > > > - `org.apache.pulsar.broker.admin.v1.Namespaces`
> > > > > > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> > > > > > - Remove V1 topic lookup endpoint:
> > > > > > - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> > > > > > - Remove V1 WebSocket handler paths
> > > > > > - Remove V1 (4-part) topic name parsing from `TopicName` and
> > related
> > > > > > classes
> > > > > > - Remove `isV2()` method and all conditional branching based on
> V1
> > vs
> > > > > > V2 topic format
> > > > > > - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> > > > > > - Remove or update all tests that exercise V1 code paths
> > > > > > - Update CLI tools that may still reference V1 format
> > > > > > - Log a clear error message if a client attempts to use a
> V1-style
> > > > > > topic name, to aid migration
> > > > > >
> > > > > > ### Out of Scope
> > > > > >
> > > > > > - Removal of the V2 Admin API in favor of V4 (that would be a
> > > separate
> > > > PIP)
> > > > > > - Changes to the binary protocol wire format
> > > > > > - Metadata store migration of existing V1 topic metadata (this
> PIP
> > > > > > covers code removal; data migration would be addressed separately
> > if
> > > > > > needed)
> > > > > >
> > > > > > ## High Level Design
> > > > > >
> > > > > > The removal will be executed in a single coordinated change:
> > > > > >
> > > > > > 1. **Admin API**: Delete the `v1` package under
> > > > > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/`
> > and
> > > > > > remove the registration of V1 REST resources from the broker's
> web
> > > > > > server initialization.
> > > > > >
> > > > > > 2. **Lookup**: Delete
> > > > > >
> > > > > >
> > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> > > > > > and remove its registration.
> > > > > >
> > > > > > 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> > > > > > 3-part V2 format (`domain://tenant/namespace/localName`). If a
> > 4-part
> > > > > > name is provided, throw a clear `IllegalArgumentException` with a
> > > > > > message explaining V1 names are no longer supported and how to
> > > > > > convert.
> > > > > >
> > > > > > 4. **WebSocket**: Remove V1 URI parsing paths from
> > > > > > `AbstractWebSocketHandler` and related classes.
> > > > > >
> > > > > > 5. **Tests**: Remove or convert all V1-specific test cases. Tests
> > > that
> > > > > > coincidentally use V1 names should be updated to V2 format.
> > > > > >
> > > > > > ## Detailed Design
> > > > > >
> > > > > > ### Admin API Removal
> > > > > >
> > > > > > The following classes will be deleted:
> > > > > > -
> > > > > >
> > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> > > > > > -
> > > > > >
> > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> > > > > > -
> > > > > >
> > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
> > > > > >
> > > > > > Their registration in the broker's Jersey/JAX-RS application
> > > > > > configuration will be removed.
> > > > > >
> > > > > > ### TopicName Simplification
> > > > > >
> > > > > > In `pulsar-common`, the `TopicName` class will be modified:
> > > > > >
> > > > > > ```java
> > > > > > // Before: accepts both V1 (4 parts) and V2 (3 parts)
> > > > > > // After: only accepts V2 (3 parts)
> > > > > > private TopicName(String completeTopicName) {
> > > > > > // ... parse domain://
> > > > > > String[] parts = rest.split("/", 3); //
> > > tenant/namespace/localName
> > > > > > if (parts.length != 3) {
> > > > > > throw new IllegalArgumentException(
> > > > > > "Invalid topic name '" + completeTopicName + "'. "
> > > > > > + "Expected format:
> > > 'persistent://tenant/namespace/topic'.
> > > > "
> > > > > > + "V1 topic names (with cluster component) are no
> > longer
> > > > > > supported. "
> > > > > > + "Please use the V2 format without the cluster
> > name.");
> > > > > > }
> > > > > > this.tenant = parts[0];
> > > > > > this.namespace = parts[1];
> > > > > > this.localName = parts[2];
> > > > > > // cluster field removed entirely
> > > > > > }
> > > > > > ```
> > > > > >
> > > > > > The `isV2()` method and `cluster` field will be removed from
> > > > > > `TopicName`. All call sites that branch on `isV2()` will be
> > > > > > simplified.
> > > > > >
> > > > > > The `NamespaceName` class will similarly be simplified to remove
> V1
> > > > > > support.
> > > > > >
> > > > > > ### Lookup Simplification
> > > > > >
> > > > > > The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> > > > > > between V1/V2 redirect paths will be removed. Lookups will only
> use
> > > V2
> > > > > > paths.
> > > > > >
> > > > > > ### WebSocket Simplification
> > > > > >
> > > > > > The `getTopic()` method in WebSocket handler classes will be
> > > > > > simplified to only parse V2-style URIs (`/ws/v2/...`).
> > > > > >
> > > > > > ## Public-facing Changes
> > > > > >
> > > > > > ### REST API
> > > > > >
> > > > > > The following REST API paths will be **removed**:
> > > > > >
> > > > > > **Persistent Topics (V1)**:
> > > > > > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list
> > > > topics
> > > > > > - `GET/PUT/DELETE
> > > > > > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > all
> > > > > > topic operations
> > > > > > - `GET/PUT/DELETE
> > > > > > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> > > > > > partitioned topic operations
> > > > > >
> > > > > > **Non-Persistent Topics (V1)**:
> > > > > > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` —
> > list
> > > > > > topics
> > > > > > - `GET/PUT/DELETE
> > > > > >
> > /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > > > > > all topic operations
> > > > > >
> > > > > > **Namespaces (V1)**:
> > > > > > - `GET/PUT/DELETE
> > /admin/namespaces/{property}/{cluster}/{namespace}`
> > > > > > — all namespace operations
> > > > > >
> > > > > > **Lookup (V1)**:
> > > > > > - `GET
> > > > > >
> > > >
> > >
> >
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> > > > > > — topic lookup
> > > > > >
> > > > > > ### Binary Protocol
> > > > > >
> > > > > > No changes to the binary protocol.
> > > > > >
> > > > > > ### Configuration
> > > > > >
> > > > > > No new configuration. The broker configuration key
> `allowV1Topics`
> > > may
> > > > > > be considered for a transitional release but is **not** proposed
> > here
> > > > > > — the removal is clean and complete.
> > > > > >
> > > > > > ### CLI
> > > > > >
> > > > > > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2
> > > topic
> > > > > > names. Passing a V1 topic name will produce a clear error message
> > > with
> > > > > > migration guidance.
> > > > > >
> > > > > > ### Metrics
> > > > > >
> > > > > > No metrics changes.
> > > > > >
> > > > > > ## Monitoring
> > > > > >
> > > > > > Operators should monitor for client errors after the upgrade.
> > Clients
> > > > > > attempting to use V1 topic names will receive clear error
> responses
> > > > > > (HTTP 404 for V1 admin paths, or client-side
> > > > > > `IllegalArgumentException` for V1 topic names).
> > > > > >
> > > > > > ## Security Considerations
> > > > > >
> > > > > > This change reduces the API attack surface by removing
> undocumented
> > > > > > but active REST endpoints. No new security considerations are
> > > > > > introduced.
> > > > > >
> > > > > > ## Backward & Forward Compatibility
> > > > > >
> > > > > > ### Upgrade
> > > > > >
> > > > > > This is a **breaking change** for any deployment still using V1
> > topic
> > > > > > names or V1 Admin API paths.
> > > > > >
> > > > > > Before upgrading to the version containing this change, operators
> > > must:
> > > > > > 1. Ensure all topic names in use follow the V2 format
> > > > > > (`persistent://tenant/namespace/topic`)
> > > > > > 2. Ensure all Admin API clients use V2 endpoints
> (`/admin/v2/...`)
> > > > > > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
> > > > > >
> > > > > > The V1 format has been deprecated since Pulsar 2.0, released in
> > June
> > > > > > 2018 — nearly 8 years ago. Any deployment that has been
> maintained
> > on
> > > > > > a supported Pulsar version should already be using V2 format
> > > > > > exclusively.
> > > > > >
> > > > > > ### Downgrade / Rollback
> > > > > >
> > > > > > Rolling back to a prior version that supports V1 topic names will
> > > work
> > > > > > without issues, as no data format changes are involved.
> > > > > >
> > > > > > ### Geo-Replication
> > > > > >
> > > > > > No impact. Geo-replication already uses V2 topic names. The
> cluster
> > > > > > component in V1 topic names was originally related to replication
> > > > > > configuration but has been decoupled since V2 was introduced.
> > > > > >
> > > > > > ## General Notes
> > > > > >
> > > > > > ### Related PIPs
> > > > > > - PIP-10: Remove cluster from topic name (introduced V2 naming)
> > > > > > - PIP-11: Short topic name (further simplified topic naming)
> > > > > > - PIP-48: Proposed V4 admin API (future direction for admin APIs)
> > > > > >
> > > > > > ### Migration Guide
> > > > > >
> > > > > > For any users who may still be using V1 topic names, the
> migration
> > is
> > > > > > straightforward:
> > > > > >
> > > > > > | V1 Format | V2 Format |
> > > > > > |---|---|
> > > > > > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> > > > > > `persistent://my-tenant/my-namespace/my-topic` |
> > > > > > | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> > > > > > `/admin/v2/persistent/my-tenant/my-namespace` |
> > > > > > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> > > > > > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
> > > > > >
> > > > > > Simply remove the cluster component from the topic name path.
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > Matteo Merli
> > > > > > <ma...@gmail.com>
> > > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Jie crossover <cr...@gmail.com>.
+1
--
Best Regards!
crossoverJie
Matteo Merli <ma...@gmail.com> 于2026年2月28日周六 05:39写道:
> I too understand your point of view, although I don’t completely agree :)
>
> I believe 8 years of deprecation have already been an abundance of heads-up
> time.
>
> I don't agree to tie this proposal with another proposal for a migration
> strategy.
>
> I would like to see the effort for such a migration strategy/tool coming
> from the *actual* users of v1 topics. I don't believe it's fair to expect
> the rest of the community to carry the cost of this long delayed/neglected
> migration.
> I reassert that I'm willing to work with you (or anyone else) to help such
> an effort.
>
> Matteo
>
> --
> Matteo Merli
> <ma...@gmail.com>
>
>
> On Fri, Feb 27, 2026 at 11:07 AM Rajan Dhabalia <rd...@apache.org>
> wrote:
>
> > I totally understand the intent and I agree with the changes as well.
> > However, removing V1 support would prevent legacy systems from upgrading
> > Pulsar, which is a significant risk. At the moment, there is no practical
> > way to migrate V1 topics to Vn topics without requiring changes in client
> > applications, and that does not seem feasible.
> >
> > I suggest linking this PIP with a dependent PIP that enables seamless
> > migration from V1 topics to Vn. Establishing a migration path now will
> also
> > make it possible to deprecate other Vx topic versions safely in the
> future.
> >
> > Thanks,
> >
> > Rajan
> >
> > On Fri, Feb 27, 2026 at 10:39 AM Matteo Merli <ma...@gmail.com>
> > wrote:
> >
> > > Hi Rajan,
> > >
> > > existing deployment using v1 era topics already had 8 years to start a
> > > migration. I don't see how waiting more time will help here.
> > >
> > > These deployments can keep staying on the 4.0.x LTS version which is
> > > still going to be maintained for significant time.
> > >
> > > I'm not against a migration mechanism, though that would require
> > > significant effort. I'm happy to help out whoever wants to work on
> > > that.
> > >
> > > Right now, I think the complexity throughout the code base required to
> > > support v1/v2 greatly overweights the benefits and it severely hinders
> > > the ability to further evolve and push Pulsar forward.
> > >
> > > Thanks,
> > > Matteo
> > >
> > > --
> > > Matteo Merli
> > > <ma...@gmail.com>
> > >
> > > On Fri, Feb 27, 2026 at 10:31 AM Rajan Dhabalia <dhabalia.me@gmail.com
> >
> > > wrote:
> > > >
> > > > Hi Matteo,
> > > >
> > > > I completely understand your concern and the motivation behind this.
> > > >
> > > > However, there are still large scale Pulsar deployments with a
> > > significant
> > > > number of V1 topic names. Removing V1 topic support would effectively
> > > > require those systems to stop using Pulsar, which does not seem like
> > the
> > > > right approach.
> > > >
> > > > We should introduce a migration mechanism to move V1 topics to the
> > newer
> > > > version so legacy systems have a clear transition path. I would not
> > > > recommend removing V1 topic support without first defining and
> agreeing
> > > on
> > > > a migration strategy.
> > > >
> > > > Thanks,
> > > > Rajan
> > > >
> > > > On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <matteo.merli@gmail.com
> >
> > > wrote:
> > > >
> > > > > https://github.com/apache/pulsar/pull/25275
> > > > >
> > > > >
> > > > > # PIP-457: Remove support for V1 topic names and V1 Admin API
> > > > >
> > > > > ## Background knowledge
> > > > >
> > > > > Apache Pulsar historically supported two topic naming formats:
> > > > >
> > > > > - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> > > > > includes the cluster name in the topic path
> > > > > - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> > > > > cluster name, making all namespaces implicitly "global"
> > > > >
> > > > > The V1 format was the original naming convention from Pulsar's
> early
> > > > > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> > > > > 2018) by removing the cluster component, and PIP-11 further
> > simplified
> > > > > naming with short topic names defaulting to
> > > > > `persistent://public/default/`. V1 topic names have been deprecated
> > > > > since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
> > > > >
> > > > > The V1 naming format also implied a separate set of Admin REST API
> > > > > endpoints, Lookup endpoints, and WebSocket paths that include
> > > > > `{property}/{cluster}/{namespace}` in their URL structure, as
> opposed
> > > > > to the V2 paths using `{tenant}/{namespace}`.
> > > > >
> > > > > These V1 APIs have been deprecated and hidden from the API
> > > > > documentation for many years. The V2 format has been the
> recommended
> > > > > and default format since Pulsar 2.0.
> > > > >
> > > > > ## Motivation
> > > > >
> > > > > The continued presence of V1 topic name support imposes several
> costs
> > > > > on the project:
> > > > >
> > > > > 1. **Maintenance burden**: Every Admin API operation must be
> > > > > duplicated across V1 and V2 endpoint classes
> (`v1.PersistentTopics`,
> > > > > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup`
> alongside
> > > > > their V2 counterparts). Bug fixes and new features touching admin
> > APIs
> > > > > must account for both code paths.
> > > > >
> > > > > 2. **Increased attack surface**: The V1 endpoints are hidden from
> > > > > documentation but still active and routable, creating undocumented
> > API
> > > > > surface area that must be secured, tested, and maintained.
> > > > >
> > > > > 3. **Code complexity in TopicName parsing**: The `TopicName` class
> > > > > must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> > > > > `isV2()` check propagates throughout the broker, lookup, and client
> > > > > code.
> > > > >
> > > > > 4. **WebSocket handler complexity**: WebSocket paths must support
> > both
> > > > > `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> > > > > (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> > > > > (V2).
> > > > >
> > > > > 5. **Confusion for new contributors and operators**: The existence
> of
> > > > > two naming schemes and two sets of admin APIs creates unnecessary
> > > > > confusion and cognitive overhead.
> > > > >
> > > > > 6. **Test matrix expansion**: V1 paths must be covered by
> integration
> > > > > and unit tests, expanding the test matrix without providing value
> to
> > > > > modern deployments.
> > > > >
> > > > > V1 topics have been deprecated since Pulsar 2.0, released in June
> > > > > 2018. With nearly 8 years having passed and the project now on the
> > 4.x
> > > > > release line, it is time to complete this deprecation and remove V1
> > > > > support entirely.
> > > > >
> > > > > ## Goals
> > > > >
> > > > > ### In Scope
> > > > >
> > > > > - Remove all V1 Admin REST API endpoint classes and their
> > > registrations:
> > > > > - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> > > > > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> > > > > - `org.apache.pulsar.broker.admin.v1.Namespaces`
> > > > > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> > > > > - Remove V1 topic lookup endpoint:
> > > > > - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> > > > > - Remove V1 WebSocket handler paths
> > > > > - Remove V1 (4-part) topic name parsing from `TopicName` and
> related
> > > > > classes
> > > > > - Remove `isV2()` method and all conditional branching based on V1
> vs
> > > > > V2 topic format
> > > > > - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> > > > > - Remove or update all tests that exercise V1 code paths
> > > > > - Update CLI tools that may still reference V1 format
> > > > > - Log a clear error message if a client attempts to use a V1-style
> > > > > topic name, to aid migration
> > > > >
> > > > > ### Out of Scope
> > > > >
> > > > > - Removal of the V2 Admin API in favor of V4 (that would be a
> > separate
> > > PIP)
> > > > > - Changes to the binary protocol wire format
> > > > > - Metadata store migration of existing V1 topic metadata (this PIP
> > > > > covers code removal; data migration would be addressed separately
> if
> > > > > needed)
> > > > >
> > > > > ## High Level Design
> > > > >
> > > > > The removal will be executed in a single coordinated change:
> > > > >
> > > > > 1. **Admin API**: Delete the `v1` package under
> > > > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/`
> and
> > > > > remove the registration of V1 REST resources from the broker's web
> > > > > server initialization.
> > > > >
> > > > > 2. **Lookup**: Delete
> > > > >
> > > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> > > > > and remove its registration.
> > > > >
> > > > > 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> > > > > 3-part V2 format (`domain://tenant/namespace/localName`). If a
> 4-part
> > > > > name is provided, throw a clear `IllegalArgumentException` with a
> > > > > message explaining V1 names are no longer supported and how to
> > > > > convert.
> > > > >
> > > > > 4. **WebSocket**: Remove V1 URI parsing paths from
> > > > > `AbstractWebSocketHandler` and related classes.
> > > > >
> > > > > 5. **Tests**: Remove or convert all V1-specific test cases. Tests
> > that
> > > > > coincidentally use V1 names should be updated to V2 format.
> > > > >
> > > > > ## Detailed Design
> > > > >
> > > > > ### Admin API Removal
> > > > >
> > > > > The following classes will be deleted:
> > > > > -
> > > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> > > > > -
> > > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> > > > > -
> > > > >
> > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
> > > > >
> > > > > Their registration in the broker's Jersey/JAX-RS application
> > > > > configuration will be removed.
> > > > >
> > > > > ### TopicName Simplification
> > > > >
> > > > > In `pulsar-common`, the `TopicName` class will be modified:
> > > > >
> > > > > ```java
> > > > > // Before: accepts both V1 (4 parts) and V2 (3 parts)
> > > > > // After: only accepts V2 (3 parts)
> > > > > private TopicName(String completeTopicName) {
> > > > > // ... parse domain://
> > > > > String[] parts = rest.split("/", 3); //
> > tenant/namespace/localName
> > > > > if (parts.length != 3) {
> > > > > throw new IllegalArgumentException(
> > > > > "Invalid topic name '" + completeTopicName + "'. "
> > > > > + "Expected format:
> > 'persistent://tenant/namespace/topic'.
> > > "
> > > > > + "V1 topic names (with cluster component) are no
> longer
> > > > > supported. "
> > > > > + "Please use the V2 format without the cluster
> name.");
> > > > > }
> > > > > this.tenant = parts[0];
> > > > > this.namespace = parts[1];
> > > > > this.localName = parts[2];
> > > > > // cluster field removed entirely
> > > > > }
> > > > > ```
> > > > >
> > > > > The `isV2()` method and `cluster` field will be removed from
> > > > > `TopicName`. All call sites that branch on `isV2()` will be
> > > > > simplified.
> > > > >
> > > > > The `NamespaceName` class will similarly be simplified to remove V1
> > > > > support.
> > > > >
> > > > > ### Lookup Simplification
> > > > >
> > > > > The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> > > > > between V1/V2 redirect paths will be removed. Lookups will only use
> > V2
> > > > > paths.
> > > > >
> > > > > ### WebSocket Simplification
> > > > >
> > > > > The `getTopic()` method in WebSocket handler classes will be
> > > > > simplified to only parse V2-style URIs (`/ws/v2/...`).
> > > > >
> > > > > ## Public-facing Changes
> > > > >
> > > > > ### REST API
> > > > >
> > > > > The following REST API paths will be **removed**:
> > > > >
> > > > > **Persistent Topics (V1)**:
> > > > > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list
> > > topics
> > > > > - `GET/PUT/DELETE
> > > > > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> all
> > > > > topic operations
> > > > > - `GET/PUT/DELETE
> > > > > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> > > > > partitioned topic operations
> > > > >
> > > > > **Non-Persistent Topics (V1)**:
> > > > > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` —
> list
> > > > > topics
> > > > > - `GET/PUT/DELETE
> > > > >
> /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > > > > all topic operations
> > > > >
> > > > > **Namespaces (V1)**:
> > > > > - `GET/PUT/DELETE
> /admin/namespaces/{property}/{cluster}/{namespace}`
> > > > > — all namespace operations
> > > > >
> > > > > **Lookup (V1)**:
> > > > > - `GET
> > > > >
> > >
> >
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> > > > > — topic lookup
> > > > >
> > > > > ### Binary Protocol
> > > > >
> > > > > No changes to the binary protocol.
> > > > >
> > > > > ### Configuration
> > > > >
> > > > > No new configuration. The broker configuration key `allowV1Topics`
> > may
> > > > > be considered for a transitional release but is **not** proposed
> here
> > > > > — the removal is clean and complete.
> > > > >
> > > > > ### CLI
> > > > >
> > > > > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2
> > topic
> > > > > names. Passing a V1 topic name will produce a clear error message
> > with
> > > > > migration guidance.
> > > > >
> > > > > ### Metrics
> > > > >
> > > > > No metrics changes.
> > > > >
> > > > > ## Monitoring
> > > > >
> > > > > Operators should monitor for client errors after the upgrade.
> Clients
> > > > > attempting to use V1 topic names will receive clear error responses
> > > > > (HTTP 404 for V1 admin paths, or client-side
> > > > > `IllegalArgumentException` for V1 topic names).
> > > > >
> > > > > ## Security Considerations
> > > > >
> > > > > This change reduces the API attack surface by removing undocumented
> > > > > but active REST endpoints. No new security considerations are
> > > > > introduced.
> > > > >
> > > > > ## Backward & Forward Compatibility
> > > > >
> > > > > ### Upgrade
> > > > >
> > > > > This is a **breaking change** for any deployment still using V1
> topic
> > > > > names or V1 Admin API paths.
> > > > >
> > > > > Before upgrading to the version containing this change, operators
> > must:
> > > > > 1. Ensure all topic names in use follow the V2 format
> > > > > (`persistent://tenant/namespace/topic`)
> > > > > 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> > > > > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
> > > > >
> > > > > The V1 format has been deprecated since Pulsar 2.0, released in
> June
> > > > > 2018 — nearly 8 years ago. Any deployment that has been maintained
> on
> > > > > a supported Pulsar version should already be using V2 format
> > > > > exclusively.
> > > > >
> > > > > ### Downgrade / Rollback
> > > > >
> > > > > Rolling back to a prior version that supports V1 topic names will
> > work
> > > > > without issues, as no data format changes are involved.
> > > > >
> > > > > ### Geo-Replication
> > > > >
> > > > > No impact. Geo-replication already uses V2 topic names. The cluster
> > > > > component in V1 topic names was originally related to replication
> > > > > configuration but has been decoupled since V2 was introduced.
> > > > >
> > > > > ## General Notes
> > > > >
> > > > > ### Related PIPs
> > > > > - PIP-10: Remove cluster from topic name (introduced V2 naming)
> > > > > - PIP-11: Short topic name (further simplified topic naming)
> > > > > - PIP-48: Proposed V4 admin API (future direction for admin APIs)
> > > > >
> > > > > ### Migration Guide
> > > > >
> > > > > For any users who may still be using V1 topic names, the migration
> is
> > > > > straightforward:
> > > > >
> > > > > | V1 Format | V2 Format |
> > > > > |---|---|
> > > > > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> > > > > `persistent://my-tenant/my-namespace/my-topic` |
> > > > > | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> > > > > `/admin/v2/persistent/my-tenant/my-namespace` |
> > > > > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> > > > > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
> > > > >
> > > > > Simply remove the cluster component from the topic name path.
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > --
> > > > > Matteo Merli
> > > > > <ma...@gmail.com>
> > > > >
> > >
> >
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Matteo Merli <ma...@gmail.com>.
I too understand your point of view, although I don’t completely agree :)
I believe 8 years of deprecation have already been an abundance of heads-up
time.
I don't agree to tie this proposal with another proposal for a migration
strategy.
I would like to see the effort for such a migration strategy/tool coming
from the *actual* users of v1 topics. I don't believe it's fair to expect
the rest of the community to carry the cost of this long delayed/neglected
migration.
I reassert that I'm willing to work with you (or anyone else) to help such
an effort.
Matteo
--
Matteo Merli
<ma...@gmail.com>
On Fri, Feb 27, 2026 at 11:07 AM Rajan Dhabalia <rd...@apache.org>
wrote:
> I totally understand the intent and I agree with the changes as well.
> However, removing V1 support would prevent legacy systems from upgrading
> Pulsar, which is a significant risk. At the moment, there is no practical
> way to migrate V1 topics to Vn topics without requiring changes in client
> applications, and that does not seem feasible.
>
> I suggest linking this PIP with a dependent PIP that enables seamless
> migration from V1 topics to Vn. Establishing a migration path now will also
> make it possible to deprecate other Vx topic versions safely in the future.
>
> Thanks,
>
> Rajan
>
> On Fri, Feb 27, 2026 at 10:39 AM Matteo Merli <ma...@gmail.com>
> wrote:
>
> > Hi Rajan,
> >
> > existing deployment using v1 era topics already had 8 years to start a
> > migration. I don't see how waiting more time will help here.
> >
> > These deployments can keep staying on the 4.0.x LTS version which is
> > still going to be maintained for significant time.
> >
> > I'm not against a migration mechanism, though that would require
> > significant effort. I'm happy to help out whoever wants to work on
> > that.
> >
> > Right now, I think the complexity throughout the code base required to
> > support v1/v2 greatly overweights the benefits and it severely hinders
> > the ability to further evolve and push Pulsar forward.
> >
> > Thanks,
> > Matteo
> >
> > --
> > Matteo Merli
> > <ma...@gmail.com>
> >
> > On Fri, Feb 27, 2026 at 10:31 AM Rajan Dhabalia <dh...@gmail.com>
> > wrote:
> > >
> > > Hi Matteo,
> > >
> > > I completely understand your concern and the motivation behind this.
> > >
> > > However, there are still large scale Pulsar deployments with a
> > significant
> > > number of V1 topic names. Removing V1 topic support would effectively
> > > require those systems to stop using Pulsar, which does not seem like
> the
> > > right approach.
> > >
> > > We should introduce a migration mechanism to move V1 topics to the
> newer
> > > version so legacy systems have a clear transition path. I would not
> > > recommend removing V1 topic support without first defining and agreeing
> > on
> > > a migration strategy.
> > >
> > > Thanks,
> > > Rajan
> > >
> > > On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <ma...@gmail.com>
> > wrote:
> > >
> > > > https://github.com/apache/pulsar/pull/25275
> > > >
> > > >
> > > > # PIP-457: Remove support for V1 topic names and V1 Admin API
> > > >
> > > > ## Background knowledge
> > > >
> > > > Apache Pulsar historically supported two topic naming formats:
> > > >
> > > > - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> > > > includes the cluster name in the topic path
> > > > - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> > > > cluster name, making all namespaces implicitly "global"
> > > >
> > > > The V1 format was the original naming convention from Pulsar's early
> > > > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> > > > 2018) by removing the cluster component, and PIP-11 further
> simplified
> > > > naming with short topic names defaulting to
> > > > `persistent://public/default/`. V1 topic names have been deprecated
> > > > since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
> > > >
> > > > The V1 naming format also implied a separate set of Admin REST API
> > > > endpoints, Lookup endpoints, and WebSocket paths that include
> > > > `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> > > > to the V2 paths using `{tenant}/{namespace}`.
> > > >
> > > > These V1 APIs have been deprecated and hidden from the API
> > > > documentation for many years. The V2 format has been the recommended
> > > > and default format since Pulsar 2.0.
> > > >
> > > > ## Motivation
> > > >
> > > > The continued presence of V1 topic name support imposes several costs
> > > > on the project:
> > > >
> > > > 1. **Maintenance burden**: Every Admin API operation must be
> > > > duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> > > > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> > > > their V2 counterparts). Bug fixes and new features touching admin
> APIs
> > > > must account for both code paths.
> > > >
> > > > 2. **Increased attack surface**: The V1 endpoints are hidden from
> > > > documentation but still active and routable, creating undocumented
> API
> > > > surface area that must be secured, tested, and maintained.
> > > >
> > > > 3. **Code complexity in TopicName parsing**: The `TopicName` class
> > > > must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> > > > `isV2()` check propagates throughout the broker, lookup, and client
> > > > code.
> > > >
> > > > 4. **WebSocket handler complexity**: WebSocket paths must support
> both
> > > > `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> > > > (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> > > > (V2).
> > > >
> > > > 5. **Confusion for new contributors and operators**: The existence of
> > > > two naming schemes and two sets of admin APIs creates unnecessary
> > > > confusion and cognitive overhead.
> > > >
> > > > 6. **Test matrix expansion**: V1 paths must be covered by integration
> > > > and unit tests, expanding the test matrix without providing value to
> > > > modern deployments.
> > > >
> > > > V1 topics have been deprecated since Pulsar 2.0, released in June
> > > > 2018. With nearly 8 years having passed and the project now on the
> 4.x
> > > > release line, it is time to complete this deprecation and remove V1
> > > > support entirely.
> > > >
> > > > ## Goals
> > > >
> > > > ### In Scope
> > > >
> > > > - Remove all V1 Admin REST API endpoint classes and their
> > registrations:
> > > > - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> > > > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> > > > - `org.apache.pulsar.broker.admin.v1.Namespaces`
> > > > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> > > > - Remove V1 topic lookup endpoint:
> > > > - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> > > > - Remove V1 WebSocket handler paths
> > > > - Remove V1 (4-part) topic name parsing from `TopicName` and related
> > > > classes
> > > > - Remove `isV2()` method and all conditional branching based on V1 vs
> > > > V2 topic format
> > > > - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> > > > - Remove or update all tests that exercise V1 code paths
> > > > - Update CLI tools that may still reference V1 format
> > > > - Log a clear error message if a client attempts to use a V1-style
> > > > topic name, to aid migration
> > > >
> > > > ### Out of Scope
> > > >
> > > > - Removal of the V2 Admin API in favor of V4 (that would be a
> separate
> > PIP)
> > > > - Changes to the binary protocol wire format
> > > > - Metadata store migration of existing V1 topic metadata (this PIP
> > > > covers code removal; data migration would be addressed separately if
> > > > needed)
> > > >
> > > > ## High Level Design
> > > >
> > > > The removal will be executed in a single coordinated change:
> > > >
> > > > 1. **Admin API**: Delete the `v1` package under
> > > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> > > > remove the registration of V1 REST resources from the broker's web
> > > > server initialization.
> > > >
> > > > 2. **Lookup**: Delete
> > > >
> > > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> > > > and remove its registration.
> > > >
> > > > 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> > > > 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> > > > name is provided, throw a clear `IllegalArgumentException` with a
> > > > message explaining V1 names are no longer supported and how to
> > > > convert.
> > > >
> > > > 4. **WebSocket**: Remove V1 URI parsing paths from
> > > > `AbstractWebSocketHandler` and related classes.
> > > >
> > > > 5. **Tests**: Remove or convert all V1-specific test cases. Tests
> that
> > > > coincidentally use V1 names should be updated to V2 format.
> > > >
> > > > ## Detailed Design
> > > >
> > > > ### Admin API Removal
> > > >
> > > > The following classes will be deleted:
> > > > -
> > > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> > > > -
> > > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> > > > -
> > > >
> >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
> > > >
> > > > Their registration in the broker's Jersey/JAX-RS application
> > > > configuration will be removed.
> > > >
> > > > ### TopicName Simplification
> > > >
> > > > In `pulsar-common`, the `TopicName` class will be modified:
> > > >
> > > > ```java
> > > > // Before: accepts both V1 (4 parts) and V2 (3 parts)
> > > > // After: only accepts V2 (3 parts)
> > > > private TopicName(String completeTopicName) {
> > > > // ... parse domain://
> > > > String[] parts = rest.split("/", 3); //
> tenant/namespace/localName
> > > > if (parts.length != 3) {
> > > > throw new IllegalArgumentException(
> > > > "Invalid topic name '" + completeTopicName + "'. "
> > > > + "Expected format:
> 'persistent://tenant/namespace/topic'.
> > "
> > > > + "V1 topic names (with cluster component) are no longer
> > > > supported. "
> > > > + "Please use the V2 format without the cluster name.");
> > > > }
> > > > this.tenant = parts[0];
> > > > this.namespace = parts[1];
> > > > this.localName = parts[2];
> > > > // cluster field removed entirely
> > > > }
> > > > ```
> > > >
> > > > The `isV2()` method and `cluster` field will be removed from
> > > > `TopicName`. All call sites that branch on `isV2()` will be
> > > > simplified.
> > > >
> > > > The `NamespaceName` class will similarly be simplified to remove V1
> > > > support.
> > > >
> > > > ### Lookup Simplification
> > > >
> > > > The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> > > > between V1/V2 redirect paths will be removed. Lookups will only use
> V2
> > > > paths.
> > > >
> > > > ### WebSocket Simplification
> > > >
> > > > The `getTopic()` method in WebSocket handler classes will be
> > > > simplified to only parse V2-style URIs (`/ws/v2/...`).
> > > >
> > > > ## Public-facing Changes
> > > >
> > > > ### REST API
> > > >
> > > > The following REST API paths will be **removed**:
> > > >
> > > > **Persistent Topics (V1)**:
> > > > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list
> > topics
> > > > - `GET/PUT/DELETE
> > > > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> > > > topic operations
> > > > - `GET/PUT/DELETE
> > > > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> > > > partitioned topic operations
> > > >
> > > > **Non-Persistent Topics (V1)**:
> > > > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> > > > topics
> > > > - `GET/PUT/DELETE
> > > > /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > > > all topic operations
> > > >
> > > > **Namespaces (V1)**:
> > > > - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> > > > — all namespace operations
> > > >
> > > > **Lookup (V1)**:
> > > > - `GET
> > > >
> >
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> > > > — topic lookup
> > > >
> > > > ### Binary Protocol
> > > >
> > > > No changes to the binary protocol.
> > > >
> > > > ### Configuration
> > > >
> > > > No new configuration. The broker configuration key `allowV1Topics`
> may
> > > > be considered for a transitional release but is **not** proposed here
> > > > — the removal is clean and complete.
> > > >
> > > > ### CLI
> > > >
> > > > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2
> topic
> > > > names. Passing a V1 topic name will produce a clear error message
> with
> > > > migration guidance.
> > > >
> > > > ### Metrics
> > > >
> > > > No metrics changes.
> > > >
> > > > ## Monitoring
> > > >
> > > > Operators should monitor for client errors after the upgrade. Clients
> > > > attempting to use V1 topic names will receive clear error responses
> > > > (HTTP 404 for V1 admin paths, or client-side
> > > > `IllegalArgumentException` for V1 topic names).
> > > >
> > > > ## Security Considerations
> > > >
> > > > This change reduces the API attack surface by removing undocumented
> > > > but active REST endpoints. No new security considerations are
> > > > introduced.
> > > >
> > > > ## Backward & Forward Compatibility
> > > >
> > > > ### Upgrade
> > > >
> > > > This is a **breaking change** for any deployment still using V1 topic
> > > > names or V1 Admin API paths.
> > > >
> > > > Before upgrading to the version containing this change, operators
> must:
> > > > 1. Ensure all topic names in use follow the V2 format
> > > > (`persistent://tenant/namespace/topic`)
> > > > 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> > > > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
> > > >
> > > > The V1 format has been deprecated since Pulsar 2.0, released in June
> > > > 2018 — nearly 8 years ago. Any deployment that has been maintained on
> > > > a supported Pulsar version should already be using V2 format
> > > > exclusively.
> > > >
> > > > ### Downgrade / Rollback
> > > >
> > > > Rolling back to a prior version that supports V1 topic names will
> work
> > > > without issues, as no data format changes are involved.
> > > >
> > > > ### Geo-Replication
> > > >
> > > > No impact. Geo-replication already uses V2 topic names. The cluster
> > > > component in V1 topic names was originally related to replication
> > > > configuration but has been decoupled since V2 was introduced.
> > > >
> > > > ## General Notes
> > > >
> > > > ### Related PIPs
> > > > - PIP-10: Remove cluster from topic name (introduced V2 naming)
> > > > - PIP-11: Short topic name (further simplified topic naming)
> > > > - PIP-48: Proposed V4 admin API (future direction for admin APIs)
> > > >
> > > > ### Migration Guide
> > > >
> > > > For any users who may still be using V1 topic names, the migration is
> > > > straightforward:
> > > >
> > > > | V1 Format | V2 Format |
> > > > |---|---|
> > > > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> > > > `persistent://my-tenant/my-namespace/my-topic` |
> > > > | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> > > > `/admin/v2/persistent/my-tenant/my-namespace` |
> > > > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> > > > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
> > > >
> > > > Simply remove the cluster component from the topic name path.
> > > >
> > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Matteo Merli
> > > > <ma...@gmail.com>
> > > >
> >
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Rajan Dhabalia <rd...@apache.org>.
I totally understand the intent and I agree with the changes as well.
However, removing V1 support would prevent legacy systems from upgrading
Pulsar, which is a significant risk. At the moment, there is no practical
way to migrate V1 topics to Vn topics without requiring changes in client
applications, and that does not seem feasible.
I suggest linking this PIP with a dependent PIP that enables seamless
migration from V1 topics to Vn. Establishing a migration path now will also
make it possible to deprecate other Vx topic versions safely in the future.
Thanks,
Rajan
On Fri, Feb 27, 2026 at 10:39 AM Matteo Merli <ma...@gmail.com>
wrote:
> Hi Rajan,
>
> existing deployment using v1 era topics already had 8 years to start a
> migration. I don't see how waiting more time will help here.
>
> These deployments can keep staying on the 4.0.x LTS version which is
> still going to be maintained for significant time.
>
> I'm not against a migration mechanism, though that would require
> significant effort. I'm happy to help out whoever wants to work on
> that.
>
> Right now, I think the complexity throughout the code base required to
> support v1/v2 greatly overweights the benefits and it severely hinders
> the ability to further evolve and push Pulsar forward.
>
> Thanks,
> Matteo
>
> --
> Matteo Merli
> <ma...@gmail.com>
>
> On Fri, Feb 27, 2026 at 10:31 AM Rajan Dhabalia <dh...@gmail.com>
> wrote:
> >
> > Hi Matteo,
> >
> > I completely understand your concern and the motivation behind this.
> >
> > However, there are still large scale Pulsar deployments with a
> significant
> > number of V1 topic names. Removing V1 topic support would effectively
> > require those systems to stop using Pulsar, which does not seem like the
> > right approach.
> >
> > We should introduce a migration mechanism to move V1 topics to the newer
> > version so legacy systems have a clear transition path. I would not
> > recommend removing V1 topic support without first defining and agreeing
> on
> > a migration strategy.
> >
> > Thanks,
> > Rajan
> >
> > On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <ma...@gmail.com>
> wrote:
> >
> > > https://github.com/apache/pulsar/pull/25275
> > >
> > >
> > > # PIP-457: Remove support for V1 topic names and V1 Admin API
> > >
> > > ## Background knowledge
> > >
> > > Apache Pulsar historically supported two topic naming formats:
> > >
> > > - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> > > includes the cluster name in the topic path
> > > - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> > > cluster name, making all namespaces implicitly "global"
> > >
> > > The V1 format was the original naming convention from Pulsar's early
> > > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> > > 2018) by removing the cluster component, and PIP-11 further simplified
> > > naming with short topic names defaulting to
> > > `persistent://public/default/`. V1 topic names have been deprecated
> > > since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
> > >
> > > The V1 naming format also implied a separate set of Admin REST API
> > > endpoints, Lookup endpoints, and WebSocket paths that include
> > > `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> > > to the V2 paths using `{tenant}/{namespace}`.
> > >
> > > These V1 APIs have been deprecated and hidden from the API
> > > documentation for many years. The V2 format has been the recommended
> > > and default format since Pulsar 2.0.
> > >
> > > ## Motivation
> > >
> > > The continued presence of V1 topic name support imposes several costs
> > > on the project:
> > >
> > > 1. **Maintenance burden**: Every Admin API operation must be
> > > duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> > > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> > > their V2 counterparts). Bug fixes and new features touching admin APIs
> > > must account for both code paths.
> > >
> > > 2. **Increased attack surface**: The V1 endpoints are hidden from
> > > documentation but still active and routable, creating undocumented API
> > > surface area that must be secured, tested, and maintained.
> > >
> > > 3. **Code complexity in TopicName parsing**: The `TopicName` class
> > > must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> > > `isV2()` check propagates throughout the broker, lookup, and client
> > > code.
> > >
> > > 4. **WebSocket handler complexity**: WebSocket paths must support both
> > > `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> > > (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> > > (V2).
> > >
> > > 5. **Confusion for new contributors and operators**: The existence of
> > > two naming schemes and two sets of admin APIs creates unnecessary
> > > confusion and cognitive overhead.
> > >
> > > 6. **Test matrix expansion**: V1 paths must be covered by integration
> > > and unit tests, expanding the test matrix without providing value to
> > > modern deployments.
> > >
> > > V1 topics have been deprecated since Pulsar 2.0, released in June
> > > 2018. With nearly 8 years having passed and the project now on the 4.x
> > > release line, it is time to complete this deprecation and remove V1
> > > support entirely.
> > >
> > > ## Goals
> > >
> > > ### In Scope
> > >
> > > - Remove all V1 Admin REST API endpoint classes and their
> registrations:
> > > - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> > > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> > > - `org.apache.pulsar.broker.admin.v1.Namespaces`
> > > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> > > - Remove V1 topic lookup endpoint:
> > > - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> > > - Remove V1 WebSocket handler paths
> > > - Remove V1 (4-part) topic name parsing from `TopicName` and related
> > > classes
> > > - Remove `isV2()` method and all conditional branching based on V1 vs
> > > V2 topic format
> > > - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> > > - Remove or update all tests that exercise V1 code paths
> > > - Update CLI tools that may still reference V1 format
> > > - Log a clear error message if a client attempts to use a V1-style
> > > topic name, to aid migration
> > >
> > > ### Out of Scope
> > >
> > > - Removal of the V2 Admin API in favor of V4 (that would be a separate
> PIP)
> > > - Changes to the binary protocol wire format
> > > - Metadata store migration of existing V1 topic metadata (this PIP
> > > covers code removal; data migration would be addressed separately if
> > > needed)
> > >
> > > ## High Level Design
> > >
> > > The removal will be executed in a single coordinated change:
> > >
> > > 1. **Admin API**: Delete the `v1` package under
> > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> > > remove the registration of V1 REST resources from the broker's web
> > > server initialization.
> > >
> > > 2. **Lookup**: Delete
> > >
> > >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> > > and remove its registration.
> > >
> > > 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> > > 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> > > name is provided, throw a clear `IllegalArgumentException` with a
> > > message explaining V1 names are no longer supported and how to
> > > convert.
> > >
> > > 4. **WebSocket**: Remove V1 URI parsing paths from
> > > `AbstractWebSocketHandler` and related classes.
> > >
> > > 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> > > coincidentally use V1 names should be updated to V2 format.
> > >
> > > ## Detailed Design
> > >
> > > ### Admin API Removal
> > >
> > > The following classes will be deleted:
> > > -
> > >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> > > -
> > >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> > > -
> > >
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
> > >
> > > Their registration in the broker's Jersey/JAX-RS application
> > > configuration will be removed.
> > >
> > > ### TopicName Simplification
> > >
> > > In `pulsar-common`, the `TopicName` class will be modified:
> > >
> > > ```java
> > > // Before: accepts both V1 (4 parts) and V2 (3 parts)
> > > // After: only accepts V2 (3 parts)
> > > private TopicName(String completeTopicName) {
> > > // ... parse domain://
> > > String[] parts = rest.split("/", 3); // tenant/namespace/localName
> > > if (parts.length != 3) {
> > > throw new IllegalArgumentException(
> > > "Invalid topic name '" + completeTopicName + "'. "
> > > + "Expected format: 'persistent://tenant/namespace/topic'.
> "
> > > + "V1 topic names (with cluster component) are no longer
> > > supported. "
> > > + "Please use the V2 format without the cluster name.");
> > > }
> > > this.tenant = parts[0];
> > > this.namespace = parts[1];
> > > this.localName = parts[2];
> > > // cluster field removed entirely
> > > }
> > > ```
> > >
> > > The `isV2()` method and `cluster` field will be removed from
> > > `TopicName`. All call sites that branch on `isV2()` will be
> > > simplified.
> > >
> > > The `NamespaceName` class will similarly be simplified to remove V1
> > > support.
> > >
> > > ### Lookup Simplification
> > >
> > > The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> > > between V1/V2 redirect paths will be removed. Lookups will only use V2
> > > paths.
> > >
> > > ### WebSocket Simplification
> > >
> > > The `getTopic()` method in WebSocket handler classes will be
> > > simplified to only parse V2-style URIs (`/ws/v2/...`).
> > >
> > > ## Public-facing Changes
> > >
> > > ### REST API
> > >
> > > The following REST API paths will be **removed**:
> > >
> > > **Persistent Topics (V1)**:
> > > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list
> topics
> > > - `GET/PUT/DELETE
> > > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> > > topic operations
> > > - `GET/PUT/DELETE
> > > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> > > partitioned topic operations
> > >
> > > **Non-Persistent Topics (V1)**:
> > > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> > > topics
> > > - `GET/PUT/DELETE
> > > /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > > all topic operations
> > >
> > > **Namespaces (V1)**:
> > > - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> > > — all namespace operations
> > >
> > > **Lookup (V1)**:
> > > - `GET
> > >
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> > > — topic lookup
> > >
> > > ### Binary Protocol
> > >
> > > No changes to the binary protocol.
> > >
> > > ### Configuration
> > >
> > > No new configuration. The broker configuration key `allowV1Topics` may
> > > be considered for a transitional release but is **not** proposed here
> > > — the removal is clean and complete.
> > >
> > > ### CLI
> > >
> > > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> > > names. Passing a V1 topic name will produce a clear error message with
> > > migration guidance.
> > >
> > > ### Metrics
> > >
> > > No metrics changes.
> > >
> > > ## Monitoring
> > >
> > > Operators should monitor for client errors after the upgrade. Clients
> > > attempting to use V1 topic names will receive clear error responses
> > > (HTTP 404 for V1 admin paths, or client-side
> > > `IllegalArgumentException` for V1 topic names).
> > >
> > > ## Security Considerations
> > >
> > > This change reduces the API attack surface by removing undocumented
> > > but active REST endpoints. No new security considerations are
> > > introduced.
> > >
> > > ## Backward & Forward Compatibility
> > >
> > > ### Upgrade
> > >
> > > This is a **breaking change** for any deployment still using V1 topic
> > > names or V1 Admin API paths.
> > >
> > > Before upgrading to the version containing this change, operators must:
> > > 1. Ensure all topic names in use follow the V2 format
> > > (`persistent://tenant/namespace/topic`)
> > > 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> > > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
> > >
> > > The V1 format has been deprecated since Pulsar 2.0, released in June
> > > 2018 — nearly 8 years ago. Any deployment that has been maintained on
> > > a supported Pulsar version should already be using V2 format
> > > exclusively.
> > >
> > > ### Downgrade / Rollback
> > >
> > > Rolling back to a prior version that supports V1 topic names will work
> > > without issues, as no data format changes are involved.
> > >
> > > ### Geo-Replication
> > >
> > > No impact. Geo-replication already uses V2 topic names. The cluster
> > > component in V1 topic names was originally related to replication
> > > configuration but has been decoupled since V2 was introduced.
> > >
> > > ## General Notes
> > >
> > > ### Related PIPs
> > > - PIP-10: Remove cluster from topic name (introduced V2 naming)
> > > - PIP-11: Short topic name (further simplified topic naming)
> > > - PIP-48: Proposed V4 admin API (future direction for admin APIs)
> > >
> > > ### Migration Guide
> > >
> > > For any users who may still be using V1 topic names, the migration is
> > > straightforward:
> > >
> > > | V1 Format | V2 Format |
> > > |---|---|
> > > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> > > `persistent://my-tenant/my-namespace/my-topic` |
> > > | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> > > `/admin/v2/persistent/my-tenant/my-namespace` |
> > > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> > > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
> > >
> > > Simply remove the cluster component from the topic name path.
> > >
> > >
> > >
> > >
> > >
> > > --
> > > Matteo Merli
> > > <ma...@gmail.com>
> > >
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Matteo Merli <ma...@gmail.com>.
Hi Rajan,
existing deployment using v1 era topics already had 8 years to start a
migration. I don't see how waiting more time will help here.
These deployments can keep staying on the 4.0.x LTS version which is
still going to be maintained for significant time.
I'm not against a migration mechanism, though that would require
significant effort. I'm happy to help out whoever wants to work on
that.
Right now, I think the complexity throughout the code base required to
support v1/v2 greatly overweights the benefits and it severely hinders
the ability to further evolve and push Pulsar forward.
Thanks,
Matteo
--
Matteo Merli
<ma...@gmail.com>
On Fri, Feb 27, 2026 at 10:31 AM Rajan Dhabalia <dh...@gmail.com> wrote:
>
> Hi Matteo,
>
> I completely understand your concern and the motivation behind this.
>
> However, there are still large scale Pulsar deployments with a significant
> number of V1 topic names. Removing V1 topic support would effectively
> require those systems to stop using Pulsar, which does not seem like the
> right approach.
>
> We should introduce a migration mechanism to move V1 topics to the newer
> version so legacy systems have a clear transition path. I would not
> recommend removing V1 topic support without first defining and agreeing on
> a migration strategy.
>
> Thanks,
> Rajan
>
> On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <ma...@gmail.com> wrote:
>
> > https://github.com/apache/pulsar/pull/25275
> >
> >
> > # PIP-457: Remove support for V1 topic names and V1 Admin API
> >
> > ## Background knowledge
> >
> > Apache Pulsar historically supported two topic naming formats:
> >
> > - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> > includes the cluster name in the topic path
> > - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> > cluster name, making all namespaces implicitly "global"
> >
> > The V1 format was the original naming convention from Pulsar's early
> > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> > 2018) by removing the cluster component, and PIP-11 further simplified
> > naming with short topic names defaulting to
> > `persistent://public/default/`. V1 topic names have been deprecated
> > since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
> >
> > The V1 naming format also implied a separate set of Admin REST API
> > endpoints, Lookup endpoints, and WebSocket paths that include
> > `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> > to the V2 paths using `{tenant}/{namespace}`.
> >
> > These V1 APIs have been deprecated and hidden from the API
> > documentation for many years. The V2 format has been the recommended
> > and default format since Pulsar 2.0.
> >
> > ## Motivation
> >
> > The continued presence of V1 topic name support imposes several costs
> > on the project:
> >
> > 1. **Maintenance burden**: Every Admin API operation must be
> > duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> > their V2 counterparts). Bug fixes and new features touching admin APIs
> > must account for both code paths.
> >
> > 2. **Increased attack surface**: The V1 endpoints are hidden from
> > documentation but still active and routable, creating undocumented API
> > surface area that must be secured, tested, and maintained.
> >
> > 3. **Code complexity in TopicName parsing**: The `TopicName` class
> > must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> > `isV2()` check propagates throughout the broker, lookup, and client
> > code.
> >
> > 4. **WebSocket handler complexity**: WebSocket paths must support both
> > `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> > (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> > (V2).
> >
> > 5. **Confusion for new contributors and operators**: The existence of
> > two naming schemes and two sets of admin APIs creates unnecessary
> > confusion and cognitive overhead.
> >
> > 6. **Test matrix expansion**: V1 paths must be covered by integration
> > and unit tests, expanding the test matrix without providing value to
> > modern deployments.
> >
> > V1 topics have been deprecated since Pulsar 2.0, released in June
> > 2018. With nearly 8 years having passed and the project now on the 4.x
> > release line, it is time to complete this deprecation and remove V1
> > support entirely.
> >
> > ## Goals
> >
> > ### In Scope
> >
> > - Remove all V1 Admin REST API endpoint classes and their registrations:
> > - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> > - `org.apache.pulsar.broker.admin.v1.Namespaces`
> > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> > - Remove V1 topic lookup endpoint:
> > - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> > - Remove V1 WebSocket handler paths
> > - Remove V1 (4-part) topic name parsing from `TopicName` and related
> > classes
> > - Remove `isV2()` method and all conditional branching based on V1 vs
> > V2 topic format
> > - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> > - Remove or update all tests that exercise V1 code paths
> > - Update CLI tools that may still reference V1 format
> > - Log a clear error message if a client attempts to use a V1-style
> > topic name, to aid migration
> >
> > ### Out of Scope
> >
> > - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
> > - Changes to the binary protocol wire format
> > - Metadata store migration of existing V1 topic metadata (this PIP
> > covers code removal; data migration would be addressed separately if
> > needed)
> >
> > ## High Level Design
> >
> > The removal will be executed in a single coordinated change:
> >
> > 1. **Admin API**: Delete the `v1` package under
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> > remove the registration of V1 REST resources from the broker's web
> > server initialization.
> >
> > 2. **Lookup**: Delete
> >
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> > and remove its registration.
> >
> > 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> > 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> > name is provided, throw a clear `IllegalArgumentException` with a
> > message explaining V1 names are no longer supported and how to
> > convert.
> >
> > 4. **WebSocket**: Remove V1 URI parsing paths from
> > `AbstractWebSocketHandler` and related classes.
> >
> > 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> > coincidentally use V1 names should be updated to V2 format.
> >
> > ## Detailed Design
> >
> > ### Admin API Removal
> >
> > The following classes will be deleted:
> > -
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> > -
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> > -
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
> >
> > Their registration in the broker's Jersey/JAX-RS application
> > configuration will be removed.
> >
> > ### TopicName Simplification
> >
> > In `pulsar-common`, the `TopicName` class will be modified:
> >
> > ```java
> > // Before: accepts both V1 (4 parts) and V2 (3 parts)
> > // After: only accepts V2 (3 parts)
> > private TopicName(String completeTopicName) {
> > // ... parse domain://
> > String[] parts = rest.split("/", 3); // tenant/namespace/localName
> > if (parts.length != 3) {
> > throw new IllegalArgumentException(
> > "Invalid topic name '" + completeTopicName + "'. "
> > + "Expected format: 'persistent://tenant/namespace/topic'. "
> > + "V1 topic names (with cluster component) are no longer
> > supported. "
> > + "Please use the V2 format without the cluster name.");
> > }
> > this.tenant = parts[0];
> > this.namespace = parts[1];
> > this.localName = parts[2];
> > // cluster field removed entirely
> > }
> > ```
> >
> > The `isV2()` method and `cluster` field will be removed from
> > `TopicName`. All call sites that branch on `isV2()` will be
> > simplified.
> >
> > The `NamespaceName` class will similarly be simplified to remove V1
> > support.
> >
> > ### Lookup Simplification
> >
> > The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> > between V1/V2 redirect paths will be removed. Lookups will only use V2
> > paths.
> >
> > ### WebSocket Simplification
> >
> > The `getTopic()` method in WebSocket handler classes will be
> > simplified to only parse V2-style URIs (`/ws/v2/...`).
> >
> > ## Public-facing Changes
> >
> > ### REST API
> >
> > The following REST API paths will be **removed**:
> >
> > **Persistent Topics (V1)**:
> > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
> > - `GET/PUT/DELETE
> > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> > topic operations
> > - `GET/PUT/DELETE
> > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> > partitioned topic operations
> >
> > **Non-Persistent Topics (V1)**:
> > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> > topics
> > - `GET/PUT/DELETE
> > /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > all topic operations
> >
> > **Namespaces (V1)**:
> > - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> > — all namespace operations
> >
> > **Lookup (V1)**:
> > - `GET
> > /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> > — topic lookup
> >
> > ### Binary Protocol
> >
> > No changes to the binary protocol.
> >
> > ### Configuration
> >
> > No new configuration. The broker configuration key `allowV1Topics` may
> > be considered for a transitional release but is **not** proposed here
> > — the removal is clean and complete.
> >
> > ### CLI
> >
> > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> > names. Passing a V1 topic name will produce a clear error message with
> > migration guidance.
> >
> > ### Metrics
> >
> > No metrics changes.
> >
> > ## Monitoring
> >
> > Operators should monitor for client errors after the upgrade. Clients
> > attempting to use V1 topic names will receive clear error responses
> > (HTTP 404 for V1 admin paths, or client-side
> > `IllegalArgumentException` for V1 topic names).
> >
> > ## Security Considerations
> >
> > This change reduces the API attack surface by removing undocumented
> > but active REST endpoints. No new security considerations are
> > introduced.
> >
> > ## Backward & Forward Compatibility
> >
> > ### Upgrade
> >
> > This is a **breaking change** for any deployment still using V1 topic
> > names or V1 Admin API paths.
> >
> > Before upgrading to the version containing this change, operators must:
> > 1. Ensure all topic names in use follow the V2 format
> > (`persistent://tenant/namespace/topic`)
> > 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
> >
> > The V1 format has been deprecated since Pulsar 2.0, released in June
> > 2018 — nearly 8 years ago. Any deployment that has been maintained on
> > a supported Pulsar version should already be using V2 format
> > exclusively.
> >
> > ### Downgrade / Rollback
> >
> > Rolling back to a prior version that supports V1 topic names will work
> > without issues, as no data format changes are involved.
> >
> > ### Geo-Replication
> >
> > No impact. Geo-replication already uses V2 topic names. The cluster
> > component in V1 topic names was originally related to replication
> > configuration but has been decoupled since V2 was introduced.
> >
> > ## General Notes
> >
> > ### Related PIPs
> > - PIP-10: Remove cluster from topic name (introduced V2 naming)
> > - PIP-11: Short topic name (further simplified topic naming)
> > - PIP-48: Proposed V4 admin API (future direction for admin APIs)
> >
> > ### Migration Guide
> >
> > For any users who may still be using V1 topic names, the migration is
> > straightforward:
> >
> > | V1 Format | V2 Format |
> > |---|---|
> > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> > `persistent://my-tenant/my-namespace/my-topic` |
> > | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> > `/admin/v2/persistent/my-tenant/my-namespace` |
> > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
> >
> > Simply remove the cluster component from the topic name path.
> >
> >
> >
> >
> >
> > --
> > Matteo Merli
> > <ma...@gmail.com>
> >
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Rajan Dhabalia <dh...@gmail.com>.
Hi Matteo,
I completely understand your concern and the motivation behind this.
However, there are still large scale Pulsar deployments with a significant
number of V1 topic names. Removing V1 topic support would effectively
require those systems to stop using Pulsar, which does not seem like the
right approach.
We should introduce a migration mechanism to move V1 topics to the newer
version so legacy systems have a clear transition path. I would not
recommend removing V1 topic support without first defining and agreeing on
a migration strategy.
Thanks,
Rajan
On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <ma...@gmail.com> wrote:
> https://github.com/apache/pulsar/pull/25275
>
>
> # PIP-457: Remove support for V1 topic names and V1 Admin API
>
> ## Background knowledge
>
> Apache Pulsar historically supported two topic naming formats:
>
> - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> includes the cluster name in the topic path
> - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> cluster name, making all namespaces implicitly "global"
>
> The V1 format was the original naming convention from Pulsar's early
> days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> 2018) by removing the cluster component, and PIP-11 further simplified
> naming with short topic names defaulting to
> `persistent://public/default/`. V1 topic names have been deprecated
> since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
>
> The V1 naming format also implied a separate set of Admin REST API
> endpoints, Lookup endpoints, and WebSocket paths that include
> `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> to the V2 paths using `{tenant}/{namespace}`.
>
> These V1 APIs have been deprecated and hidden from the API
> documentation for many years. The V2 format has been the recommended
> and default format since Pulsar 2.0.
>
> ## Motivation
>
> The continued presence of V1 topic name support imposes several costs
> on the project:
>
> 1. **Maintenance burden**: Every Admin API operation must be
> duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> their V2 counterparts). Bug fixes and new features touching admin APIs
> must account for both code paths.
>
> 2. **Increased attack surface**: The V1 endpoints are hidden from
> documentation but still active and routable, creating undocumented API
> surface area that must be secured, tested, and maintained.
>
> 3. **Code complexity in TopicName parsing**: The `TopicName` class
> must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> `isV2()` check propagates throughout the broker, lookup, and client
> code.
>
> 4. **WebSocket handler complexity**: WebSocket paths must support both
> `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> (V2).
>
> 5. **Confusion for new contributors and operators**: The existence of
> two naming schemes and two sets of admin APIs creates unnecessary
> confusion and cognitive overhead.
>
> 6. **Test matrix expansion**: V1 paths must be covered by integration
> and unit tests, expanding the test matrix without providing value to
> modern deployments.
>
> V1 topics have been deprecated since Pulsar 2.0, released in June
> 2018. With nearly 8 years having passed and the project now on the 4.x
> release line, it is time to complete this deprecation and remove V1
> support entirely.
>
> ## Goals
>
> ### In Scope
>
> - Remove all V1 Admin REST API endpoint classes and their registrations:
> - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.Namespaces`
> - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> - Remove V1 topic lookup endpoint:
> - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> - Remove V1 WebSocket handler paths
> - Remove V1 (4-part) topic name parsing from `TopicName` and related
> classes
> - Remove `isV2()` method and all conditional branching based on V1 vs
> V2 topic format
> - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> - Remove or update all tests that exercise V1 code paths
> - Update CLI tools that may still reference V1 format
> - Log a clear error message if a client attempts to use a V1-style
> topic name, to aid migration
>
> ### Out of Scope
>
> - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
> - Changes to the binary protocol wire format
> - Metadata store migration of existing V1 topic metadata (this PIP
> covers code removal; data migration would be addressed separately if
> needed)
>
> ## High Level Design
>
> The removal will be executed in a single coordinated change:
>
> 1. **Admin API**: Delete the `v1` package under
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> remove the registration of V1 REST resources from the broker's web
> server initialization.
>
> 2. **Lookup**: Delete
>
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> and remove its registration.
>
> 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> name is provided, throw a clear `IllegalArgumentException` with a
> message explaining V1 names are no longer supported and how to
> convert.
>
> 4. **WebSocket**: Remove V1 URI parsing paths from
> `AbstractWebSocketHandler` and related classes.
>
> 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> coincidentally use V1 names should be updated to V2 format.
>
> ## Detailed Design
>
> ### Admin API Removal
>
> The following classes will be deleted:
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
>
> Their registration in the broker's Jersey/JAX-RS application
> configuration will be removed.
>
> ### TopicName Simplification
>
> In `pulsar-common`, the `TopicName` class will be modified:
>
> ```java
> // Before: accepts both V1 (4 parts) and V2 (3 parts)
> // After: only accepts V2 (3 parts)
> private TopicName(String completeTopicName) {
> // ... parse domain://
> String[] parts = rest.split("/", 3); // tenant/namespace/localName
> if (parts.length != 3) {
> throw new IllegalArgumentException(
> "Invalid topic name '" + completeTopicName + "'. "
> + "Expected format: 'persistent://tenant/namespace/topic'. "
> + "V1 topic names (with cluster component) are no longer
> supported. "
> + "Please use the V2 format without the cluster name.");
> }
> this.tenant = parts[0];
> this.namespace = parts[1];
> this.localName = parts[2];
> // cluster field removed entirely
> }
> ```
>
> The `isV2()` method and `cluster` field will be removed from
> `TopicName`. All call sites that branch on `isV2()` will be
> simplified.
>
> The `NamespaceName` class will similarly be simplified to remove V1
> support.
>
> ### Lookup Simplification
>
> The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> between V1/V2 redirect paths will be removed. Lookups will only use V2
> paths.
>
> ### WebSocket Simplification
>
> The `getTopic()` method in WebSocket handler classes will be
> simplified to only parse V2-style URIs (`/ws/v2/...`).
>
> ## Public-facing Changes
>
> ### REST API
>
> The following REST API paths will be **removed**:
>
> **Persistent Topics (V1)**:
> - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> topic operations
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> partitioned topic operations
>
> **Non-Persistent Topics (V1)**:
> - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> topics
> - `GET/PUT/DELETE
> /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> all topic operations
>
> **Namespaces (V1)**:
> - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> — all namespace operations
>
> **Lookup (V1)**:
> - `GET
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> — topic lookup
>
> ### Binary Protocol
>
> No changes to the binary protocol.
>
> ### Configuration
>
> No new configuration. The broker configuration key `allowV1Topics` may
> be considered for a transitional release but is **not** proposed here
> — the removal is clean and complete.
>
> ### CLI
>
> `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> names. Passing a V1 topic name will produce a clear error message with
> migration guidance.
>
> ### Metrics
>
> No metrics changes.
>
> ## Monitoring
>
> Operators should monitor for client errors after the upgrade. Clients
> attempting to use V1 topic names will receive clear error responses
> (HTTP 404 for V1 admin paths, or client-side
> `IllegalArgumentException` for V1 topic names).
>
> ## Security Considerations
>
> This change reduces the API attack surface by removing undocumented
> but active REST endpoints. No new security considerations are
> introduced.
>
> ## Backward & Forward Compatibility
>
> ### Upgrade
>
> This is a **breaking change** for any deployment still using V1 topic
> names or V1 Admin API paths.
>
> Before upgrading to the version containing this change, operators must:
> 1. Ensure all topic names in use follow the V2 format
> (`persistent://tenant/namespace/topic`)
> 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
>
> The V1 format has been deprecated since Pulsar 2.0, released in June
> 2018 — nearly 8 years ago. Any deployment that has been maintained on
> a supported Pulsar version should already be using V2 format
> exclusively.
>
> ### Downgrade / Rollback
>
> Rolling back to a prior version that supports V1 topic names will work
> without issues, as no data format changes are involved.
>
> ### Geo-Replication
>
> No impact. Geo-replication already uses V2 topic names. The cluster
> component in V1 topic names was originally related to replication
> configuration but has been decoupled since V2 was introduced.
>
> ## General Notes
>
> ### Related PIPs
> - PIP-10: Remove cluster from topic name (introduced V2 naming)
> - PIP-11: Short topic name (further simplified topic naming)
> - PIP-48: Proposed V4 admin API (future direction for admin APIs)
>
> ### Migration Guide
>
> For any users who may still be using V1 topic names, the migration is
> straightforward:
>
> | V1 Format | V2 Format |
> |---|---|
> | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> `persistent://my-tenant/my-namespace/my-topic` |
> | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> `/admin/v2/persistent/my-tenant/my-namespace` |
> | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
>
> Simply remove the cluster component from the topic name path.
>
>
>
>
>
> --
> Matteo Merli
> <ma...@gmail.com>
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Matteo Merli <ma...@gmail.com>.
Thanks for the feedback. I'll move this discussion to a vot.
--
Matteo Merli
<ma...@gmail.com>
On Mon, Mar 2, 2026 at 6:02 PM Tao Jiuming <da...@apache.org> wrote:
>
> +1
>
> Matteo Merli <ma...@gmail.com>于2026年2月28日 周六01:50写道:
>
> > https://github.com/apache/pulsar/pull/25275
> >
> >
> > # PIP-457: Remove support for V1 topic names and V1 Admin API
> >
> > ## Background knowledge
> >
> > Apache Pulsar historically supported two topic naming formats:
> >
> > - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> > includes the cluster name in the topic path
> > - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> > cluster name, making all namespaces implicitly "global"
> >
> > The V1 format was the original naming convention from Pulsar's early
> > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> > 2018) by removing the cluster component, and PIP-11 further simplified
> > naming with short topic names defaulting to
> > `persistent://public/default/`. V1 topic names have been deprecated
> > since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
> >
> > The V1 naming format also implied a separate set of Admin REST API
> > endpoints, Lookup endpoints, and WebSocket paths that include
> > `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> > to the V2 paths using `{tenant}/{namespace}`.
> >
> > These V1 APIs have been deprecated and hidden from the API
> > documentation for many years. The V2 format has been the recommended
> > and default format since Pulsar 2.0.
> >
> > ## Motivation
> >
> > The continued presence of V1 topic name support imposes several costs
> > on the project:
> >
> > 1. **Maintenance burden**: Every Admin API operation must be
> > duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> > their V2 counterparts). Bug fixes and new features touching admin APIs
> > must account for both code paths.
> >
> > 2. **Increased attack surface**: The V1 endpoints are hidden from
> > documentation but still active and routable, creating undocumented API
> > surface area that must be secured, tested, and maintained.
> >
> > 3. **Code complexity in TopicName parsing**: The `TopicName` class
> > must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> > `isV2()` check propagates throughout the broker, lookup, and client
> > code.
> >
> > 4. **WebSocket handler complexity**: WebSocket paths must support both
> > `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> > (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> > (V2).
> >
> > 5. **Confusion for new contributors and operators**: The existence of
> > two naming schemes and two sets of admin APIs creates unnecessary
> > confusion and cognitive overhead.
> >
> > 6. **Test matrix expansion**: V1 paths must be covered by integration
> > and unit tests, expanding the test matrix without providing value to
> > modern deployments.
> >
> > V1 topics have been deprecated since Pulsar 2.0, released in June
> > 2018. With nearly 8 years having passed and the project now on the 4.x
> > release line, it is time to complete this deprecation and remove V1
> > support entirely.
> >
> > ## Goals
> >
> > ### In Scope
> >
> > - Remove all V1 Admin REST API endpoint classes and their registrations:
> > - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> > - `org.apache.pulsar.broker.admin.v1.Namespaces`
> > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> > - Remove V1 topic lookup endpoint:
> > - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> > - Remove V1 WebSocket handler paths
> > - Remove V1 (4-part) topic name parsing from `TopicName` and related
> > classes
> > - Remove `isV2()` method and all conditional branching based on V1 vs
> > V2 topic format
> > - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> > - Remove or update all tests that exercise V1 code paths
> > - Update CLI tools that may still reference V1 format
> > - Log a clear error message if a client attempts to use a V1-style
> > topic name, to aid migration
> >
> > ### Out of Scope
> >
> > - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
> > - Changes to the binary protocol wire format
> > - Metadata store migration of existing V1 topic metadata (this PIP
> > covers code removal; data migration would be addressed separately if
> > needed)
> >
> > ## High Level Design
> >
> > The removal will be executed in a single coordinated change:
> >
> > 1. **Admin API**: Delete the `v1` package under
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> > remove the registration of V1 REST resources from the broker's web
> > server initialization.
> >
> > 2. **Lookup**: Delete
> >
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> > and remove its registration.
> >
> > 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> > 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> > name is provided, throw a clear `IllegalArgumentException` with a
> > message explaining V1 names are no longer supported and how to
> > convert.
> >
> > 4. **WebSocket**: Remove V1 URI parsing paths from
> > `AbstractWebSocketHandler` and related classes.
> >
> > 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> > coincidentally use V1 names should be updated to V2 format.
> >
> > ## Detailed Design
> >
> > ### Admin API Removal
> >
> > The following classes will be deleted:
> > -
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> > -
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> > -
> > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
> >
> > Their registration in the broker's Jersey/JAX-RS application
> > configuration will be removed.
> >
> > ### TopicName Simplification
> >
> > In `pulsar-common`, the `TopicName` class will be modified:
> >
> > ```java
> > // Before: accepts both V1 (4 parts) and V2 (3 parts)
> > // After: only accepts V2 (3 parts)
> > private TopicName(String completeTopicName) {
> > // ... parse domain://
> > String[] parts = rest.split("/", 3); // tenant/namespace/localName
> > if (parts.length != 3) {
> > throw new IllegalArgumentException(
> > "Invalid topic name '" + completeTopicName + "'. "
> > + "Expected format: 'persistent://tenant/namespace/topic'. "
> > + "V1 topic names (with cluster component) are no longer
> > supported. "
> > + "Please use the V2 format without the cluster name.");
> > }
> > this.tenant = parts[0];
> > this.namespace = parts[1];
> > this.localName = parts[2];
> > // cluster field removed entirely
> > }
> > ```
> >
> > The `isV2()` method and `cluster` field will be removed from
> > `TopicName`. All call sites that branch on `isV2()` will be
> > simplified.
> >
> > The `NamespaceName` class will similarly be simplified to remove V1
> > support.
> >
> > ### Lookup Simplification
> >
> > The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> > between V1/V2 redirect paths will be removed. Lookups will only use V2
> > paths.
> >
> > ### WebSocket Simplification
> >
> > The `getTopic()` method in WebSocket handler classes will be
> > simplified to only parse V2-style URIs (`/ws/v2/...`).
> >
> > ## Public-facing Changes
> >
> > ### REST API
> >
> > The following REST API paths will be **removed**:
> >
> > **Persistent Topics (V1)**:
> > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
> > - `GET/PUT/DELETE
> > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> > topic operations
> > - `GET/PUT/DELETE
> > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> > partitioned topic operations
> >
> > **Non-Persistent Topics (V1)**:
> > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> > topics
> > - `GET/PUT/DELETE
> > /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> > all topic operations
> >
> > **Namespaces (V1)**:
> > - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> > — all namespace operations
> >
> > **Lookup (V1)**:
> > - `GET
> > /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> > — topic lookup
> >
> > ### Binary Protocol
> >
> > No changes to the binary protocol.
> >
> > ### Configuration
> >
> > No new configuration. The broker configuration key `allowV1Topics` may
> > be considered for a transitional release but is **not** proposed here
> > — the removal is clean and complete.
> >
> > ### CLI
> >
> > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> > names. Passing a V1 topic name will produce a clear error message with
> > migration guidance.
> >
> > ### Metrics
> >
> > No metrics changes.
> >
> > ## Monitoring
> >
> > Operators should monitor for client errors after the upgrade. Clients
> > attempting to use V1 topic names will receive clear error responses
> > (HTTP 404 for V1 admin paths, or client-side
> > `IllegalArgumentException` for V1 topic names).
> >
> > ## Security Considerations
> >
> > This change reduces the API attack surface by removing undocumented
> > but active REST endpoints. No new security considerations are
> > introduced.
> >
> > ## Backward & Forward Compatibility
> >
> > ### Upgrade
> >
> > This is a **breaking change** for any deployment still using V1 topic
> > names or V1 Admin API paths.
> >
> > Before upgrading to the version containing this change, operators must:
> > 1. Ensure all topic names in use follow the V2 format
> > (`persistent://tenant/namespace/topic`)
> > 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
> >
> > The V1 format has been deprecated since Pulsar 2.0, released in June
> > 2018 — nearly 8 years ago. Any deployment that has been maintained on
> > a supported Pulsar version should already be using V2 format
> > exclusively.
> >
> > ### Downgrade / Rollback
> >
> > Rolling back to a prior version that supports V1 topic names will work
> > without issues, as no data format changes are involved.
> >
> > ### Geo-Replication
> >
> > No impact. Geo-replication already uses V2 topic names. The cluster
> > component in V1 topic names was originally related to replication
> > configuration but has been decoupled since V2 was introduced.
> >
> > ## General Notes
> >
> > ### Related PIPs
> > - PIP-10: Remove cluster from topic name (introduced V2 naming)
> > - PIP-11: Short topic name (further simplified topic naming)
> > - PIP-48: Proposed V4 admin API (future direction for admin APIs)
> >
> > ### Migration Guide
> >
> > For any users who may still be using V1 topic names, the migration is
> > straightforward:
> >
> > | V1 Format | V2 Format |
> > |---|---|
> > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> > `persistent://my-tenant/my-namespace/my-topic` |
> > | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> > `/admin/v2/persistent/my-tenant/my-namespace` |
> > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
> >
> > Simply remove the cluster component from the topic name path.
> >
> >
> >
> >
> >
> > --
> > Matteo Merli
> > <ma...@gmail.com>
> >
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by Tao Jiuming <da...@apache.org>.
+1
Matteo Merli <ma...@gmail.com>于2026年2月28日 周六01:50写道:
> https://github.com/apache/pulsar/pull/25275
>
>
> # PIP-457: Remove support for V1 topic names and V1 Admin API
>
> ## Background knowledge
>
> Apache Pulsar historically supported two topic naming formats:
>
> - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> includes the cluster name in the topic path
> - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> cluster name, making all namespaces implicitly "global"
>
> The V1 format was the original naming convention from Pulsar's early
> days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> 2018) by removing the cluster component, and PIP-11 further simplified
> naming with short topic names defaulting to
> `persistent://public/default/`. V1 topic names have been deprecated
> since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
>
> The V1 naming format also implied a separate set of Admin REST API
> endpoints, Lookup endpoints, and WebSocket paths that include
> `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> to the V2 paths using `{tenant}/{namespace}`.
>
> These V1 APIs have been deprecated and hidden from the API
> documentation for many years. The V2 format has been the recommended
> and default format since Pulsar 2.0.
>
> ## Motivation
>
> The continued presence of V1 topic name support imposes several costs
> on the project:
>
> 1. **Maintenance burden**: Every Admin API operation must be
> duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> their V2 counterparts). Bug fixes and new features touching admin APIs
> must account for both code paths.
>
> 2. **Increased attack surface**: The V1 endpoints are hidden from
> documentation but still active and routable, creating undocumented API
> surface area that must be secured, tested, and maintained.
>
> 3. **Code complexity in TopicName parsing**: The `TopicName` class
> must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> `isV2()` check propagates throughout the broker, lookup, and client
> code.
>
> 4. **WebSocket handler complexity**: WebSocket paths must support both
> `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> (V2).
>
> 5. **Confusion for new contributors and operators**: The existence of
> two naming schemes and two sets of admin APIs creates unnecessary
> confusion and cognitive overhead.
>
> 6. **Test matrix expansion**: V1 paths must be covered by integration
> and unit tests, expanding the test matrix without providing value to
> modern deployments.
>
> V1 topics have been deprecated since Pulsar 2.0, released in June
> 2018. With nearly 8 years having passed and the project now on the 4.x
> release line, it is time to complete this deprecation and remove V1
> support entirely.
>
> ## Goals
>
> ### In Scope
>
> - Remove all V1 Admin REST API endpoint classes and their registrations:
> - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.Namespaces`
> - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> - Remove V1 topic lookup endpoint:
> - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> - Remove V1 WebSocket handler paths
> - Remove V1 (4-part) topic name parsing from `TopicName` and related
> classes
> - Remove `isV2()` method and all conditional branching based on V1 vs
> V2 topic format
> - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> - Remove or update all tests that exercise V1 code paths
> - Update CLI tools that may still reference V1 format
> - Log a clear error message if a client attempts to use a V1-style
> topic name, to aid migration
>
> ### Out of Scope
>
> - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
> - Changes to the binary protocol wire format
> - Metadata store migration of existing V1 topic metadata (this PIP
> covers code removal; data migration would be addressed separately if
> needed)
>
> ## High Level Design
>
> The removal will be executed in a single coordinated change:
>
> 1. **Admin API**: Delete the `v1` package under
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> remove the registration of V1 REST resources from the broker's web
> server initialization.
>
> 2. **Lookup**: Delete
>
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> and remove its registration.
>
> 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> name is provided, throw a clear `IllegalArgumentException` with a
> message explaining V1 names are no longer supported and how to
> convert.
>
> 4. **WebSocket**: Remove V1 URI parsing paths from
> `AbstractWebSocketHandler` and related classes.
>
> 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> coincidentally use V1 names should be updated to V2 format.
>
> ## Detailed Design
>
> ### Admin API Removal
>
> The following classes will be deleted:
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
>
> Their registration in the broker's Jersey/JAX-RS application
> configuration will be removed.
>
> ### TopicName Simplification
>
> In `pulsar-common`, the `TopicName` class will be modified:
>
> ```java
> // Before: accepts both V1 (4 parts) and V2 (3 parts)
> // After: only accepts V2 (3 parts)
> private TopicName(String completeTopicName) {
> // ... parse domain://
> String[] parts = rest.split("/", 3); // tenant/namespace/localName
> if (parts.length != 3) {
> throw new IllegalArgumentException(
> "Invalid topic name '" + completeTopicName + "'. "
> + "Expected format: 'persistent://tenant/namespace/topic'. "
> + "V1 topic names (with cluster component) are no longer
> supported. "
> + "Please use the V2 format without the cluster name.");
> }
> this.tenant = parts[0];
> this.namespace = parts[1];
> this.localName = parts[2];
> // cluster field removed entirely
> }
> ```
>
> The `isV2()` method and `cluster` field will be removed from
> `TopicName`. All call sites that branch on `isV2()` will be
> simplified.
>
> The `NamespaceName` class will similarly be simplified to remove V1
> support.
>
> ### Lookup Simplification
>
> The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> between V1/V2 redirect paths will be removed. Lookups will only use V2
> paths.
>
> ### WebSocket Simplification
>
> The `getTopic()` method in WebSocket handler classes will be
> simplified to only parse V2-style URIs (`/ws/v2/...`).
>
> ## Public-facing Changes
>
> ### REST API
>
> The following REST API paths will be **removed**:
>
> **Persistent Topics (V1)**:
> - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> topic operations
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> partitioned topic operations
>
> **Non-Persistent Topics (V1)**:
> - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> topics
> - `GET/PUT/DELETE
> /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> all topic operations
>
> **Namespaces (V1)**:
> - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> — all namespace operations
>
> **Lookup (V1)**:
> - `GET
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> — topic lookup
>
> ### Binary Protocol
>
> No changes to the binary protocol.
>
> ### Configuration
>
> No new configuration. The broker configuration key `allowV1Topics` may
> be considered for a transitional release but is **not** proposed here
> — the removal is clean and complete.
>
> ### CLI
>
> `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> names. Passing a V1 topic name will produce a clear error message with
> migration guidance.
>
> ### Metrics
>
> No metrics changes.
>
> ## Monitoring
>
> Operators should monitor for client errors after the upgrade. Clients
> attempting to use V1 topic names will receive clear error responses
> (HTTP 404 for V1 admin paths, or client-side
> `IllegalArgumentException` for V1 topic names).
>
> ## Security Considerations
>
> This change reduces the API attack surface by removing undocumented
> but active REST endpoints. No new security considerations are
> introduced.
>
> ## Backward & Forward Compatibility
>
> ### Upgrade
>
> This is a **breaking change** for any deployment still using V1 topic
> names or V1 Admin API paths.
>
> Before upgrading to the version containing this change, operators must:
> 1. Ensure all topic names in use follow the V2 format
> (`persistent://tenant/namespace/topic`)
> 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
>
> The V1 format has been deprecated since Pulsar 2.0, released in June
> 2018 — nearly 8 years ago. Any deployment that has been maintained on
> a supported Pulsar version should already be using V2 format
> exclusively.
>
> ### Downgrade / Rollback
>
> Rolling back to a prior version that supports V1 topic names will work
> without issues, as no data format changes are involved.
>
> ### Geo-Replication
>
> No impact. Geo-replication already uses V2 topic names. The cluster
> component in V1 topic names was originally related to replication
> configuration but has been decoupled since V2 was introduced.
>
> ## General Notes
>
> ### Related PIPs
> - PIP-10: Remove cluster from topic name (introduced V2 naming)
> - PIP-11: Short topic name (further simplified topic naming)
> - PIP-48: Proposed V4 admin API (future direction for admin APIs)
>
> ### Migration Guide
>
> For any users who may still be using V1 topic names, the migration is
> straightforward:
>
> | V1 Format | V2 Format |
> |---|---|
> | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> `persistent://my-tenant/my-namespace/my-topic` |
> | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> `/admin/v2/persistent/my-tenant/my-namespace` |
> | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
>
> Simply remove the cluster component from the topic name path.
>
>
>
>
>
> --
> Matteo Merli
> <ma...@gmail.com>
>
Re: [DISCUSS] PIP-457: Remove support for V1 topic names and V1 Admin API
Posted by PengHui Li <pe...@apache.org>.
+1
Regards,
Penghui
On Fri, Feb 27, 2026 at 9:50 AM Matteo Merli <ma...@gmail.com> wrote:
> https://github.com/apache/pulsar/pull/25275
>
>
> # PIP-457: Remove support for V1 topic names and V1 Admin API
>
> ## Background knowledge
>
> Apache Pulsar historically supported two topic naming formats:
>
> - **V1 format**: `persistent://tenant/cluster/namespace/topic` —
> includes the cluster name in the topic path
> - **V2 format**: `persistent://tenant/namespace/topic` — omits the
> cluster name, making all namespaces implicitly "global"
>
> The V1 format was the original naming convention from Pulsar's early
> days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June
> 2018) by removing the cluster component, and PIP-11 further simplified
> naming with short topic names defaulting to
> `persistent://public/default/`. V1 topic names have been deprecated
> since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
>
> The V1 naming format also implied a separate set of Admin REST API
> endpoints, Lookup endpoints, and WebSocket paths that include
> `{property}/{cluster}/{namespace}` in their URL structure, as opposed
> to the V2 paths using `{tenant}/{namespace}`.
>
> These V1 APIs have been deprecated and hidden from the API
> documentation for many years. The V2 format has been the recommended
> and default format since Pulsar 2.0.
>
> ## Motivation
>
> The continued presence of V1 topic name support imposes several costs
> on the project:
>
> 1. **Maintenance burden**: Every Admin API operation must be
> duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`,
> `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside
> their V2 counterparts). Bug fixes and new features touching admin APIs
> must account for both code paths.
>
> 2. **Increased attack surface**: The V1 endpoints are hidden from
> documentation but still active and routable, creating undocumented API
> surface area that must be secured, tested, and maintained.
>
> 3. **Code complexity in TopicName parsing**: The `TopicName` class
> must handle both 3-part (V2) and 4-part (V1) name parsing, and the
> `isV2()` check propagates throughout the broker, lookup, and client
> code.
>
> 4. **WebSocket handler complexity**: WebSocket paths must support both
> `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}`
> (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}`
> (V2).
>
> 5. **Confusion for new contributors and operators**: The existence of
> two naming schemes and two sets of admin APIs creates unnecessary
> confusion and cognitive overhead.
>
> 6. **Test matrix expansion**: V1 paths must be covered by integration
> and unit tests, expanding the test matrix without providing value to
> modern deployments.
>
> V1 topics have been deprecated since Pulsar 2.0, released in June
> 2018. With nearly 8 years having passed and the project now on the 4.x
> release line, it is time to complete this deprecation and remove V1
> support entirely.
>
> ## Goals
>
> ### In Scope
>
> - Remove all V1 Admin REST API endpoint classes and their registrations:
> - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
> - `org.apache.pulsar.broker.admin.v1.Namespaces`
> - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
> - Remove V1 topic lookup endpoint:
> - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
> - Remove V1 WebSocket handler paths
> - Remove V1 (4-part) topic name parsing from `TopicName` and related
> classes
> - Remove `isV2()` method and all conditional branching based on V1 vs
> V2 topic format
> - Remove `LOOKUP_PATH_V1` constant and related redirect logic
> - Remove or update all tests that exercise V1 code paths
> - Update CLI tools that may still reference V1 format
> - Log a clear error message if a client attempts to use a V1-style
> topic name, to aid migration
>
> ### Out of Scope
>
> - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
> - Changes to the binary protocol wire format
> - Metadata store migration of existing V1 topic metadata (this PIP
> covers code removal; data migration would be addressed separately if
> needed)
>
> ## High Level Design
>
> The removal will be executed in a single coordinated change:
>
> 1. **Admin API**: Delete the `v1` package under
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and
> remove the registration of V1 REST resources from the broker's web
> server initialization.
>
> 2. **Lookup**: Delete
>
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
> and remove its registration.
>
> 3. **TopicName parsing**: Simplify `TopicName` to only accept the
> 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part
> name is provided, throw a clear `IllegalArgumentException` with a
> message explaining V1 names are no longer supported and how to
> convert.
>
> 4. **WebSocket**: Remove V1 URI parsing paths from
> `AbstractWebSocketHandler` and related classes.
>
> 5. **Tests**: Remove or convert all V1-specific test cases. Tests that
> coincidentally use V1 names should be updated to V2 format.
>
> ## Detailed Design
>
> ### Admin API Removal
>
> The following classes will be deleted:
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
> -
> `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
>
> Their registration in the broker's Jersey/JAX-RS application
> configuration will be removed.
>
> ### TopicName Simplification
>
> In `pulsar-common`, the `TopicName` class will be modified:
>
> ```java
> // Before: accepts both V1 (4 parts) and V2 (3 parts)
> // After: only accepts V2 (3 parts)
> private TopicName(String completeTopicName) {
> // ... parse domain://
> String[] parts = rest.split("/", 3); // tenant/namespace/localName
> if (parts.length != 3) {
> throw new IllegalArgumentException(
> "Invalid topic name '" + completeTopicName + "'. "
> + "Expected format: 'persistent://tenant/namespace/topic'. "
> + "V1 topic names (with cluster component) are no longer
> supported. "
> + "Please use the V2 format without the cluster name.");
> }
> this.tenant = parts[0];
> this.namespace = parts[1];
> this.localName = parts[2];
> // cluster field removed entirely
> }
> ```
>
> The `isV2()` method and `cluster` field will be removed from
> `TopicName`. All call sites that branch on `isV2()` will be
> simplified.
>
> The `NamespaceName` class will similarly be simplified to remove V1
> support.
>
> ### Lookup Simplification
>
> The `LOOKUP_PATH_V1` constant and any conditional logic choosing
> between V1/V2 redirect paths will be removed. Lookups will only use V2
> paths.
>
> ### WebSocket Simplification
>
> The `getTopic()` method in WebSocket handler classes will be
> simplified to only parse V2-style URIs (`/ws/v2/...`).
>
> ## Public-facing Changes
>
> ### REST API
>
> The following REST API paths will be **removed**:
>
> **Persistent Topics (V1)**:
> - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all
> topic operations
> - `GET/PUT/DELETE
> /admin/persistent/{property}/{cluster}/{namespace}/partitioned` —
> partitioned topic operations
>
> **Non-Persistent Topics (V1)**:
> - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list
> topics
> - `GET/PUT/DELETE
> /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` —
> all topic operations
>
> **Namespaces (V1)**:
> - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}`
> — all namespace operations
>
> **Lookup (V1)**:
> - `GET
> /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
> — topic lookup
>
> ### Binary Protocol
>
> No changes to the binary protocol.
>
> ### Configuration
>
> No new configuration. The broker configuration key `allowV1Topics` may
> be considered for a transitional release but is **not** proposed here
> — the removal is clean and complete.
>
> ### CLI
>
> `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic
> names. Passing a V1 topic name will produce a clear error message with
> migration guidance.
>
> ### Metrics
>
> No metrics changes.
>
> ## Monitoring
>
> Operators should monitor for client errors after the upgrade. Clients
> attempting to use V1 topic names will receive clear error responses
> (HTTP 404 for V1 admin paths, or client-side
> `IllegalArgumentException` for V1 topic names).
>
> ## Security Considerations
>
> This change reduces the API attack surface by removing undocumented
> but active REST endpoints. No new security considerations are
> introduced.
>
> ## Backward & Forward Compatibility
>
> ### Upgrade
>
> This is a **breaking change** for any deployment still using V1 topic
> names or V1 Admin API paths.
>
> Before upgrading to the version containing this change, operators must:
> 1. Ensure all topic names in use follow the V2 format
> (`persistent://tenant/namespace/topic`)
> 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
> 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
>
> The V1 format has been deprecated since Pulsar 2.0, released in June
> 2018 — nearly 8 years ago. Any deployment that has been maintained on
> a supported Pulsar version should already be using V2 format
> exclusively.
>
> ### Downgrade / Rollback
>
> Rolling back to a prior version that supports V1 topic names will work
> without issues, as no data format changes are involved.
>
> ### Geo-Replication
>
> No impact. Geo-replication already uses V2 topic names. The cluster
> component in V1 topic names was originally related to replication
> configuration but has been decoupled since V2 was introduced.
>
> ## General Notes
>
> ### Related PIPs
> - PIP-10: Remove cluster from topic name (introduced V2 naming)
> - PIP-11: Short topic name (further simplified topic naming)
> - PIP-48: Proposed V4 admin API (future direction for admin APIs)
>
> ### Migration Guide
>
> For any users who may still be using V1 topic names, the migration is
> straightforward:
>
> | V1 Format | V2 Format |
> |---|---|
> | `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
> `persistent://my-tenant/my-namespace/my-topic` |
> | `/admin/persistent/my-tenant/my-cluster/my-namespace` |
> `/admin/v2/persistent/my-tenant/my-namespace` |
> | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
> `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
>
> Simply remove the cluster component from the topic name path.
>
>
>
>
>
> --
> Matteo Merli
> <ma...@gmail.com>
>