From ffccf55829aef92ac841e5bfa23facc4ca603aa2 Mon Sep 17 00:00:00 2001 From: April M Date: Wed, 23 Jul 2025 16:28:43 -0700 Subject: [PATCH 1/5] zdm for hcd --- antora.yml | 2 +- modules/ROOT/nav.adoc | 2 +- modules/ROOT/pages/dse-migration-paths.adoc | 5 +- modules/ROOT/pages/hcd-migration-paths.adoc | 79 +++++++++++++++++++++ 4 files changed, 85 insertions(+), 3 deletions(-) create mode 100644 modules/ROOT/pages/hcd-migration-paths.adoc diff --git a/antora.yml b/antora.yml index 9cea5ad0..1bca9135 100644 --- a/antora.yml +++ b/antora.yml @@ -21,7 +21,7 @@ asciidoc: hcd-short: 'HCD' mc: 'Mission Control' #Astra DB attributes - astra-db: 'Astra DB' + astra-db: 'Astra DB' astra: 'Astra' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 4c2c4fcf..55deeb85 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -3,7 +3,7 @@ * xref:ROOT:zdm-proxy-migration-paths.adoc[] * xref:ROOT:astra-migration-paths.adoc[] * xref:ROOT:dse-migration-paths.adoc[] -//* xref:ROOT:hcd-migration-paths.adoc[] +* xref:ROOT:hcd-migration-paths.adoc[] * xref:ROOT:mc-migration-paths.adoc[] .{product} diff --git a/modules/ROOT/pages/dse-migration-paths.adoc b/modules/ROOT/pages/dse-migration-paths.adoc index 6cd757fb..bdeacefe 100644 --- a/modules/ROOT/pages/dse-migration-paths.adoc +++ b/modules/ROOT/pages/dse-migration-paths.adoc @@ -23,21 +23,24 @@ The following information provides guidance on migrations _to_ {dse-short}. Generally, {company} recommends migrating to the latest version of {dse-short}, unless you have a compatibility issue that requires an interim migration to an earlier version before upgrading. -//TODO: Resolve duplication and replace these at the source with one summary page that points to here. +//TODO: Resolve DSE topic duplication and replace these at the source with one summary page that points to here. * {dse-short} 6.9 + ** xref:6.9@dse:tooling:migration-path-dse.adoc[{dse-short} 6.9 migration tools] ** xref:6.9@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.9] +** xref:ROOT:hcd-migration-paths.adoc[Migrate to {hcd-short}] * {dse-short} 6.8 + ** xref:6.8@dse:tooling:migration-path-dse.adoc[{dse-short} 6.8 migration tools] ** xref:6.8@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.8] +** xref:ROOT:hcd-migration-paths.adoc[Migrate to {hcd-short}] * {dse-short} 5.1 + ** xref:5.1@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 5.1] +** xref:ROOT:hcd-migration-paths.adoc[Migrate to {hcd-short}] -- Migrate data from {dse-short}:: diff --git a/modules/ROOT/pages/hcd-migration-paths.adoc b/modules/ROOT/pages/hcd-migration-paths.adoc new file mode 100644 index 00000000..b3bfca85 --- /dev/null +++ b/modules/ROOT/pages/hcd-migration-paths.adoc @@ -0,0 +1,79 @@ += {hcd-short} migration toolkit +:description: Learn which migration tools you can use to migrate data to {hcd-short}. + +The {hcd} migration toolkit includes the xref:ROOT:components.adoc[{company} migration tools] that you can use to migrate your data to {hcd-short} from another {cass-reg}-based database, such as {astra-db}, {cass-short}, or {dse-short}. + +Whenever possible, {company} strongly recommends using the {product} ({product-short}) tools to orchestrate ongoing read/write traffic when you migrate to {hcd-short}. + +[#zdm-to-hcd] +== Zero-downtime migrations to {hcd-short} + +The {product} ({product-short}) tools allow you to standup your new {hcd-short} clusters independently of your existing {dse-short} clusters. +Then, {product-proxy} orchestrates live traffic and synchronizes ongoing writes while you migrate data to your new clusters using any {product-short}-compatible data migration and validation tool. +Finally, you can use {product-proxy} to simulate the live workload on your new clusters before permanently switching your traffic over. + +{product-proxy} and {product-automation} provide the safest upgrade approach with blue-green deployment capabilities that eliminate time pressure and ensure optimal availability and operational safety. +You can rollback up to the last stage of the migration if necessary. + +By orchestrating independent clusters with the {product-short} tools, you can specify your ideal {hcd-short} configuration settings that you otherwise wouldn't be able to change during an in-place cluster upgrade. +Incompatibilities in cluster configuration don't disrupt the migration because your existing cluster stays active and unchanged while you setup the new cluster and migrate your data. + +=== Data validation with {product-short} + +The {product-short} tools don't migrate your data. +During the {product-short} process, you use a xref:ROOT:migrate-and-validate-data.adoc[data migration tool] to rewrite the data from your existing cluster to your new cluster. + +{company} recommends that you do the following: + +* Choose a data migration tool that also includes strong validation capabilities, such as [{cass-migrator} ({cass-migrator-short})]. +* Be aware of incompatible data types that can fail to migrate from your old cluster. +For example, {hcd-short} 1.2 doesn't support tuples in {dse-short} versions 6.8.4 and earlier. + +Data validation tools can catch these inconsistencies as missing or mismatched data, but you will still need to have a plan to resolve the inconsistencies. +For example, you might need to modify your applications to use a different data type, or you might need to perform additional post-migration writes to populate lost data. + +It is crucial that you fully validate and test your new cluster before switching your traffic over to it. + +{product-proxy} is ideal for supporting this transition because it allows both clusters to remain in place until you are completely certain you are ready to switch to the new cluster. +Additionally, your old cluster remains untouched and available for rollback or reversion if necessary. + +=== Get started with {product-short} and {hcd-short} + +For information about clusters that are eligible for {product} to {hcd-short}, see xref:ROOT:zdm-proxy-migration-paths.adoc[]. + +To begin your {product} to {hcd-short}, go to xref:ROOT:introduction.adoc[]. + +You must setup your {hcd-short} clusters before you can enable the {product-proxy}. +For information about installing and configuring {hcd-short}, see the xref:1.2@hcd:get-started:get-started-hcd.adoc[{hcd-short} documentation]. + +== Migrate your code + +After migrating your data to {hcd-short}, your applications can connect exclusively to your new databases. + +If you are already using a compatible {cass-short} driver, you can modify the driver connection string to connect to the new or upgraded databases. + +[IMPORTANT] +==== +Your {cass-short} driver version must be compatible with {hcd-short}. + +If you are using an early driver version or a {dse-short}-only driver, you must upgrade to a driver version that is compatible with {hcd-short}. + +For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc[]. +==== + +For some migrations, changing the connection string might be the only change you need to make to your code. +However, you might want to update your code to take advantage of features and improvements available in your new database platform or a newer driver version. + +For example, {hcd-short} includes an {astra} {data-api} server that you can use for application development with your {hcd-short} databases, including vector search and hybrid search capabilities. +It provides several client libraries and direct access over HTTP. + +For more information about connecting to {hcd-short} databases, see the xref:1.2@hcd:get-started:get-started-hcd.adoc[{hcd-short} documentation]. + +== Get support for your migration + +If you have questions about your {hcd-short} migration, contact your {company} account representative or {support-url}[{company} Support]. + +== See also + +* xref:ROOT:mc-migration-paths.adoc[] +* xref:1.2@hcd:migrate:dse-68-to-hcd-12.adoc[In-place upgrade from {dse-short} 6.8 to {hcd-short} 1.2] \ No newline at end of file From 92928cebcbf9674e5fac79bfa1e20f7a82a18885 Mon Sep 17 00:00:00 2001 From: April M Date: Thu, 24 Jul 2025 06:07:35 -0700 Subject: [PATCH 2/5] fix 2 issues --- antora.yml | 2 +- modules/ROOT/pages/dse-migration-paths.adoc | 5 +---- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/antora.yml b/antora.yml index 1bca9135..9cea5ad0 100644 --- a/antora.yml +++ b/antora.yml @@ -21,7 +21,7 @@ asciidoc: hcd-short: 'HCD' mc: 'Mission Control' #Astra DB attributes - astra-db: 'Astra DB' + astra-db: 'Astra DB' astra: 'Astra' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' diff --git a/modules/ROOT/pages/dse-migration-paths.adoc b/modules/ROOT/pages/dse-migration-paths.adoc index bdeacefe..14edba56 100644 --- a/modules/ROOT/pages/dse-migration-paths.adoc +++ b/modules/ROOT/pages/dse-migration-paths.adoc @@ -29,25 +29,22 @@ Generally, {company} recommends migrating to the latest version of {dse-short}, + ** xref:6.9@dse:tooling:migration-path-dse.adoc[{dse-short} 6.9 migration tools] ** xref:6.9@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.9] -** xref:ROOT:hcd-migration-paths.adoc[Migrate to {hcd-short}] * {dse-short} 6.8 + ** xref:6.8@dse:tooling:migration-path-dse.adoc[{dse-short} 6.8 migration tools] ** xref:6.8@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.8] -** xref:ROOT:hcd-migration-paths.adoc[Migrate to {hcd-short}] * {dse-short} 5.1 + ** xref:5.1@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 5.1] -** xref:ROOT:hcd-migration-paths.adoc[Migrate to {hcd-short}] -- Migrate data from {dse-short}:: + -- When migrating _from_ {dse-short} to another {cass-short}-based database, follow the migration guidance for your target database to determine cluster compatibility, migration options, and recommendations. -For example, for {astra-db}, see xref:ROOT:astra-migration-paths.adoc[]. +For example, for {astra-db}, see xref:ROOT:astra-migration-paths.adoc[], and for {hcd-short}, see xref:ROOT:hcd-migration-paths.adoc[]. If your target database isn't directly compatible with a migration from {dse-short}, you might need to take interim steps to prepare your data for migration, such as upgrading your {dse-short} version or modifying the data in your existing database to be compatible with the target database. -- From dcce6757d876155bf6bd0e03408d5a814cc6a4a4 Mon Sep 17 00:00:00 2001 From: April M Date: Thu, 24 Jul 2025 09:24:23 -0700 Subject: [PATCH 3/5] peer review and comment/edit links to pass build --- modules/ROOT/pages/hcd-migration-paths.adoc | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/hcd-migration-paths.adoc b/modules/ROOT/pages/hcd-migration-paths.adoc index b3bfca85..72c6ced1 100644 --- a/modules/ROOT/pages/hcd-migration-paths.adoc +++ b/modules/ROOT/pages/hcd-migration-paths.adoc @@ -16,7 +16,7 @@ Finally, you can use {product-proxy} to simulate the live workload on your new c You can rollback up to the last stage of the migration if necessary. By orchestrating independent clusters with the {product-short} tools, you can specify your ideal {hcd-short} configuration settings that you otherwise wouldn't be able to change during an in-place cluster upgrade. -Incompatibilities in cluster configuration don't disrupt the migration because your existing cluster stays active and unchanged while you setup the new cluster and migrate your data. +Incompatibilities in cluster configuration don't disrupt the migration because your existing cluster remains active and unchanged while you set up the new cluster and migrate your data. === Data validation with {product-short} @@ -27,10 +27,10 @@ During the {product-short} process, you use a xref:ROOT:migrate-and-validate-dat * Choose a data migration tool that also includes strong validation capabilities, such as [{cass-migrator} ({cass-migrator-short})]. * Be aware of incompatible data types that can fail to migrate from your old cluster. -For example, {hcd-short} 1.2 doesn't support tuples in {dse-short} versions 6.8.4 and earlier. +//For example, {hcd-short} 1.2.3 doesn't support tuples in {dse-short} versions 6.8.4 and earlier. -Data validation tools can catch these inconsistencies as missing or mismatched data, but you will still need to have a plan to resolve the inconsistencies. -For example, you might need to modify your applications to use a different data type, or you might need to perform additional post-migration writes to populate lost data. +Data validation tools can identify inconsistencies as missing or mismatched data, but you still need to have a plan to resolve them. +For example, you might need to modify your applications to use a different data type or perform additional post-migration writes to populate lost data. It is crucial that you fully validate and test your new cluster before switching your traffic over to it. @@ -43,8 +43,8 @@ For information about clusters that are eligible for {product} to {hcd-short}, s To begin your {product} to {hcd-short}, go to xref:ROOT:introduction.adoc[]. -You must setup your {hcd-short} clusters before you can enable the {product-proxy}. -For information about installing and configuring {hcd-short}, see the xref:1.2@hcd:get-started:get-started-hcd.adoc[{hcd-short} documentation]. +You must set up your {hcd-short} clusters before you can enable the {product-proxy}. +For information about installing and configuring {hcd-short}, see the xref:1.1@hcd:get-started:get-started-hcd.adoc[{hcd-short} documentation]. == Migrate your code @@ -76,4 +76,5 @@ If you have questions about your {hcd-short} migration, contact your {company} a == See also * xref:ROOT:mc-migration-paths.adoc[] -* xref:1.2@hcd:migrate:dse-68-to-hcd-12.adoc[In-place upgrade from {dse-short} 6.8 to {hcd-short} 1.2] \ No newline at end of file +//* xref:1.2@hcd:migrate:dse-68-to-hcd-12.adoc[In-place upgrade from {dse-short} 6.8 to {hcd-short} 1.2.3] +//* xref:1.1@hcd:migrate:dse-51-to-hcd-11.adoc[In-place upgrade from {dse-short} 5.1 to {hcd-short} 1.1] \ No newline at end of file From 739396771692f8c2b121822415585b5d1b441475 Mon Sep 17 00:00:00 2001 From: April M Date: Thu, 24 Jul 2025 09:31:37 -0700 Subject: [PATCH 4/5] fix xrefs --- modules/ROOT/pages/hcd-migration-paths.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/hcd-migration-paths.adoc b/modules/ROOT/pages/hcd-migration-paths.adoc index 72c6ced1..610957d4 100644 --- a/modules/ROOT/pages/hcd-migration-paths.adoc +++ b/modules/ROOT/pages/hcd-migration-paths.adoc @@ -44,7 +44,7 @@ For information about clusters that are eligible for {product} to {hcd-short}, s To begin your {product} to {hcd-short}, go to xref:ROOT:introduction.adoc[]. You must set up your {hcd-short} clusters before you can enable the {product-proxy}. -For information about installing and configuring {hcd-short}, see the xref:1.1@hcd:get-started:get-started-hcd.adoc[{hcd-short} documentation]. +For information about installing and configuring {hcd-short}, see the xref:1.1@hyper-converged-database:get-started:get-started-hcd.adoc[{hcd-short} documentation]. == Migrate your code @@ -67,7 +67,7 @@ However, you might want to update your code to take advantage of features and im For example, {hcd-short} includes an {astra} {data-api} server that you can use for application development with your {hcd-short} databases, including vector search and hybrid search capabilities. It provides several client libraries and direct access over HTTP. -For more information about connecting to {hcd-short} databases, see the xref:1.2@hcd:get-started:get-started-hcd.adoc[{hcd-short} documentation]. +For more information about connecting to {hcd-short} databases, see the xref:1.1@hyper-converged-database:get-started:get-started-hcd.adoc[{hcd-short} documentation]. == Get support for your migration @@ -76,5 +76,5 @@ If you have questions about your {hcd-short} migration, contact your {company} a == See also * xref:ROOT:mc-migration-paths.adoc[] -//* xref:1.2@hcd:migrate:dse-68-to-hcd-12.adoc[In-place upgrade from {dse-short} 6.8 to {hcd-short} 1.2.3] -//* xref:1.1@hcd:migrate:dse-51-to-hcd-11.adoc[In-place upgrade from {dse-short} 5.1 to {hcd-short} 1.1] \ No newline at end of file +//* xref:1.2@hyper-converged-database:migrate:dse-68-to-hcd-12.adoc[In-place upgrade from {dse-short} 6.8 to {hcd-short} 1.2.3] +//* xref:1.1@hyper-converged-database:migrate:dse-51-to-hcd-11.adoc[In-place upgrade from {dse-short} 5.1 to {hcd-short} 1.1] \ No newline at end of file From 8cd098987b8c9cf66bdcfb41f8109ed112412a29 Mon Sep 17 00:00:00 2001 From: April M Date: Thu, 24 Jul 2025 10:06:19 -0700 Subject: [PATCH 5/5] clarify mc paragraph --- modules/ROOT/pages/mc-migration-paths.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/mc-migration-paths.adoc b/modules/ROOT/pages/mc-migration-paths.adoc index 656a1555..a45a7875 100644 --- a/modules/ROOT/pages/mc-migration-paths.adoc +++ b/modules/ROOT/pages/mc-migration-paths.adoc @@ -11,9 +11,9 @@ Additionally, {mc} isn't applicable to {astra-db}, which has its own interface f Cluster migration moves your entire cluster from one infrastructure to another, including its data. **It is meant as an infrastructure migration only, not a database software migration.** -If you are migrating both your infrastructure _and_ your database software, create your new cluster in {mc}, and then migrate your data from your old cluster directly to the new cluster on {mc}. +If you are migrating both your infrastructure _and_ your database software, create your new cluster in {mc}, and then use xref:ROOT:components.adoc[{company} migration tools] to migrate your data from your old cluster directly to the new cluster on {mc}. -For information about migrating your infrastructure to {mc}, see the following: +For information about migrating your infrastructure _only_ to {mc}, see the following: * xref:mission-control:migrate:oss-cass-to-mission-control.adoc[Migrate {cass-short} clusters to {mc}] * xref:mission-control:migrate:dse-to-mission-control.adoc[Migrate {dse-short} and other {cass-short}-based clusters to {mc}] \ No newline at end of file