# Mountable Topics > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt) --- title: Mountable Topics latest-redpanda-tag: v25.2.1 latest-console-tag: v3.7.3 latest-operator-version: v26.1.4 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "true" page-is-past-eol: "false" page-eol-date: July 31, 2026 latest-connect-version: 4.93.0 docname: mountable-topics page-component-name: streaming page-version: "25.2" page-component-version: "25.2" page-component-title: Streaming page-relative-src-path: mountable-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/v/25.2/modules/manage/pages/mountable-topics.adoc description: Safely attach and detach Tiered Storage topics to and from a Redpanda cluster. page-git-created-date: "2024-12-03" page-git-modified-date: "2025-07-31" support-status: nearing end-of-life --- For topics with Tiered Storage enabled, you can unmount a topic to safely detach it from a cluster and keep the topic data in the cluster’s object storage bucket or container. You can mount the detached topic to either the same origin cluster, or a different one. This allows you to hibernate a topic and free up system resources taken up by the topic, or migrate a topic to a different cluster. ## [](#prerequisites)Prerequisites > 📝 **NOTE** > > This feature requires an [enterprise license](https://docs.redpanda.com/streaming/25.2/get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](https://docs.redpanda.com/streaming/25.2/get-started/licensing/#self-managed) apply. - [Install `rpk`](https://docs.redpanda.com/streaming/25.2/get-started/rpk-install/), or ensure that you have access to the Admin API. - Enable [Tiered Storage](https://docs.redpanda.com/streaming/25.2/manage/tiered-storage/) for specific topics, or for the entire cluster (all topics). ## [](#unmount-a-topic-from-a-cluster-to-object-storage)Unmount a topic from a cluster to object storage When you unmount a topic, all incoming writes to the topic are blocked as Redpanda unmounts the topic from the cluster to object storage. Producers and consumers of the topic receive a message in the protocol replies indicating that the topic is no longer available: - Produce requests receive an `invalid_topic_exception` or `resource_is_being_migrated` response from the broker. - Consume requests receive an `invalid_topic_exception` response from the broker. An unmounted topic in object storage is detached from all clusters. The original cluster releases ownership of the topic. > 📝 **NOTE** > > The unmounted topic is deleted in the source cluster, but can be mounted back again from object storage. ### rpk In your cluster, run this command to unmount a topic to object storage: ```none rpk cluster storage unmount / ``` ### Admin API To unmount topics from a cluster using the Admin API, make a POST request to the `/v1/topics/unmount` endpoint. Specify the names of the desired topics in the request body: ```none curl -X POST http://localhost:9644/v1/topics/unmount -d { "topics": [ { "topic": "" }, { "topic": "" }, { "topic": "" } ] } ``` You may optionally include the topic namespace (`ns`). Only `kafka` is supported. You can use the ID returned by the command to [monitor the progress](#monitor-progress) of the unmount operation using `rpk` or the API. ## [](#mount-a-topic-to-a-cluster)Mount a topic to a cluster ### rpk 1. In your target cluster, run this command to list the topics that are available to mount from object storage: ```none rpk cluster storage list-mountable ``` The command output returns a `LOCATION` value in the format `//`. Redpanda assigns an `initial-revision` number to a topic upon creation. The location value uniquely identifies a topic in object storage if multiple topics had the same name when they were unmounted from different origin clusters. For example: ```none TOPIC NAMESPACE LOCATION testtopic kafka testtopic/67f5505a-32f3-4677-bcad-3c75a1a702a6/10 ``` You can use the location as the topic reference instead of just the topic name to uniquely identify a topic to mount in the next step. 2. Mount a topic from object storage: ```none rpk cluster storage mount ``` Replace `` with the name of the topic to mount. If there are multiple topics wih the same name in object storage, you are required to use the location value from `rpk cluster storage list-mountable` to uniquely identify a topic. You can also specify a new name for the topic as you mount it to the target cluster: ```none rpk cluster storage mount --to ``` You only use the new name for the topic in the target cluster. This name does not persist if you unmount this topic again. Redpanda keeps the original name in object storage if you remount the topic later. ### Admin API 1. List the topics that are available to mount from object storage by making a GET request to the `v1/topics/mountable` endpoint. ```none curl http://localhost:9644/v1/topics/mountable ``` The response object contains an array of topics: ```bash "topics": [ { "topic_location": "topic-1-name//", "topic": "topic-1-name" }, { "topic_location": "topic-2-name//", "topic": "topic-2-name" } ] ``` The `topic_location` is the unique topic location in object storage, in the format `//`. Redpanda assigns the number `initial-revision` to a topic upon creation. You can use `topic-location` as the topic reference instead of just the topic name to identify a unique topic to mount in the next step. 2. To mount topics to a target cluster using the Admin API, make a POST request to the `/v1/topics/mount` endpoint. Specify the names of the topics in the request body: ```none curl -X POST http://localhost:9644/v1/topics/mount -d { "topics": [ { "source_topic_reference": {"ns": "kafka", "topic": "//"}, "alias": {"topic": ""} }, { "source_topic_reference": {"ns": "kafka", "topic": ""} } ] } ``` - `ns` is the topic namespace. This field is optional and only `kafka` is supported. - You may have multiple topics with the same name that are available to mount from object storage. This can happen if you have unmounted topics using the same name in different clusters. To uniquely identify a source topic, use `//` as the topic reference. - To rename a topic in the target cluster, use the optional `alias` object in the request body. The following example shows how to specify a new name for topic 1 in the target cluster, while topic 2 retains its original name in the target cluster. You can use the ID returned by the operation to [monitor its progress](#monitor-progress) using `rpk` or the API. When the mount operation is complete, the target cluster handles produce and consume workloads for the topics. ## [](#monitor-progress)Monitor progress ### rpk To list active mount and unmount operations, run the command: ```none rpk cluster storage list-mount ``` ### Admin API Issue a GET request to the `/migrations` endpoint to view the status of topic mount and unmount operations: ```none curl http://localhost:9644/v1/migrations ``` You can also retrieve the status of a specific operation by running the command: ### rpk ```none rpk cluster storage status-mount ``` ### Admin API ```none curl http://localhost:9644/v1/migrations/ ``` `` is the unique identifier of the operation. Redpanda returns this ID when you start a mount or unmount. You can also retrieve the ID by listing [existing operations](#monitor-progress). The response returns the IDs and state of existing mount and unmount operations ("migrations"): | State | Unmount operation (outbound) | Mount operation (inbound) | | --- | --- | --- | | planned | Redpanda validates the mount or unmount operation definition. | | preparing | Redpanda flushes topic data, including topic manifests, to the destination bucket or container in object storage. | Redpanda recreates the topics in a disabled state in the target cluster. The cluster allocates partitions but does not add log segments yet. Topic metadata is populated from the topic manifests found in object storage. | | prepared | The operation is ready to execute. In this state, the cluster still accepts client reads and writes for the topics. | Topics exist in the cluster but clients do not yet have access to consume or produce. | | executing | The cluster rejects client reads and writes for the topics. Redpanda uploads any remaining topic data that has not yet been copied to object storage. Uncommitted transactions involving the topic are aborted. | The target cluster checks that the topic to be mounted has not already been mounted in any cluster. | | executed | All unmounted topic data from the cluster is available in object storage. | The target cluster has verified that the topic has not already been mounted. | | cut_over | Redpanda deletes topic metadata from the cluster, and marks the data in object storage as available for mount operations. | The topic data in object storage is no longer available to mount to any clusters. | | finished | The operation is complete. | The operation is complete. The target cluster starts to handle produce and consume requests. | | canceling | Redpanda is in the process of canceling the mount or unmount operation. | | cancelled | The mount or unmount operation is cancelled. | ## [](#cancel-a-mount-or-unmount-operation)Cancel a mount or unmount operation You can cancel a topic mount or unmount by running the command: ### rpk ```none rpk cluster storage cancel-mount ``` ### Admin API ```none curl -X POST http://localhost:9644/v1//?action=cancel ``` You cannot cancel mount and unmount operations in the following [states](#monitor-progress): - `planned` (but you may still [delete](https://docs.redpanda.com/api/doc/admin/operation/operation-delete_migration) a planned mount or unmount) - `cut_over` - `finished` - `canceling` - `cancelled` ## [](#additional-considerations)Additional considerations Redpanda prevents you from mounting the same topic to multiple clusters at once. This ensures that multiple clusters don’t write to the same location in object storage and corrupt the topic. If you attempt to mount a topic where the name matches a topic already in the target cluster, Redpanda fails the operation and emits a warning message in the logs. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](https://docs.redpanda.com/labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](https://docs.redpanda.com/labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](https://docs.redpanda.com/labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](https://docs.redpanda.com/labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](https://docs.redpanda.com/labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](https://docs.redpanda.com/labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](https://docs.redpanda.com/labs/kubernetes/iceberg/) See more [Search all labs](https://docs.redpanda.com/labs)