Phase 1: ZDM Proxy and Data-Copy Setup for Astra

This phase prepares the tooling that moves the data and traffic. There are two parts:

• the Zero-Downtime Migration (ZDM) Proxy, which sits between the application and both databases and mirrors writes to each; and
• a bulk-copy tool that copies the data already in Astra to the new cluster. The recommended tool is the Cassandra Data Migrator (CDM), which also validates row-level consistency. Apache Spark is an alternative (see Data Migration).

Astra is the origin and the open-source Apache Cassandra cluster is the target.

ZDM Proxy licensing and attribution

The ZDM Proxy is open source under the Apache License 2.0. AxonOps maintains a fork, github.com/axonops/zdm-proxy. The fork adds migration metrics for monitoring the proxy layer and finer control over write consistency to the target (see Relaxing the target write consistency below), and AxonOps can extend it further for the specifics of the environment (contact AxonOps).

How the proxy works

The application connects to the ZDM Proxy instead of directly to a database. The proxy in turn connects to both the origin (Astra) and the target (the new cluster):

• Writes go to both databases concurrently from the moment the proxy is deployed (dual-writes).
• Reads initially go to Astra only. Later, asynchronous dual reads are enabled to exercise the target, and primary reads are finally switched to the target.

The only change the application sees is its connection endpoint: it points at the proxy instead of at Astra.

Connecting the proxy to Astra (the origin)

This is the Astra-specific part of the setup. Where a migration from a self-managed cluster would give the proxy a list of contact points for the origin, an Astra origin is reached through the Secure Connect Bundle (SCB) and an application token.

For an Astra origin, the username is the literal string token and the password is the Astra application token. The proxy is pointed at the Secure Connect Bundle rather than at contact points. The target is configured the ordinary way, with contact points, port, and credentials for the open-source cluster:

# Origin: Astra DB (via Secure Connect Bundle + application token)
origin_username: "token"
origin_password: "<astra-application-token>"
origin_secure_connect_bundle_path: "/path/to/secure-connect-astra.zip"

# Target: the open-source Apache Cassandra cluster
target_username: "cassandra"
target_password: "<password>"
target_contact_points: "10.0.0.10"
target_port: 9042

primary_cluster: ORIGIN        # reads served from Astra initially
read_mode: PRIMARY_ONLY        # switch to dual/async reads during validation

Leave the application's own Secure Connect Bundle in place for now. It is only retired at cutover, once traffic has moved to the new cluster. Consult the ZDM Proxy configuration reference for the full set of options for the proxy version in use.

The bulk-copy tool also needs the Secure Connect Bundle

CDM (or a Spark job) reads from Astra directly rather than through the proxy, so it also needs the Astra Secure Connect Bundle and an application token to connect to the origin. The target side uses normal contact points and credentials.

Sizing the migration infrastructure

The proxy and the bulk-copy tool run on dedicated migration infrastructure, separate from the target cluster. For a production migration, plan for at least:

• 3 ZDM Proxy instances (the minimum supported for production; a single instance is for local testing only);
• 1 jumphost or monitoring instance; and
• 1 instance to run the bulk-copy tool.

Size the instances against the data volume and throughput.

Prepare the target before deploying the proxy

Dual-writes begin the instant the proxy is deployed, so the target must be ready to accept them.

Create the target schema, roles, and credentials first

If the target keyspaces, tables, roles, permissions, and user passwords are not in place when the proxy starts, writes to the target will fail, and those failures can propagate back to the application. Before deploying the proxy, these steps must be complete:

1. Provision the target Apache Cassandra cluster and confirm every node reports UN (Up/Normal) in nodetool status.
2. Recreate all keyspaces and tables on the target with matching definitions (from the schema exported during assessment).
3. Recreate all roles, permissions, and user passwords. The bulk-copy tooling migrates table data only, not credentials, so these must be created manually.

Building and operating that Apache Cassandra cluster, including automating the install and keeping the nodes' clocks synchronised, is covered in Data Migration.

Relaxing the target write consistency

A useful feature of the AxonOps ZDM Proxy fork is the ability to set the write consistency level for the target independently of what the application requests. An application might write at LOCAL_QUORUM, for example, while the proxy writes to the target at LOCAL_ONE.

This is helpful during a migration. The target is a brand-new cluster, and it commonly undergoes operations that would not be applied to a live database: adding or replacing nodes, running compactions, and restarting for configuration changes. Decoupling the target's write consistency from the application's means that work does not turn a transient target hiccup into a failed write. It also makes dual-writes more tolerant of a slow or briefly unavailable target replica, which is far less likely to fail a write.

Relaxing target consistency is safe here because of how the migration works. During dual-writes, reads are not served from the target, so strong read-your-writes guarantees are not yet required. Any replicas that miss a write at the lower consistency level are reconciled by the full repair run on the target before cutover (see Validation). The approach trades write consistency that is not yet needed during the copy for resilience that is, and the end-of-migration repair restores full consistency before the target takes production reads.

Once the target and tooling are ready, move on to Data Migration.