diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 55deeb85..15df5024 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -37,7 +37,6 @@ ** xref:ROOT:troubleshooting-scenarios.adoc[] ** xref:ROOT:faqs.adoc[] ** xref:ROOT:glossary.adoc[] -** xref:ROOT:contributions.adoc[] * Release notes ** {product-proxy-repo}/releases[{product-proxy} release notes] ** {product-automation-repo}/releases[{product-automation} release notes] diff --git a/modules/ROOT/pages/astra-migration-paths.adoc b/modules/ROOT/pages/astra-migration-paths.adoc index 4d19ad53..f2095047 100644 --- a/modules/ROOT/pages/astra-migration-paths.adoc +++ b/modules/ROOT/pages/astra-migration-paths.adoc @@ -1,12 +1,12 @@ = {astra} migration toolkit :description: Learn which migration tools you can use to migrate data to {astra}. -The {astra} migration toolkit includes all xref:ROOT:components.adoc[{company} migration tools] that are designed to help you migrate your data to {astra-db}. +The {astra} migration toolkit includes all xref:ROOT:components.adoc[{company} migration tools] that are designed to help you xref:astra-db-serverless:databases:migration-path-serverless.adoc[migrate your data to {astra-db}]. -== Migration tool compatibility - -Use the following table to learn which tools are compatible with your current database provider or service: +Use the following table to learn which tools are compatible with your current database provider or service. +If you have questions about migrating from a specific source to {astra-db}, contact your {company} account representative or {support-url}[{company} Support]. +.Migration tool compatibility [cols="2,1,1,1,1"] |=== |Origin |{sstable-sideloader} |{cass-migrator} |{product-proxy} |{dsbulk-migrator}/{dsbulk-loader} @@ -95,13 +95,4 @@ Use the following table to learn which tools are compatible with your current da |icon:check[role="text-success",alt="Supported"] |icon:check[role="text-success",alt="Supported"] -|=== - -== Get support for your migration - -If you have questions about migrating from a specific source to {astra-db}, contact your {company} account representative, {support-url}[{company} Support], or an https://www.datastax.com/products/datastax-astra/migration-toolkit[{astra} migration toolkit expert]. - -== See also - -* https://www.datastax.com/events/migrating-your-legacy-cassandra-app-to-astra-db[Migrating your legacy {cass-reg} app to {astra-db}] -* xref:astra-db-serverless:databases:migration-path-serverless.adoc[Migrate to {astra-db}] \ No newline at end of file +|=== \ No newline at end of file diff --git a/modules/ROOT/pages/change-read-routing.adoc b/modules/ROOT/pages/change-read-routing.adoc index e16a7889..777eea64 100644 --- a/modules/ROOT/pages/change-read-routing.adoc +++ b/modules/ROOT/pages/change-read-routing.adoc @@ -1,5 +1,4 @@ = Route reads to the target -:page-tag: migration,zdm,zero-downtime,zdm-proxy,read-routing This topic explains how you can configure {product-proxy} to route all reads to the target cluster instead of the origin cluster. diff --git a/modules/ROOT/pages/components.adoc b/modules/ROOT/pages/components.adoc index 8ad4fcbe..5396b05e 100644 --- a/modules/ROOT/pages/components.adoc +++ b/modules/ROOT/pages/components.adoc @@ -1,7 +1,6 @@ = Compare {company} migration tools :navtitle: Compare migration tools :description: Learn about {company} migration tools. -:page-tag: migration,zdm,zero-downtime,zdm-proxy,components The {company} {product} ({product-short}) toolkit includes {product-proxy}, {product-utility}, {product-automation}, and several data migration tools. @@ -14,7 +13,7 @@ You can use these tools alone or with {product-proxy}. == {product-proxy} The main component of the {company} {product} toolkit is {product-proxy-repo}[{product-proxy}], which is designed to be a lightweight proxy that handles all real-time requests generated by your client applications during the migration process. -This tool is open-source software that is open for xref:ROOT:contributions.adoc[public contributions]. +This tool is open-source software. {product-proxy} is an orchestrator for monitoring application activity and keeping multiple clusters (databases) in sync through dual writes. {product-proxy} isn't linked to the actual migration process. diff --git a/modules/ROOT/pages/connect-clients-to-proxy.adoc b/modules/ROOT/pages/connect-clients-to-proxy.adoc index 3950a851..7c80c7e6 100644 --- a/modules/ROOT/pages/connect-clients-to-proxy.adoc +++ b/modules/ROOT/pages/connect-clients-to-proxy.adoc @@ -1,6 +1,5 @@ = Connect your client applications to {product-proxy} :navtitle: Connect client applications to {product-proxy} -:page-tag: migration,zdm,zero-downtime,zdm-proxy,connect-apps {product-proxy} is designed to be similar to a conventional {cass-reg} cluster. You communicate with it using the CQL query language used in your existing client applications. @@ -66,14 +65,7 @@ The details may vary but you'll still see the same general pattern described in This topic does not describe details or APIs for any of the drivers mentioned above. All the drivers come with a complete set of documentation for exactly this task. -The following links provide some good starting points for learning about the interfaces for each specific driver: - -//TODO: Move this to the driver docs and replace this whole list with a link to the connect page. -* The https://docs.datastax.com/en/developer/java-driver/latest/manual/core/[core driver section] of the Java driver manual. -* The https://docs.datastax.com/en/developer/python-driver/latest/getting_started/[getting started guide] for the Python driver. -* The https://docs.datastax.com/en/developer/csharp-driver/latest/index.html#basic-usage[basic usage section] of the C# driver documentation. -* The https://docs.datastax.com/en/developer/cpp-driver/latest/topics/[getting started section] of the C/C++ driver documentation. -* The https://docs.datastax.com/en/developer/nodejs-driver/latest/#basic-usage[basic usage section] of the Node.js driver documentation. +For driver documentation, see xref:datastax-drivers:ROOT:index.adoc[]. == Connect applications to {product-proxy} diff --git a/modules/ROOT/pages/connect-clients-to-target.adoc b/modules/ROOT/pages/connect-clients-to-target.adoc index 20a640ec..3b0764e4 100644 --- a/modules/ROOT/pages/connect-clients-to-target.adoc +++ b/modules/ROOT/pages/connect-clients-to-target.adoc @@ -1,6 +1,5 @@ = Phase 5: Connect your client applications directly to the target :navtitle: Phase 5: Connect client applications directly to the target -:page-tag: migration,zdm,zero-downtime,zdm-proxy,connect-apps,target Phase 5 is the last phase of the xref:ROOT:introduction.adoc[migration process]. In this phase, you configure your client applications to connect directly and exclusively to the target cluster. @@ -142,8 +141,6 @@ session = cluster.connect() .Driver pseudocode to connect to {astra-db} [%collapsible] ==== -//Recalling the xref:connect-clients-to-proxy.adoc#_connecting_company_drivers_to_cassandra[pseudocode to enable your client application to connect to the proxy], here it is how your code needs to change to connect directly to {astra-db}: - The following pseudocode provides guidance on how you might change your driver's code to connect directly to {astra-db}. This is for illustration purposes only; the exact syntax depends on your driver and programming language. @@ -206,8 +203,4 @@ Your migration is now complete, and your target cluster is the source of truth f When you are ready, you can decommission your origin cluster and {product-proxy}, as these are no longer needed and clean xref:ROOT:rollback.adoc[rollback] is no longer possible. -If you need to revert to the origin cluster after this point, you must perform a full migration with your previous origin cluster as the target to ensure that all data is rewritten and synchronized back to the origin. - -== See also - -* https://www.datastax.com/events/migrating-your-legacy-cassandra-app-to-astra-db[Migrating your legacy {cass-reg} app to {astra-db}] \ No newline at end of file +If you need to revert to the origin cluster after this point, you must perform a full migration with your previous origin cluster as the target to ensure that all data is rewritten and synchronized back to the origin. \ No newline at end of file diff --git a/modules/ROOT/pages/contributions.adoc b/modules/ROOT/pages/contributions.adoc deleted file mode 100644 index 97f3a685..00000000 --- a/modules/ROOT/pages/contributions.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= Contribution guidelines -:page-tag: migration,zdm,zero-downtime,zdm-proxy,contributions - -{company} {product} ({product-short}) provides a simple and reliable way for users to migrate an existing {cass-reg} or {dse} cluster to {astra-db}, or to any {cass-short} or {dse-short} cluster, without any interruption of service to the client applications and data. - -{product-proxy} is open source software (OSS). We welcome contributions from the developer community via Pull Requests on a fork, for evaluation by the {product-short} team. - -The code sources for additional {product} components -- including {product-utility}, {product-automation}, {cass-migrator}, and {dsbulk-migrator} -- are available in public GitHub repos, where you may submit feedback and ideas via GitHub Issues. -Code contributions for those additional components are not open for PRs at this time. - -== {product-proxy} License - -{product-proxy} is licensed under the open-source {product-proxy-repo}/blob/main/LICENSE[**Apache-2.0 license agreement**]. - -== Contributor License Agreement - -Acceptance of the {company} https://cla.datastax.com/[Contributor License Agreement] (CLA) is required before we can consider accepting your {product-proxy} code contribution. -Refer to the https://cla.datastax.com/[CLA terms] and, if you agree, indicate your acceptance on each Pull Request (PR) that you submit while using the {product-proxy-repo}[{product-proxy} GitHub repository]. - -// You will see the CLA listed on the standard pull request checklist (TBS) -// for the {product-proxy-repo}[{product-proxy}] repository. - -== {product-proxy} code contributions - -The overall procedure: - -. Fork the {product-proxy-repo}[{product-proxy} open-source public repo]. -. Make your changes locally on your fork. Git commit and push only to your fork. -. Wait for CI to run successfully in GitHub Actions before submitting a PR. -. Submit a Pull Request (PR) with your forked updates. -As noted above, be sure to indicate in the PR's Comments your acceptance (if you agree) with the {company} https://cla.datastax.com/[Contributor License Agreement] (CLA). -. If you're not yet ready for a review, add "WIP" to the PR name to indicate it's a work in progress. -. Wait for the automated PR workflow to do some checks. -Members of the {product-proxy} community will review your PR and decide whether to approve and merge it. - -In addition to potential {product-proxy} OSS code contribution, we encourage you to submit feedback and ideas via GitHub Issues in the repo, starting from {product-proxy-repo}/issues. -Add a label to help categorize the issue, such as the complexity level, component name, and other labels you'll find in the repo's Issues display. - -== Submitting GitHub Issues in related public repos - -The following {company} {product} GitHub repos are public. -You are welcome to read the source and submit feedback and ideas via GitHub Issues per repo. -In addition to the {product-proxy-repo}[{product-proxy}] open-source repo, refer to: - -* {product-automation-repo}/issues[{product-automation}] repo for Ansible-based {product-automation} and {product-utility}. - -* {cass-migrator-repo}/issues[{cass-migrator}] repo. - -* {dsbulk-migrator-repo}/issues[{dsbulk-migrator}] repo. - -Again, add a label to help categorize each issue, such as the complexity level, component name, and other labels you'll find in the repo's Issues display. diff --git a/modules/ROOT/pages/create-target.adoc b/modules/ROOT/pages/create-target.adoc index 78a8c4dd..2baf9e7a 100644 --- a/modules/ROOT/pages/create-target.adoc +++ b/modules/ROOT/pages/create-target.adoc @@ -1,6 +1,5 @@ = Create the target environment for your migration :navtitle: Create target environment for migration -:page-tag: migration,zdm,zero-downtime,zdm-proxy,target In this phase of the 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. diff --git a/modules/ROOT/pages/deploy-proxy-monitoring.adoc b/modules/ROOT/pages/deploy-proxy-monitoring.adoc index dd9cdac2..4d9ff623 100644 --- a/modules/ROOT/pages/deploy-proxy-monitoring.adoc +++ b/modules/ROOT/pages/deploy-proxy-monitoring.adoc @@ -1,5 +1,4 @@ = Deploy {product-proxy} and monitoring -:page-tag: migration,zdm,zero-downtime,deploy,zdm-proxy,monitoring This topic explains how to use the Ansible automation playbooks that you set up in the xref:setup-ansible-playbooks.adoc[prior topic] to deploy {product-proxy} and its monitoring stack. diff --git a/modules/ROOT/pages/deployment-infrastructure.adoc b/modules/ROOT/pages/deployment-infrastructure.adoc index 87c91cae..86b9c6bb 100644 --- a/modules/ROOT/pages/deployment-infrastructure.adoc +++ b/modules/ROOT/pages/deployment-infrastructure.adoc @@ -1,5 +1,4 @@ = Deployment and infrastructure considerations -:page-tag: migration,zdm,zero-downtime,zdm-proxy,deploy,infrastructure As part of planning your migration, you need to prepare your infrastructure. diff --git a/modules/ROOT/pages/faqs.adoc b/modules/ROOT/pages/faqs.adoc index 7531b153..ce81fafe 100644 --- a/modules/ROOT/pages/faqs.adoc +++ b/modules/ROOT/pages/faqs.adoc @@ -1,6 +1,6 @@ = Frequently Asked Questions :navtitle: FAQs -:page-tag: migration,zdm,zero-downtime,zdm-proxy,faq +:page-aliases: ROOT:contributions.adoc If you're new to the {company} {product} features, these FAQs are for you. @@ -84,24 +84,19 @@ Before {company} {product} was available, migrating client applications between == Is there support available if I have questions or issues during our migration? -{product-proxy} and related software tools in the migration suite include technical assistance by {support-url}[{company} Support] for {dse-short} and Luna subscribers, and {astra} users who are on an Enterprise plan. -Free and Pay As You Go plan users do not have support access and must raise questions in the {astra-ui} chat. -https://www.datastax.com/products/luna[Luna] is a subscription to the {cass} support and expertise at {company}. +{product-proxy} and related software tools in the migration suite include technical assistance by {support-url}[{company} Support] for {dse-short} users, https://www.ibm.com/docs/en/esfac[IBM Elite Support for {cass}] subscribers, and {astra} organizations on an Enterprise plan. For any observed problems with {product-proxy}, submit a {product-proxy-repo}/issues[GitHub Issue] in the {product-proxy} GitHub repo. Additional examples serve as templates, from which you can learn about migrations. {company} does not assume responsibility for making the templates work for specific use cases. -== Where are the public GitHub repos? - -//TODO: Move to contribution guide. +== Can I contribute to {product-proxy}? -All the {product-proxy} GitHub repos are public and open source. -You are welcome to read the code and submit feedback via GitHub Issues per repo. -In addition to sending feedback, you may submit Pull Requests (PRs) for potential inclusion. +Yes. +See https://github.com/datastax/zdm-proxy/blob/main/CONTRIBUTING.md[CONTRIBUTING.md]. -To submit PRs, you must for first agree to the https://cla.datastax.com/[{company} Contribution License Agreement (CLA)]. +== Where are the public GitHub repos? * {product-proxy-repo}[{product-proxy}] repo. @@ -111,7 +106,6 @@ To submit PRs, you must for first agree to the https://cla.datastax.com/[{compan * {dsbulk-migrator-repo}[dsbulk-migrator] repo for the tool that allows simple data migrations without validation and reconciliation capabilities. - == Does {product-proxy} support Transport Layer Security (TLS)? Yes, and here's a summary: @@ -164,14 +158,5 @@ At the same time, with on-premise clusters you take on the cost of infrastructur Ranging from large enterprises to small teams, IT managers, operators, and developers are realizing that the Total Cost of Ownership (TCO) with cloud solutions is much lower than continuing to run on-prem physical data centers. A CNDB like {astra-db} is a different environment. -Running on proven cloud providers like AWS, Google Cloud, and Azure, {astra-db} greatly reduces complexity and increases convenience by surfacing a subset of configurable settings, providing a UI (the {astra-ui}) and APIs and CLI tools to interact with your {astra-db} organizations and databases. - -//TODO: Content to incorporate somewhere: - -//// -Zero-Downtime Migration (ZDM) Proxy is a proxy that mirrors traffic between the origin and target database. The requests are CQL-oriented - effectively, any database that uses the Cassandra drivers can use the proxy. Therefore, it can be used with Apache Cassandra, DataStax Enterprise (including Search and Graph through the driver), ScyllaDB, Instaclutsr, Amazon Keyspaces, Microsoft CosmosDB, Aiven’s Cassandra, Yugabyte, and anything else that the drivers can connect to. A matrix of what we’ve tested is found here: CQL databases tested with ZDM Proxy. - -Cassandra Data Migrator migrates historical data and does validation and reconciliation. It uses the CQL interface to do its work. Therefore, it can be used to migrate data from any origin database that speaks CQL. - -Astra DB Sideloader is able to import native Cassandra data (sstables) such as backups from an origin database and load them directly into the Astra Serverless data plane. Because it takes native Cassandra data, we can only import data from (specific versions of) native Cassandra databases such as Apache Cassandra, DataStax Enterprise, Hyper-Converged Database, Instaclustr, and Aiven. Sideloader cannot import data from databases that are simply Cassandra compatible, such as ScyllaDB, Keyspaces, CosmosDB, or Yugabyte, which don’t have the same native Cassandra format. In such cases, customers can use the Cassandra Data Migrator, which uses CQL. -//// \ No newline at end of file +Running on proven cloud providers like AWS, Google Cloud, and Azure, {astra-db} greatly reduces complexity and increases convenience by surfacing a subset of configurable settings. +It provides a UI (the {astra-ui}), APIs, and CLI tools to interact with your {astra-db} organizations and databases. \ No newline at end of file diff --git a/modules/ROOT/pages/feasibility-checklists.adoc b/modules/ROOT/pages/feasibility-checklists.adoc index c8ce515d..f1abed2c 100644 --- a/modules/ROOT/pages/feasibility-checklists.adoc +++ b/modules/ROOT/pages/feasibility-checklists.adoc @@ -1,5 +1,4 @@ = Feasibility checks -:page-tag: migration,zdm,zero-downtime,zdm-proxy,feasibility :page-aliases: ROOT:preliminary-steps.adoc Before starting your migration, refer to the following considerations to ensure that your client application workload and xref:glossary.adoc#origin[**Origin**] are suitable for this {product} process. @@ -66,7 +65,7 @@ For example, if your compound primary key is `PRIMARY KEY (A, B)` and you always == Considerations for {astra-db} 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 https://docs.datastax.com/en/astra-serverless/docs/plan/planning.html#_astra_db_database_guardrails_and_limits[guardrails and limits] to make sure that your application workload can be successful within these limits. +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. diff --git a/modules/ROOT/pages/glossary.adoc b/modules/ROOT/pages/glossary.adoc index 52146546..fd245662 100644 --- a/modules/ROOT/pages/glossary.adoc +++ b/modules/ROOT/pages/glossary.adoc @@ -1,5 +1,4 @@ = Glossary -:page-tag: migration,zdm,zero-downtime,glossary //TODO: Determine which terms are actually needed. Convert to partials if the definitions need to be repeated, otherwise replace links to this page with links to more useful and complete information. @@ -27,7 +26,7 @@ For more information, see xref:ROOT:enable-async-dual-reads.adoc[]. {cass-short} Query Language (CQL) is a query language for the {cass-short} database. It includes DDL and DML statements. -For details, see https://docs.datastax.com/en/astra/astra-db-vector/cql/develop-with-cql.html[Develop with the {cass-short} Query Language]. +For details, see the xref:cql:ROOT:index.adoc[{cass-short} Query Language documentation]. == Dual-write logic diff --git a/modules/ROOT/pages/hcd-migration-paths.adoc b/modules/ROOT/pages/hcd-migration-paths.adoc index 319bda3e..5781538b 100644 --- a/modules/ROOT/pages/hcd-migration-paths.adoc +++ b/modules/ROOT/pages/hcd-migration-paths.adoc @@ -27,7 +27,6 @@ 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 xref:ROOT:cassandra-data-migrator.adoc[{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.3 doesn't support tuples in {dse-short} versions 6.8.4 and earlier. 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. @@ -76,5 +75,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@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 +* 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 diff --git a/modules/ROOT/pages/introduction.adoc b/modules/ROOT/pages/introduction.adoc index 2e405053..5d0afb98 100644 --- a/modules/ROOT/pages/introduction.adoc +++ b/modules/ROOT/pages/introduction.adoc @@ -1,7 +1,6 @@ = Phases of the {product} process :navtitle: About the {product-short} process :description: Before you begin, learn about migration concepts, software components, and the sequence of operations. -:page-tag: migration,zdm,zero-downtime,zdm-proxy,introduction 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. @@ -128,7 +127,7 @@ image:migration-phase5ra.png["Migration Phase 5."] [#lab] == {product} interactive lab -As a companion to the {product-short} documentation, you can use the https://www.datastax.com/dev/zdm[{product} interactive lab] to try the entire migration process in a demo environment. +As a companion to the {product-short} documentation, you can use the https://app.gitpod.io/login?navigateTo=%2F%23https%3A%2F%2Fgithub.com%2FDataStax-Academy%2Fzdm-scenario-katapod.git[{product} interactive lab] to try the entire migration process in a demo environment. The lab only requires a GitHub account and a supported browser. All browsers are supported except Safari. diff --git a/modules/ROOT/pages/manage-proxy-instances.adoc b/modules/ROOT/pages/manage-proxy-instances.adoc index 8c2ff379..9e36d1b5 100644 --- a/modules/ROOT/pages/manage-proxy-instances.adoc +++ b/modules/ROOT/pages/manage-proxy-instances.adoc @@ -1,5 +1,4 @@ = Manage your {product-proxy} instances -:page-tag: migration,zdm,zero-downtime,zdm-proxy In this topic, we'll learn how to perform simple operations on your {product-proxy} deployment with no interruption to its availability: diff --git a/modules/ROOT/pages/metrics.adoc b/modules/ROOT/pages/metrics.adoc index 6f5bbd74..397eeb84 100644 --- a/modules/ROOT/pages/metrics.adoc +++ b/modules/ROOT/pages/metrics.adoc @@ -1,5 +1,4 @@ = Leverage metrics provided by {product-proxy} -:page-tag: migration,zdm,zero-downtime,metrics This topic provides detailed information about the metrics captured by {product-proxy} and explains how to interpret the metrics. diff --git a/modules/ROOT/pages/phase1.adoc b/modules/ROOT/pages/phase1.adoc index d2a61a01..78473841 100644 --- a/modules/ROOT/pages/phase1.adoc +++ b/modules/ROOT/pages/phase1.adoc @@ -1,5 +1,4 @@ = Phase 1: Deploy {product-proxy} and connect client applications -:page-tag: migration,zdm,zero-downtime,deploy,zdm-proxy,connect-apps This section presents the following: @@ -9,6 +8,4 @@ This section presents the following: * xref:connect-clients-to-proxy.adoc[] * xref:manage-proxy-instances.adoc[] -image::migration-phase1ra.png[Phase 1 diagram shows deployed {product-proxy} instances, client app connections to proxies, and the target cluster is setup.] - -//For illustrations of all the migration phases, see the xref:introduction.adoc#_migration_phases[Introduction]. +image::migration-phase1ra.png[Phase 1 diagram shows deployed {product-proxy} instances, client app connections to proxies, and the target cluster is setup.] \ No newline at end of file diff --git a/modules/ROOT/pages/rollback.adoc b/modules/ROOT/pages/rollback.adoc index 364580c0..45cab323 100644 --- a/modules/ROOT/pages/rollback.adoc +++ b/modules/ROOT/pages/rollback.adoc @@ -1,6 +1,5 @@ = Understand the rollback options :navtitle: Understand rollback options -:page-tag: migration,zdm,zero-downtime,rollback At any point from Phase 1 through Phase 4, if you encounter an unexpected issue and need to stop or roll back the migration, you can revert your client applications to connect directly to the origin cluster. diff --git a/modules/ROOT/pages/setup-ansible-playbooks.adoc b/modules/ROOT/pages/setup-ansible-playbooks.adoc index 1f598b9a..a48fa305 100644 --- a/modules/ROOT/pages/setup-ansible-playbooks.adoc +++ b/modules/ROOT/pages/setup-ansible-playbooks.adoc @@ -1,5 +1,4 @@ = Set up {product-automation} with {product-utility} -:page-tag: migration,zdm,zero-downtime,zdm-automation,zdm-proxy,ansible This page explains how to use {product-utility} to set up the Ansible Control Host container for {product-automation}. diff --git a/modules/ROOT/pages/tls.adoc b/modules/ROOT/pages/tls.adoc index 62c2be28..7f32cdc4 100644 --- a/modules/ROOT/pages/tls.adoc +++ b/modules/ROOT/pages/tls.adoc @@ -1,6 +1,5 @@ = Configure Transport Layer Security (TLS) :navtitle: Configure Transport Layer Security -:page-tag: migration,zdm,zero-downtime,tls,transport-layer,zdm-proxy {product-proxy} supports proxy-to-cluster and application-to-proxy TLS encryption. diff --git a/modules/ROOT/pages/troubleshooting-scenarios.adoc b/modules/ROOT/pages/troubleshooting-scenarios.adoc index f5ae48d8..6b68f9f2 100644 --- a/modules/ROOT/pages/troubleshooting-scenarios.adoc +++ b/modules/ROOT/pages/troubleshooting-scenarios.adoc @@ -1,5 +1,4 @@ = Troubleshooting scenarios -:page-tag: migration,zdm,zero-downtime,zdm-proxy,troubleshooting //TODO: use same format as driver troubleshooting. //TODO: Remove or hide issues that have been resolved by a later release. @@ -143,18 +142,9 @@ None. == Authentication errors -=== Symptoms - -[source,log] ----- -{"log":"\u001b[33mWARN\u001b[0m[0110] Secondary (TARGET) handshake failed with an auth error, returning ERROR AUTHENTICATION ERROR (code=ErrorCode AuthenticationError [0x00000100], msg=We recently improved your database security. To find out more and reconnect, see https://docs.datastax.com/en/astra/docs/manage-application-tokens.html) to client. \r\n","stream":"stdout","time":"2022-09-06T18:31:31.348472345Z"} ----- - -=== Cause +Authentication errors indicate that credentials are incorrect or have insufficient permissions. -Credentials are incorrect or have insufficient permissions. - -There are three sets of credentials in play with {product-proxy}: +There are three sets of credentials used with {product-proxy}: * Target: credentials that you set in the proxy configuration through the `ZDM_TARGET_USERNAME` and `ZDM_TARGET_PASSWORD` settings. @@ -162,24 +152,18 @@ There are three sets of credentials in play with {product-proxy}: * Client: credentials that the client application sends to the proxy during the connection handshake, these are set in the application configuration, not the proxy configuration. -This error means that at least one of these three sets of credentials is incorrect or has insufficient permissions. - -=== Solution or Workaround +Authentication errors mean that at least one of these three sets of credentials is incorrect or has insufficient permissions. If the authentication error is preventing the proxy from starting then it's either the origin or target credentials that are incorrect or have insufficient permissions. The log message shows whether it is the origin or target handshake that is failing. -If the proxy is able to start up -- that is, this message can be seen in the logs: - -`Proxy started. Waiting for SIGINT/SIGTERM to shutdown.` - -then the authentication error is happening when a client application tries to open a connection to the proxy. -In this case, the issue is with the Client credentials so the application itself is using invalid credentials (incorrect username/password or insufficient permissions). +If the proxy is able to start up, and you can see the following message in the logs: `Proxy started. Waiting for SIGINT/SIGTERM to shutdown`, then the authentication error is happening when a client application tries to open a connection to the proxy. +In this case, the issue is with the client credentials. +The application itself is using invalid credentials, such as an incorrect username/password, expired token, or insufficient permissions. Note that the proxy startup message has log level `INFO`, so if the configured log level on the proxy is `warning` or `error`, you must rely on other ways to know whether {product-proxy} started correctly. You can check if the docker container is running (or process if docker isn't being used) or if there is a log message similar to `Error launching proxy`. - == {product-proxy} listens on a custom port, and all applications are able to connect to one proxy instance only === Symptoms diff --git a/modules/ROOT/pages/troubleshooting-tips.adoc b/modules/ROOT/pages/troubleshooting-tips.adoc index d4a2377b..308d1210 100644 --- a/modules/ROOT/pages/troubleshooting-tips.adoc +++ b/modules/ROOT/pages/troubleshooting-tips.adoc @@ -1,5 +1,4 @@ = Troubleshooting tips -:page-tag: migration,zdm,zero-downtime,zdm-proxy,troubleshooting :page-aliases: ROOT:troubleshooting.adoc :description: Get help with {product}. @@ -7,7 +6,7 @@ This page provides general troubleshooting advice and describes some common issu For specific error messages, see xref:troubleshooting-scenarios.adoc[]. -You can also contact your {company} account representative or {support-url}[{company} Support], if you have a https://www.datastax.com/products/luna[Luna service contract]. +You can also contact your {company} account representative or {support-url}[{company} Support], if you have an IBM Elite Support for {cass} contract. [#proxy-logs] == {product-proxy} logs diff --git a/modules/ROOT/partials/migration-scenarios.adoc b/modules/ROOT/partials/migration-scenarios.adoc index 1f8b5d77..daec618d 100644 --- a/modules/ROOT/partials/migration-scenarios.adoc +++ b/modules/ROOT/partials/migration-scenarios.adoc @@ -3,15 +3,15 @@ You can use {product-proxy} to support migrations from {cass-reg}, {dse}, {hcd}, Compatible origin clusters:: Migrate from one of the following: + -* https://www.datastax.com/products/datastax-enterprise[{dse}] version 4.7.1 and later -* https://cassandra.apache.org/_/index.html[{cass-reg}] version 2.1.6 and later +* {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. Compatible target clusters:: Migrate to one of the following: + -* https://www.datastax.com/products/hyper-converged-database-hcd[{hcd}] +* {hcd} * A cluster running the same or later version of {cass-short} or {dse-short} -* https://www.datastax.com/products/datastax-astra[{astra-db}] +* {astra-db} + For more {astra-db} migration paths, see xref:ROOT:astra-migration-paths.adoc[]. \ No newline at end of file diff --git a/modules/sideloader/pages/migrate-sideloader.adoc b/modules/sideloader/pages/migrate-sideloader.adoc index 326bdcb5..eca68e26 100644 --- a/modules/sideloader/pages/migrate-sideloader.adoc +++ b/modules/sideloader/pages/migrate-sideloader.adoc @@ -195,8 +195,6 @@ For example, {astra-db} doesn't support materialized views, and {sstable-sideloa However, indexes don't need to match. You can define indexes in your target database independently from the origin cluster because {sstable-sideloader} ignores Storage Attached Indexes (SAI) defined on the origin cluster. During the migration, {sstable-sideloader} automatically populates any SAI defined in your target database, even if those SAI weren't present in your origin cluster. -//TODO: Difference between "indexes" and "SAI" here? -//You can define {astra-db}-supported indexes independently on the target database and they will populate as part of the data migration process. ==== . Get the following schema properties for _each table_ that you want to migrate: @@ -230,7 +228,7 @@ CREATE TABLE smart_home.sensor_readings ( PRIMARY KEY (device_id, room_id, reading_timestamp) ) WITH CLUSTERING ORDER BY (room_id ASC, reading_timestamp DESC); ---- -//However, {sstable-sideloader} cannot import data to a xref:astra-db-serverless:databases:collection in a {db-serverless-vector} database. + . Recreate the schemas in your target database: + .. In the {astra-ui-link} navigation menu, click *Databases*, and then click the name of your {astra-db} database. @@ -241,7 +239,6 @@ image::sideloader:cql-console-create-identical-schema.png[] + {astra-db} rejects or ignores some table properties, such as compaction strategy. See xref:astra-db-serverless:databases:database-limits.adoc[] for more information. -//TODO: Does this matter? . In your terminal, set environment variables for your target database: + @@ -789,5 +786,4 @@ include::sideloader:partial$validate.adoc[] == See also * xref:sideloader:cleanup-sideloader.adoc[] -* xref:sideloader:troubleshoot-sideloader.adoc[] -* https://www.datastax.com/events/migrating-your-legacy-cassandra-app-to-astra-db[Migrating your legacy {cass-reg} app to {astra-db}] \ No newline at end of file +* xref:sideloader:troubleshoot-sideloader.adoc[] \ No newline at end of file diff --git a/modules/sideloader/pages/prepare-sideloader.adoc b/modules/sideloader/pages/prepare-sideloader.adoc index 49526348..92605324 100644 --- a/modules/sideloader/pages/prepare-sideloader.adoc +++ b/modules/sideloader/pages/prepare-sideloader.adoc @@ -22,22 +22,15 @@ Make sure you understand how to securely store and use sensitive credentials whe * Your {astra} organization must be on an *Enterprise* xref:astra-db-serverless:administration:subscription-plans.adoc[subscription plan]. + -{sstable-sideloader} is a premium feature that incurs costs based on usage: +{sstable-sideloader} is a premium feature that incurs costs based on usage. +This includes the total amount (GB) of data processed as part of the {sstable-sideloader} workload, and the amount of data stored in the migration bucket is metered at the standard {astra-db} storage rate. + -** Total amount (GB) of data processed as part of the {sstable-sideloader} workload. -** The amount of data stored in the migration bucket is metered at the standard {astra-db} storage rate. - -+ --- -For more information and specific rates, see the https://www.datastax.com/pricing/astra-db[{astra} Pricing page]. - [TIP] ==== Migration directories are automatically cleaned up after one week of idle time. To minimize costs, you can xref:sideloader:cleanup-sideloader.adoc[manually clean up migration directories] when you no longer need them. ==== --- * Your target database must be an {astra-db} Serverless database. + diff --git a/modules/sideloader/pages/troubleshoot-sideloader.adoc b/modules/sideloader/pages/troubleshoot-sideloader.adoc index cb74602a..ecda4a35 100644 --- a/modules/sideloader/pages/troubleshoot-sideloader.adoc +++ b/modules/sideloader/pages/troubleshoot-sideloader.adoc @@ -61,7 +61,6 @@ If the migration fails again, see <>. //// Future: === Reset failed migration endpoint -https://datastax.slack.com/archives/C044Q060210/p1741772318884679?thread_ts=1741691860.400749&cid=C044Q060210 TODO: Add to this page and stop-restart page. "resetting" a failed/aborted migration: