From 9df9fda50eb19272f1990a07e107bba23069095f Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 20 Nov 2025 08:11:33 -0800 Subject: [PATCH 1/5] revise create target page --- modules/ROOT/nav.adoc | 2 +- modules/ROOT/pages/create-target.adoc | 120 +++++++++--------- .../ROOT/pages/feasibility-checklists.adoc | 42 ++++-- modules/ROOT/pages/introduction.adoc | 49 +++---- 4 files changed, 115 insertions(+), 98 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 1de294e2..7457d69a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -8,7 +8,7 @@ .{product} * xref:ROOT:introduction.adoc[] -* Plan your migration +* Plan and prepare ** xref:ROOT:feasibility-checklists.adoc[] ** xref:ROOT:deployment-infrastructure.adoc[] ** xref:ROOT:create-target.adoc[] diff --git a/modules/ROOT/pages/create-target.adoc b/modules/ROOT/pages/create-target.adoc index 67bc1588..bfa35620 100644 --- a/modules/ROOT/pages/create-target.adoc +++ b/modules/ROOT/pages/create-target.adoc @@ -1,52 +1,56 @@ = Create the target environment -Before you begin your migration, you must create and prepare a new database (cluster) to be the target for your migration. -You must also gather authentication credentials to allow {product-proxy} and your client applications to connect to the new database. +After you review the xref:ROOT:feasibility-checklists.adoc[feasibility checklists] and prepare the xref:ROOT:deployment-infrastructure.adoc[{product-proxy} infrastructure], you must prepare your target cluster for the migration. -== Prepare the target database +This includes the following: -The preparation steps depend on your target database platform. +* Create the new cluster that will be the target of your migration. +* Recreate the schema from your origin cluster on the target cluster. +* Gather authentication credentials and connection details for the target cluster. + +The preparation steps depend on your target platform. + +[IMPORTANT] +==== +For complex migrations, such as those that involve multi-datacenter clusters, many-to-one/one-to-many mappings, or unresolvable mismatched schemas, see the xref:ROOT:feasibility-checklists.adoc#considerations-for-multi-datacenter-clusters-and-other-complex-migrations[considerations for complex migrations]. +==== [tabs] ====== -Use an {astra-db} database as the target:: +Migrate to {astra}:: + -- -To migrate data to an {astra-db} database, do the following: - -. Sign in to your {astra-url}[{astra} account^]. +. Sign in to the {astra-ui-link} and xref:astra-db-serverless:administration:manage-organizations.adoc#switch-organizations[switch to the organization] where you want to create the new database. + -You can use any subscription plan tier. -However, paid subscription plans offer premium features that can facilitate your migration, including support for {sstable-sideloader}, more databases, and no automatic database hibernation. -These plans also support advanced features like customer-managed encryption keys and metrics exports. -For more information, see xref:astra-db-serverless:administration:subscription-plans.adoc[]. +{product-proxy} can be used with any xref:astra-db-serverless:administration:subscription-plans.adoc[{astra} subscription plan]. +However, paid plans offer premium features that can facilitate your migration, including support for {sstable-sideloader}, more databases, and no automatic database hibernation. -. xref:astra-db-serverless:databases:create-database.adoc[Create an {astra-db} Serverless database] with your preferred database name, keyspace name, region, and other details. -+ -The keyspace is a handle that establishes the database's context in subsequent DDL and DML statements. +. xref:astra-db-serverless:databases:create-database.adoc[Create a database] with your preferred database name, cloud provider, region, and other details. + -For multi-region databases, see <>. +All databases start with an initial keyspace. +If the name of this keyspace doesn't match your origin cluster's schema, you can delete the initial keyspace after recreating the schema later in this process. . When your database reaches **Active** status, xref:astra-db-serverless:administration:manage-application-tokens.adoc[create an application token] with a role like *Read/Write User* or **Database Administrator**, and then store the credentials (Client ID, Client Secret, and Token) securely. + -These credentials are used by the client application, {product-proxy}, and {product-automation} to read and write to your target database. +These credentials are used by the client application and {product-proxy} to read and write to your target database. +Make sure the token's role has sufficient permission to perform the actions required by your client application. . xref:astra-db-serverless:databases:secure-connect-bundle.adoc[Download your database's {scb}]. The {scb-short} is a zip file that contains TLS encryption certificates and other metadata required to connect to your database. +It is used during and after the migration process to securely connect to your {astra-db} database. + [IMPORTANT] ==== The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates. Treat it as you would any other sensitive values, such as passwords or tokens. ==== -+ -Your client application uses the {scb-short} to connect directly to {astra-db} near the end of the migration, and {cass-migrator} and {dsbulk-migrator} use the {scb-short} to migrate and validate data in {astra-db}. -. Use `scp` to copy the {scb-short} to your client application instance: +. Use your preferred method to copy the {scb-short} to your client application instance. +For example, you could use `scp`: + [source,bash] ---- -scp -i /path/to/scb.zip @: +scp -i some-key.pem /path/to/scb.zip user@client-ip-or-host: ---- . Recreate your client application's schema on your {astra-db} database, including each keyspace and table that you want to migrate. @@ -54,74 +58,70 @@ scp -i /path/to/scb.zip @>. ==== -.. Recommended: Consider testing your new cluster to ensure it meets your performance requirements, and then tune it as necessary before beginning the migration. -. If you enabled authentication, create a user with the required permissions for your client application to use to read and write to the cluster. +. Recommended: Consider testing your new cluster to ensure it meets your performance requirements, and then tune it as necessary before beginning the migration. -. Recreate your client application's schema on your new cluster, including each keyspace and table that you want to migrate. +. If you enabled authentication in your cluster, create a user with the required permissions for your client application to use to read and write to the cluster. ++ +Store the authentication credentials securely for use by your client application and {product-proxy} later in the migration process. + +. Note your cluster's connection details, including the contact points (IP addresses or hostnames) and port number. + +. Recreate your origin cluster's schema on your new cluster, including each keyspace and table that you want to migrate. + [IMPORTANT] ==== -On your new cluster, the keyspace names, table names, column names, data types, and primary keys must match the schema on the origin cluster, or the migration will fail. +On your new cluster, the keyspace names, table names, column names, data types, and primary keys must be identical to the schema on the origin cluster or the migration will fail. ==== + -To copy the schema, you can run CQL `describe` on the origin cluster to get the schema that is being migrated, and then run the output on your new cluster. +To copy the schema, you can run CQL `DESCRIBE` on the origin cluster to get the schema that is being migrated, and then run the output on your new cluster. +Alternatively, you can use the `generate-ddl` functionality in the {dsbulk-migrator-repo}[{dsbulk-migrator}]. + -If you are migrating from an old version, you might need to edit CQL clauses that are no longer supported in newer versions, such as `COMPACT STORAGE`. -For specific changes in each version, see your driver's changelog or release notes. +If your origin cluster is running an earlier version, you might need to edit CQL clauses that are no longer supported in newer versions, such as `COMPACT STORAGE`. +For specific changes in each version, see the release notes for your database platform and {cass-short} driver. -- -====== -[#considerations-for-multi-region-migrations] -== Considerations for multi-region migrations +Other CQL-compatible data stores:: ++ +-- +Support for other CQL-compatible data stores isn't guaranteed for {product-proxy}. -include::ROOT:partial$multi-region-migrations.adoc[] +If your origin and target clusters meet the protocol version requirements described in the xref:ROOT:feasibility-checklists.adoc[feasibility checklists], you might be able to use {product-proxy} for your migration. +As with any migration, {company} recommends that you test this in isolation before attempting a full-scale production migration. -== Next steps +See your data store provider's documentation for information about creating your cluster and schema, generating authentication credentials, and gathering the connection details. +-- +====== -Learn about xref:ROOT:rollback.adoc[rollback options] before you begin Phase 1 of the migration process. \ No newline at end of file +Next, learn about xref:ROOT:rollback.adoc[rollback options] before you begin xref:ROOT:phase1.adoc[Phase 1] of the migration process. \ No newline at end of file diff --git a/modules/ROOT/pages/feasibility-checklists.adoc b/modules/ROOT/pages/feasibility-checklists.adoc index 29db369c..d92551e7 100644 --- a/modules/ROOT/pages/feasibility-checklists.adoc +++ b/modules/ROOT/pages/feasibility-checklists.adoc @@ -1,10 +1,11 @@ = Feasibility checks :page-aliases: ROOT:preliminary-steps.adoc -Before starting your migration, review the following information to ensure that your client application workload and origin (source) cluster are suitable for the {product} process. +True zero downtime migration with {product-proxy} is possible only if your clusters, data model, and application logic meet the compatibility requirements described on this page. -True zero downtime migration is only possible if your database meets the minimum requirements described on this page. -If your database doesn't meet these requirements, you can still complete the migration, but downtime might be necessary to finish the migration. +You might need to adjust your data model or application logic to ensure compatibility between the origin and target clusters during the migration and ongoing compatibility with the target cluster after the migration. + +If you cannot meet these requirements, particularly the cluster and schema compatibility requirements, see xref:ROOT:components.adoc[] for alternative migration tools and strategies. == {cass-short} Native Protocol version and cluster version support @@ -13,11 +14,11 @@ If your database doesn't meet these requirements, you can still complete the mig //TODO: V5 status: https://github.com/datastax/zdm-proxy/blob/main/faq.md#what-versions-of-apache-cassandra-or-cql-compatible-data-stores-does-the-zdm-proxy-support {product-proxy} technically doesn't support `v5`. If `v5` is requested, the proxy handles protocol negotiation so that the client application properly downgrades the protocol version to `v4`. -This means that any client application using a recent driver that supports protocol version `v5`can be migrated using{product-proxy} as long as the application doesn't use v5-specific functionality. +This means that you can use {product-proxy} with any client application that uses a driver version supporting protocol version `v5`, as long as the application doesn't use v5-specific functionality. -=== Thrift is not supported by {product-proxy} +=== Thrift isn't supported by {product-proxy} -If you are using a very old driver or cluster version that only supports Thrift, you need to change your client application to use CQL and potentially upgrade your cluster before starting the migration process. +If you are using an earlier driver or cluster version that only supports Thrift, you must change your client application to use CQL, and, if needed, upgrade your cluster before starting the migration process. === Supported cluster versions and migration paths @@ -39,17 +40,24 @@ TODO: Need to verify as these are in conflict with other information in this gui * {astra-db}. See also: https://github.com/datastax/zdm-proxy/blob/main/faq.md#what-versions-of-apache-cassandra-or-cql-compatible-data-stores-does-the-zdm-proxy-support +"Other CQL-compatible data stores might be compatible targets with {product-proxy}, but {company} doesn't test all possible targets." //// [TIP] ==== -Before you begin the migration process, test directly connecting your client application to your target cluster, without {product-proxy}. +Before you begin the migration process, try directly connecting your client application to your target cluster without {product-proxy}. This ensures that you know the connection will work when you disconnect {product-proxy} at the end of the migration. ==== == Schema/keyspace compatibility -{product-proxy} does not modify or transform CQL statements besides the optional feature that replaces `now()` functions with timestamp literals. +[IMPORTANT] +==== +To successfully migrate with {product-proxy}, the origin and target clusters must have matching schemas, including keyspace names, table names, column names, and data types. +A CQL statement produced by your client application must be able to succeed _without modification_ on both clusters because {product-proxy} routes the exact same CQL statements to both clusters. +==== + +{product-proxy} does not modify or transform CQL statements besides the optional feature that can replace `now()` functions with timestamp literals. See <> for more information about this feature. A CQL statement that your client application sends to {product-proxy} must be able to succeed on both clusters. @@ -90,11 +98,6 @@ If you are migrating to {astra} from an origin cluster that uses any of these AP Before you migrate, you must change your applications to use other programmatic access, such as {cass-short} drivers or the {data-api}. For more information, see xref:astra-db-serverless:api-reference:compare-dataapi-to-stargate.adoc[]. -=== Multi-region and multi-node {astra} migrations - -If your migration involves multi-region or multi-node clusters, plan your strategy for migrating and replicating data to the different regions. -For more information, see the xref:sideloader:prepare-sideloader.adoc#additional-preparation-for-specific-migration-scenarios[{sstable-sideloader} preparations for specific migration scenarios] and the xref:ROOT:deployment-infrastructure.adoc[{product-proxy} infrastructure guidelines for multi-datacenter clusters]. - [[_read_only_applications]] === Read-only applications @@ -232,6 +235,8 @@ This approach means the queries are regular CQL `SELECT` statements, so {product + If you use the HTTP API then you can either modify your applications to use the CQL API instead or you will have to move those applications directly from the origin to the target when the migration is complete if that is acceptable. +For more {dse-short}-specific migration considerations, see xref:6.9@dse:managing:operations/migrate-data.adoc[]. + == Client compression The binary protocol used by {cass-short}, {dse-short}, {hcd-short}, and {astra-db} supports optional compression of transport-level requests and responses that reduces network traffic at the cost of CPU overhead. @@ -259,6 +264,17 @@ In contrast, a cluster's _authenticator_ must be compatible with {product-proxy} The origin and target clusters can have different authentication configurations because {product-proxy} treats them independently. +[#considerations-for-multi-datacenter-clusters-and-other-complex-migrations] +== Considerations for multi-datacenter clusters and other complex migrations + +Complex migration scenarios, such as multi-datacenter migrations or many-to-one migrations, require additional planning to configure {product-proxy} and migrate the data efficiently. + +include::ROOT:partial$multi-region-migrations.adoc[] + +To configure {product-proxy} for a multi-datacenter migration, see the xref:ROOT:deployment-infrastructure.adoc[{product-proxy} infrastructure guidelines for multi-datacenter clusters]. + +For more guidance on migrations to {astra}, see the xref:sideloader:prepare-sideloader.adoc#additional-preparation-for-specific-migration-scenarios[{sstable-sideloader} preparations for specific migration scenarios]. + == Next steps Next, xref:ROOT:deployment-infrastructure.adoc[prepare the {product-proxy} infrastructure]. \ No newline at end of file diff --git a/modules/ROOT/pages/introduction.adoc b/modules/ROOT/pages/introduction.adoc index aa612ed0..e0a7a678 100644 --- a/modules/ROOT/pages/introduction.adoc +++ b/modules/ROOT/pages/introduction.adoc @@ -2,7 +2,7 @@ :navtitle: About the {product-short} process :description: Before you begin, learn about migration concepts, software components, and the sequence of operations. -With {product}, your applications can continue to run while you migrate data from one {cass-short}-based database to another, resulting in little or no downtime and minimal service interruptions. +With the {product} ({product-short}) process, your applications can continue to run while you migrate data from one {cass-short}-based database to another, resulting in little or no downtime and minimal service interruptions. .Why migrate? [%collapsible] @@ -20,53 +20,54 @@ For example, you might move from self-managed clusters to a cloud-based Database * You want to consolidate client applications running on separate clusters onto one shared cluster to minimize sprawl and maintenance. ==== -{product-short} is comprised of {product-proxy}, {product-utility}, and {product-automation}, which orchestrate activity-in-transition on your databases. -To move and validate data, you use {sstable-sideloader}, {cass-migrator}, or {dsbulk-migrator}. -{product-proxy} keeps your databases in sync at all times by the dual-writes feature, which means you can stop the migration or xref:rollback.adoc[roll back] at any point. +The {product-short} process uses {product-proxy}, {product-utility}, and {product-automation} to orchestrate live reads and writes on your databases while you move and validate data with a data migration tool, such as {sstable-sideloader}, {cass-migrator}, or {dsbulk-migrator}. + +{product-proxy} keeps your databases in sync at all times through its dual-writes feature, which means you can seamlessly stop or abandon the migration at any point before the last phase of the migration (the final cutover to the new database). For more information about these tools, see xref:ROOT:components.adoc[]. -When the migration is complete, the data is present in the new database, and you can update your client applications to connect exclusively to the new database. -The old database becomes obsolete and can be removed. +When the migration is complete, all data is present in the new database, and you can switch your client applications to connect exclusively to the new database. +The old database becomes obsolete and can be shut down. == Requirements for zero downtime -True zero downtime migration is only possible if your database meets the minimum requirements, including cluster compatibility, described in xref:ROOT:feasibility-checklists.adoc[] -If your database doesn't meet these requirements, you can still complete the migration, but downtime might be necessary to finish the migration. - -For more information, see xref:ROOT:feasibility-checklists.adoc[] +True zero downtime migration with {product-proxy} is only possible if your database meets the minimum requirements, including cluster compatibility, that are described in xref:ROOT:feasibility-checklists.adoc[] +If your database doesn't meet these requirements, you can still complete the migration, but you might not be able to use {product-proxy} and some downtime might be necessary to finish the migration. == Migration phases A migration project includes preparation for the migration and five migration phases. -The following sections describe the major events in each phase and how your client applications perform read and write operations on your origin and target databases during each phase. +The following sections describe the major events in each phase and how your client applications connect to your origin cluster, {product-proxy}, and the target cluster during each phase. -The _origin_ is is your existing {cass-short}-based environment, which can be {cass}, {dse-short}, or {astra-db}. -The _target_ is your new {cass-short}-based environment where you want to migrate your data and client applications. +The _origin cluster_ is is your existing {cass-short}-based environment, such as {dse-short} or open-source {cass}. +The _target cluster_ is your new {cass-short}-based environment where you want to migrate your data and client applications. -=== Migration planning +=== Plan and prepare for your migration -Before you begin a migration, your client applications perform read/write operations with your existing xref:cql:ROOT:index.adoc[CQL]-compatible database, such as {cass}, {dse-short}, {hcd-short}, or {astra-db}. +From a functional standpoint, before you begin a migration, your client applications perform read/write operations directly with your existing xref:cql:ROOT:index.adoc[CQL]-compatible database, such as {cass}, {dse-short}, {hcd-short}, or {astra-db}. +Over the course of the migration, the contact points change to incorporate {product-proxy} and eventually switch to the target database. image:pre-migration0ra.png[Before the migration begins, your applications connect exclusively to your origin cluster] -While your application is stable with the current data model and database platform, you might need to make some adjustments before enabling {product-proxy}. +To plan and prepare for the migration, do the following: +. xref:ROOT:feasibility-checklists.adoc[]: Review compatibility requirements for {product-proxy}, and understand how certain operations are handled by {product-proxy}. ++ [IMPORTANT] ==== -For the migration to succeed, the origin and target databases must have matching schemas, including keyspace names, table names, column names, and data types. +To successfully migrate with {product-proxy}, a read or write request produced by your client application must be able to succeed _without modification_ on both your origin (existing) and target (new) clusters. +This means that the origin and target clusters must have matching schemas, including keyspace names, table names, column names, and data types. -A CQL statement that your client application sends to {product-proxy} must be able to succeed on both databases. +You might need to adjust your data model or application logic to ensure compatibility between the two clusters during the migration and ongoing compatibility with the target cluster after the migration. -For more information, see xref:feasibility-checklists.adoc#_schemakeyspace_compatibility[Schema/keyspace compatibility]. +For more information, see xref:feasibility-checklists.adoc[]. ==== -Before you begin the migration, plan and prepare for the migration by setting up your target infrastructure, reviewing compatibility requirements for {product-proxy}, and understanding when you can rollback the migration if necessary: +. xref:ROOT:deployment-infrastructure.adoc[]: Set up the infrastructure to host the {product-short} tools. + +. xref:ROOT:create-target.adoc[]: Set up your target cluster, and create schemas that match those on your origin cluster. -* xref:ROOT:feasibility-checklists.adoc[] -* xref:ROOT:deployment-infrastructure.adoc[] -* xref:ROOT:create-target.adoc[] -* xref:ROOT:rollback.adoc[] +. xref:ROOT:rollback.adoc[]: Learn when and how you can stop or rollback an in-progress migration. === Phase 1: Deploy {product-proxy} and connect client applications From 825410ab22e456429a8ebc28724974270cf74315 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 20 Nov 2025 08:50:04 -0800 Subject: [PATCH 2/5] start feasibility checks --- modules/ROOT/pages/create-target.adoc | 10 ++++++++-- modules/ROOT/pages/deploy-proxy-monitoring.adoc | 2 +- .../ROOT/pages/deployment-infrastructure.adoc | 1 + modules/ROOT/pages/feasibility-checklists.adoc | 17 ++++++----------- modules/ROOT/pages/introduction.adoc | 8 +++----- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/create-target.adoc b/modules/ROOT/pages/create-target.adoc index bfa35620..51ff9b3a 100644 --- a/modules/ROOT/pages/create-target.adoc +++ b/modules/ROOT/pages/create-target.adoc @@ -1,6 +1,6 @@ = Create the target environment -After you review the xref:ROOT:feasibility-checklists.adoc[feasibility checklists] and prepare the xref:ROOT:deployment-infrastructure.adoc[{product-proxy} infrastructure], you must prepare your target cluster for the migration. +After you review the xref:ROOT:feasibility-checklists.adoc[compatibility requirements] and prepare the xref:ROOT:deployment-infrastructure.adoc[{product-proxy} infrastructure], you must prepare your target cluster for the migration. This includes the following: @@ -117,11 +117,17 @@ Other CQL-compatible data stores:: -- Support for other CQL-compatible data stores isn't guaranteed for {product-proxy}. -If your origin and target clusters meet the protocol version requirements described in the xref:ROOT:feasibility-checklists.adoc[feasibility checklists], you might be able to use {product-proxy} for your migration. +If your origin and target clusters meet the xref:ROOT:feasibility-checklists.adoc[protocol version compatibility requirements], you might be able to use {product-proxy} for your migration. As with any migration, {company} recommends that you test this in isolation before attempting a full-scale production migration. See your data store provider's documentation for information about creating your cluster and schema, generating authentication credentials, and gathering the connection details. -- ====== +[TIP] +==== +Before you begin the migration process, try connecting your client application directly to your target cluster without {product-proxy}. +This ensures that the connection will work when you disconnect {product-proxy} at the end of the migration. +==== + Next, learn about xref:ROOT:rollback.adoc[rollback options] before you begin xref:ROOT:phase1.adoc[Phase 1] of the migration process. \ No newline at end of file diff --git a/modules/ROOT/pages/deploy-proxy-monitoring.adoc b/modules/ROOT/pages/deploy-proxy-monitoring.adoc index 6dde98ce..e8905d2e 100644 --- a/modules/ROOT/pages/deploy-proxy-monitoring.adoc +++ b/modules/ROOT/pages/deploy-proxy-monitoring.adoc @@ -175,7 +175,7 @@ For more information, see xref:manage-proxy-instances.adoc[]. ==== Multi-datacenter clusters -For xref:ROOT:feasibility-checklists.adoc[multi-datacenter origin clusters], specify the name of the datacenter that {product-proxy} should consider local. +For xref:ROOT:deployment-infrastructure.adoc#multiple-datacenter-clusters[multi-datacenter origin clusters], specify the name of the datacenter that {product-proxy} should consider local. To do this, set the `origin_local_datacenter` property to the local datacenter name. Similarly, for multi-datacenter target clusters, set the `target_local_datacenter` property to the local datacenter name. These two variables are stored in `vars/zdm_proxy_advanced_config.yml`. diff --git a/modules/ROOT/pages/deployment-infrastructure.adoc b/modules/ROOT/pages/deployment-infrastructure.adoc index 02aac877..64add96f 100644 --- a/modules/ROOT/pages/deployment-infrastructure.adoc +++ b/modules/ROOT/pages/deployment-infrastructure.adoc @@ -18,6 +18,7 @@ The following diagram shows a typical deployment with connectivity between clien image::zdm-during-migration3.png[Connectivity between client applications, proxy instances, and clusters.] +[#multiple-datacenter-clusters] === Multiple datacenter clusters If you have a multi-datacenter cluster with multiple set of client application instances deployed to geographically distributed datacenters, you must plan a separate {product-proxy} deployment for each datacenter. diff --git a/modules/ROOT/pages/feasibility-checklists.adoc b/modules/ROOT/pages/feasibility-checklists.adoc index d92551e7..f8677908 100644 --- a/modules/ROOT/pages/feasibility-checklists.adoc +++ b/modules/ROOT/pages/feasibility-checklists.adoc @@ -1,4 +1,5 @@ -= Feasibility checks += Compatibility requirements for {product-proxy} +:navtitle: Compatibility requirements :page-aliases: ROOT:preliminary-steps.adoc True zero downtime migration with {product-proxy} is possible only if your clusters, data model, and application logic meet the compatibility requirements described on this page. @@ -7,20 +8,20 @@ You might need to adjust your data model or application logic to ensure compatib If you cannot meet these requirements, particularly the cluster and schema compatibility requirements, see xref:ROOT:components.adoc[] for alternative migration tools and strategies. -== {cass-short} Native Protocol version and cluster version support +== Supported {cass-short} Native Protocol versions {product-proxy} supports protocol versions `v3`, `v4`, `DSE_V1`, and `DSE_V2`. //TODO: V5 status: https://github.com/datastax/zdm-proxy/blob/main/faq.md#what-versions-of-apache-cassandra-or-cql-compatible-data-stores-does-the-zdm-proxy-support {product-proxy} technically doesn't support `v5`. If `v5` is requested, the proxy handles protocol negotiation so that the client application properly downgrades the protocol version to `v4`. -This means that you can use {product-proxy} with any client application that uses a driver version supporting protocol version `v5`, as long as the application doesn't use v5-specific functionality. +This means that you can use {product-proxy} with any client application that uses a driver version supporting protocol version `v5`, as long as the application doesn't use `v5`-specific functionality. === Thrift isn't supported by {product-proxy} If you are using an earlier driver or cluster version that only supports Thrift, you must change your client application to use CQL, and, if needed, upgrade your cluster before starting the migration process. -=== Supported cluster versions and migration paths +== Supported data store providers, versions, and migration paths include::ROOT:partial$migration-scenarios.adoc[] @@ -43,12 +44,6 @@ See also: https://github.com/datastax/zdm-proxy/blob/main/faq.md#what-versions-o "Other CQL-compatible data stores might be compatible targets with {product-proxy}, but {company} doesn't test all possible targets." //// -[TIP] -==== -Before you begin the migration process, try directly connecting your client application to your target cluster without {product-proxy}. -This ensures that you know the connection will work when you disconnect {product-proxy} at the end of the migration. -==== - == Schema/keyspace compatibility [IMPORTANT] @@ -74,7 +69,7 @@ For example, if your compound primary key is `PRIMARY KEY (A, B)` and you always See xref:ROOT:components.adoc#how-zdm-proxy-handles-reads-and-writes[How {product-proxy} handles reads and writes]. -== Considerations for {astra-db} migrations +== Considerations for {astra} migrations {astra-db} implements guardrails and sets limits to ensure good practices, foster availability, and promote optimal configurations for your databases. Check the list of xref:astra-db-serverless:databases:database-limits.adoc[guardrails and limits] to make sure that your application workload can be successful within these limits. diff --git a/modules/ROOT/pages/introduction.adoc b/modules/ROOT/pages/introduction.adoc index e0a7a678..753dedd5 100644 --- a/modules/ROOT/pages/introduction.adoc +++ b/modules/ROOT/pages/introduction.adoc @@ -40,6 +40,7 @@ A migration project includes preparation for the migration and five migration ph The following sections describe the major events in each phase and how your client applications connect to your origin cluster, {product-proxy}, and the target cluster during each phase. The _origin cluster_ is is your existing {cass-short}-based environment, such as {dse-short} or open-source {cass}. + The _target cluster_ is your new {cass-short}-based environment where you want to migrate your data and client applications. === Plan and prepare for your migration @@ -51,16 +52,13 @@ image:pre-migration0ra.png[Before the migration begins, your applications connec To plan and prepare for the migration, do the following: -. xref:ROOT:feasibility-checklists.adoc[]: Review compatibility requirements for {product-proxy}, and understand how certain operations are handled by {product-proxy}. +. xref:ROOT:feasibility-checklists.adoc[Review compatibility requirements for {product-proxy}]: Make sure your clusters, data model, and application logic are compatible with {product-proxy}, and understand how certain operations are handled by {product-proxy}. +If needed, adjust your data model or application logic to ensure compatibility between the two clusters during the migration and ongoing compatibility with the target cluster after the migration. + [IMPORTANT] ==== To successfully migrate with {product-proxy}, a read or write request produced by your client application must be able to succeed _without modification_ on both your origin (existing) and target (new) clusters. This means that the origin and target clusters must have matching schemas, including keyspace names, table names, column names, and data types. - -You might need to adjust your data model or application logic to ensure compatibility between the two clusters during the migration and ongoing compatibility with the target cluster after the migration. - -For more information, see xref:feasibility-checklists.adoc[]. ==== . xref:ROOT:deployment-infrastructure.adoc[]: Set up the infrastructure to host the {product-short} tools. From 81a211c84b00d2db42106380dee2b6129911a964 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 20 Nov 2025 14:45:15 -0800 Subject: [PATCH 3/5] feasibility checks page --- modules/ROOT/pages/create-target.adoc | 11 +- .../ROOT/pages/feasibility-checklists.adoc | 244 +++++++++--------- .../ROOT/pages/zdm-proxy-migration-paths.adoc | 6 - .../ROOT/partials/migration-scenarios.adoc | 35 ++- 4 files changed, 152 insertions(+), 144 deletions(-) diff --git a/modules/ROOT/pages/create-target.adoc b/modules/ROOT/pages/create-target.adoc index 51ff9b3a..ef2593a4 100644 --- a/modules/ROOT/pages/create-target.adoc +++ b/modules/ROOT/pages/create-target.adoc @@ -12,7 +12,7 @@ The preparation steps depend on your target platform. [IMPORTANT] ==== -For complex migrations, such as those that involve multi-datacenter clusters, many-to-one/one-to-many mappings, or unresolvable mismatched schemas, see the xref:ROOT:feasibility-checklists.adoc#considerations-for-multi-datacenter-clusters-and-other-complex-migrations[considerations for complex migrations]. +For complex migrations, such as those that involve multi-datacenter clusters, many-to-one/one-to-many mappings, or unresolvable mismatched schemas, see the xref:ROOT:feasibility-checklists.adoc#multi-datacenter-clusters-and-other-complex-migrations[considerations for complex migrations]. ==== [tabs] @@ -126,8 +126,15 @@ See your data store provider's documentation for information about creating your [TIP] ==== -Before you begin the migration process, try connecting your client application directly to your target cluster without {product-proxy}. +After you create the target cluster, try connecting your client application directly to the target cluster without {product-proxy}. This ensures that the connection will work when you disconnect {product-proxy} at the end of the migration. + +Additionally, {company} recommends running performance tests and measuring benchmarks in a test environment where your client application is connected directly to your target cluster. +This helps you understand how your application workloads will perform on the new cluster. +This is particularly valuable when migrating to a new platform, such as {dse-short} to {astra}, where you might be unfamiliar with the platform's performance characteristics. + +Depending on the results of your tests, you might need to adjust your application logic, data model, or cluster configuration to achieve your performance goals. +For example, you might need to optimize queries to avoid anti-patterns that were acceptable on your origin cluster but degrade performance on the target cluster. ==== Next, learn about xref:ROOT:rollback.adoc[rollback options] before you begin xref:ROOT:phase1.adoc[Phase 1] of the migration process. \ No newline at end of file diff --git a/modules/ROOT/pages/feasibility-checklists.adoc b/modules/ROOT/pages/feasibility-checklists.adoc index f8677908..24f1ee74 100644 --- a/modules/ROOT/pages/feasibility-checklists.adoc +++ b/modules/ROOT/pages/feasibility-checklists.adoc @@ -12,7 +12,6 @@ If you cannot meet these requirements, particularly the cluster and schema compa {product-proxy} supports protocol versions `v3`, `v4`, `DSE_V1`, and `DSE_V2`. -//TODO: V5 status: https://github.com/datastax/zdm-proxy/blob/main/faq.md#what-versions-of-apache-cassandra-or-cql-compatible-data-stores-does-the-zdm-proxy-support {product-proxy} technically doesn't support `v5`. If `v5` is requested, the proxy handles protocol negotiation so that the client application properly downgrades the protocol version to `v4`. This means that you can use {product-proxy} with any client application that uses a driver version supporting protocol version `v5`, as long as the application doesn't use `v5`-specific functionality. @@ -25,105 +24,55 @@ If you are using an earlier driver or cluster version that only supports Thrift, include::ROOT:partial$migration-scenarios.adoc[] -//// -TODO: Need to verify as these are in conflict with other information in this guide: - -{product-proxy} supports migrations to and from the following cluster versions: - -* {cass-reg} 2.1 and later, including {cass-short} 4.x. -+ -{cass-short} 2.0 migration support may be introduced when protocol version v2 is supported. - -* {dse} 4.7.1 and later. -+ -{dse-short} 4.6 migration support may be introduced when protocol version v2 is supported. - -* {astra-db}. - -See also: https://github.com/datastax/zdm-proxy/blob/main/faq.md#what-versions-of-apache-cassandra-or-cql-compatible-data-stores-does-the-zdm-proxy-support -"Other CQL-compatible data stores might be compatible targets with {product-proxy}, but {company} doesn't test all possible targets." -//// - -== Schema/keyspace compatibility +== Schema and keyspace alignment [IMPORTANT] ==== To successfully migrate with {product-proxy}, the origin and target clusters must have matching schemas, including keyspace names, table names, column names, and data types. A CQL statement produced by your client application must be able to succeed _without modification_ on both clusters because {product-proxy} routes the exact same CQL statements to both clusters. + +Even without {product-proxy}, matching schemas are required for most CQL-based data migration tools, such as {sstable-sideloader} and {cass-migrator}. +If it is impossible to match the schemas, your migration cannot use {product-proxy}. +See xref:ROOT:components.adoc[] for alternative migration tools and strategies, such as extract, transform, and load (ETL) processes. ==== -{product-proxy} does not modify or transform CQL statements besides the optional feature that can replace `now()` functions with timestamp literals. -See <> for more information about this feature. +{product-proxy} _doesn't_ modify or transform CQL statements with the exception of <>. A CQL statement that your client application sends to {product-proxy} must be able to succeed on both clusters. -This means that any keyspace that your client application uses must exist on both the origin and target clusters with the same name (although they can have different replication strategies and durable writes settings). -Table names must also match. +This means that any keyspace that your client application uses must exist on both the origin and target clusters with the same keyspace name, table names, column names, and compatible data types. +However, the keyspaces can have different replication strategies and durable write settings. -The schema doesn't have to be an exact match as long as the CQL statements can be executed successfully on both clusters. -For example, if a table has 10 columns but your client application only uses 5 of those columns then you could create that table on the target with just those 5 columns. +At the column level, the schema doesn't need to be a one-to-one match as long as the CQL statements can be executed successfully on both clusters. +For example, if a table has 10 columns, and your client application uses only five of those columns, then you can recreate the table on the target cluster with only the five required columns. +However, the data from the other columns won't be migrated to the target cluster if those columns don't exist on the target cluster. +Before you decide to omit a column from the target cluster, make sure that it is acceptable to permanently lose that data after the migration. -You can also change the primary key in some cases. -For example, if your compound primary key is `PRIMARY KEY (A, B)` and you always provide parameters for the `A` and `B` columns in your CQL statements then you could change the key to `PRIMARY KEY (B, A)` when creating the schema on the target because your CQL statements will still run successfully. +In some cases, you can change the primary key on the target cluster. +For example, if your compound primary key is `PRIMARY KEY (A, B)`, and you always provide parameters for the `A` and `B` columns in your CQL statements, then you could change the key to `PRIMARY KEY (B, A)` when creating the schema on the target because your CQL statements will still run successfully. -== Request and error handling expectations with {product-proxy} +== Request and error handling with {product-proxy} See xref:ROOT:components.adoc#how-zdm-proxy-handles-reads-and-writes[How {product-proxy} handles reads and writes]. -== Considerations for {astra} migrations - -{astra-db} implements guardrails and sets limits to ensure good practices, foster availability, and promote optimal configurations for your databases. -Check the list of xref:astra-db-serverless:databases:database-limits.adoc[guardrails and limits] to make sure that your application workload can be successful within these limits. - -If you need to make changes to the application or data model to ensure that your workload can run successfully in {astra-db}, then you need to do these changes before you start the migration process. - -It is also highly recommended to perform tests and benchmarks when connected directly to {astra-db} prior to the migration, so that you don't find unexpected issues during the migration process. - -=== {astra} doesn't support CL.ONE - -`CL.ONE` isn't supported by {astra}, and read and write requests sent through {product-proxy} with `CL.ONE` to {astra-db} databases always fail. - -{product-proxy} doesn't mute these failures because you need to be aware of them. -You must adapt your client application to use a consistency level that is supported by both clusters to ensure that the migration is seamless and error-free. - -=== {astra} doesn't support the Stargate APIs - -The Stargate APIs (Document, REST, GraphQL, gRPC) are deprecated for {astra}. - -If you are migrating to {astra} from an origin cluster that uses any of these APIs, your client applications won't work with {astra}. -Before you migrate, you must change your applications to use other programmatic access, such as {cass-short} drivers or the {data-api}. -For more information, see xref:astra-db-serverless:api-reference:compare-dataapi-to-stargate.adoc[]. - -[[_read_only_applications]] -=== Read-only applications - -In versions 2.1.0 and later, {product-proxy} sends periodic heartbeats to keep idle cluster connections alive. -The default interval is 30,000 milliseconds, and it can be configured with the `xref:ROOT:manage-proxy-instances.adoc#change-mutable-config-variable[heartbeat_interval_ms]` variable, or by directly setting the `ZDM_HEARTBEAT_INTERVAL_MS` environment variable if you aren't using {product-automation}. - -In {product-proxy} versions earlier than 2.1.0, read-only applications require special handling to avoid connection termination due to inactivity. - -{company} recommends that you use {product-proxy} version 2.1.0 or later to benefit from the heartbeat feature. -If you cannot use version 2.1.0 or later, see the alternatives described in xref:ROOT:troubleshooting-tips.adoc#client-application-closed-connection-errors-every-10-minutes-when-migrating-to-astra-db[Client application closed connection errors every 10 minutes when migrating to {astra-db}]. - [[non-idempotent-operations]] == Lightweight Transactions and other non-idempotent operations -Examples of non-idempotent operations in CQL are: +Non-idempotent CQL operations don't produce the exact same result each time the request is executed. +Whether the request is executed and the actual value written to the database depend on the column's current value or other conditions at the time of the request. +Examples of non-idempotent operations include the following: -* Lightweight Transactions (LWTs) (see <<_lightweight_transactions_and_the_applied_flag>>) +* Conditional writes and Lightweight Transactions (LWTs) (see <<_lightweight_transactions_and_the_applied_flag>>) * Counter updates * Collection updates with `+=` and `-=` operators * Non-deterministic functions like `now()` and `uuid()` (see <>) -Given that there are two separate clusters involved, the state of each cluster can be different. -For conditional writes, this can create a temporary divergent state. - -If you use non-idempotent operations, {company} recommends adding a reconciliation phase to your migration before and after Phase 4 (where you switch reads to the target). -This allows you additional opportunities to resolve any data inconsistencies that are produced by non-idempotent operations. +By design, a {product-short} migration involves two separate clusters, and it is possible for the clusters to have differences due to non-idempotent operations. -The {cass-migrator} is ideal for detecting and reconciling these types of inconsistencies. -For more information, see xref:migrate-and-validate-data.adoc[]. +If you use non-idempotent operations, {company} recommends adding a reconciliation phase to your migration before and after xref:ROOT:change-read-routing.adoc[Phase 4]. +This allows you an additional opportunity to resolve any data inconsistencies that are produced by non-idempotent operations. +The xref:ROOT:cassandra-data-migrator.adoc[{cass-migrator}] is ideal for detecting and reconciling these types of inconsistencies. -If your application workloads can tolerate inconsistencies produced by LWTs and non-idempotent operations, you might not need to perform any additional validation or reconciliation steps. +However, if your application workloads can tolerate inconsistencies produced by LWTs and non-idempotent operations, you might not need to perform any additional validation or reconciliation steps. This depends entirely on your application business logic and requirements. It is your responsibility to determine whether your workloads can tolerate these inconsistencies and to what extent. @@ -140,30 +89,38 @@ For conditional writes, this may create a divergent state for a time. It may not make a difference in many cases, but if Lightweight Transactions are used, we would recommend a reconciliation phase in the migration before switching reads to rely on the TARGET cluster. //// -{product-proxy} handles LWTs as write operations. -The proxy sends the LWT to the origin and target clusters concurrently, and then waits for a response from both. -{product-proxy} will return a `success` status to the client if both the origin and target send successful acknowledgements. -Otherwise, it will return a `failure` status if one or both do not return an acknowledgement. +{product-proxy} handles LWTs in the same way as other xref:ROOT:components.adoc#how-zdm-proxy-handles-reads-and-writes[write requests]: It sends the request to both clusters concurrently, and then it waits for both to respond. +{product-proxy} returns a `success` status to the client _only_ if both clusters send successful acknowledgements; otherwise, it returns a `failure` status. -What sets LWTs apart from regular writes is that they are conditional. -In other words, a LWT can appear to have been successful (its execution worked as expected). -However, the change will be applied only if the LWT's condition was met. -Whether the condition was met depends on the state of the data on the cluster. -In a migration, the clusters will not be in sync until all existing data has been imported into the target. -Up to that point, an LWT's condition can be evaluated differently on each side, leading to a different outcome even though the LWT was technically successful on both sides. +However, clusters can consider an LWT to be successful with or without data modification, because LWTs modify data only if a specific condition is met, and they don't fail if the condition isn't met. +With {product-proxy}, this means both clusters can return successful acknowledgements with _different outcomes on each cluster_. +This is because the evaluation of an LWT's condition is based on the state of the data on the cluster at the time of the request. +For example, if the condition is met on the origin cluster but not on the target cluster, then the data is modified on the origin cluster only. -The response that a cluster sends after executing a LWT includes a flag called `applied`. -This flag tells the client whether the LWT update was actually applied. -The status depends on the condition, which in turn depends on the state of the data. -When {product-proxy} receives a response from both the origin and target, each response would have its own `applied` flag. +If your application logic includes LWTs, you must reconcile any inconsistences caused by LWTs, and understand how the `applied` flag is handled by {product-proxy}: -However, {product-proxy} can only return a *single response* to the client. -Recall that the client has no knowledge that there are two clusters behind the proxy. -Therefore, {product-proxy} returns the `applied` flag from the cluster that is *currently used as primary*. -If your client has logic that depends on the `applied` flag, be aware that during the migration, you will only have visibility of the flag coming from the primary cluster; that is, the cluster to which synchronous reads are routed. +Repeatedly validate and reconcile data to catch all inconsistencies:: +During the {product-short} process, the clusters aren't fully synchronized until the data has been completely replicated and thoroughly validated at the end of xref:ROOT:migrate-and-validate-data.adoc[Phase 2]. +Up to that point, LWTs can produce inconsistent data that you must reconcile at the end of Phase 2. +Furthermore, because {product-proxy} is designed to continuously route writes to both clusters, you might need to validate and reconcile the data multiple times to catch additional inconsistencies that occurred while you were reconciling previous inconsistencies. -To reiterate, {product-proxy} only returns the `applied` value from the primary cluster, which is the cluster from where read results are returned to the client application. By default, this is the origin cluster. -This means that when you set the target cluster as your primary cluster, then the `applied` value returned to the client application will come from the target cluster. +Don't rely on the `applied` flag:: +A cluster's response to an LWT includes an `applied` flag. +If `applied` is `True`, then the LWT's condition was met and the data was actually modified. +If `applied` is `False`, then the condition wasn't met and the data wasn't modified. ++ +Outside of a migration scenario, this flag is passed to the client application from the one cluster that the client is connected to. +However, with {product-proxy}, the responses from both clusters are passed to {product-proxy}, which then passes only _one_ response back to the client application. +This is intentional because {product-proxy} is designed to be transparent to the client application: The client application believes it is interacting with a single cluster. ++ +Specifically, {product-proxy} returns the response, including the `applied` flag, from the xref:ROOT:faqs.adoc#what-are-origin-target-primary-and-secondary-clusters[primary cluster]. +For the majority of the migration process, the origin cluster is the primary cluster. +Near the end of the migration (xref:ROOT:change-read-routing.adoc[Phase 4]), the target cluster becomes the primary cluster. ++ +If your application logic depends on the `applied` flag, be aware that, during the migration, your application receives the `applied` flag from the primary cluster only. +It cannot access the `applied` flag from the secondary cluster. +If needed, modify your application logic in anticipation of this behavior. +Or, plan to thoroughly reconcile inconsistencies that occur due to LWTs before the final phases of the migration (xref:ROOT:change-read-routing.adoc[Phase 4] and xref:ROOT:connect-clients-to-target.adoc[Phase 5]) where the target cluster becomes the primary cluster and your applications stop using the origin cluster. [[cql-function-replacement]] === Server-side non-deterministic functions in the primary key @@ -200,41 +157,19 @@ The {product-short} process requires you to perform rolling restarts of your cli This is standard practice for client applications that are deployed over multiple instances, and it is a widely used approach to roll out releases and configuration changes. ==== -As part of the normal migration process, the {product-proxy} instances will have to be restarted in between phases to apply configuration changes. -From the point of view of the client application, this is a similar behavior to a {dse-short} or {cass-short} cluster going through a rolling restart in a non-migration scenario. - -If your application already tolerates rolling restarts of your current cluster then you should see no issues when there is a rolling restart of {product-proxy} instances. - -To ensure that your client application retries requests when a database connection is closed you should check the section of your driver's documentation related to retry policies. +Throughout the migration process, you must restart {product-proxy} instances to apply configuration changes. +Client applications handle this in the same way as typical rolling restarts of {dse-short} or {cass-short} clusters. -Most {company}-compatible drivers require a statement to be marked as `idempotent` in order to retry it in case of a connection error (such as the termination of a database connection). -This means that, by default, these drivers treat statements as non-idempotent, and the drivers don't automatically retry them in the event of a connection error. +If your applications already tolerate rolling restarts of your origin cluster, then you shouldn't expect any issues during rolling restarts of {product-proxy} instances. -For more information, see the following driver documentation: - -* xref:datastax-drivers:developing:query-idempotence.adoc[] -* xref:datastax-drivers:connecting:retry-policies.adoc[] - -== {dse-short} advanced workloads - -Graph:: -{product-proxy} handles all {dse-short} Graph requests as write requests even if the traversals are read-only. There is no special handling for these requests, so you need to take a look at the traversals that your client application sends and determine whether the traversals are idempotent. If the traversals are non-idempotent then the reconciliation step is needed. -+ -Keep in mind that our recommended tools for data migration and reconciliation are CQL-based, so they can be used for migrations where the origin cluster is a database that uses the new {dse-short} Graph engine released with {dse-short} 6.8, but *cannot be used for the old Graph engine* that older {dse-short} versions relied on. -See <> for more information about non-idempotent operations. - -Search:: -Read-only {dse-short} Search workloads can be moved directly from the origin to the target without {product-proxy} being involved. -If your client application uses Search and also issues writes, or if you need the read routing capabilities from {product-proxy}, then you can connect your Search workloads to it as long as you are using xref:datastax-drivers:compatibility:driver-matrix.adoc[{company}-compatible drivers] to submit these queries. -This approach means the queries are regular CQL `SELECT` statements, so {product-proxy} handles them as regular read requests. -+ -If you use the HTTP API then you can either modify your applications to use the CQL API instead or you will have to move those applications directly from the origin to the target when the migration is complete if that is acceptable. - -For more {dse-short}-specific migration considerations, see xref:6.9@dse:managing:operations/migrate-data.adoc[]. +To ensure that your client application retries requests that fail due to connection errors caused by the rolling restart process, check your driver's retry policies and whether your requests are marked as idempotent. +Most drivers treat all statements as non-idempotent by default, and they don't automatically retry them. +This means that you must explicitly mark statements as idempotent to trigger retries after connection errors. +For more information, see xref:datastax-drivers:developing:query-idempotence.adoc[] and xref:datastax-drivers:connecting:retry-policies.adoc[]. == Client compression -The binary protocol used by {cass-short}, {dse-short}, {hcd-short}, and {astra-db} supports optional compression of transport-level requests and responses that reduces network traffic at the cost of CPU overhead. +The binary protocol used by {astra}, {dse-short}, {hcd-short}, and open-source {cass-short} supports optional compression of transport-level requests and responses that reduces network traffic at the cost of CPU overhead. When establishing connections from client applications, {product-proxy} responds with a list of compression algorithms supported by both clusters. The compression algorithm configured in your {company}-compatible driver must match any item from the common list, or CQL request compression must be disabled completely. @@ -248,7 +183,6 @@ Storage/table compression doesn't affect the client application or {product-prox A cluster's _authorizer_ doesn't affect client applications or {product-proxy}, which means that you can use any kind of authorizer configuration on your clusters, and they can use different authorizers. In contrast, a cluster's _authenticator_ must be compatible with {product-proxy}. - {product-proxy} supports the following cluster authenticator configurations: * No authenticator @@ -259,8 +193,62 @@ In contrast, a cluster's _authenticator_ must be compatible with {product-proxy} The origin and target clusters can have different authentication configurations because {product-proxy} treats them independently. -[#considerations-for-multi-datacenter-clusters-and-other-complex-migrations] -== Considerations for multi-datacenter clusters and other complex migrations +== {dse-short} advanced workloads + +This section describes how {product-proxy} handles certain {dse-short} advanced workloads. +For more {dse-short}-specific migration considerations, see xref:6.9@dse:managing:operations/migrate-data.adoc[]. + +{dse-short} Graph:: +{product-proxy} handles all {dse-short} Graph requests as write requests even if the traversals are read-only. +There is no special handling for these requests, so you must consider the traversals that your client application sends and determine whether the traversals are idempotent. +If the traversals are non-idempotent, then your must thoroughly validate and reconcile the data and the end of xref:ROOT:migrate-and-validate-data.adoc[Phase 2] to ensure that the target cluster is truly consistent with the origin cluster. +For more information, see <>. ++ +{company}'s recommended tools for data migration and reconciliation are CQL-based, so they only support migrations where the origin cluster is a database that uses the new {dse-short} Graph engine ({dse-short} 6.8 and later). +They _cannot_ be used with the earlier Graph engine in {dse-short} versions prior to 6.8. + +{dse-short} Search:: +Read-only {dse-short} Search workloads can be moved directly from the origin to the target without {product-proxy} being involved. +If your client application uses Search and also issues writes, or if you need the read routing capabilities from {product-proxy}, then you can connect your Search workloads to {product-proxy} as long as you are using xref:datastax-drivers:compatibility:driver-matrix.adoc[{company}-compatible drivers] to submit these queries. +This approach means the queries are regular CQL `SELECT` statements, so {product-proxy} handles them as regular read requests. ++ +If you use the HTTP API then you can either modify your applications to use the CQL API instead, or you must move those applications directly from the origin to the target when the migration is complete, if that is acceptable for your use case. + +== {astra} migrations + +This section describes specific considerations for {astra} migrations. +If you need to make any changes to your data model or application logic for compatibility with {astra}, do so before starting the migration. +As mentioned previously, this is because {product-proxy} requires that the same CQL statements can be executed successfully on both clusters, and the data migration tools require matching schemas. + +{astra} guardrails, limits, and CQL compatibility:: +As a managed database-as-a-service (DBaaS) offering, {astra} implements xref:astra-db-serverless:databases:database-limits.adoc[guardrails and limits] on its databases, and xref:astra-db-serverless:cql:develop-with-cql.adoc[{astra} doesn't support all CQL functionality]. +Make sure your application workloads and CQL statements are compatible with these limitations. ++ +In self-managed clusters, such as {dse-short} and {cass-short}, you can configure the database limits in `cassandra.yml`. +Many of these limits aren't configurable in {astra}, and those that can be changed require intervention by {company} Support. + +{astra} doesn't support consistency level ONE:: +`CL.ONE` isn't supported by {astra}, and read and write requests sent through {product-proxy} with `CL.ONE` to {astra-db} databases always fail. +{product-proxy} doesn't mute these failures because you need to be aware of them. +You must adapt your client application to use a consistency level that is supported by both clusters to ensure that the migration is seamless and error-free. + +{astra} doesn't support the Stargate APIs:: +The Stargate APIs (Document, REST, GraphQL, gRPC) are deprecated for {astra}. +If you are migrating to {astra} from an origin cluster that uses any of these APIs, your client applications won't work with {astra}. +Before you migrate, you must change your applications to use other programmatic access, such as {cass-short} drivers or the {data-api}. +For more information, see xref:astra-db-serverless:api-reference:compare-dataapi-to-stargate.adoc[]. + +[[_read_only_applications]]Read-only applications:: +In versions 2.1.0 and later, {product-proxy} sends periodic heartbeats to keep idle cluster connections alive. +The default interval is 30,000 milliseconds, and it can be configured with the `xref:ROOT:manage-proxy-instances.adoc#change-mutable-config-variable[heartbeat_interval_ms]` variable, or by directly setting the `ZDM_HEARTBEAT_INTERVAL_MS` environment variable if you aren't using {product-automation}. ++ +In {product-proxy} versions earlier than 2.1.0, read-only applications require special handling to avoid connection termination due to inactivity. ++ +{company} recommends that you use {product-proxy} version 2.1.0 or later to benefit from the heartbeat feature. +If you cannot use version 2.1.0 or later, see the alternatives described in xref:ROOT:troubleshooting-tips.adoc#client-application-closed-connection-errors-every-10-minutes-when-migrating-to-astra-db[Client application closed connection errors every 10 minutes when migrating to {astra-db}]. + +[#multi-datacenter-clusters-and-other-complex-migrations] +== Multi-datacenter clusters and other complex migrations Complex migration scenarios, such as multi-datacenter migrations or many-to-one migrations, require additional planning to configure {product-proxy} and migrate the data efficiently. diff --git a/modules/ROOT/pages/zdm-proxy-migration-paths.adoc b/modules/ROOT/pages/zdm-proxy-migration-paths.adoc index 56e56433..86a070a8 100644 --- a/modules/ROOT/pages/zdm-proxy-migration-paths.adoc +++ b/modules/ROOT/pages/zdm-proxy-migration-paths.adoc @@ -7,12 +7,6 @@ True zero downtime migration is only possible if your database meets the minimum include::ROOT:partial$migration-scenarios.adoc[] -[TIP] -==== -You can use {product-short} to support major version upgrades for your current database platform, such as upgrades from {dse-short} 5.0 to {dse-short} 6.9. -Using {product-short} reduces the risk of data loss or corruption due to breaking changes between versions, provides a seamless rollback option, and streamlines the upgrade process, eliminating the need for interim upgrades and progressive manual reconfiguration. -==== - [#incompatible-clusters-and-migrations-with-some-downtime] == Incompatible clusters and migrations with some downtime diff --git a/modules/ROOT/partials/migration-scenarios.adoc b/modules/ROOT/partials/migration-scenarios.adoc index daec618d..04a28962 100644 --- a/modules/ROOT/partials/migration-scenarios.adoc +++ b/modules/ROOT/partials/migration-scenarios.adoc @@ -1,17 +1,36 @@ -You can use {product-proxy} to support migrations from {cass-reg}, {dse}, {hcd}, {astra-db}, and other {cass-short}-based databases to any other {cass-short}-based database of the equivalent type or version: +You can use {product-proxy} to support migrations between {astra}, {dse}, {hcd}, open-source {cass-reg}, and and other {cass-short}-based databases. +Supported migration paths include cross-platform migrations and same-platform upgrades. + +{company} tests {product-proxy} compatibility with {astra}, {dse-short}, {hcd-short}, and open-source {cass-short}. +Support for other {cass-short}-based databases is possible if the origin and target clusters share a common xref:ROOT:feasibility-checklists.adoc[protocol version]. +However, {company} neither tests all data store providers nor guarantees support for any specific data source aside from the sources and versions listed here. Compatible origin clusters:: Migrate from one of the following: + -* {dse} version 4.7.1 and later -* {cass-reg} version 2.1.6 and later -* Other {cass-short}-based databases that are based on a compatible {cass-short} version, such as {astra-db} Classic, ScyllaDB, and Yugabyte. +* {astra-db} Serverless or {astra} Managed Clusters ({astra-db} Classic). +* {hcd}. +* {dse} version 4.7.1 and later. +* {cass-reg} version 2.1.6 and later. ++ +{product-proxy} requires that the origin and target clusters share a common xref:ROOT:feasibility-checklists.adoc[protocol version]. +Therefore, {cass-short} 2.0 migrations are only possible when migrating to 2.1 or 2.2 because {cass-short} 2.0 supports only `v2`. +* Other {cass-short}-based databases that are based on a compatible {cass-short} version, such as ScyllaDB and Yugabyte. Compatible target clusters:: Migrate to one of the following: + -* {hcd} -* A cluster running the same or later version of {cass-short} or {dse-short} -* {astra-db} +* {astra-db} Serverless or {astra} Managed Clusters ({astra-db} Classic). + -For more {astra-db} migration paths, see xref:ROOT:astra-migration-paths.adoc[]. \ No newline at end of file +For more {astra-db} migration paths, see xref:ROOT:astra-migration-paths.adoc[]. +* {hcd-short}. +* {dse-short}, if the cluster is running the same or later version as the origin cluster. ++ +Check the xref:6.9@dse:planning:compatibility.adoc[built-in {cass-short} version for your target {dse-short} version]. +* {cass-short}, if the cluster is running the same or later version as the origin cluster. + +[TIP] +==== +You can use {product-short} for major version upgrades to your current database platform, such as upgrades from {dse-short} 5.0 to {dse-short} 6.9. +Using {product-short} reduces the risk of data loss or corruption due to breaking changes between versions, provides a seamless rollback option, and streamlines the upgrade process, eliminating the need for interim upgrades and progressive manual reconfiguration. +==== \ No newline at end of file From f013f491688e881df3f420cd59194fe849fccd8d Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 20 Nov 2025 16:14:42 -0800 Subject: [PATCH 4/5] deployment infra page --- .../ROOT/pages/deployment-infrastructure.adoc | 196 +++++++++++------- 1 file changed, 116 insertions(+), 80 deletions(-) diff --git a/modules/ROOT/pages/deployment-infrastructure.adoc b/modules/ROOT/pages/deployment-infrastructure.adoc index 64add96f..e0cc7519 100644 --- a/modules/ROOT/pages/deployment-infrastructure.adoc +++ b/modules/ROOT/pages/deployment-infrastructure.adoc @@ -1,22 +1,27 @@ = Prepare the {product-proxy} deployment infrastructure :navtitle: Prepare {product-proxy} infrastructure -As part of planning your migration, you need to prepare your infrastructure. +After confirming that your clusters, data model, and application logic meet the xref:ROOT:feasibility-checklists.adoc[compatibility requirements for {product-proxy}], you must prepare the infrastructure to deploy your {product-proxy} instances. + +{company} recommends using {product-automation} and {product-utility} to manage your {product-proxy} deployment. +If you choose to use these tools, you must also prepare infrastructure for {product-automation}. == Choose where to deploy the proxy A typical {product-proxy} deployment is made up of multiple proxy instances. -A minimum of three proxy instances is recommended for any deployment apart from those for demo or local testing purposes. +{company} recommends a minimum of three proxy instances for any deployment other than local test or demo environments. -All {product-proxy} instances must be reachable by the client application and must be able to connect to your origin and target clusters. -The {product-proxy} process is lightweight, requiring only a small amount of resources and no storage to persist state (apart from logs). +All {product-proxy} instances must be reachable by your client application, and they must be able to connect to your origin and target clusters. +{company} recommends that you deploy {product-proxy} as close to your client application instances as possible. +For more information, see <>. -{product-proxy} should be deployed close to your client application instances. -This can be on any cloud provider as well as on-premise, depending on your existing infrastructure. +You can deploy {product-proxy} on any cloud provider or on-premises, depending on your existing infrastructure. The following diagram shows a typical deployment with connectivity between client applications, {product-proxy} instances, and clusters: -image::zdm-during-migration3.png[Connectivity between client applications, proxy instances, and clusters.] +image::zdm-during-migration3.png[Connectivity between client applications, proxy instances, and clusters] + +The {product-proxy} process is lightweight, requiring only a small amount of resources and no storage to persist its state aside from logs. [#multiple-datacenter-clusters] === Multiple datacenter clusters @@ -41,103 +46,134 @@ This deployment model provides maximum resilience and failure tolerance guarante Conversely, deploying a single {product-proxy} instance undermines this resilience mechanism and creates a single point of failure, which can affect client applications if one or more nodes of the underlying origin or target clusters go offline. In a sidecar deployment, each client application instance would be connecting to a single {product-proxy} instance, and would, therefore, be exposed to this risk. -== Infrastructure requirements - -To deploy {product-proxy} and its companion monitoring stack, you must provision infrastructure that meets the following requirements. - [[_machines]] -=== Machines - -We will use the term "machine" to indicate a cloud instance (on any cloud provider), a VM, or a physical server. - -* N machines to run the desired number of {product-proxy} instances: -** You will need one machine for each {product-proxy} instance. -** Requirements for each {product-proxy} instance: -*** Ubuntu Linux 20.04 or 22.04, Red Hat Family Linux 7 or newer -*** 4 vCPUs -*** 8GB RAM -*** 20GB - 100GB root volume -*** Equivalent to AWS `c5.xlarge` / GCP `e2-standard-4` / Azure `A4 v2` -* One machine for the jumphost, which is typically also used as Ansible Control Host and to run the monitoring stack (Prometheus + Grafana): -** The most common option is using a single machine for all these functions, but you could split these functions across different machines if you prefer. -** Requirements: -*** Ubuntu Linux 20.04 or 22.04, Red Hat Family Linux 7 or newer -*** 8 vCPUs -*** 16GB RAM -*** 200GB - 500GB storage (depending on the amount of metrics history that you wish to retain) -*** Equivalent to AWS `c5.2xlarge` / GCP `e2-standard-8` / Azure `A8 v2` -* 1-M machines to run either {dsbulk-migrator} or {cass-migrator}. -** It's recommended that you start with at least one VM with 16 vCPUs and 64GB RAM and a minimum of 200GB storage. Depending on the total amount of data that is planned for migration, more than one VM may be needed. -** Requirements: -*** Ubuntu Linux 20.04 or 22.04, Red Hat Family Linux 7 or newer -*** 16 vCPUs -*** 64GB RAM -*** 200GB - 2TB storage (if you use dsbulk-migrator to unload multiple terabytes of data from origin, then load into target, you may need to consider more space to accommodate the data that needs to be staged) -*** Equivalent to AWS `m5.4xlarge` / GCP `e2-standard-16` / Azure `D16v5` - -[NOTE] -==== -* Scenario: If you have 20 TBs of existing data to be migrated and want to speed up the migration, you could use multiple VMs. -For example, you can use four VMs that are the equivalent of an AWS m5.4xlarge, a GCP e2-standard-16 or an Azure D16v5. -+ -Next, run {dsbulk-migrator} or {cass-migrator} in parallel on each VM with each one responsible for migrating around 5TB of data. -If there is one super large table (e.g. 15 TB of 20 TB is in one table), you can choose to migrate this table in three parts on three separate VMs in parallel by splitting the full token range into three parts and migrating the rest of the tables on the fourth VM. +== Hardware requirements -* Ensure that your origin and target clusters can handle high traffic from {cass-migrator} or {dsbulk-migrator} in addition to the live traffic from your application. +You need a number of machines to run your {product-proxy} instances, plus additional machines for the centralized jumphost, and for running {dsbulk-migrator} or {cass-migrator} (which are recommended data migration and validation tools). -* Test any migration in a lower environment before you plan to do it in production. +This section uses the term _machine_ broadly to refer to a cloud instance (on any cloud provider), a VM, or a physical server. -* Contact {support-url}[{company} Support] for help configuring your workload. -==== +{product-proxy} instances:: +You need one machine for each {product-proxy} instance. +{company} recommends a minimum of three proxy instances for all migrations that aren't for local testing purposes. ++ +Each machine must meet the following specifications: ++ +* Ubuntu Linux 20.04 or 22.04, Red Hat Family Linux 7 or newer +* 4 vCPUs +* 8 GB RAM +* 20 to 100 GB of storage for the root volume +* Equivalent to AWS **c5.xlarge**, GCP **e2-standard-4**, or Azure **A4 v2** -// TODO: investigate how to "leverage the parallelism of {cass-migrator} to run the migration process across all 4 machines." ++ +These machines can be on any cloud provider or on-premises, depending on your existing infrastructure, and they should be as close as possible to your client application instances for best performance. + +Jumphost and monitoring:: +You need at least one machine for the jumphost, which is the centralized manager for the {product-proxy} instances and runs the monitoring stack (Prometheus and Grafana). +With {product-automation}, the jumphost also runs the Ansible Control Host container. ++ +Typically, a single machine is used for all of these functions, but you can split them across different machines if you prefer. +This documentation assumes you are using a single machine. ++ +The jumphost machine must meet the following specifications: ++ +* Ubuntu Linux 20.04 or 22.04, Red Hat Family Linux 7 or newer +* 8 vCPUs +* 16 GB RAM +* 200 to 500 GB of storage depending on the amount of metrics history that you want to retain +* Equivalent to AWS **c5.2xlarge**, GCP **e2-standard-8**, or Azure **A8 v2** + +Data migration tools ({dsbulk-migrator} or {cass-migrator}):: +You need at least one machine to run {dsbulk-migrator} or {cass-migrator} for the data migration and validation (xref:ROOT:migrate-and-validate-data.adoc[Phase 2]). +Even if you plan to use another data migration tool, you might need infrastructure for these tools or your chosen tool. +For example, you can use {dsbulk-migrator} to generate DDL statements to help you recreate your origin cluster's schema on your target cluster, and {cass-migrator} is used for data validation after migrating data with {sstable-sideloader}. ++ +{company} recommends that you start with at least one VM that meets the following minimum specifications: ++ +* Ubuntu Linux 20.04 or 22.04, Red Hat Family Linux 7 or newer +* 16 vCPUs +* 64 GB RAM +* 200 GB to 2 TB of storage ++ +If you plan to use {dsbulk-migrator} to unload and load multiple terabytes of data from the origin cluster to the target cluster, consider allocating additional space for data that needs to be staged between unloading and loading. +* Equivalent to AWS **m5.4xlarge**, GCP **e2-standard-16**, or Azure **D16 v5** -=== Connectivity ++ +-- +Whether you need additional machines depends on the total amount of data you need to migrate. +All machines must meet the minimum specifications. -The {product-proxy} machines must be reachable by: +For example, if you have 20 TBs of existing data to migrate, you could use 4 VMs to speed up the migration. +Then, you would run {dsbulk-migrator} or {cass-migrator} in parallel on each VM with each one responsible for migrating specific tables or a portion of the data, such as 25% or 5 TB. -* The client application instances, on port 9042 -* The monitoring machine on port 14001 -* The jumphost on port 22 +If you have one especially large table, such as 75% of the total data in one table, you can use multiple VMs to migrate that one table. +For example, if you have 4 VMs, you can use three VMs in parallel for the large table by splitting the table's full token range into three groups. +Then, each VM migrates one group of tokens, and you use the fourth VM to migrate the remaining smaller portion of the data. [IMPORTANT] ==== -The {product-proxy} machines should not be directly accessible by external machines. -The only direct access to these machines should be from the jumphost. +Make sure that your origin and target clusters can handle high traffic from your chosen data migration tool in addition to the live traffic from your application. + +Test migrations in a lower environment before you proceed with production migrations. + +If you need assistance with your migration, contact {support-url}[{company} Support]. ==== +-- -The {product-proxy} machines must be able to connect to the origin and target cluster nodes: +[#connectivity-requirements] +== Connectivity requirements -* For self-managed clusters ({cass} or {dse-short}), connectivity is needed to the {cass-short} native protocol port (typically 9042). -* For {astra-db}, you will need to ensure outbound connectivity to the {astra} endpoint indicated in the xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb}]. -Connectivity over Private Link is also supported. +[IMPORTANT] +==== +Don't allow external machines to directly access the {product-proxy} machines. +The jumphost is the only machine that should have direct access to the {product-proxy} machines. +==== -The connectivity requirements for the jumphost / monitoring machine are: +Core infrastructure ports:: +The {product-proxy} machines must be reachable by the following: ++ +* The client application instances on port 9042 +* The jumphost on port 22 +* The machine running the monitoring stack (the jumphost or a separate machine) on port 14001 -* Connecting to the {product-proxy} instances: on port 14001 for metrics collection, and on port 22 to run the Ansible automation and for log inspection or troubleshooting. -* Allowing incoming ssh connections from outside, potentially from allowed IP ranges only. -* Exposing the Grafana UI on port 3000. +Clusters:: +The {product-proxy} machines must be able to connect to the origin and target cluster nodes. ++ +For self-managed clusters like {cass-short} and {dse-short}, {product-proxy} must be able to connect on the {cass-short} Native Protocol port, which is typically 9042. ++ +For {astra}, you must ensure that outbound connectivity is possible over the {astra} endpoint indicated in the xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb}]. +Connections over xref:astra-db-serverless:administration:manage-private-endpoints.adoc[private endpoints] are supported. +Jumphost and monitoring:: +The following connectivity requirements apply to the jumphost and monitoring machine. +If you use separate machines for these functions, these requirements apply to both machines. ++ +* Connect to {product-proxy} instances on port 14001 for metrics collection. +* Connect to {product-proxy} instances on port 22 for {product-automation}, log inspection, and troubleshooting. +* Allow incoming, external SSH connections. ++ [IMPORTANT] ==== -It is strongly recommended **to restrict external access** to this machine to specific IP ranges (for example, the IP range of your corporate networks or trusted VPNs). +{company} strongly recommends that you limit external access to specific IP ranges. +For example, limit access to the IP ranges of your corporate networks or trusted VPNs. ==== +* Expose the Grafana UI on port 3000. -The {product-proxy} and monitoring machines must be able to connect externally, as the automation will download: - -* Various software packages (Docker, Prometheus, Grafana). -* {product-proxy} image from DockerHub repo. ++ +External connections are required so that {product-automation} can download the necessary software packages (Docker, Prometheus, Grafana) and the {product-proxy} image from DockerHub. === Connect to {product-proxy} infrastructure from an external machine To connect to the jumphost from an external machine, ensure that its IP address belongs to a permitted IP range. -If you are connecting through a VPN that only intercepts connections to selected destinations, you may have to add a route from your VPN IP gateway to the public IP of the jumphost. +If you are connecting through a VPN that only intercepts connections to selected destinations, you might need to add a route from your VPN IP gateway to the public IP of the jumphost. -To simplify connecting to the jumphost and, through it, to the {product-proxy} instances, you can create a custom SSH config file. -You can use this template and replace all the placeholders in angle brackets with the appropriate values for your deployment, adding more entries if you have more than three proxy instances. -Save this file, for example calling it `zdm_ssh_config`. +A custom SSH config file can simplify the process of connecting to the jumphost and, by extension, the {product-proxy} instances. -[source,bash] +To use the following template, replace all placeholders (in angle brackets) with the appropriate values for your deployment, and add more entries if you have more than three proxy instances. +Save the file with any name you prefer, such as `zdm_ssh_config`. + +.zdm_ssh_config +[source,config] ---- Host jumphost Hostname @@ -157,21 +193,21 @@ Host zdm-proxy-2 Host * User - IdentityFile < Filename (with absolute path) of the locally generated key pair for the ZDM infrastructure. Example ~/.ssh/zdm-key-XXX > + IdentityFile IdentitiesOnly yes StrictHostKeyChecking no GlobalKnownHostsFile /dev/null UserKnownHostsFile /dev/null ---- -With this file, you can connect to your jumphost simply with: +Then, use the SSH config file to connect to your jumphost: [source,bash] ---- ssh -F zdm_ssh_config jumphost ---- -Likewise, connecting to any {product-proxy} instance is as easy as this (replacing the instance number as desired): +Connect to a {product-proxy} instance by specifying the corresponding instance number in your config file: [source,bash] ---- From 68b52d7b2d6b66a150458c62b9d3fa80b6450e83 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Fri, 21 Nov 2025 03:56:46 -0800 Subject: [PATCH 5/5] peer review --- .../ROOT/pages/deployment-infrastructure.adoc | 25 ++++++++++--------- .../ROOT/partials/migration-scenarios.adoc | 2 +- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/deployment-infrastructure.adoc b/modules/ROOT/pages/deployment-infrastructure.adoc index e0cc7519..f545e8af 100644 --- a/modules/ROOT/pages/deployment-infrastructure.adoc +++ b/modules/ROOT/pages/deployment-infrastructure.adoc @@ -169,31 +169,32 @@ If you are connecting through a VPN that only intercepts connections to selected A custom SSH config file can simplify the process of connecting to the jumphost and, by extension, the {product-proxy} instances. -To use the following template, replace all placeholders (in angle brackets) with the appropriate values for your deployment, and add more entries if you have more than three proxy instances. +To use the following template, replace all placeholders with the appropriate values for your deployment. +Add more entries if you have more than three proxy instances. Save the file with any name you prefer, such as `zdm_ssh_config`. .zdm_ssh_config -[source,config] +[source,config,subs="+quotes"] ---- -Host jumphost - Hostname +Host **JUMPHOST_PRIVATE_IP_ADDRESS** jumphost + Hostname **JUMPHOST_PUBLIC_IP_ADDRESS** Port 22 -Host zdm-proxy-0 - Hostname +Host **PRIVATE_IP_ADDRESS_OF_PROXY_INSTANCE_0** zdm-proxy-0 + Hostname **PRIVATE_IP_ADDRESS_OF_PROXY_INSTANCE_0** ProxyJump jumphost -Host zdm-proxy-1 - Hostname +Host **PRIVATE_IP_ADDRESS_OF_PROXY_INSTANCE_1** zdm-proxy-1 + Hostname **PRIVATE_IP_ADDRESS_OF_PROXY_INSTANCE_1** ProxyJump jumphost -Host zdm-proxy-2 - Hostname +Host **PRIVATE_IP_ADDRESS_OF_PROXY_INSTANCE_2** zdm-proxy-2 + Hostname **PRIVATE_IP_ADDRESS_OF_PROXY_INSTANCE_2** ProxyJump jumphost Host * - User - IdentityFile + User **LINUX_USER** + IdentityFile **ABSOLUTE PATH WITH FILENAME FOR LOCALLY GENERATED KEY PAIR LIKE ~/.ssh/zdm-key-XXX** IdentitiesOnly yes StrictHostKeyChecking no GlobalKnownHostsFile /dev/null diff --git a/modules/ROOT/partials/migration-scenarios.adoc b/modules/ROOT/partials/migration-scenarios.adoc index 04a28962..fa943ddb 100644 --- a/modules/ROOT/partials/migration-scenarios.adoc +++ b/modules/ROOT/partials/migration-scenarios.adoc @@ -3,7 +3,7 @@ Supported migration paths include cross-platform migrations and same-platform up {company} tests {product-proxy} compatibility with {astra}, {dse-short}, {hcd-short}, and open-source {cass-short}. Support for other {cass-short}-based databases is possible if the origin and target clusters share a common xref:ROOT:feasibility-checklists.adoc[protocol version]. -However, {company} neither tests all data store providers nor guarantees support for any specific data source aside from the sources and versions listed here. +However, {company} doesn't test all data store providers, and {company} doesn't guarantee full support for any specific data store aside from the platforms and versions listed here. Compatible origin clusters:: Migrate from one of the following: