>.
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:6.9@dse:drivers:cassandra-drivers-overview.adoc[{dse-short}-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.
+Read-only {dse-short} Search workloads can be moved directly from the origin to the target without {zdm-proxy} being involved.
+If your client application uses Search and also issues writes, or if you need the read routing capabilities from {zdm-proxy}, then you can connect your Search workloads to {zdm-proxy} as long as you are using xref:6.9@dse:drivers:cassandra-drivers-overview.adoc[{dse-short}-compatible drivers] to submit these queries.
+This approach means the queries are regular CQL `SELECT` statements, so {zdm-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.
@@ -308,7 +308,7 @@ If you use the HTTP API then you can either modify your applications to use the
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.
+As mentioned previously, this is because {zdm-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].
@@ -318,8 +318,8 @@ In self-managed clusters, such as {dse-short} and {cass-short}, you can configur
However, the xref:astra-db-serverless:databases:database-limits.adoc#cassandra-configuration-properties[{astra} `cassandra.yml`] cannot be changed unless explicitly approved and implemented by {company}.
{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.
+`CL.ONE` isn't supported by {astra}, and read and write requests sent through {zdm-proxy} with `CL.ONE` to {astra-db} databases always fail.
+{zdm-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::
@@ -329,25 +329,25 @@ Before you migrate, you must change your applications to use other programmatic
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 versions 2.1.0 and later, {zdm-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 {zdm-automation}.
+
-In {product-proxy} versions earlier than 2.1.0, read-only applications require special handling to avoid connection termination due to inactivity.
+In {zdm-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.
+{company} recommends that you use {zdm-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.
+Complex migration scenarios, such as multi-datacenter migrations or many-to-one migrations, require additional planning to configure {zdm-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].
+To configure {zdm-proxy} for a multi-datacenter migration, see the xref:ROOT:deployment-infrastructure.adoc[{zdm-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
+Next, xref:ROOT:deployment-infrastructure.adoc[prepare the {zdm-proxy} infrastructure].
\ No newline at end of file
diff --git a/modules/ROOT/pages/hcd-migration-paths.adoc b/modules/ROOT/pages/hcd-migration-paths.adoc
index f793e25c..3993a87d 100644
--- a/modules/ROOT/pages/hcd-migration-paths.adoc
+++ b/modules/ROOT/pages/hcd-migration-paths.adoc
@@ -3,29 +3,29 @@
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}.
+Whenever possible, {company} strongly recommends using the {zdm} 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.
+The {zdm} tools allow you to standup your new {hcd-short} clusters independently of your existing {dse-short} clusters.
+Then, {zdm-proxy} orchestrates live traffic and synchronizes ongoing writes while you migrate data to your new clusters using any {zdm-short}-compatible data migration and validation tool.
+Finally, you can use {zdm-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.
+{zdm-proxy} and {zdm-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.
+By orchestrating independent clusters with the {zdm-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 remains active and unchanged while you set up the new cluster and migrate your data.
-=== Data validation with {product-short}
+=== Data validation with {zdm-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.
+The {zdm-short} tools don't migrate your data.
+During the {zdm-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 xref:ROOT:cassandra-data-migrator.adoc[{cass-migrator}].
+* Choose a data migration tool that also includes strong validation capabilities, such as {cass-migrator-repo-url}[{cass-migrator}].
* Be aware of incompatible data types that can fail to migrate from your old cluster.
Data validation tools can identify inconsistencies as missing or mismatched data, but you still need to have a plan to resolve them.
@@ -33,16 +33,16 @@ For example, you might need to modify your applications to use a different 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.
+{zdm-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}
+=== Get started with {zdm-short} and {hcd-short}
-For information about clusters that are eligible for {product} to {hcd-short}, see xref:ROOT:zdm-proxy-migration-paths.adoc[].
+For information about clusters that are eligible for {zdm} to {hcd-short}, see xref:ROOT:zdm-proxy-migration-paths.adoc[].
-To begin your {product} to {hcd-short}, go to xref:ROOT:introduction.adoc[].
+To begin your {zdm} to {hcd-short}, go to xref:ROOT:introduction.adoc[].
-You must set up your {hcd-short} clusters before you can enable the {product-proxy}.
+You must set up your {hcd-short} clusters before you can enable the {zdm-proxy}.
For information about installing and configuring {hcd-short}, see the xref:hyper-converged-database:get-started:get-started-hcd.adoc[{hcd-short} documentation].
== Migrate your code
diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc
index 65997e64..6777e3b7 100644
--- a/modules/ROOT/pages/index.adoc
+++ b/modules/ROOT/pages/index.adoc
@@ -16,7 +16,7 @@
Bulk-load terabytes while shifting traffic with little or no downtime, securely and reliably.
- xref:ROOT:introduction.adoc[Get started with {product},role="btn btn-primary btn-solid"]
+ xref:ROOT:introduction.adoc[Get started with {zdm},role="btn btn-primary btn-solid"]
xref:ROOT:components.adoc[Compare tools,role="btn btn-neutral btn-outlined"]
@@ -43,11 +43,11 @@ svg::sideloader:astra-migration-toolkit.svg[role="absolute bottom-1/2 translate-
svg:common:ROOT:icons/datastax/cloud-backup-restore.svg[role="mx-auto max-w-xs md:mx-0 lg:max-w-none"]
- {product-proxy}
+ {zdm-proxy}
- To support live migrations, {product-proxy} orchestrates activity-in-transition on your clusters, allowing your applications to run while you migrate data.
+ To support live migrations, {zdm-proxy} orchestrates activity-in-transition on your clusters, allowing your applications to run while you migrate data.
- xref:ROOT:introduction.adoc[Get started with {product-short}]
+ xref:ROOT:introduction.adoc[Get started with {zdm-short}]
@@ -73,7 +73,7 @@ svg::sideloader:astra-migration-toolkit.svg[role="absolute bottom-1/2 translate-
{cass-migrator-short} can migrate and validate data between {cass-short}-based clusters, with optional logging and reconciliation support.
- xref:ROOT:cassandra-data-migrator.adoc[Get started with {cass-migrator-short}]
+ {cass-migrator-repo-url}[Get started with {cass-migrator-short}]
diff --git a/modules/ROOT/pages/introduction.adoc b/modules/ROOT/pages/introduction.adoc
index 259ef8f1..5a449e64 100644
--- a/modules/ROOT/pages/introduction.adoc
+++ b/modules/ROOT/pages/introduction.adoc
@@ -1,12 +1,12 @@
-= Phases of the {product} process
-:navtitle: About the {product-short} process
+= Phases of the {zdm} process
+:navtitle: About the {zdm-short} process
:description: Before you begin, learn about migration concepts, software components, and the sequence of operations.
-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.
+With the {zdm} 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.
-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}.
+The {zdm-short} process uses {zdm-proxy}, {zdm-utility}, and {zdm-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}.
-{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).
+{zdm-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, all data is present in the new database, and you can switch your client applications to connect exclusively to the new database.
@@ -15,15 +15,15 @@ The old database becomes obsolete and can be shut down.
.Requirements for zero downtime
[IMPORTANT]
====
-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.
+True zero downtime migration with {zdm-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 {zdm-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 connect to your origin cluster, {product-proxy}, and the target cluster during each phase.
+The following sections describe the major events in each phase and how your client applications connect to your origin cluster, {zdm-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}.
@@ -32,41 +32,41 @@ The _target cluster_ is your new {cass-short}-based environment where you want t
=== Plan and prepare for your migration
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.
+Over the course of the migration, the contact points change to incorporate {zdm-proxy} and eventually switch to the target database.
image::ROOT:pre-migration0ra.svg[Before the migration begins, your applications connect exclusively to your origin cluster]
To plan and prepare for the migration, do the following:
-. 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}.
+. xref:ROOT:feasibility-checklists.adoc[Review compatibility requirements for {zdm-proxy}]: Make sure your clusters, data model, and application logic are compatible with {zdm-proxy}, and understand how certain operations are handled by {zdm-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.
+To successfully migrate with {zdm-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.
====
-. xref:ROOT:deployment-infrastructure.adoc[]: Set up the infrastructure to host the {product-short} tools.
+. xref:ROOT:deployment-infrastructure.adoc[]: Set up the infrastructure to host the {zdm-short} tools.
. xref:ROOT:create-target.adoc[]: Set up your target cluster, and create schemas that match those on your origin cluster.
. 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
+=== Phase 1: Deploy {zdm-proxy} and connect client applications
-In this first phase, deploy the {product-proxy} instances and connect client applications to the proxies.
+In this first phase, deploy the {zdm-proxy} instances and connect client applications to the proxies.
This phase activates the dual-write logic.
Writes are sent to both the origin and target databases, while reads are executed on the origin only.
-For more information and instructions, see xref:ROOT:phase1.adoc[Phase 1: Deploy and connect {product-proxy}].
+For more information and instructions, see xref:ROOT:phase1.adoc[Phase 1: Deploy and connect {zdm-proxy}].
-image::ROOT:migration-phase1ra.svg[In Phase 1, you deploy and connect {product-proxy}]
+image::ROOT:migration-phase1ra.svg[In Phase 1, you deploy and connect {zdm-proxy}]
=== Phase 2: Migrate data
In this phase, you use a data migration tool to copy your existing data to the target database.
-{product-proxy} continues to perform dual writes so that you can focus on moving data that was present before you connected {product-proxy}.
+{zdm-proxy} continues to perform dual writes so that you can focus on moving data that was present before you connected {zdm-proxy}.
Then, you thoroughly validate the migrated data, resolving missing and mismatched records, before moving on to the next phase.
For more information and instructions, see xref:ROOT:migrate-and-validate-data.adoc[].
@@ -79,15 +79,15 @@ This phase is optional but recommended.
In this phase, you can enable the _asynchronous dual reads_ feature to test the target database's ability to handle a production workload before you permanently switch your applications to the target database at the end of the migration process.
-When enabled, {product-proxy} sends asynchronous read requests to the secondary database in addition to the synchronous read requests that are sent to the primary database by default.
+When enabled, {zdm-proxy} sends asynchronous read requests to the secondary database in addition to the synchronous read requests that are sent to the primary database by default.
-For more information, see xref:ROOT:enable-async-dual-reads.adoc[] and xref:ROOT:components.adoc#how_zdm_proxy_handles_reads_and_writes[How {product-proxy} handles reads and writes].
+For more information, see xref:ROOT:enable-async-dual-reads.adoc[] and xref:ROOT:components.adoc#how_zdm_proxy_handles_reads_and_writes[How {zdm-proxy} handles reads and writes].
image::ROOT:migration-phase3ra.svg[In Phase 3, you test your target cluster's production readiness]
=== Phase 4: Route reads to the target database
-In this phase, read routing on {product-proxy} is switched to the target database so that all reads are executed on the target.
+In this phase, read routing on {zdm-proxy} is switched to the target database so that all reads are executed on the target.
Writes are still sent to both databases in case you need to rollback the migration.
At this point, the target database becomes the primary database.
@@ -98,21 +98,21 @@ image::ROOT:migration-phase4ra.svg[In Phase 4, you route reads to the target clu
=== Phase 5: Connect directly to the target database
-In the final phase of the migration, you move your client applications off {product-proxy} and connect them directly to the target database.
+In the final phase of the migration, you move your client applications off {zdm-proxy} and connect them directly to the target database.
Once this happens, the migration is complete, and you now exclusively use the target database.
Whether you choose to destroy to retain the origin database depends on your organization's policies and whether you might need to revert to it in the future.
-However, be aware that the origin database is no longer synchronized with the target database, and the origin database won't contain writes that happen after you disconnect {product-proxy}.
+However, be aware that the origin database is no longer synchronized with the target database, and the origin database won't contain writes that happen after you disconnect {zdm-proxy}.
For more information, see xref:ROOT:connect-clients-to-target.adoc[].
image::ROOT:migration-phase5ra.svg[In Phase 5, you connect your client applications directly and exclusively to the target cluster]
[#lab]
-== {product} interactive lab
+== {zdm} interactive lab
-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.
+As a companion to the {zdm-short} documentation, you can use the https://app.gitpod.io/login?navigateTo=%2F%23https%3A%2F%2Fgithub.com%2FDataStax-Academy%2Fzdm-scenario-katapod.git[{zdm} 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 a26b1b1c..6e9539f3 100644
--- a/modules/ROOT/pages/manage-proxy-instances.adoc
+++ b/modules/ROOT/pages/manage-proxy-instances.adoc
@@ -1,13 +1,13 @@
-= Manage your {product-proxy} instances
+= Manage your {zdm-proxy} instances
-After you deploy {product-proxy} instances, you might need to perform various management operations, such as rolling restarts, configuration changes, log inspection, version upgrades, and infrastructure changes.
+After you deploy {zdm-proxy} instances, you might need to perform various management operations, such as rolling restarts, configuration changes, log inspection, version upgrades, and infrastructure changes.
-If you are using {product-automation}, you can use Ansible playbooks for all of these operations.
+If you are using {zdm-automation}, you can use Ansible playbooks for all of these operations.
[#perform-a-rolling-restart-of-the-proxies]
== Perform a rolling restart of the proxies
-Rolling restarts of the {product-proxy} instances are useful to apply configuration changes or to upgrade the {product-proxy} version without impacting the availability of the deployment.
+Rolling restarts of the {zdm-proxy} instances are useful to apply configuration changes or to upgrade the {zdm-proxy} version without impacting the availability of the deployment.
[IMPORTANT]
====
@@ -15,9 +15,9 @@ A rolling restart is a destructive action because it stops the previous containe
xref:ROOT:zdm-logs.adoc[Collect the logs] before you apply the configuration change if you want to keep them.
====
-=== Rolling restart with {product-automation}
+=== Rolling restart with {zdm-automation}
-If you use {product-automation} to manage your {product-proxy} deployment, you can use a dedicated playbook to perform rolling restarts of all {product-proxy} instances in a deployment:
+If you use {zdm-automation} to manage your {zdm-proxy} deployment, you can use a dedicated playbook to perform rolling restarts of all {zdm-proxy} instances in a deployment:
. Connect to your Ansible Control Host container.
+
@@ -48,29 +48,29 @@ ubuntu@52772568517c:~$
ansible-playbook rolling_update_zdm_proxy.yml -i zdm_ansible_inventory
----
-The rolling restart playbook re-creates each {product-proxy} container, one by one.
-The {product-proxy} deployment remains available at all times, and you can safely use it throughout this operation.
+The rolling restart playbook re-creates each {zdm-proxy} container, one by one.
+The {zdm-proxy} deployment remains available at all times, and you can safely use it throughout this operation.
If you modified mutable configuration variables, the new containers use the updated configuration files.
The playbook performs the following actions automatically:
-. {product-automation} stops one container gracefully, and then waits for it to shut down.
-. {product-automation} re-creates the container, and then starts it.
-. {product-automation} calls the xref:ROOT:metrics.adoc#call-the-liveliness-and-readiness-endpoints[readiness endpoint] to check the container's status:
+. {zdm-automation} stops one container gracefully, and then waits for it to shut down.
+. {zdm-automation} re-creates the container, and then starts it.
+. {zdm-automation} calls the xref:ROOT:metrics.adoc#call-the-liveliness-and-readiness-endpoints[readiness endpoint] to check the container's status:
+
-* If the status check fails, {product-automation} repeats the check up to six times at 5-second intervals.
-If all six attempts fail, {product-automation} interrupts the entire rolling restart process.
-* If the check succeeds, {product-automation} waits a fixed amount of time, and then moves on to the next container.
+* If the status check fails, {zdm-automation} repeats the check up to six times at 5-second intervals.
+If all six attempts fail, {zdm-automation} interrupts the entire rolling restart process.
+* If the check succeeds, {zdm-automation} waits a fixed amount of time, and then moves on to the next container.
The default pause between containers is 10 seconds.
You can change the pause duration in `zdm-proxy-automation/ansible/vars/zdm_playbook_internal_config.yml`.
-=== Rolling restart without {product-automation}
+=== Rolling restart without {zdm-automation}
-If you don't use {product-automation}, you must manually restart each instance.
+If you don't use {zdm-automation}, you must manually restart each instance.
To avoid downtime, wait for each instance to fully restart and begin receiving traffic before restarting the next instance.
-== Inspect {product-proxy} logs
+== Inspect {zdm-proxy} logs
include::ROOT:partial$zdm-logs-intro.adoc[]
For more information, see xref:ROOT:zdm-logs.adoc[].
@@ -78,11 +78,11 @@ For more information, see xref:ROOT:zdm-logs.adoc[].
[[change-mutable-config-variable]]
== Change mutable configuration variables
-Some, but not all, configuration variables can be changed after you deploy a {product-proxy} instance.
+Some, but not all, configuration variables can be changed after you deploy a {zdm-proxy} instance.
-This section lists the _mutable_ configuration variables that you can change on an existing {product-proxy} deployment.
+This section lists the _mutable_ configuration variables that you can change on an existing {zdm-proxy} deployment.
-After you edit mutable variables in their corresponding configuration files (`vars/zdm_proxy_core_config.yml`, `vars/zdm_proxy_cluster_config.yml`, or `vars/zdm_proxy_advanced_config.yml`), you must <> to apply the configuration changes to your {product-proxy} instances.
+After you edit mutable variables in their corresponding configuration files (`vars/zdm_proxy_core_config.yml`, `vars/zdm_proxy_cluster_config.yml`, or `vars/zdm_proxy_advanced_config.yml`), you must <> to apply the configuration changes to your {zdm-proxy} instances.
=== Mutable variables in `vars/zdm_proxy_core_config.yml`
@@ -93,7 +93,7 @@ At the start of the migration, the primary cluster is the origin cluster because
After all the existing data has been transferred and validated/reconciled on the new cluster, you can switch the primary cluster to the target cluster.
`read_mode`::
-Determines how reads are handled by {product-proxy}:
+Determines how reads are handled by {zdm-proxy}:
+
* **`PRIMARY_ONLY` (default)**: Reads are sent synchronously to the primary cluster only.
* **`DUAL_ASYNC_ON_SECONDARY`**: Reads are sent synchronously to the primary cluster, and also asynchronously to the secondary cluster.
@@ -104,7 +104,7 @@ This is because asynchronous dual reads are primarily intended to help test prod
When you are ready to switch `primary_cluster` to `TARGET`, revert `read_mode` to `PRIMARY_ONLY` because there is no need to send writes to both clusters at that point in the migration.
`log_level`::
-Set the {product-proxy} log level as `INFO` (default) or `DEBUG`.
+Set the {zdm-proxy} log level as `INFO` (default) or `DEBUG`.
+
Only use `DEBUG` while temporarily troubleshooting an issue.
Revert to `INFO` as soon as possible because the extra logging can impact performance slightly.
@@ -118,7 +118,7 @@ In `vars/zdm_proxy_cluster_config.yml`, you can change the connection credential
=== Mutable variables in `vars/zdm_proxy_advanced_config.yml`
`zdm_proxy_max_clients_connections`::
-The maximum number of client connections that {product-proxy} can accept.
+The maximum number of client connections that {zdm-proxy} can accept.
Each client connection results in additional cluster connections and causes the allocation of several in-memory structures.
A high number of client connections per proxy instance can cause performance degradation, especially at high throughput.
Adjust this variable to limit the total number of connections on each instance.
@@ -126,10 +126,10 @@ Adjust this variable to limit the total number of connections on each instance.
Default: `1000`
`replace_cql_functions`::
-Whether {product-proxy} replaces standard `now()` CQL function calls in write requests with an explicit timeUUID value computed at proxy level.
+Whether {zdm-proxy} replaces standard `now()` CQL function calls in write requests with an explicit timeUUID value computed at proxy level.
+
* **`false` (default)**: Replacement of `now()` is disabled.
-* **`true`**: {product-proxy} replaces instances of `now()` in write requests with an explicit timeUUID value before sending the write to each cluster.
+* **`true`**: {zdm-proxy} replaces instances of `now()` in write requests with an explicit timeUUID value before sending the write to each cluster.
+
[IMPORTANT]
====
@@ -149,14 +149,14 @@ For more information, see xref:ROOT:feasibility-checklists.adoc#cql-function-rep
[[zdm_proxy_request_timeout_ms]]
`zdm_proxy_request_timeout_ms`::
Global timeout in milliseconds of a request at proxy level.
-Determines how long {product-proxy} waits for one cluster (for reads) or both clusters (for writes) to reply to a request.
-Upon reaching the timeout limit, {product-proxy} abandons the request and no longer considers it pending, which frees up internal resources to processes other requests.
+Determines how long {zdm-proxy} waits for one cluster (for reads) or both clusters (for writes) to reply to a request.
+Upon reaching the timeout limit, {zdm-proxy} abandons the request and no longer considers it pending, which frees up internal resources to processes other requests.
+
-When a request is abandoned due to a timeout, {product-proxy} doesn't return any result or error.
+When a request is abandoned due to a timeout, {zdm-proxy} doesn't return any result or error.
A timeout warning or error is only returned when the client application's own timeout is reached and the request is expired on the driver side.
+
Make sure `zdm_proxy_request_timeout_ms` is always greater than your client application's client-side timeout.
-If the client has an especially high timeout because it routinely generates long-running requests, you must increase the `zdm_proxy_request_timeout_ms` timeout accordingly so that the {product-proxy} doesn't abandon requests prematurely.
+If the client has an especially high timeout because it routinely generates long-running requests, you must increase the `zdm_proxy_request_timeout_ms` timeout accordingly so that the {zdm-proxy} doesn't abandon requests prematurely.
+
Default: `10000`
@@ -169,7 +169,7 @@ Default: `30000`
Timeout in milliseconds for the initialization (handshake) of the connection that is used solely for asynchronous dual reads between the proxy and the secondary cluster.
+
Upon reaching the timeout limit, the asynchronous reads aren't sent because the connection failed to be established.
-This has no impact on the handling of synchronous requests: {product-proxy} continues to handle all synchronous reads and writes as normal against the primary cluster.
+This has no impact on the handling of synchronous requests: {zdm-proxy} continues to handle all synchronous reads and writes as normal against the primary cluster.
+
Default: `4000`
@@ -182,30 +182,30 @@ Default: `30000`
`metrics_enabled`::
Whether to enable metrics collection.
+
-* **`true` (default)**: {product-proxy} collects and exposes metrics.
-* **`false`**: {product-proxy} metrics collection is completely disabled.
+* **`true` (default)**: {zdm-proxy} collects and exposes metrics.
+* **`false`**: {zdm-proxy} metrics collection is completely disabled.
This isn't recommended.
[[zdm_proxy_max_stream_ids]]
`zdm_proxy_max_stream_ids`::
-Set the maximum pool size of available stream IDs managed by {product-proxy} per client connection.
+Set the maximum pool size of available stream IDs managed by {zdm-proxy} per client connection.
Use the same value as your driver's maximum stream IDs configuration.
+
In the CQL protocol, every request has a unique stream ID.
However, if there are a lot of requests in a given amount of time, errors can occur due to xref:6.9@dse:drivers:speculative-execution.adoc#stream-id-exhaustion[stream ID exhaustion].
+
In the client application, the stream IDs are managed internally by the driver.
-For most drivers, the maximum is 2048, which is the same default value used by {product-proxy}.
+For most drivers, the maximum is 2048, which is the same default value used by {zdm-proxy}.
If you have a custom driver configuration with a higher value, make sure `zdm_proxy_max_stream_ids` matches your driver's maximum stream IDs.
+
Default: `2048`
[#blocked-protocol-versions]
`blocked_protocol_versions`::
-This variable requires {product-proxy} and {product-automation} version 2.4.0 or later.
+This variable requires {zdm-proxy} and {zdm-automation} version 2.4.0 or later.
+
-Use `blocked_protocol_versions` to block specific {cass-short} Native Protocol versions that are supported by {product-proxy}.
-Blocking unsupported versions isn't necessary because {product-proxy} automatically rejects those versions.
+Use `blocked_protocol_versions` to block specific {cass-short} Native Protocol versions that are supported by {zdm-proxy}.
+Blocking unsupported versions isn't necessary because {zdm-proxy} automatically rejects those versions.
+
Allowed values include the following:
+
@@ -237,7 +237,7 @@ For more information, see xref:ROOT:feasibility-checklists.adoc#supported-cassan
=== Deprecated mutable variables
-Deprecated variables will be removed in a future {product-proxy} release.
+Deprecated variables will be removed in a future {zdm-proxy} release.
Replace them with their recommended alternatives as soon as possible.
`forward_client_credentials_to_origin`::
@@ -249,7 +249,7 @@ Whether to use the credentials provided by the client application to connect to
+
This deprecated variable is no longer functional.
Instead, the expected credentials are based on the authentication requirements of the origin and target clusters.
-For more information, see xref:ROOT:connect-clients-to-proxy.adoc#connect-applications-to-zdm-proxy[Connect applications to {product-proxy}].
+For more information, see xref:ROOT:connect-clients-to-proxy.adoc#connect-applications-to-zdm-proxy[Connect applications to {zdm-proxy}].
[#change-immutable-configuration-variables]
== Change immutable configuration variables
@@ -262,15 +262,15 @@ ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory
----
You can re-run the deployment playbook as many times as necessary.
-However, this playbook decommissions and re-creates _all_ {product-proxy} instances simultaneously.
-This results in a brief period of time where the entire {product-proxy} deployment is offline because no instances are available.
+However, this playbook decommissions and re-creates _all_ {zdm-proxy} instances simultaneously.
+This results in a brief period of time where the entire {zdm-proxy} deployment is offline because no instances are available.
-For more information, see xref:ROOT:troubleshooting-tips.adoc#configuration-changes-arent-applied-by-zdm-automation[Configuration changes aren't applied by {product-automation}].
+For more information, see xref:ROOT:troubleshooting-tips.adoc#configuration-changes-arent-applied-by-zdm-automation[Configuration changes aren't applied by {zdm-automation}].
[[_upgrade_the_proxy_version]]
== Upgrade the proxy version
-The same playbook that you use for configuration changes can also be used to upgrade the {product-proxy} version in a rolling fashion.
+The same playbook that you use for configuration changes can also be used to upgrade the {zdm-proxy} version in a rolling fashion.
All containers are re-created with the given image version.
[IMPORTANT]
@@ -279,10 +279,10 @@ A version change is a destructive action because the rolling restart playbook re
xref:ROOT:zdm-logs.adoc[Collect the logs] before you run the playbook if you want to keep them.
====
-To check your current {product-proxy} version, see xref:ROOT:troubleshooting-tips.adoc#check-version[Check your {product-proxy} version].
+To check your current {zdm-proxy} version, see xref:ROOT:troubleshooting-tips.adoc#check-version[Check your {zdm-proxy} version].
. In `vars/zdm_proxy_container.yml`, set `zdm_proxy_image` to the desired tag.
-For available tags, see the https://hub.docker.com/r/datastax/zdm-proxy/tags[{product-proxy} Docker Hub repository].
+For available tags, see the https://hub.docker.com/r/datastax/zdm-proxy/tags[{zdm-proxy} Docker Hub repository].
+
[source,yaml,subs="+quotes"]
----
@@ -296,36 +296,36 @@ For example:
zdm_proxy_image: datastax/zdm-proxy:2.3.4
----
-. <> to update all {product-proxy} instances to the new version.
+. <> to update all {zdm-proxy} instances to the new version.
-== Scale {product-proxy} instances
+== Scale {zdm-proxy} instances
-The process for scaling your {product-proxy} instance depends on whether you use {product-automation} to manage your deployment.
+The process for scaling your {zdm-proxy} instance depends on whether you use {zdm-automation} to manage your deployment.
-=== Scale with {product-automation}
+=== Scale with {zdm-automation}
-{product-automation} doesn't provide a way to scale operations up or down in a rolling fashion.
-If you are using {product-automation} and you need a larger {product-proxy} deployment, you can create a new deployment, or you can add instances to an existing deployment.
+{zdm-automation} doesn't provide a way to scale operations up or down in a rolling fashion.
+If you are using {zdm-automation} and you need a larger {zdm-proxy} deployment, you can create a new deployment, or you can add instances to an existing deployment.
Create a new deployment (recommended)::
-This option is the recommended way to scale your {product-proxy} deployment because it requires no downtime.
+This option is the recommended way to scale your {zdm-proxy} deployment because it requires no downtime.
+
-Create a new {product-proxy} deployment, and then reconfigure your client application to use the new instance:
+Create a new {zdm-proxy} deployment, and then reconfigure your client application to use the new instance:
+
-. xref:ROOT:setup-ansible-playbooks.adoc[Create a new {product-proxy} deployment] with the desired topology on a new set of machines.
-. Change the contact points in the application configuration so that the application instances point to the new {product-proxy} deployment.
+. xref:ROOT:setup-ansible-playbooks.adoc[Create a new {zdm-proxy} deployment] with the desired topology on a new set of machines.
+. Change the contact points in the application configuration so that the application instances point to the new {zdm-proxy} deployment.
. Perform a rolling restart of the application instances to apply the new contact point configuration.
+
The rolling restart ensures there is no interruption of service.
The application instances switch seamlessly from the old deployment to the new one, and they are able to serve requests immediately.
-. After restarting all application instances, you can safely remove the old {product-proxy} deployment.
+. After restarting all application instances, you can safely remove the old {zdm-proxy} deployment.
Add instances to an existing deployment::
This option requires manual configuration and a small amount of downtime.
+
-Change the topology of your existing {product-proxy} deployment, and then restart the entire deployment to apply the change:
+Change the topology of your existing {zdm-proxy} deployment, and then restart the entire deployment to apply the change:
+
-. Amend the inventory file so that it contains one line for each machine where you want to deploy a {product-proxy} instance.
+. Amend the inventory file so that it contains one line for each machine where you want to deploy a {zdm-proxy} instance.
+
For example, if you want to add three nodes to a deployment with six nodes, then the amended inventory file must contain nine total IPs, including the six existing IPs and the three new IPs.
+
@@ -337,51 +337,51 @@ ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory
----
+
Rerunning the playbook stops the existing instances, destroys them, and then creates and starts a new deployment with new instances based on the amended inventory.
-This results in a brief interruption of service for your entire {product-proxy} deployment.
+This results in a brief interruption of service for your entire {zdm-proxy} deployment.
-=== Scale without {product-automation}
+=== Scale without {zdm-automation}
-If you aren't using {product-automation}, use these steps to add, change, or remove {product-proxy} instances.
+If you aren't using {zdm-automation}, use these steps to add, change, or remove {zdm-proxy} instances.
Add an instance::
+
-. Prepare and configure the new {product-proxy} instances appropriately based on your other instances.
-Make sure the new instance's configuration references all planned {product-proxy} cluster nodes.
-. On all {product-proxy} instances, add the new instance's address to the `ZDM_PROXY_TOPOLOGY_ADDRESSES` environment variable.
+. Prepare and configure the new {zdm-proxy} instances appropriately based on your other instances.
+Make sure the new instance's configuration references all planned {zdm-proxy} cluster nodes.
+. On all {zdm-proxy} instances, add the new instance's address to the `ZDM_PROXY_TOPOLOGY_ADDRESSES` environment variable.
Make sure to include all new nodes.
-. On the new {product-proxy} instance, set the `ZDM_PROXY_TOPOLOGY_INDEX` to the next sequential integer after the greatest one in your existing deployment.
-. Perform a rolling restart of all {product-proxy} instances, one at a time.
+. On the new {zdm-proxy} instance, set the `ZDM_PROXY_TOPOLOGY_INDEX` to the next sequential integer after the greatest one in your existing deployment.
+. Perform a rolling restart of all {zdm-proxy} instances, one at a time.
Vertically scale existing instances::
-Use these steps to increase or decrease resources for existing {product-proxy} instances, such as CPU or memory.
+Use these steps to increase or decrease resources for existing {zdm-proxy} instances, such as CPU or memory.
To avoid downtime, perform the following steps on one instance at a time:
+
-. Stop the first {product-proxy} instance that you want to modify.
+. Stop the first {zdm-proxy} instance that you want to modify.
. Modify the instance's resources as required.
Make sure the instance's IP address remains the same.
If the IP address changes, you must treat it as a new instance; follow the steps to **Add an instance** instead.
-. Restart the modified {product-proxy} instance.
+. Restart the modified {zdm-proxy} instance.
. Wait until the instance starts, and then confirm that it is receiving traffic.
. Repeat these steps to modify each additional instance, one at a time.
Remove an instance::
+
-. On all {product-proxy} instances, remove the unused instance's address from the `ZDM_PROXY_TOPOLOGY_ADDRESSES` environment variable.
-. Perform a rolling restart of all remaining {product-proxy} instances.
+. On all {zdm-proxy} instances, remove the unused instance's address from the `ZDM_PROXY_TOPOLOGY_ADDRESSES` environment variable.
+. Perform a rolling restart of all remaining {zdm-proxy} instances.
. Clean up resources used by the removed instance, such as the container or VM.
=== Proxy topology addresses enable failover and high availability
-When you configure a {product-proxy} deployment, either through {product-automation} or manually-managed {product-proxy} instances, you specify the addresses of your instances.
+When you configure a {zdm-proxy} deployment, either through {zdm-automation} or manually-managed {zdm-proxy} instances, you specify the addresses of your instances.
These are populated in the `ZDM_PROXY_TOPOLOGY_ADDRESSES` variable, either manually or automatically depending on how you manage your instances.
{cass-short} drivers look up nodes on a cluster by querying the `system.peers` table.
-{product-proxy} uses the topology addresses to effectively respond to the driver's request for connection nodes.
-If there are no topology addresses specified, {product-proxy} defaults to a single-instance configuration.
-This means that driver connections use only that one {product-proxy} instance rather than all instances in your {product-proxy} deployment.
+{zdm-proxy} uses the topology addresses to effectively respond to the driver's request for connection nodes.
+If there are no topology addresses specified, {zdm-proxy} defaults to a single-instance configuration.
+This means that driver connections use only that one {zdm-proxy} instance rather than all instances in your {zdm-proxy} deployment.
-If that one instance goes down, {product-proxy} won't know that there are other instances available, and your application can experience an outage.
-Additionally, if you need to restart {product-proxy} instances, and there is only one instance specified in the topology addresses, your migration will have downtime while that one instance restarts.
+If that one instance goes down, {zdm-proxy} won't know that there are other instances available, and your application can experience an outage.
+Additionally, if you need to restart {zdm-proxy} instances, and there is only one instance specified in the topology addresses, your migration will have downtime while that one instance restarts.
== See also
diff --git a/modules/ROOT/pages/metrics.adoc b/modules/ROOT/pages/metrics.adoc
index 8966753a..2e95d4e9 100644
--- a/modules/ROOT/pages/metrics.adoc
+++ b/modules/ROOT/pages/metrics.adoc
@@ -1,28 +1,28 @@
-= Monitor {product-proxy}
+= Monitor {zdm-proxy}
-{product-proxy} can gather a large number of metrics that provide you with insight into its health and operations, communication with client applications and clusters, and request handling.
+{zdm-proxy} can gather a large number of metrics that provide you with insight into its health and operations, communication with client applications and clusters, and request handling.
This visibility is important to your migration.
It builds confidence in the health of your deployment, and it helps you investigate errors or performance degradation.
-{company} strongly recommends that you use {product-automation} to deploy the {product-proxy} monitoring stack, or import the pre-built Grafana dashboards into your own monitoring infrastructure.
+{company} strongly recommends that you use {zdm-automation} to deploy the {zdm-proxy} monitoring stack, or import the pre-built Grafana dashboards into your own monitoring infrastructure.
-Do this after you xref:ROOT:setup-ansible-playbooks.adoc[set up {product-automation}] and xref:ROOT:deploy-proxy-monitoring.adoc[deploy the {product-proxy} instances].
+Do this after you xref:ROOT:setup-ansible-playbooks.adoc[set up {zdm-automation}] and xref:ROOT:deploy-proxy-monitoring.adoc[deploy the {zdm-proxy} instances].
== Deploy the monitoring stack
-{product-automation} enables you to easily set up a self-contained monitoring stack that is preconfigured to collect metrics from your {product-proxy} instances and display them in ready-to-use Grafana dashboards.
+{zdm-automation} enables you to easily set up a self-contained monitoring stack that is preconfigured to collect metrics from your {zdm-proxy} instances and display them in ready-to-use Grafana dashboards.
The monitoring stack is deployed entirely on Docker.
It includes the following components, all deployed as Docker containers:
-* Prometheus node exporter, which runs on each {product-proxy} host and makes OS- and host-level metrics available to Prometheus.
-* Prometheus server, to collect metrics from {product-proxy}, its Golang runtime, and the Prometheus node exporter.
+* Prometheus node exporter, which runs on each {zdm-proxy} host and makes OS- and host-level metrics available to Prometheus.
+* Prometheus server, to collect metrics from {zdm-proxy}, its Golang runtime, and the Prometheus node exporter.
* Grafana, to visualize the metrics in preconfigured dashboards.
-After running the monitoring playbook, you will have a fully configured monitoring stack connected to your {product-proxy} deployment.
+After running the monitoring playbook, you will have a fully configured monitoring stack connected to your {zdm-proxy} deployment.
-Aside from xref:ROOT:deployment-infrastructure.adoc[preparing the infrastructure], you don't need to install any {product-proxy} dependencies on the monitoring host machine. The playbook automatically installs all required software packages.
+Aside from xref:ROOT:deployment-infrastructure.adoc[preparing the infrastructure], you don't need to install any {zdm-proxy} dependencies on the monitoring host machine. The playbook automatically installs all required software packages.
. Connect to the Ansible Control Host Docker container.
You can do this from the jumphost machine by running the following command:
@@ -76,9 +76,9 @@ If you deployed your monitoring stack on another machine, replace `**MONITORING_
[#call-the-liveliness-and-readiness-endpoints]
== Call the `liveness` and `readiness` HTTP endpoints
-{product-short} metrics provide `/health/liveness` and `/health/readiness` HTTP endpoints, that you can call to determine the state of the {product-proxy} instances.
+{zdm-short} metrics provide `/health/liveness` and `/health/readiness` HTTP endpoints, that you can call to determine the state of the {zdm-proxy} instances.
-For example, after deploying the {product-proxy} monitoring stack, you can use the `liveness` and `readiness` HTTP endpoints to confirm that your {product-proxy} instances are running.
+For example, after deploying the {zdm-proxy} monitoring stack, you can use the `liveness` and `readiness` HTTP endpoints to confirm that your {zdm-proxy} instances are running.
=== Liveliness endpoint
@@ -92,7 +92,7 @@ Replace the following:
* `**METRICS_PORT**`: The `metrics_port` you set in the `zdm_monitoring_config.yml` file.
The default port is 14001.
-* `**ZDM_PROXY_PRIVATE_IP**`: The private IP address, hostname, or other valid identifier for the {product-proxy} instance you want to check.
+* `**ZDM_PROXY_PRIVATE_IP**`: The private IP address, hostname, or other valid identifier for the {zdm-proxy} instance you want to check.
Example request with variables:
@@ -120,7 +120,7 @@ Replace the following:
* `**METRICS_PORT**`: The `metrics_port` you set in the `zdm_monitoring_config.yml` file.
The default port is 14001.
-* `**ZDM_PROXY_PRIVATE_IP**`: The private IP address, hostname, or other valid identifier for the {product-proxy} instance you want to check.
+* `**ZDM_PROXY_PRIVATE_IP**`: The private IP address, hostname, or other valid identifier for the {zdm-proxy} instance you want to check.
Example request with variables:
@@ -157,23 +157,23 @@ Example result:
}
----
-== Inspect {product-proxy} metrics
+== Inspect {zdm-proxy} metrics
-{product-proxy} exposes an HTTP endpoint that returns metrics in the Prometheus format.
+{zdm-proxy} exposes an HTTP endpoint that returns metrics in the Prometheus format.
-After you deploy the monitoring stack, the {product-proxy} Grafana dashboards automatically start displaying these metrics as they are scraped from the instances.
+After you deploy the monitoring stack, the {zdm-proxy} Grafana dashboards automatically start displaying these metrics as they are scraped from the instances.
-If you already have a Grafana deployment, then you can import the dashboards from the {product-automation-repo}/tree/main/grafana-dashboards[{product-short} dashboard files] in the {product-short} GitHub repository.
+If you already have a Grafana deployment, then you can import the dashboards from the {zdm-automation-repo-url}/tree/main/grafana-dashboards[{zdm-short} dashboard files] in the {zdm-short} GitHub repository.
-=== Grafana dashboard for {product-proxy} metrics
+=== Grafana dashboard for {zdm-proxy} metrics
-The {product-proxy} metrics dashboard includes proxy level metrics, node level metrics, and asynchronous read requests metrics.
+The {zdm-proxy} metrics dashboard includes proxy level metrics, node level metrics, and asynchronous read requests metrics.
-image::ROOT:zdm-grafana-proxy-dashboard1.png[Grafana dashboard shows three categories of {product-short} metrics for the proxy.]
+image::ROOT:zdm-grafana-proxy-dashboard1.png[Grafana dashboard shows three categories of {zdm-short} metrics for the proxy.]
This dashboard can help you identify issues such as the following:
-* If the number of client connections is near 1000 per {product-proxy} instance, be aware that {product-proxy} will start rejecting client connections after accepting 1000 connections.
+* If the number of client connections is near 1000 per {zdm-proxy} instance, be aware that {zdm-proxy} will start rejecting client connections after accepting 1000 connections.
* If Prepared Statement cache metrics are always increasing, check the **entries** and **misses** metrics.
* If you have error metrics reporting for specific error types, evaluate these issues on a case-by-case basis.
@@ -182,10 +182,10 @@ This dashboard can help you identify issues such as the following:
* **Latency**:
+
-** **Read Latency**: Total latency measured by {product-proxy} per read request, including post-processing, such as response aggregation.
+** **Read Latency**: Total latency measured by {zdm-proxy} per read request, including post-processing, such as response aggregation.
This metric has two labels: `reads_origin` and `reads_target`.
The label that has data depends on which cluster is receiving the reads, which is the current xref:ROOT:faqs.adoc#what-are-origin-target-primary-and-secondary-clusters[primary cluster].
-** **Write Latency**: Total latency measured by {product-proxy} per write request, including post-processing, such as response aggregation.
+** **Write Latency**: Total latency measured by {zdm-proxy} per write request, including post-processing, such as response aggregation.
This metric is measured as the total latency across both clusters for a single xref:ROOT:components.adoc#how-zdm-proxy-handles-reads-and-writes[bifurcated write request].
* **Throughput**: Follows the same structure as the latency metrics but measures **Read Throughput** and **Write Throughput**.
@@ -196,7 +196,7 @@ This metric is measured as the total latency across both clusters for a single x
* **Prepared Statement cache**:
+
-** **Cache Misses**: If a prepared statement is sent to {product-proxy} but the statement's `preparedID` isn't present in the node's cache, then {product-proxy} sends an `UNPREPARED` response to the client to reprepare the statement.
+** **Cache Misses**: If a prepared statement is sent to {zdm-proxy} but the statement's `preparedID` isn't present in the node's cache, then {zdm-proxy} sends an `UNPREPARED` response to the client to reprepare the statement.
This metric tracks the number of times this happens.
** **Number of cached prepared statements**
@@ -213,7 +213,7 @@ The label that contains data depends on which cluster is currently considered th
*** `failed_on=both`: The write request failed on both the origin and target clusters.
* **Request Failure Counters**: Number of total request failures.
-Resets if the {product-proxy} instance restarts.
+Resets if the {zdm-proxy} instance restarts.
+
** **Connect Failure Counters**: Has the same labels as the connect failure rate.
** **Read Failure Counters**: Has the same labels as the read failure rate.
@@ -227,8 +227,8 @@ For error metrics by error type, see the <<_node_level_metrics,node-level error
* **Latency**: Node-level latency metrics report combined read and write latency per cluster, not per request.
For latency by request type, see <>.
+
-** **Origin**: Latency, as measured by {product-proxy}, up to the point that it received a response from the origin connection.
-** **Target**: Latency, as measured by {product-proxy}, up to the point it received a response from the target connection.
+** **Origin**: Latency, as measured by {zdm-proxy}, up to the point that it received a response from the origin connection.
+** **Target**: Latency, as measured by {zdm-proxy}, up to the point it received a response from the target connection.
* **Throughput**: Same as the node-level latency metrics.
Reads and writes are combined.
@@ -263,9 +263,9 @@ These metrics track the following information for asynchronous read requests:
=== Go runtime metrics dashboard
-The Go runtime metrics dashboard is used less often than the {product-proxy} metrics dashboard.
+The Go runtime metrics dashboard is used less often than the {zdm-proxy} metrics dashboard.
-This dashboard can be helpful for troubleshooting {product-proxy} performance issues.
+This dashboard can be helpful for troubleshooting {zdm-proxy} performance issues.
It provides metrics for memory usage, Garbage Collection (GC) duration, open FDs (file descriptors), and the number of goroutines.
image::ROOT:zdm-golang-dashboard.png[Golang metrics dashboard example is shown.]
@@ -279,10 +279,10 @@ Watch for the following problem areas on the Go runtime metrics dashboard:
=== System-level metrics dashboard
-The {product-short} monitoring stack's system-level dashboard metrics are collected through the Prometheus Node Exporter.
+The {zdm-short} monitoring stack's system-level dashboard metrics are collected through the Prometheus Node Exporter.
This dashboard contains hardware and OS-level metrics for the host on which the proxy runs.
This can be useful to check the available resources and identify low-level bottlenecks or issues.
== Next steps
-To continue Phase 1 of the migration, xref:ROOT:connect-clients-to-proxy.adoc[connect your client applications to {product-proxy}].
\ No newline at end of file
+To continue Phase 1 of the migration, xref:ROOT:connect-clients-to-proxy.adoc[connect your client applications to {zdm-proxy}].
\ No newline at end of file
diff --git a/modules/ROOT/pages/migrate-and-validate-data.adoc b/modules/ROOT/pages/migrate-and-validate-data.adoc
index 91abb545..7a61328d 100644
--- a/modules/ROOT/pages/migrate-and-validate-data.adoc
+++ b/modules/ROOT/pages/migrate-and-validate-data.adoc
@@ -1,11 +1,11 @@
= Phase 2: Migrate and validate data
:page-aliases: ROOT:sideloader-zdm.adoc, ROOT:dsbulk-migrator-overview.adoc, ROOT:dsbulk-migrator.adoc
-In xref:ROOT:phase1.adoc[Phase 1], you set up {product-proxy} to orchestrate live traffic to your origin and target clusters.
+In xref:ROOT:phase1.adoc[Phase 1], you set up {zdm-proxy} to orchestrate live traffic to your origin and target clusters.
-In Phase 2 of {product}, you migrate data from the origin to the target, and then validate the migrated data.
+In Phase 2 of {zdm}, you migrate data from the origin to the target, and then validate the migrated data.
-image::ROOT:migration-phase2ra.svg[In {product-short} Phase 2, you migrate data from the origin cluster to the target cluster]
+image::ROOT:migration-phase2ra.svg[In {zdm-short} Phase 2, you migrate data from the origin cluster to the target cluster]
To move and validate data, you can use a dedicated data migration tool, such as {sstable-sideloader}, {cass-migrator}, or {dsbulk}, or your can create your own custom data migration script.
@@ -25,11 +25,11 @@ For compatible origin clusters, see xref:ROOT:astra-migration-paths.adoc[].
* *Cloud provider CLI*: Upload snapshots to a dedicated cloud storage bucket for your migration.
* *{astra} {devops-api}*: Run the {sstable-sideloader} commands to write the data from cloud storage to your {astra-db} database.
-You can use {sstable-sideloader} alone or with {product-proxy}.
+You can use {sstable-sideloader} alone or with {zdm-proxy}.
For more information and instructions, see xref:sideloader:sideloader-overview.adoc[].
-.Use {sstable-sideloader} with {product-proxy}
+.Use {sstable-sideloader} with {zdm-proxy}
svg::sideloader:astra-migration-toolkit.svg[]
== {cass-migrator}
@@ -37,9 +37,9 @@ svg::sideloader:astra-migration-toolkit.svg[]
You can use {cass-migrator-short} for data migration and validation between {cass-short}-based databases.
It offers extensive functionality and configuration options to support large and complex migrations as well as post-migration data validation.
-You can use {cass-migrator-short} alone, with {product-proxy}, or for data validation after using another data migration tool.
+You can use {cass-migrator-short} alone, with {zdm-proxy}, or for data validation after using another data migration tool.
-For more information, see xref:ROOT:cassandra-data-migrator.adoc[].
+For more information, see the {cass-migrator-repo-url}[{cass-migrator-short} repository].
== {dsbulk}
@@ -48,7 +48,7 @@ You can use it to load, unload, and count records.
Because {dsbulk-short} doesn't have the same data validation capabilities as {cass-migrator-short}, it is best for migrations that don't require extensive data validation, aside from post-migration row counts.
-You can use {dsbulk-short} alone or with {product-proxy}.
+You can use {dsbulk-short} alone or with {zdm-proxy}.
For more information, see xref:dsbulk:overview:dsbulk-about.adoc[].
@@ -59,16 +59,16 @@ include::ROOT:partial$dsbulk-migrator-deprecation.adoc[]
== Other data migration processes
-Depending on your origin and target databases, there might be other {product-short}-compatible data migration tools available, or you can write your own custom data migration processes with a tool like {spark-reg}.
+Depending on your origin and target databases, there might be other {zdm-short}-compatible data migration tools available, or you can write your own custom data migration processes with a tool like {spark-reg}.
-To use a data migration tool with {product-proxy}, it must meet the following requirements:
+To use a data migration tool with {zdm-proxy}, it must meet the following requirements:
* Built-in data validation functionality or compatibility with another data validation tool, such as {cass-migrator-short}.
This is crucial to a successful migration.
-* Preserves the data model, including column names and data types, so that {product-proxy} can send the same read/write statements to both databases successfully.
+* Preserves the data model, including column names and data types, so that {zdm-proxy} can send the same read/write statements to both databases successfully.
+
-Migrations that perform significant data transformations might not be compatible with {product-proxy}.
+Migrations that perform significant data transformations might not be compatible with {zdm-proxy}.
The impact of data transformations depends on your specific data model, database platforms, and the scale of your migration.
== Next steps
diff --git a/modules/ROOT/pages/phase1.adoc b/modules/ROOT/pages/phase1.adoc
index a5916d3b..aab9e190 100644
--- a/modules/ROOT/pages/phase1.adoc
+++ b/modules/ROOT/pages/phase1.adoc
@@ -1,13 +1,13 @@
-= Deploy and connect {product-proxy}
+= Deploy and connect {zdm-proxy}
-After you plan and prepare for your migration, you can start Phase 1 of the migration process where you deploy and connect {product-proxy}.
+After you plan and prepare for your migration, you can start Phase 1 of the migration process where you deploy and connect {zdm-proxy}.
-image::ROOT:migration-phase1ra.svg[In migration Phase 1, you deploy {product-proxy} instances, and then connect your client applications to the proxies]
+image::ROOT:migration-phase1ra.svg[In migration Phase 1, you deploy {zdm-proxy} instances, and then connect your client applications to the proxies]
To complete Phase 1, do the following:
. xref:setup-ansible-playbooks.adoc[].
. xref:deploy-proxy-monitoring.adoc[].
-. Deploy the xref:metrics.adoc[{product-proxy} monitoring stack] and learn about {product-proxy} metrics.
+. Deploy the xref:metrics.adoc[{zdm-proxy} monitoring stack] and learn about {zdm-proxy} metrics.
. xref:connect-clients-to-proxy.adoc[].
-. Learn how to xref:manage-proxy-instances.adoc[manage {product-proxy} instances], including scaling, upgrading, reconfiguring, and restarting them.
\ No newline at end of file
+. Learn how to xref:manage-proxy-instances.adoc[manage {zdm-proxy} instances], including scaling, upgrading, reconfiguring, and restarting them.
\ No newline at end of file
diff --git a/modules/ROOT/pages/rollback.adoc b/modules/ROOT/pages/rollback.adoc
index dbcfa852..5a1fb6b1 100644
--- a/modules/ROOT/pages/rollback.adoc
+++ b/modules/ROOT/pages/rollback.adoc
@@ -8,14 +8,14 @@ image::ROOT:migration-all-phases.svg[Migration phases from start to finish.]
== Phase 5 is the point of no return
-After moving your client applications off the {product-proxy} instances (Phase 5), writes are no longer sent to both the origin and target clusters.
+After moving your client applications off the {zdm-proxy} instances (Phase 5), writes are no longer sent to both the origin and target clusters.
The data on origin cluster is no longer kept up-to-date, and you lose this seamless rollback option.
This is the point at which you commit to using the target cluster permanently.
-The {product-proxy} deployment can be destroyed, and the origin cluster is no longer needed by the client applications that have been migrated.
+The {zdm-proxy} deployment can be destroyed, and the origin cluster is no longer needed by the client applications that have been migrated.
However, should you decide to move back to the origin cluster later, or if you want to move to a new cluster entirely, you can rerun the same migration process.
In this case, you use your original target cluster as the new origin cluster, and you set the new target cluster to whatever cluster you want to migrate to (which could even be the original ancestor origin cluster).
== Next steps
-After preparing the infrastructure for {product-proxy} and your target cluster, begin xref:ROOT:phase1.adoc[Phase 1] of the migration.
\ No newline at end of file
+After preparing the infrastructure for {zdm-proxy} and your target cluster, begin xref:ROOT:phase1.adoc[Phase 1] of the migration.
\ No newline at end of file
diff --git a/modules/ROOT/pages/setup-ansible-playbooks.adoc b/modules/ROOT/pages/setup-ansible-playbooks.adoc
index 0248a0b3..6c42835c 100644
--- a/modules/ROOT/pages/setup-ansible-playbooks.adoc
+++ b/modules/ROOT/pages/setup-ansible-playbooks.adoc
@@ -1,37 +1,37 @@
-= Set up {product-automation} with {product-utility}
+= Set up {zdm-automation} with {zdm-utility}
-{product-automation} uses Ansible to deploy and configure the {product-proxy} instances and the associated monitoring stack.
+{zdm-automation} uses Ansible to deploy and configure the {zdm-proxy} instances and the associated monitoring stack.
Specifically, these configuration processes are defined in Ansible playbooks that you execute from the Ansible Control Host container.
-First, you must use {product-utility} to set up the Ansible Control Host container, and then you can xref:deploy-proxy-monitoring.adoc[use {product-automation} to deploy your {product-proxy} instances] and the xref:ROOT:metrics.adoc[monitoring stack].
-After you complete both of these procedures, you will have an active and fully monitored {product-proxy} deployment.
+First, you must use {zdm-utility} to set up the Ansible Control Host container, and then you can xref:deploy-proxy-monitoring.adoc[use {zdm-automation} to deploy your {zdm-proxy} instances] and the xref:ROOT:metrics.adoc[monitoring stack].
+After you complete both of these procedures, you will have an active and fully monitored {zdm-proxy} deployment.
-{product-utility} is a Golang (Go) executable program that runs anywhere.
+{zdm-utility} is a Golang (Go) executable program that runs anywhere.
This utility prompts you for a few configuration values, with helpful embedded explanations and error handling, and then it creates and prepares the Ansible Control Host container automatically.
-From this container, you will configure and run the {product-automation} Ansible playbooks.
+From this container, you will configure and run the {zdm-automation} Ansible playbooks.
-image::ROOT:docker-container-and-zdm-utility.png[{product-proxy} connections from Docker container created by {product-utility}]
+image::ROOT:docker-container-and-zdm-utility.png[{zdm-proxy} connections from Docker container created by {zdm-utility}]
-For more information about {product-utility} and {product-automation}, see xref:ROOT:components.adoc[].
+For more information about {zdm-utility} and {zdm-automation}, see xref:ROOT:components.adoc[].
== Prerequisites
-Before running {product-utility} to create the Ansible Control Host container, you must complete the following prerequisites:
+Before running {zdm-utility} to create the Ansible Control Host container, you must complete the following prerequisites:
-* xref:ROOT:deployment-infrastructure.adoc[Provision all {product-proxy} infrastructure]: This means your server machines are ready, and you know their IP addresses.
+* xref:ROOT:deployment-infrastructure.adoc[Provision all {zdm-proxy} infrastructure]: This means your server machines are ready, and you know their IP addresses.
+
This infrastructure can be on-premise or in any cloud provider of your choice.
+
-If your {product-proxy} machines use private IPs, which are recommended for production deployments, configure these before running {product-utility}.
-If you enable private IPs later, you must reconfigure and redeploy your {product-proxy} instances.
-This is a disruptive operation that requires a small amount of downtime because the deployment playbook decommissions and re-creates all {product-proxy} containers simultaneously.
+If your {zdm-proxy} machines use private IPs, which are recommended for production deployments, configure these before running {zdm-utility}.
+If you enable private IPs later, you must reconfigure and redeploy your {zdm-proxy} instances.
+This is a disruptive operation that requires a small amount of downtime because the deployment playbook decommissions and re-creates all {zdm-proxy} containers simultaneously.
* https://docs.docker.com/engine/install/#server[Install Docker] on the machine that will run the Ansible Control Host container, and ensure that the `docker` command https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user[doesn't require superuser privileges].
+
[TIP]
====
You don't need to install Docker on any other machines.
-{product-automation} will install Docker on the other {product-proxy} machines as part of the deployment process.
+{zdm-automation} will install Docker on the other {zdm-proxy} machines as part of the deployment process.
====
== Alternative Docker configurations
@@ -45,7 +45,7 @@ For instructions, see the Docker documentation on https://docs.docker.com/docker
Airgapped local registry::
Local registries that aren't connected to the internet require administrators to manually add containers to their registry.
-For {product-utility}, you need the following five containers to install and configure the jumphost, {product-proxy}, and monitoring:
+For {zdm-utility}, you need the following five containers to install and configure the jumphost, {zdm-proxy}, and monitoring:
+
[source,plaintext]
----
@@ -61,24 +61,24 @@ datastax/zdm-proxy:2.x
This guide uses a jumphost to run the Ansible Control Host container.
A jumphost is a server on a network that is used to access and manage devices in a separate security zone, providing a controlled means of access between them.
-The jumphost can be, for example, a Linux server machine that is able to access the server machines that you wish to use for your {product-proxy} deployment.
+The jumphost can be, for example, a Linux server machine that is able to access the server machines that you wish to use for your {zdm-proxy} deployment.
-The jumphost is used to access the {product-proxy} machines, and run the Ansible Control Host container, from which you run {product-automation}.
-In this example, the jumphost also runs the {product-proxy} monitoring stack, which uses Prometheus and Grafana to expose the metrics of all the {product-proxy} instances to preconfigured dashboards.
+The jumphost is used to access the {zdm-proxy} machines, and run the Ansible Control Host container, from which you run {zdm-automation}.
+In this example, the jumphost also runs the {zdm-proxy} monitoring stack, which uses Prometheus and Grafana to expose the metrics of all the {zdm-proxy} instances to preconfigured dashboards.
However, you can run the monitoring stack on a different machine.
. Add SSH keys to the jumphost.
+
-To run {product-automation}, the Ansible Control Host must be able to connect to all other instances of the {product-proxy} deployment.
+To run {zdm-automation}, the Ansible Control Host must be able to connect to all other instances of the {zdm-proxy} deployment.
For this reason, it needs to have the SSH key required by those instances.
+
[TIP]
====
-To simplify accessing the jumphost and {product-proxy} instances from your machine, you can create a xref:ROOT:deployment-infrastructure.adoc#connect-to-zdm-proxy-infrastructure-from-an-external-machine[custom SSH configuration file].
+To simplify accessing the jumphost and {zdm-proxy} instances from your machine, you can create a xref:ROOT:deployment-infrastructure.adoc#connect-to-zdm-proxy-infrastructure-from-an-external-machine[custom SSH configuration file].
These steps assume that this file exists.
====
+
-From your local machine, transfer (`scp`) the SSH private key for the {product-proxy} deployment to the jumphost.
+From your local machine, transfer (`scp`) the SSH private key for the {zdm-proxy} deployment to the jumphost.
For example:
+
[source,bash]
@@ -93,15 +93,15 @@ scp -F path/to/zdm_ssh_config zdm_key_name jumphost:
ssh -F path/to/zdm_ssh_config jumphost
----
-. From the jumphost, download the latest {product-utility} executable from the {product-automation-repo}/releases[{product-automation} GitHub repository] {product-automation-shield}.
+. From the jumphost, download the latest {zdm-utility} executable from the {zdm-automation-repo-url}/releases[{zdm-automation} GitHub repository].
+
The package filename format is `zdm-util-**PLATFORM**-**VERSION**.tgz`.
-The following example downloads {product-utility} version 2.3.1 for Linux amd64.
+The following example downloads {zdm-utility} version 2.3.1 for Linux amd64.
To download a different package, change the version and package filename accordingly.
+
[source,bash,subs="+attributes"]
----
-wget {product-automation-repo}/releases/download/v2.3.1/zdm-util-linux-amd64-v2.3.1.tgz
+wget {zdm-automation-repo-url}/releases/download/v2.3.1/zdm-util-linux-amd64-v2.3.1.tgz
----
. Extract the archive:
@@ -111,7 +111,7 @@ wget {product-automation-repo}/releases/download/v2.3.1/zdm-util-linux-amd64-v2.
tar -xvf zdm-util-linux-amd64-v2.3.1.tgz
----
-. Run {product-utility}:
+. Run {zdm-utility}:
+
[source,bash]
----
@@ -119,20 +119,20 @@ tar -xvf zdm-util-linux-amd64-v2.3.1.tgz
----
. Enter configuration values as you are prompted for them.
-{product-utility} creates and initializes the Ansible Control Host container after it has all required configuration values.
+{zdm-utility} creates and initializes the Ansible Control Host container after it has all required configuration values.
+
-{product-utility} validates each value that you enter.
+{zdm-utility} validates each value that you enter.
In case of invalid values, it prompts you for the variable again and prints a message to help you fix potential problems.
You have five attempts to enter valid values.
-If all five attempts are invalid, you must rerun {product-utility}.
+If all five attempts are invalid, you must rerun {zdm-utility}.
+
[TIP]
====
-{product-utility} stores your provided configuration values in a file named `ansible_container_init_config` in the current directory.
+{zdm-utility} stores your provided configuration values in a file named `ansible_container_init_config` in the current directory.
If you run the utility again, it detects this file, and then asks you if you want to use the existing configuration or discard it.
If the file contains any invalid values, you are prompted for the missing or invalid parameters only.
-You can also pass a custom configuration file to {product-utility} with the optional command-line parameter `-utilConfigFile`.
+You can also pass a custom configuration file to {zdm-utility} with the optional command-line parameter `-utilConfigFile`.
For example:
[source,bash]
@@ -159,20 +159,20 @@ For example:
+
* If you have an existing Ansible inventory file that is present on the jumphost, specify that file.
* If you don't have an Ansible inventory file, type kbd:[N].
-{product-utility} prompts you for the required values, and then creates a `zdm_ansible_inventory` file in the working directory.
+{zdm-utility} prompts you for the required values, and then creates a `zdm_ansible_inventory` file in the working directory.
-. Indicate whether this deployment is for local testing and evaluation (such as when you're creating a demo or experimenting with {product-proxy}) or not.
+. Indicate whether this deployment is for local testing and evaluation (such as when you're creating a demo or experimenting with {zdm-proxy}) or not.
For production deployments, type kbd:[N].
+
[TIP]
====
-Depending on your environment and {product-utility} configuration choices, your prompts might differ from the examples shown here.
+Depending on your environment and {zdm-utility} configuration choices, your prompts might differ from the examples shown here.
You might receive additional prompts that aren't given here, or you might bypass some prompts.
In any case, the utility guides you through the process with helpful hints and troubleshooting guidance.
-Regardless of the individual prompts, a successful outcome always results in a configured Ansible Control Host container that is ready to run {product-automation}.
+Regardless of the individual prompts, a successful outcome always results in a configured Ansible Control Host container that is ready to run {zdm-automation}.
====
-. For production deployments, enter at least three proxy private IP addresses for the machines that will run the {product-proxy} instances.
+. For production deployments, enter at least three proxy private IP addresses for the machines that will run the {zdm-proxy} instances.
For local testing and evaluation, only one proxy private IP address is required.
+
Enter each IP address on a separate line, for example:
@@ -186,44 +186,44 @@ Enter each IP address on a separate line, for example:
+
When you are done entering IP addresses, press kbd:[Return] at the blank prompt.
-. Optional: When prompted, enter the private IP address of the machine where you want to deploy the {product-proxy} monitoring stack.
+. Optional: When prompted, enter the private IP address of the machine where you want to deploy the {zdm-proxy} monitoring stack.
+
-You can use the jumphost or a different machine, as long as it can connect to the {product-proxy} instances over TCP on ports 9100 (to collect host-level metrics) and the port on which {product-proxy} exposes its own metrics, typically 14001.
+You can use the jumphost or a different machine, as long as it can connect to the {zdm-proxy} instances over TCP on ports 9100 (to collect host-level metrics) and the port on which {zdm-proxy} exposes its own metrics, typically 14001.
+
You can skip this step if you haven't decided which machine to use for monitoring, or you want to use your own monitoring stack.
+
[IMPORTANT]
====
-{company} strongly recommends that you configure a monitoring instance to expose xref:ROOT:metrics.adoc[{product-proxy} metrics and preconfigured dashboards] with {product-automation}.
-This is the most simplified approach to {product-proxy} montioring, and it is preferred unless you intend (or are required) to use a monitoring stack that you already have.
+{company} strongly recommends that you configure a monitoring instance to expose xref:ROOT:metrics.adoc[{zdm-proxy} metrics and preconfigured dashboards] with {zdm-automation}.
+This is the most simplified approach to {zdm-proxy} montioring, and it is preferred unless you intend (or are required) to use a monitoring stack that you already have.
-Metrics are essential for understanding the performance and health of your {product-proxy} instances, especially for migrations that run over multiple days or weeks.
+Metrics are essential for understanding the performance and health of your {zdm-proxy} instances, especially for migrations that run over multiple days or weeks.
You cannot rely solely on information in the logs.
-Logs report connection or protocol errors, but they don't provide enough information about how {product-proxy} is functioning and how each cluster is responding.
+Logs report connection or protocol errors, but they don't provide enough information about how {zdm-proxy} is functioning and how each cluster is responding.
In contrast, metrics provide insightful data and graphs illustrating key values and changes over time.
====
+
-The following example uses the same IP address as the Ansible Control Host machine, which is the jumphost machine where {product-utility} is running:
+The following example uses the same IP address as the Ansible Control Host machine, which is the jumphost machine where {zdm-utility} is running:
+
[source,bash]
----
172.18.100.128
----
-. Review the configuration summary printed to the terminal by {product-utility}.
-At this point, {product-utility} has created the Ansible inventory file name `zdm_ansible_inventory` (unless you provided your own custom file), and it has written the {product-utility} configuration to `ansible_container_init_config`.
+. Review the configuration summary printed to the terminal by {zdm-utility}.
+At this point, {zdm-utility} has created the Ansible inventory file name `zdm_ansible_inventory` (unless you provided your own custom file), and it has written the {zdm-utility} configuration to `ansible_container_init_config`.
+
image::ROOT:zdm-go-utility-results3.png[A summary of the configuration provided is displayed in the terminal]
. Type kbd:[Y] to continue and trigger the following processes:
+
-.. {product-utility} creates and downloads the image of the Ansible Docker container.
-.. {product-utility} creates, configures, and starts the Ansible Control Host container.
-.. {product-utility} prints a message when the Ansible container is fully initialized and ready to use.
+.. {zdm-utility} creates and downloads the image of the Ansible Docker container.
+.. {zdm-utility} creates, configures, and starts the Ansible Control Host container.
+.. {zdm-utility} prints a message when the Ansible container is fully initialized and ready to use.
+
image::ROOT:zdm-go-utility-success3.png[Ansible Docker container success messages]
== Next steps
-After you use {product-utility} to set up the Ansible Control Host container, xref:deploy-proxy-monitoring.adoc[use {product-automation} to deploy your {product-proxy} instances].
\ No newline at end of file
+After you use {zdm-utility} to set up the Ansible Control Host container, xref:deploy-proxy-monitoring.adoc[use {zdm-automation} to deploy your {zdm-proxy} instances].
\ No newline at end of file
diff --git a/modules/ROOT/pages/troubleshooting-tips.adoc b/modules/ROOT/pages/troubleshooting-tips.adoc
index 72cf5d23..2bf2d8c1 100644
--- a/modules/ROOT/pages/troubleshooting-tips.adoc
+++ b/modules/ROOT/pages/troubleshooting-tips.adoc
@@ -1,22 +1,22 @@
-= Troubleshoot {product}
-:navtitle: Troubleshoot {product-short}
+= Troubleshoot {zdm}
+:navtitle: Troubleshoot {zdm-short}
:page-aliases: ROOT:troubleshooting.adoc, ROOT:troubleshooting-scenarios.adoc
-:description: Get help with {product}.
+:description: Get help with {zdm}.
-This page provides general troubleshooting advice and describes some common issues you might encounter with {product} ({product-short}).
+This page provides general troubleshooting advice and describes some common issues you might encounter with {zdm}.
For additional assistance, you can <>, contact your {company} account representative, or contact {support-url}[IBM Support].
[#proxy-logs]
-== Check {product-proxy} logs
+== Check {zdm-proxy} logs
include::ROOT:partial$zdm-logs-intro.adoc[]
For more information, see xref:ROOT:zdm-logs.adoc[].
[#check-version]
-== Check your {product-proxy} version
+== Check your {zdm-proxy} version
-The {product-proxy} version is printed at startup, and it is the first message in the logs, immediately before the long `Parsed configuration` string:
+The {zdm-proxy} version is printed at startup, and it is the first message in the logs, immediately before the long `Parsed configuration` string:
[source,console]
----
@@ -24,7 +24,7 @@ time="2023-01-13T13:37:28+01:00" level=info msg="Starting ZDM proxy version 2.1.
time="2023-01-13T13:37:28+01:00" level=info msg="Parsed configuration: ..."
----
-You can also pass the `-version` flag to {product-proxy} to print the version.
+You can also pass the `-version` flag to {zdm-proxy} to print the version.
For example, you can use the following Docker command, replacing `**TAG**` with the `zdm_proxy_image` tag set in `vars/zdm_proxy_container.yml`:
[source,bash,subs="+quotes"]
@@ -32,7 +32,7 @@ For example, you can use the following Docker command, replacing `**TAG**` with
docker run --rm datastax/zdm-proxy:**TAG** -version
----
-The output shows the binary version of {product-proxy} that is currently running:
+The output shows the binary version of {zdm-proxy} that is currently running:
.Result
[source,console]
@@ -42,15 +42,15 @@ ZDM proxy version 2.1.0
[IMPORTANT]
====
-Don't use `--rm` when you launch the {product-proxy} container.
-This flag will prevent you from accessing the logs when {product-proxy} stops or crashes.
+Don't use `--rm` when you launch the {zdm-proxy} container.
+This flag will prevent you from accessing the logs when {zdm-proxy} stops or crashes.
====
== Query system.peers and system.local to check for configuration issues
-Querying `system.peers` and `system.local` can help you investigate {product-proxy} configuration issues:
+Querying `system.peers` and `system.local` can help you investigate {zdm-proxy} configuration issues:
-. xref:ROOT:connect-clients-to-proxy.adoc#connect-cqlsh-to-zdm-proxy[Connect the {cql-shell} to a {product-proxy} instance].
+. xref:ROOT:connect-clients-to-proxy.adoc#connect-cqlsh-to-zdm-proxy[Connect the {cql-shell} to a {zdm-proxy} instance].
. Query `system.peers`:
+
@@ -66,9 +66,9 @@ SELECT * FROM system.peers
SELECT * FROM system.local
----
-. Repeat for each of your {product-proxy} instances.
+. Repeat for each of your {zdm-proxy} instances.
+
-Because `system.peers` and `system.local` reflect the local {product-proxy} instance's configuration, you must query all instances to get all information and identify potential misconfigurations.
+Because `system.peers` and `system.local` reflect the local {zdm-proxy} instance's configuration, you must query all instances to get all information and identify potential misconfigurations.
. Compare the results from each instance by searching for values related to an error that you are troubleshooting, such as IP addresses or tokens.
+
@@ -76,14 +76,14 @@ For example, you might compare `cluster_name` to ensure that all instances are c
== Troubleshooting scenarios
-The following sections provide troubleshooting advice for specific issues or error messages related to {product}.
+The following sections provide troubleshooting advice for specific issues or error messages related to {zdm}.
[#configuration-changes-arent-applied-by-zdm-automation]
-=== Configuration changes aren't applied by {product-automation}
+=== Configuration changes aren't applied by {zdm-automation}
-If some configuration changes aren't applied to your {product-proxy} instances after a rolling restart, this typically means that you modified an immutable configuration variable.
+If some configuration changes aren't applied to your {zdm-proxy} instances after a rolling restart, this typically means that you modified an immutable configuration variable.
-Not all {product-proxy} configuration variables can be changed after deployment, with or without a rolling restart.
+Not all {zdm-proxy} configuration variables can be changed after deployment, with or without a rolling restart.
For a list of variables that you can change on a live deployment, see xref:manage-proxy-instances.adoc#change-mutable-config-variable[Change mutable configuration variables].
Any configuration variables excluded from the mutable variables list are considered _immutable_, and you must fully redeploy your instances to change them.
@@ -92,9 +92,9 @@ Allowing these values to change from a rolling restart could propagate a misconf
If you change the value of an immutable configuration variable, you must run the `deploy_zdm_proxy.yml` playbook again.
You can run this playbook as many times as needed.
-Each time, {product-automation} re-creates your entire {product-proxy} deployment with the new configuration.
-However, this doesn't happen in a rolling fashion: The existing {product-proxy} instances are torn down simultaneously, and then they are re-created.
-This results in a brief period of downtime where the entire {product-proxy} deployment is unavailable.
+Each time, {zdm-automation} re-creates your entire {zdm-proxy} deployment with the new configuration.
+However, this doesn't happen in a rolling fashion: The existing {zdm-proxy} instances are torn down simultaneously, and then they are re-created.
+This results in a brief period of downtime where the entire {zdm-proxy} deployment is unavailable.
=== Client application throws unsupported protocol version error
@@ -132,9 +132,9 @@ For more information, see the documentation for your version of the Java driver:
=== Logs report protocol errors but clients connect successfully
-`PROTOCOL ERROR` messages in {product-proxy} logs are a normal part of the handshake process while the protocol version is being negotiated.
+`PROTOCOL ERROR` messages in {zdm-proxy} logs are a normal part of the handshake process while the protocol version is being negotiated.
-These messages indicate that a protocol version downgrades happened because {product-proxy} or one of the clusters doesn't support the version requested by the client.
+These messages indicate that a protocol version downgrades happened because {zdm-proxy} or one of the clusters doesn't support the version requested by the client.
Protocol version downgrades result from a request by a cluster that doesn't support the version that the client requested.
include::ROOT:partial$cassandra-protocol-versions.adoc[]
@@ -150,14 +150,14 @@ msg=Invalid or unsupported protocol version (5)).\"\n","stream":"stderr","time":
`PROTOCOL ERROR` messages recorded at a higher log level, especially `level=error`, might indicate a bug because this means that the error occurred outside of the handshake process.
This is a fatal unexpected error that terminates the connection.
-If you observe this behavior in your logs, <> so the issue can be investigated by the {product-short} team.
+If you observe this behavior in your logs, <> so the issue can be investigated by the {zdm-short} team.
=== Proxy fails to start due to invalid or unsupported protocol version
-If the {product-proxy} logs contain `debug` messages with `Invalid or unsupported protocol version: 3`, this means that one of the origin clusters doesn't support protocol `V3` or later.
+If the {zdm-proxy} logs contain `debug` messages with `Invalid or unsupported protocol version: 3`, this means that one of the origin clusters doesn't support protocol `V3` or later.
Specifically, this happens with {cass-short} 2.0 and {dse-short} 4.6.
-{product-short} cannot be used for these migrations because the {product-proxy} control connections don't perform protocol version negotiation; they only attempt to use `V3`.
+{zdm-short} cannot be used for these migrations because the {zdm-proxy} control connections don't perform protocol version negotiation; they only attempt to use `V3`.
.Example: Invalid or unsupported protocol version logs
[source,log]
@@ -192,33 +192,33 @@ time="2022-10-01T19:58:15+01:00" level=error msg="Couldn't start proxy, retrying
Authentication errors indicate that credentials are incorrect or have insufficient permissions.
-There are three sets of credentials used with {product-proxy}:
+There are three sets of credentials used with {zdm-proxy}:
-* Target cluster: Credentials that you set in the {product-proxy} configuration through the `ZDM_TARGET_USERNAME` and `ZDM_TARGET_PASSWORD` settings.
+* Target cluster: Credentials that you set in the {zdm-proxy} configuration through the `ZDM_TARGET_USERNAME` and `ZDM_TARGET_PASSWORD` settings.
-* Origin cluster: Credentials that you set in the {product-proxy} configuration through the `ZDM_ORIGIN_USERNAME` and `ZDM_ORIGIN_PASSWORD` settings.
+* Origin cluster: Credentials that you set in the {zdm-proxy} configuration through the `ZDM_ORIGIN_USERNAME` and `ZDM_ORIGIN_PASSWORD` settings.
* Client application: Credentials that the client application sends to the proxy during the connection handshake.
These are set in the application configuration, not the proxy configuration.
Authentication errors mean that at least one of these three sets of credentials is incorrect or has insufficient permissions.
-If the authentication error prevents {product-proxy} from starting, then the issue is in the origin or target cluster credentials.
+If the authentication error prevents {zdm-proxy} from starting, then the issue is in the origin or target cluster credentials.
The log message shows whether the origin or target handshake failed.
-If {product-proxy} starts but the logs contain a message like `Proxy started. Waiting for SIGINT/SIGTERM to shutdown`, then the authentication error occurs when a client application tries to open a connection to the proxy.
+If {zdm-proxy} starts but the logs contain a message like `Proxy started. Waiting for SIGINT/SIGTERM to shutdown`, then the authentication error occurs when a client application tries to open a connection to the proxy.
This means that the client application itself has invalid credentials, such as an incorrect username/password, expired token, or insufficient permissions.
[TIP]
====
Proxy startup messages are reported at `level=info`.
-If your configured log level is `warning` or `error`, you won't see these messages in the logs, and you must use another method to determine if {product-proxy} started correctly.
-For example, you can check if the {product-proxy} process or Docker container is running, or check for log messages like `Error launching proxy`.
+If your configured log level is `warning` or `error`, you won't see these messages in the logs, and you must use another method to determine if {zdm-proxy} started correctly.
+For example, you can check if the {zdm-proxy} process or Docker container is running, or check for log messages like `Error launching proxy`.
====
-=== {product-proxy} listens on a custom port, and all applications connect to one proxy instance only
+=== {zdm-proxy} listens on a custom port, and all applications connect to one proxy instance only
-If {product-proxy} is listening on a custom port (not 9042), you might see either of the following issues:
+If {zdm-proxy} is listening on a custom port (not 9042), you might see either of the following issues:
* The Grafana dashboard shows only one proxy instance receiving all the connections from the application.
* Only one proxy instance has log messages like `level=info msg="Accepted connection from 10.4.77.210:39458"`.
@@ -226,7 +226,7 @@ If {product-proxy} is listening on a custom port (not 9042), you might see eithe
This happens because the application specifies the custom port as part of the contact points using the format
`**PROXY_IP_ADDRESS**:**CUSTOM_PORT**`.
-For example, if the {product-proxy} instances were listening on port 14035, the contact points for the {cass-short} Java driver might be specified as `.addContactPoints("172.18.10.36:14035", "172.18.11.48:14035", "172.18.12.61:14035")`.
+For example, if the {zdm-proxy} instances were listening on port 14035, the contact points for the {cass-short} Java driver might be specified as `.addContactPoints("172.18.10.36:14035", "172.18.11.48:14035", "172.18.12.61:14035")`.
The contact point is the first point of contact to the cluster, but the driver discovers the rest of the nodes through CQL queries.
However, this discovery process finds the addresses only, not the ports.
@@ -245,7 +245,7 @@ For example, for the Java driver, use `.withPort(**CUSTOM_PORT**)`:
=== Proxy logs contain SyntaxError no viable alternative at input 'CALL'
-{product-proxy} log messages such as the following indicate that the server doesn't recognize the word "CALL" in the query string, which typically means that it is a remote procedure call (RPC):
+{zdm-proxy} log messages such as the following indicate that the server doesn't recognize the word "CALL" in the query string, which typically means that it is a remote procedure call (RPC):
[source,log]
----
@@ -264,26 +264,26 @@ For example, in the Java driver, you can set `{java-driver-url}/blob/4.x/core/sr
=== Default Grafana credentials don't work
-When you deploy the {product-automation} metrics component, a Grafana instance is deployed that _doesn't_ use Grafana's default `admin`/`admin` credentials.
+When you deploy the {zdm-automation} metrics component, a Grafana instance is deployed that _doesn't_ use Grafana's default `admin`/`admin` credentials.
-Instead, {product-automation} specifies a custom set of credentials.
+Instead, {zdm-automation} specifies a custom set of credentials.
-You can find the credentials for your {product-automation} Grafana instance in the `vars/zdm_monitoring_config.yml` file in the {product-automation} directory.
+You can find the credentials for your {zdm-automation} Grafana instance in the `vars/zdm_monitoring_config.yml` file in the {zdm-automation} directory.
You can also modify these credentials before deploying the metrics stack.
=== Proxy starts but client cannot connect (connection timed out or connection closed)
-If the {product-proxy} logs contain messages like `Couldn't connect to`, `context timed out or cancelled while opening connection`, and `context deadline exceeded`, it can indicate that the {product-proxy} couldn't establish a connection with a particular node.
+If the {zdm-proxy} logs contain messages like `Couldn't connect to`, `context timed out or cancelled while opening connection`, and `context deadline exceeded`, it can indicate that the {zdm-proxy} couldn't establish a connection with a particular node.
-This can happen because {product-proxy} has connectivity to a specific subset of the nodes.
-The control connection, which is established during {product-proxy} startup, cycles through the nodes until it finds one that it can connect to successfully.
+This can happen because {zdm-proxy} has connectivity to a specific subset of the nodes.
+The control connection, which is established during {zdm-proxy} startup, cycles through the nodes until it finds one that it can connect to successfully.
For client connections, each proxy instance cycles through its assigned nodes only.
Each proxy instance has a different group of _assigned nodes_, which are a subset of the cluster nodes.
Generally, these are unique for each proxy instances to avoid interference with load balancing that is already in place at client-side driver level.
The assigned nodes aren't necessarily contact points: Even discovered nodes undergo assignment to proxy instances.
-In the following example, {product-proxy} doesn't have connectivity to `10.0.63.20`, which was chosen as the origin node for the incoming client connection, but it connected to `10.0.63.163` during startup:
+In the following example, {zdm-proxy} doesn't have connectivity to `10.0.63.20`, which was chosen as the origin node for the incoming client connection, but it connected to `10.0.63.163` during startup:
[source,log]
----
@@ -313,21 +313,21 @@ ERRO[0066] [openTCPConnectionWithBackoff] Couldn't connect to 10.0.63.20:9042, r
ERRO[0076] Client Handler could not be created: ORIGIN-CONNECTOR context timed out or cancelled while opening connection to ORIGIN: context deadline exceeded
----
-To avoid this issue, ensure that a stable network connection exists between the {product-proxy} instances and all nodes of your origin and target clusters in the client application's local datacenter.
+To avoid this issue, ensure that a stable network connection exists between the {zdm-proxy} instances and all nodes of your origin and target clusters in the client application's local datacenter.
=== Client application driver takes too long to reconnect to a proxy instance
-When a {product-proxy} instance comes back online after being unavailable for some time, then your client application might take too long to reconnect.
+When a {zdm-proxy} instance comes back online after being unavailable for some time, then your client application might take too long to reconnect.
-If {product-proxy} doesn't send topology events to the client application, the driver's reconnection policy determines the time required for the driver to reconnect to the {product-proxy} instance.
+If {zdm-proxy} doesn't send topology events to the client application, the driver's reconnection policy determines the time required for the driver to reconnect to the {zdm-proxy} instance.
You can restart the client application to force an immediate reconnection attempt.
-If you expect {product-proxy} instances to go down frequently, change the driver's reconnection policy to shorten the interval between reconnection attempts.
+If you expect {zdm-proxy} instances to go down frequently, change the driver's reconnection policy to shorten the interval between reconnection attempts.
-=== {astra} DevOps API errors when using {product-automation}
+=== {astra} DevOps API errors when using {zdm-automation}
-{product-automation} logs might report errors that contain your {astra} DevOps API endpoint:
+{zdm-automation} logs might report errors that contain your {astra} DevOps API endpoint:
[source,log]
----
@@ -337,11 +337,11 @@ Connection failure: Remote end closed connection without response", "redirected"
----
This can indicate that the {astra} DevOps API is temporarily unavailable.
-You can either wait to retry the operation, or you can xref:astra-db-serverless:databases:secure-connect-bundle.adoc[download your database's {scb} from the {astra-ui}], and then provide the path the {scb-short} zip file in the xref:deploy-proxy-monitoring.adoc#cluster-and-core-configuration[{product-automation} configuration].
+You can either wait to retry the operation, or you can xref:astra-db-serverless:databases:secure-connect-bundle.adoc[download your database's {scb} from the {astra-ui}], and then provide the path the {scb-short} zip file in the xref:deploy-proxy-monitoring.adoc#cluster-and-core-configuration[{zdm-automation} configuration].
=== Metadata service returned not successful status code (4xx or 5xx)
-If {product-proxy} doesn't start, the logs might contain messages with `not successful status code`:
+If {zdm-proxy} doesn't start, the logs might contain messages with `not successful status code`:
[source,log]
----
@@ -351,7 +351,7 @@ metadata service (Astra) returned not successful status code
There are two possible causes for this:
-* The credentials that {product-proxy} is using for {astra-db} don't have sufficient permissions.
+* The credentials that {zdm-proxy} is using for {astra-db} don't have sufficient permissions.
* The {astra-db} database is hibernated or otherwise unavailable.
To resolve this issue, sign in to the {astra-ui}, and then check the xref:astra-db-serverless:databases:database-statuses.adoc[database status].
@@ -364,7 +364,7 @@ Try using an xref:astra-db-serverless:administration:manage-application-tokens.a
[[_async_read_timeouts_stream_id_map_exhausted]]
=== Async read timeouts / stream id map exhausted
-When dual reads are enabled, you might find the following messages in the {product-proxy} logs:
+When dual reads are enabled, you might find the following messages in the {zdm-proxy} logs:
[source,log]
----
@@ -388,63 +388,63 @@ In this case the async connection might not recover.
Starting in version 2.1.0, you can tune the maximum number of stream IDs available per connection.
The default is 2048, and you can increase it to match your driver configuration with the `xref:manage-proxy-instances.adoc#zdm_proxy_max_stream_ids[zdm_proxy_max_stream_ids]` property.
-If you are running a version prior to 2.1.0, upgrade {product-proxy}.
+If you are running a version prior to 2.1.0, upgrade {zdm-proxy}.
-If these errors are constantly written to the log files over a period of minutes or hours, then you likely need to restart the client application _or_ {product-proxy} to fix the issue.
-If you find an error like this, <> so the {product-short} team can investigate it.
+If these errors are constantly written to the log files over a period of minutes or hours, then you likely need to restart the client application _or_ {zdm-proxy} to fix the issue.
+If you find an error like this, <> so the {zdm-short} team can investigate it.
[#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}
-This issue is fixed in {product-proxy} 2.1.0.
+This issue is fixed in {zdm-proxy} 2.1.0.
-In {product-proxy} versions earlier than 2.1.0, the logs can report that the {astra-db} `TARGET-CONNECTOR` is disconnected every 10 minutes.
+In {zdm-proxy} versions earlier than 2.1.0, the logs can report that the {astra-db} `TARGET-CONNECTOR` is disconnected every 10 minutes.
This happens because {astra-db} terminates idle connections after 10 minutes of inactivity.
-In the absence of asynchronous dual reads, the target cluster won't get any traffic when the client application produces only read requests because {product-short} forwards all reads to the origin cluster only.
+In the absence of asynchronous dual reads, the target cluster won't get any traffic when the client application produces only read requests because {zdm-short} forwards all reads to the origin cluster only.
-To resolve this issue, {company} recommends that you upgrade your {product-proxy} instances to 2.1.0 or later to take advantage of the heartbeats feature, which keeps the connection alive during periods of inactivity.
-You can tune the heartbeat interval 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}.
+To resolve this issue, {company} recommends that you upgrade your {zdm-proxy} instances to 2.1.0 or later to take advantage of the heartbeats feature, which keeps the connection alive during periods of inactivity.
+You can tune the heartbeat interval 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 {zdm-automation}.
If upgrading is impossible, you can try the following alternatives:
-* Don't connect the read-only client applications to {product-proxy}, and then manually ensure that these client applications switch reads to the target at any point after all the data has been migrated, validated, and reconciled on the target cluster.
+* Don't connect the read-only client applications to {zdm-proxy}, and then manually ensure that these client applications switch reads to the target at any point after all the data has been migrated, validated, and reconciled on the target cluster.
* Implement a mechanism in your client application that creates a new `Session` periodically to avoid the {astra-db} inactivity timeout.
* Implement a mechanism in your client application to issue a periodic meaningless write request to prevent the {astra-db} connection from becoming idle.
-=== Performance degradation with {product-proxy}
+=== Performance degradation with {zdm-proxy}
-If you run separate benchmarks against {astra-db} directly, the origin cluster directly, and {product-proxy} with both {astra-db} and the origin cluster, then the results of these tests might show that latency or throughput is worse with {product-proxy} than when connecting to {astra-db} or origin cluster directly.
+If you run separate benchmarks against {astra-db} directly, the origin cluster directly, and {zdm-proxy} with both {astra-db} and the origin cluster, then the results of these tests might show that latency or throughput is worse with {zdm-proxy} than when connecting to {astra-db} or origin cluster directly.
-This is observed because {product-short} always increases latency and, depending on the nature of the test, reduces throughput.
-Whether this performance hit is expected or not depends on the difference between the {product-short} test results and the test results with the cluster that performed the worst.
+This is observed because {zdm-short} always increases latency and, depending on the nature of the test, reduces throughput.
+Whether this performance hit is expected or not depends on the difference between the {zdm-short} test results and the test results with the cluster that performed the worst.
-Writes through {product-short} require successful acknowledgement from both clusters, whereas reads require only the result from the primary cluster, which is typically the origin cluster.
-This means that if the origin cluster has better performance than the target cluster, then {product-short} will inevitably have worse write performance than the target cluster alone.
+Writes through {zdm-short} require successful acknowledgement from both clusters, whereas reads require only the result from the primary cluster, which is typically the origin cluster.
+This means that if the origin cluster has better performance than the target cluster, then {zdm-short} will inevitably have worse write performance than the target cluster alone.
-Although it is typical for latency to increase with {product-proxy}, you can minimize performance degradation with {product-proxy}:
+Although it is typical for latency to increase with {zdm-proxy}, you can minimize performance degradation with {zdm-proxy}:
-* Make sure your {product-proxy} infrastructure or configuration doesn't unnecessarily increase latency.
+* Make sure your {zdm-proxy} infrastructure or configuration doesn't unnecessarily increase latency.
+
-For example, make sure your {product-proxy} instances are in the same availability zone (AZ) as your origin cluster or application instances.
+For example, make sure your {zdm-proxy} instances are in the same availability zone (AZ) as your origin cluster or application instances.
* Understand the impact of simple and batch statements on latency, as compared to typical prepared statements.
+
-Avoid simple statements with {product-proxy} because they require significant time for {product-proxy} to parse the queries.
+Avoid simple statements with {zdm-proxy} because they require significant time for {zdm-proxy} to parse the queries.
+
As an alternative, use prepared statements, which are parsed once, and then reused on subsequent requests if repreparation isn't required.
-However, inefficient use of prepared statements can degrade performance further, but this would be observed even without {product-proxy}.
+However, inefficient use of prepared statements can degrade performance further, but this would be observed even without {zdm-proxy}.
* Increase the number of proxies only if the VMs resources (CPU, RAM or network IO) are near capacity.
-{product-proxy} doesn't use a lot of RAM, but it uses a lot of CPU and network IO.
-Deploying the proxy instances on VMs with faster CPUs and faster network IO might help, but there is no standardized approach to scaling these resources for {product-proxy}.
+{zdm-proxy} doesn't use a lot of RAM, but it uses a lot of CPU and network IO.
+Deploying the proxy instances on VMs with faster CPUs and faster network IO might help, but there is no standardized approach to scaling these resources for {zdm-proxy}.
This is because the ideal balance of resources depends on the workload type and your environment, such as network/VPC configurations and hardware.
If you choose to adjust the infrastructure, you must repeat your tests to determine if there was any benefit
=== Permission errors related to InsightsRpc
-If the {product-proxy} logs contain messages such as the following, it's likely that you have an origin {dse-short} cluster where {metrics-collector} is enabled, and the user named in the logs doesn't have sufficient permissions to report Insights data:
+If the {zdm-proxy} logs contain messages such as the following, it's likely that you have an origin {dse-short} cluster where {metrics-collector} is enabled, and the user named in the logs doesn't have sufficient permissions to report Insights data:
[source,log]
----
@@ -452,7 +452,7 @@ time="2023-05-05T19:14:31Z" level=debug msg="Recording ORIGIN-CONNECTOR other er
time="2023-05-05T19:14:31Z" level=debug msg="Recording TARGET-CONNECTOR other error: ERROR SERVER ERROR (code=ErrorCode ServerError [0x00000000], msg=Unexpected persistence error: Unable to authorize statement com.datastax.bdp.cassandra.cql3.RpcCallStatement)"
----
-These are reported as `level=debug`, so {product-proxy} isn't affected by them.
+These are reported as `level=debug`, so {zdm-proxy} isn't affected by them.
There are two ways to resolve this issue:
@@ -487,12 +487,12 @@ Replace **USER** with the actual username given in the logs.
[#report-an-issue]
== Report an issue
-To report an issue or get additional support, submit an issue in the {product-short} component GitHub repositories:
+To report an issue or get additional support, submit an issue in the {zdm-short} component GitHub repositories:
-* {product-proxy-repo}/issues[{product-proxy} repository]
-* {product-automation-repo}/issues[{product-automation} repository] (includes {product-automation} and {product-utility})
-* {cass-migrator-repo}/issues[{cass-migrator-short} repository]
-* {dsbulk-repo}/issues[{dsbulk-short} repository]
+* {zdm-proxy-repo-url}/issues[{zdm-proxy} repository]
+* {zdm-automation-repo-url}/issues[{zdm-automation} repository] (includes {zdm-automation} and {zdm-utility})
+* {cass-migrator-repo-url}/issues[{cass-migrator-short} repository]
+* {dsbulk-repo-url}/issues[{dsbulk-short} repository]
[IMPORTANT]
====
@@ -503,14 +503,14 @@ Don't include any proprietary or private information in issues, pull requests, o
In the issue description, include as much of the following information as possible, and make sure to remove all proprietary and private information before submitting the issue:
-* Your <>.
+* Your <>.
-* <>, ideally at `DEBUG` level, if you can easily reproduce the issue and tolerate restarting the proxy instances to apply the log level configuration change.
+* <>, ideally at `DEBUG` level, if you can easily reproduce the issue and tolerate restarting the proxy instances to apply the log level configuration change.
* Database deployment type ({dse-short}, {hcd-short}, {cass-short}, or {astra-db}) and version for the origin and target clusters.
The version isn't required for {astra-db}.
-* Screenshots of the xref:ROOT:metrics.adoc[{product-proxy} metrics] dashboards from Grafana or your chosen visualization tool.
+* Screenshots of the xref:ROOT:metrics.adoc[{zdm-proxy} metrics] dashboards from Grafana or your chosen visualization tool.
+
Direct read access to your metrics dashboard is preferred, if permitted by your security policy.
This is particularly helpful for performance-related issues.
@@ -534,8 +534,8 @@ For performance-related issues, provide the following additional information:
This feature is disabled by default.
To determine if this feature is enabled, check the following variables:
+
-** If you use {product-automation}, check the Ansible advanced configuration variable `replace_cql_functions`.
-** If you don't use {product-automation}, check the environment variable `ZDM_REPLACE_CQL_FUNCTIONS`.
+** If you use {zdm-automation}, check the Ansible advanced configuration variable `replace_cql_functions`.
+** If you don't use {zdm-automation}, check the environment variable `ZDM_REPLACE_CQL_FUNCTIONS`.
== See also
diff --git a/modules/ROOT/pages/zdm-logs.adoc b/modules/ROOT/pages/zdm-logs.adoc
index e0eab094..70947927 100644
--- a/modules/ROOT/pages/zdm-logs.adoc
+++ b/modules/ROOT/pages/zdm-logs.adoc
@@ -1,35 +1,35 @@
-= Configure and read {product-proxy} logs
-:navtitle: Get {product-short} logs
-:description: Configure and retrieve {product-proxy} logs.
+= Configure and read {zdm-proxy} logs
+:navtitle: Get {zdm-short} logs
+:description: Configure and retrieve {zdm-proxy} logs.
include::ROOT:partial$zdm-logs-intro.adoc[]
[#set-the-zdm-proxy-log-level]
-== Set the {product-proxy} log level
+== Set the {zdm-proxy} log level
-Set the {product-proxy} log level to print the messages that you need.
+Set the {zdm-proxy} log level to print the messages that you need.
The default log level is `INFO`, which is adequate for most logging.
If you need more detail for temporary troubleshooting, you can set the log level to `DEBUG`.
However, this can slightly degrade performance, and {company} recommends that you revert to `INFO` logging as soon as possible.
-How you set the log level depends on how you deployed {product-proxy}:
+How you set the log level depends on how you deployed {zdm-proxy}:
-* If you used {product-automation} to deploy {product-proxy}, set `log_level` in `vars/zdm_proxy_core_config.yml`, and then run the `rolling_update_zdm_proxy.yml` playbook.
+* If you used {zdm-automation} to deploy {zdm-proxy}, set `log_level` in `vars/zdm_proxy_core_config.yml`, and then run the `rolling_update_zdm_proxy.yml` playbook.
For more information, see xref:manage-proxy-instances.adoc#change-mutable-config-variable[Change a mutable configuration variable].
-* If you didn't use {product-automation} to deploy {product-proxy}, set the `ZDM_LOG_LEVEL` environment variable on each proxy instance, and then restart each instance.
+* If you didn't use {zdm-automation} to deploy {zdm-proxy}, set the `ZDM_LOG_LEVEL` environment variable on each proxy instance, and then restart each instance.
-== Get {product-proxy} log files
+== Get {zdm-proxy} log files
-If you used {product-automation} to deploy {product-proxy}, then you can get logs for a single proxy instance, and you can use a playbook to retrieve logs for all instances.
+If you used {zdm-automation} to deploy {zdm-proxy}, then you can get logs for a single proxy instance, and you can use a playbook to retrieve logs for all instances.
=== View or tail logs for one instance
-{product-proxy} runs as a Docker container on each proxy host.
+{zdm-proxy} runs as a Docker container on each proxy host.
-To view the logs for a single {product-proxy} instance, connect to a proxy host, and then run the following command:
+To view the logs for a single {zdm-proxy} instance, connect to a proxy host, and then run the following command:
[source,bash]
----
@@ -47,7 +47,7 @@ Keep in mind that Docker logs are deleted if the container is re-created.
=== Collect logs for multiple instances
-{product-automation} has a dedicated playbook, `collect_zdm_proxy_logs.yml`, that you can use to collect logs for all {product-proxy} instances in a deployment.
+{zdm-automation} has a dedicated playbook, `collect_zdm_proxy_logs.yml`, that you can use to collect logs for all {zdm-proxy} instances in a deployment.
You can view the playbook's configuration in `vars/zdm_proxy_log_collection_config.yml`, but no changes are required to run it.
@@ -87,9 +87,9 @@ Replace the following:
* `**TIMESTAMP**`: The timestamp from the name of your log file archive
* `**DESTINATION_DIRECTORY_ON_JUMPHOST**`: The path to the directory where you want to copy the archive
-=== Get logs for deployments that don't use {product-automation}
+=== Get logs for deployments that don't use {zdm-automation}
-If you didn't use {product-automation} to deploy {product-proxy}, you must access the logs another way, depending on your deployment configuration and infrastructure.
+If you didn't use {zdm-automation} to deploy {zdm-proxy}, you must access the logs another way, depending on your deployment configuration and infrastructure.
For example, if you used Docker, you can use the following command to export a container's logs to a `log.txt` file:
@@ -114,17 +114,17 @@ However, they can help you find the source of a problem by providing information
* `level=warn`: Reports an event that wasn't fatal to the overall process but might indicate an issue with an individual request or connection.
-* `level=error`: Indicates an issue with {product-proxy}, the client application, or the clusters.
+* `level=error`: Indicates an issue with {zdm-proxy}, the client application, or the clusters.
These messages require further examination.
If the meaning of a `warn` or `error` message isn't clear, you can <>.
== Common log messages
-Here are some of the most common messages in the {product-proxy} logs.
+Here are some of the most common messages in the {zdm-proxy} logs.
-{product-proxy} startup message::
-If the log level doesn't filter out `info` entries, you can look for a `Proxy started` log message to verify that {product-proxy} started correctly.
+{zdm-proxy} startup message::
+If the log level doesn't filter out `info` entries, you can look for a `Proxy started` log message to verify that {zdm-proxy} started correctly.
For example:
+
[source,json]
@@ -134,8 +134,8 @@ msg=\"Proxy started. Waiting for SIGINT/SIGTERM to shutdown.
\"\n","stream":"stderr","time":"2023-01-13T11:50:48.522097083Z"}
----
-{product-proxy} configuration message::
-If the log level doesn't filter out `info` entries, the first few lines of a {product-proxy} log file contain all configuration variables and values in a long JSON string.
+{zdm-proxy} configuration message::
+If the log level doesn't filter out `info` entries, the first few lines of a {zdm-proxy} log file contain all configuration variables and values in a long JSON string.
+
The following example log message is truncated for readability:
+
diff --git a/modules/ROOT/pages/zdm-proxy-migration-paths.adoc b/modules/ROOT/pages/zdm-proxy-migration-paths.adoc
index 6c13c5c0..734c75c5 100644
--- a/modules/ROOT/pages/zdm-proxy-migration-paths.adoc
+++ b/modules/ROOT/pages/zdm-proxy-migration-paths.adoc
@@ -1,5 +1,5 @@
-= Cluster compatibility for {product}
-:description: Learn which sources and targets are eligible for {product}.
+= Cluster compatibility for {zdm}
+:description: Learn which sources and targets are eligible for {zdm}.
True zero downtime migration is only possible if your database meets the minimum requirements described in xref:ROOT:feasibility-checklists.adoc[], including compatibility of the origin (source) and target (destination) clusters.
@@ -10,9 +10,9 @@ include::ROOT:partial$migration-scenarios.adoc[]
[#incompatible-clusters-and-migrations-with-some-downtime]
== Incompatible clusters and migrations with some downtime
-If you don't want to use {product-proxy} or your databases don't meet the zero-downtime requirements, you can still complete the migration, but some downtime might be necessary to finish the migration.
+If you don't want to use {zdm-proxy} or your databases don't meet the zero-downtime requirements, you can still complete the migration, but some downtime might be necessary to finish the migration.
-If your origin cluster is incompatible with {product-proxy}, {product-utility}, and {product-automation}, you might be able to use standalone xref:ROOT:components.adoc#data-migration-tools[data migration tools] such as {dsbulk-short} or a custom data migration script.
+If your origin cluster is incompatible with {zdm-proxy}, {zdm-utility}, and {zdm-automation}, you might be able to use standalone xref:ROOT:components.adoc#data-migration-tools[data migration tools] such as {dsbulk-short} or a custom data migration script.
Make sure you transform or prepare the data to comply with the target cluster's schema.
For more complex migrations, such as RDBMS-to-NoSQL migrations, it is likely that your migration will require downtime for additional processing, such as extract, transform, and load (ETL) operations.
diff --git a/modules/ROOT/partials/cassandra-protocol-versions.adoc b/modules/ROOT/partials/cassandra-protocol-versions.adoc
index c52b697c..842476da 100644
--- a/modules/ROOT/partials/cassandra-protocol-versions.adoc
+++ b/modules/ROOT/partials/cassandra-protocol-versions.adoc
@@ -1 +1 @@
-{product-proxy} supports protocol `V2`, `V3`, `V4`, `V5`, `DSE_V1`, and `DSE_V2`.
\ No newline at end of file
+{zdm-proxy} supports protocol `V2`, `V3`, `V4`, `V5`, `DSE_V1`, and `DSE_V2`.
\ No newline at end of file
diff --git a/modules/ROOT/partials/dsbulk-migrator-deprecation.adoc b/modules/ROOT/partials/dsbulk-migrator-deprecation.adoc
index 36aaedeb..6f4b60db 100644
--- a/modules/ROOT/partials/dsbulk-migrator-deprecation.adoc
+++ b/modules/ROOT/partials/dsbulk-migrator-deprecation.adoc
@@ -1,3 +1,3 @@
-The {dsbulk-migrator} tool, which was an extension of {dsbulk}, is deprecated.
+The {dsbulk-short} Migrator tool, which was an extension of {dsbulk}, is deprecated.
This tool is no longer recommended.
Instead, use the unload, load, and count commands included with {dsbulk-short}, or use another data migration tool, such as {cass-migrator-short}.
\ No newline at end of file
diff --git a/modules/ROOT/partials/migration-scenarios.adoc b/modules/ROOT/partials/migration-scenarios.adoc
index fa943ddb..36c88071 100644
--- a/modules/ROOT/partials/migration-scenarios.adoc
+++ b/modules/ROOT/partials/migration-scenarios.adoc
@@ -1,7 +1,7 @@
-You can use {product-proxy} to support migrations between {astra}, {dse}, {hcd}, open-source {cass-reg}, and and other {cass-short}-based databases.
+You can use {zdm-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}.
+{company} tests {zdm-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} 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.
@@ -13,7 +13,7 @@ Migrate from one of the following:
* {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].
+{zdm-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.
@@ -31,6 +31,6 @@ Check the xref:6.9@dse:planning:compatibility.adoc[built-in {cass-short} version
[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.
+You can use {zdm-short} for major version upgrades to your current database platform, such as upgrades from {dse-short} 5.0 to {dse-short} 6.9.
+Using {zdm-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
diff --git a/modules/ROOT/partials/zdm-logs-intro.adoc b/modules/ROOT/partials/zdm-logs-intro.adoc
index 04bd663d..9486978a 100644
--- a/modules/ROOT/partials/zdm-logs-intro.adoc
+++ b/modules/ROOT/partials/zdm-logs-intro.adoc
@@ -1 +1 @@
-{product-proxy} logs can help you verify that your {product-proxy} instances are operating normally, investigate how processes are executed, and troubleshoot issues.
\ No newline at end of file
+{zdm-proxy} logs can help you verify that your {zdm-proxy} instances are operating normally, investigate how processes are executed, and troubleshoot issues.
\ No newline at end of file
diff --git a/modules/sideloader/pages/prepare-sideloader.adoc b/modules/sideloader/pages/prepare-sideloader.adoc
index 1f3ce2d9..f06a37fb 100644
--- a/modules/sideloader/pages/prepare-sideloader.adoc
+++ b/modules/sideloader/pages/prepare-sideloader.adoc
@@ -161,7 +161,7 @@ If you choose the alternative option, you must modify the commands accordingly f
* *{sstable-sideloader} doesn't support encrypted data*: If your origin cluster uses xref:6.9@dse:securing:transparent-data-encryption.adoc[{dse-short} Transparent Data Encryption], be aware that {sstable-sideloader} cannot migrate these SSTables.
+
If you have a mix of encrypted and unencrypted data, you can use {sstable-sideloader} to migrate the unencrypted data.
-After the initial migration, you can use another strategy to move the encrypted data, such as {cass-migrator-repo}[{cass-migrator}] or a manual export and reupload.
+After the initial migration, you can use another strategy to move the encrypted data, such as {cass-migrator-repo-url}[{cass-migrator}] or a manual export and reupload.
* *{sstable-sideloader} doesn't support secondary indexes*: If you don't remove or replace these in your origin cluster, {sstable-sideloader} ignores these directories when importing the data to your {astra-db} database.
@@ -173,7 +173,7 @@ Your administration server must have SSH access to each node in your origin clus
{company} recommends that you install the following additional software on your administration server:
-* {cass-migrator-repo}[{cass-migrator-short}] to validate imported data and, with {product-proxy}, reconcile it with the origin cluster.
+* {cass-migrator-repo-url}[{cass-migrator-short}] to validate imported data and, with {zdm-proxy}, reconcile it with the origin cluster.
* https://jqlang.github.io/jq/[jq] to format JSON responses from the {astra} {devops-api}.
The {devops-api} commands in this guide use this tool.
@@ -237,7 +237,7 @@ The number of node snapshots that you uploaded to the migration bucket doesn't d
The success of the import depends primarily on the validity of the schemas and the data in the snapshots.
. After the import, validate the migrated data to ensure that it matches the data in the origin cluster.
-For example, you can xref:ROOT:cassandra-data-migrator.adoc#cdm-validation-steps[run {cass-migrator-short} in validation mode].
+For example, you can {cass-migrator-repo-url}?tab=readme-ov-file#steps-for-data-validation[run {cass-migrator-short} in validation mode].
==== Migrate multiple nodes to multiple databases
@@ -278,7 +278,7 @@ The number of node snapshots that you uploaded to the migration bucket doesn't d
The success of the import depends primarily on the validity of the schemas and the data in the snapshots.\
. After the import, validate the migrated data to ensure that it matches the data in the origin cluster.
-For example, you can xref:ROOT:cassandra-data-migrator.adoc#cdm-validation-steps[run {cass-migrator-short} in validation mode].
+For example, you can {cass-migrator-repo-url}?tab=readme-ov-file#steps-for-data-validation[run {cass-migrator-short} in validation mode].
=== Multiple migrations to the same database
@@ -297,7 +297,7 @@ For example, if you have 10 migration IDs for the same database, you must run 10
Each import must completely finish before starting the next import.
After all of the imports are complete, validate the migrated data in your target database to ensure that it matches the data in the origin cluster.
-For example, you can xref:ROOT:cassandra-data-migrator.adoc#cdm-validation-steps[run {cass-migrator-short} in validation mode].
+For example, you can {cass-migrator-repo-url}?tab=readme-ov-file#steps-for-data-validation[run {cass-migrator-short} in validation mode].
== Next steps
diff --git a/modules/sideloader/pages/sideloader-overview.adoc b/modules/sideloader/pages/sideloader-overview.adoc
index c6a9c73a..491b5ea4 100644
--- a/modules/sideloader/pages/sideloader-overview.adoc
+++ b/modules/sideloader/pages/sideloader-overview.adoc
@@ -4,7 +4,7 @@
{sstable-sideloader} is a service running in {astra-db} that directly imports data from snapshot backups that you've uploaded to {astra-db} from an existing {cass-reg}, {dse}, or {hcd} cluster.
-Because it imports data directly, {sstable-sideloader} can offer several advantages over CQL-based tools like xref:dsbulk:overview:dsbulk-about.adoc[{dsbulk}] and xref:ROOT:cassandra-data-migrator.adoc[{cass-migrator}], including faster, more cost-effective data loading, and minimal performance impacts on your origin cluster and target database.
+Because it imports data directly, {sstable-sideloader} can offer several advantages over CQL-based tools like xref:dsbulk:overview:dsbulk-about.adoc[{dsbulk}] and {cass-migrator-repo-url}[{cass-migrator}], including faster, more cost-effective data loading, and minimal performance impacts on your origin cluster and target database.
== {sstable-sideloader} concepts
@@ -44,7 +44,7 @@ Each snapshot for each node in the origin cluster must include all the keyspaces
These snapshots are ideal for database migrations because creating snapshots has a negligible performance impact on the origin cluster, and the snapshots preserve metadata like `writetime` and `ttl` values.
-When using {sstable-sideloader} with {product-proxy}, {cass-short}'s last-write-wins semantics ensure that new, real-time writes accurately take precedence over historical writes.
+When using {sstable-sideloader} with {zdm-proxy}, {cass-short}'s last-write-wins semantics ensure that new, real-time writes accurately take precedence over historical writes.
Last-write-wins compares the `writetime` of conflicting records, and then retains the most recent write.
For example, if a new write occurs in your target database with a `writetime` of `2023-10-01T12:05:00Z`, and then {sstable-sideloader} migrates a record against the same row with a `writetime` of `2023-10-01T12:00:00Z`, the target database retains the data from the new write because it has the most recent `writetime`.
@@ -157,7 +157,7 @@ Once {sstable-sideloader} begins to import SSTable metadata (the next step), you
+
If the dataset contains tombstones, any read operations on the target database can return inconsistent results during this step.
Since compaction is disabled, there is no risk of permanent inconsistencies.
-However, in the context of xref:ROOT:introduction.adoc[{product}], it's important that the {product-short} proxy continues to read from the origin cluster.
+However, in the context of xref:ROOT:introduction.adoc[{zdm}], it's important that the {zdm-short} proxy continues to read from the origin cluster.
. Re-enables compactions on the {astra-db} Serverless database.
@@ -172,11 +172,11 @@ For instructions and more information, see xref:sideloader:migrate-sideloader.ad
include::sideloader:partial$validate.adoc[]
-== Use {sstable-sideloader} with {product-proxy}
+== Use {sstable-sideloader} with {zdm-proxy}
-If you need to migrate a live database, you can use {sstable-sideloader} instead of {dsbulk-short} or {cass-migrator-short} during of xref:ROOT:migrate-and-validate-data.adoc[Phase 2 of {product}].
+If you need to migrate a live database, you can use {sstable-sideloader} instead of {dsbulk-short} or {cass-migrator-short} during of xref:ROOT:migrate-and-validate-data.adoc[Phase 2 of {zdm}].
-.Use {sstable-sideloader} with {product-proxy}
+.Use {sstable-sideloader} with {zdm-proxy}
svg::sideloader:astra-migration-toolkit.svg[]
== Next steps
diff --git a/modules/sideloader/partials/validate.adoc b/modules/sideloader/partials/validate.adoc
index bac5da4d..df391ab1 100644
--- a/modules/sideloader/partials/validate.adoc
+++ b/modules/sideloader/partials/validate.adoc
@@ -1,4 +1,4 @@
After the migration is complete, you can query the migrated data using the xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[{cql-shell}] (`cqlsh`) or xref:astra-db-serverless:api-reference:row-methods/find-many.adoc[{data-api}].
-You can xref:ROOT:cassandra-data-migrator.adoc#cdm-validation-steps[run {cass-migrator-short} in validation mode] for more thorough validation.
+You can {cass-migrator-repo-url}?tab=readme-ov-file#steps-for-data-validation[run {cass-migrator-short} in validation mode] for more thorough validation.
{cass-migrator-short} also offers an AutoCorrect mode to reconcile any differences that it detects.
\ No newline at end of file
From a714614b2859497a50cc197d8627c95ad001c2de Mon Sep 17 00:00:00 2001
From: April M <36110273+aimurphy@users.noreply.github.com>
Date: Mon, 1 Jun 2026 09:32:46 -0700
Subject: [PATCH 2/2] fix attributes because I am a dumdum today
---
antora.yml | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/antora.yml b/antora.yml
index f5686ba8..052c8915 100644
--- a/antora.yml
+++ b/antora.yml
@@ -42,13 +42,13 @@ asciidoc:
devops-api: 'DevOps API'
devops-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$devops-api/index.html'
data-api: 'Data API'
- product: 'Zero Downtime Migration (ZDM)'
- product-short: 'ZDM'
- product-proxy: 'ZDM Proxy'
- product-proxy-repo: 'https://github.com/datastax/zdm-proxy'
- product-utility: 'ZDM Utility'
- product-automation: 'ZDM Proxy Automation'
- product-automation-repo: 'https://github.com/datastax/zdm-proxy-automation'
+ zdm: 'Zero Downtime Migration (ZDM)'
+ zdm-short: 'ZDM'
+ zdm-proxy: 'ZDM Proxy'
+ zdm-proxy-repo-url: 'https://github.com/datastax/zdm-proxy'
+ zdm-utility: 'ZDM Utility'
+ zdm-automation: 'ZDM Proxy Automation'
+ zdm-automation-repo-url: 'https://github.com/datastax/zdm-proxy-automation'
dsbulk: 'DataStax Bulk Loader (DSBulk)'
dsbulk-short: 'DSBulk'
dsbulk-repo-url: 'https://github.com/datastax/dsbulk'