DOC-5408 - move some content from driver doc, update astra connect

modules/ROOT/pages/connect-clients-to-proxy.adoc

@@ -115,35 +115,27 @@ For information about self-managed cluster credentials in your {product-proxy} c
 [#expected-authentication-credentials-for-astra-db]
 ==== Expected authentication credentials for {astra-db}
 
-For {astra-db} databases, your client application can provide either application token credentials or a {scb}.
-
-[tabs]
-======
-Application token::
-+
---
-For token-based authentication, do the following:
+For {astra-db} databases, your client application need your database's {scb} and an application token:
 
 . xref:astra-db-serverless:administration:manage-application-tokens.adoc[Generate an application token] with the *Organization Administrator* role.
+You can change the token to reduce the permissions after the migration, but this role is recommended to avoid permissions-related request failures during the migration.
 +
 The token has three values: `clientId`, `secret`, and `token`.
-
-. Specify one of the following sets of credentials in your client application:
-
-* Recommended: Set `username` to the literal string `token`, and set `password` to the {astra-db} `token` value (`AstraCS:...`).
-* Legacy applications and older drivers: Set `username` to the `clientId` value, and set `password` to the `secret` value.
---
-
-{scb-short}::
+You must specify one of the following sets of credentials in your client application:
 +
---
-For information about downloading the {scb-short}, see xref:astra-db-serverless:databases:secure-connect-bundle.adoc[].
+* Token-only authentication (Recommended): Set `username` to the literal string `token`, and set `password` to the actual application token (`AstraCS:...`).
+* Legacy authentication for older applications and drivers: Set `username` to the `clientId` value, and set `password` to the `secret` value.
 
-For information about using a {scb-short} with a driver, see your driver's documentation.
---
-======
+. Download your database's xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb-short}].
++
+[IMPORTANT]
+====
+The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates.
+Treat it as you would any other sensitive values, such as passwords or tokens.
+====
 
-For information about {astra-db} credentials in your {product-proxy} configuration, see xref:ROOT:deploy-proxy-monitoring.adoc#cluster-and-core-configuration[Cluster and core configuration].
+. Configure {product-proxy} to use your {astra-db} credentials when connecting to your {astra-db} database.
+For more information, see xref:ROOT:deploy-proxy-monitoring.adoc#cluster-and-core-configuration[{product-proxy} cluster and core configuration].
 
 === Disable client-side compression with {product-proxy}
 

modules/ROOT/pages/connect-clients-to-target.adoc

@@ -2,69 +2,136 @@
 :navtitle: Phase 5: Connect client applications directly to the target
 :page-tag: migration,zdm,zero-downtime,zdm-proxy,connect-apps,target
 
-//TODO: Add HCD (driver or data API) and Astra (Data API) options
+Phase 5 is the last phase of the xref:ROOT:introduction.adoc[migration process].
+In this phase, you configure your client applications to connect directly and exclusively to the target cluster.
+This removes the dependency on {product-proxy} and completes the migration.
 
-At this point in our migration phases, we've completed:
+image::migration-phase5ra.png[In Phase 5, your applications no longer using the proxy and, instead, connect directly to the target.]
 
-* Phase 1: Connected client applications to {product-proxy}, which included setting up Ansible playbooks with {product-utility} and using {product-automation} to deploy the {product-proxy} instances with the Docker container.
+The minimum requirements for reconfiguring these connections depend on whether your target cluster is {astra-db} or a generic CQL cluster, such as {cass-reg}, {dse}, or {hcd}.
 
-* Phase 2: Migrated and validated our data with {cass-migrator} and/or {dsbulk-migrator}.
+[WARNING]
+====
+Once you switch your client applications to connect directly to the target cluster, you can no longer cleanly roll back to the origin cluster.
+From this point onward, the clusters will diverge, and the target cluster becomes the source of truth for your client applications and data.
 
-* Phase 3: Optionally enabled async data reads to check that the target cluster can handle the full production workload of read/write traffic.
+Be sure that you have thoroughly xref:ROOT:migrate-and-validate-data.adoc[validated your data (Phase 2)], xref:ROOT:enable-async-dual-reads.adoc[tested your target cluster's performance (Phase 3)], and xref:ROOT:change-read-routing.adoc[routed all reads to the target (Phase 4)] before permanently switching the connection.
+====
 
-* Phase 4: Changed read routing to the target cluster.
+== Connect a driver to a generic CQL cluster
 
-In Phase 5 you will configure your client applications to connect directly to the target cluster.
-How you do this depends on whether your target cluster is {astra-db}, {cass-reg}, or {dse-short}.
+If your origin and target clusters are both generic CQL clusters ({cass-short}, {dse-short}, or {hcd-short}), then the driver connection strings can be similar, requiring only minor changes to connect to the target cluster.
 
-image::migration-phase5ra.png[In Phase 5, your apps no longer using the proxy and, instead, connect directly to the target.]
+. At minimum, update your driver configuration to use the appropriate contact points for your target cluster.
++
+You might need to make additional configuration changes depending on your target cluster's setup, such as authentication and encryption.
+For example, if you have execution profiles with unique datacenter-aware load balancing policies, you must update the profiles to use the target datacenters.
++
+For information about driver connections for different {cass-short}-compatible clusters, see xref:datastax-drivers:connecting:connect-cloud.adoc[].
 
-//For illustrations of all the migration phases, see the xref:introduction.adoc#_migration_phases[Introduction].
+. Verify that your driver version is compatible with your target cluster and supports the features that you want to use on your new cluster.
+For example, if you want to use the vector data type on an {hcd-short} cluster, you must use a driver version that supports both {hcd-short} and the vector type.
++
+When upgrading from an older driver version, you might need to make additional code changes to account for enhancements, deprecations, removals, and differences in platform features.
+Depending on your application's requirements, you might need to make these changes immediately, or you might make them after switching the connection.
++
+For more information on supported drivers, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
 
-== Configuring your driver to connect to a generic CQL cluster
+== Connect a driver to {astra-db}
 
-If your target cluster is a generic CQL cluster, such as {cass-short} or {dse-short}, then you can connect your client application to it in a similar way as you previously connected it to the origin cluster, but with the appropriate contact points and any additional configuration that your target cluster may require.
-For connection details, see the documentation for your driver language and version.
+//TODO: Maybe unify and reduce duplication with datastax-drivers:compatibility:connect-cloud.adoc and data-migration:ROOT:connect-clients-to-proxy.adoc.
 
-Make sure that your driver version is compatible with your target cluster.
-For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
+Connections to {astra-db} are different from connections to generic CQL clusters.
 
-== Configuring your driver to connect to {astra-db}
+=== Get {astra-db} credentials
 
-To connect to {astra-db}, you need the following:
+To connect a driver to {astra-db}, you need the same credentials that you used to xref:ROOT:connect-clients-to-proxy.adoc#expected-authentication-credentials-for-astra-db[connect your applications to {product-proxy}]:
 
-* The xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] credentials that you used to xref:ROOT:connect-clients-to-proxy.adoc[connect your applications to {product-proxy}].
-+
-As before, you can use either of the following sets of credentials to connect to your {astra-db} database:
-+
-** Token-only authentication: Set `username` to the literal string `token`, and set `password` to your {astra-db} application token.
-** Client ID and secret authentication (legacy): Set `username` to the `clientId` generated with your application token, and then set `password` to the `secret` generated with your application token.
+* An xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token]
 
-* Your {astra-db} database's {scb}.
-+
-The {scb-short} is a zip file that contains TLS encryption certificates and other metadata required to connect to your database.
-Databases can have one or more {scb-short}s.
-For more information, see xref:astra-db-serverless:databases:secure-connect-bundle.adoc[].
+* Your {astra-db} database's xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb}].
 +
-[IMPORTANT]
-====
-The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates.
-Treat it as you would any other sensitive values, such as passwords or tokens.
-====
+If you replicate your databases to multiple regions or use custom domains for {astra}, then your databases will have more than one {scb-short}.
+After making these changes in {astra}, your driver connections will need to be updated to use the appropriate {scb-short} for the desired region or domain when connecting to your databases.
+
+[#compare-connection-parameters]
+=== Compare driver connection parameters for self-managed {cass-short} clusters and {astra-db}
+
+To help you understand the required changes for your driver connection strings, the following table compares driver connection parameters for self-managed {cass-short} clusters and {astra-db} databases:
+
+[cols=3]
+|===
+| Parameter | Self-managed clusters | {astra-db} databases
+
+| Contact points
+| Required, set manually
+| Automatically set by the {scb-short}
+
+| {scb}
+| Not applicable
+| Required
 
-* Recommended: A driver language and version that is compatible with {astra-db}.
+| SSL context
+| Optional, set manually
+| Automatically set by the {scb-short}
+
+| Local datacenter
+| Required, set manually
+| Automatically set by the {scb-short}
+
+| Database username
+| Requirement depends on cluster configuration.
+If required, set to the relevant user name for authentication.
+a| Required.
+
+* Token-only authentication (Recommended): Set to the literal string `token`.
+* Client ID and secret authentication (Legacy): Set to the `clientId` generated with your token.
+
+| Database password
+| Requirement depends on cluster configuration.
+If required, set to the relevant password for authentication.
+a| Required.
+
+* Token-only authentication (Recommended): Set to your application token (`AstraCS:...`).
+* Client ID and secret authentication (Legacy): Set to the `secret` generated with your token.
+|===
+
+=== Verify driver compatibility and update connection strings
+
+Verify that your driver version is compatible with {astra-db} and the features that you want to use in {astra-db}, such as the vector data type.
 For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
 
-If your client application uses an old version of a driver without built-in {scb-short} support, {company} strongly recommends upgrading to a compatible driver to simplify configuration and get the latest features and bug fixes.
-However, you can still connect to {astra-db} for this migration by using https://github.com/datastax/cql-proxy[CQL Proxy] or extracting the {scb-short} archive and using the individual files to enable mTLS in your driver's configuration.
+If your client application uses an older driver version without built-in {scb-short} support, {company} strongly recommends upgrading to a compatible driver to simplify configuration and get the latest features and bug fixes.
+If you prefer to make this change after the migration, or you must support a legacy application that relies on an older driver, you can connect to {astra-db} with https://github.com/datastax/cql-proxy[CQL Proxy], or by extracting the {scb-short} archive and using the individual files to enable mTLS in your driver's configuration.
 
 If your driver has built-in support for the {astra-db} {scb-short}, the changes to enable your application to connect to {astra-db} are minimal.
+The following example demonstrates an {astra-db} connection through the Python driver using an {scb-short} and application token.
+For more information and examples, see <<compare-connection-parameters>> and xref:datastax-drivers:connecting:connect-cloud.adoc[].
+
+[source,python]
+----
+import os
+from cassandra.cluster import Cluster
+from cassandra.auth import PlainTextAuthProvider
+import json
+
+cloud_config= {
+        'secure_connect_bundle': '/path/to/scb.zip'
+        }
+auth_provider = PlainTextAuthProvider("token", os.environ["APPLICATION_TOKEN"])
+cluster = Cluster(cloud=cloud_config, auth_provider=auth_provider)
+session = cluster.connect()
+----
 
+.Driver pseudocode to connect to {astra-db}
+[%collapsible]
+====
 //Recalling the xref:connect-clients-to-proxy.adoc#_connecting_company_drivers_to_cassandra[pseudocode to enable your client application to connect to the proxy], here it is how your code needs to change to connect directly to {astra-db}:
 
-The following pseudocode provides guidance on how you might change your driver's code to connect directly to {astra-db}:
+The following pseudocode provides guidance on how you might change your driver's code to connect directly to {astra-db}.
+This is for illustration purposes only; the exact syntax depends on your driver and programming language.
 
-[source]
+[source,text]
 ----
 // Create an object to represent a Cassandra cluster
 // Note: there is no need to specify contact points when connecting to Astra DB.
@@ -87,27 +154,40 @@ my_cluster.close()
 // Display the release version to the user
 print(release_version)
 ----
+====
 
-As noted before, this pseudocode is just a guideline to illustrate the changes that are needed.
-For the specific syntax that applies to your driver, see the following documentation:
-//TODO: Bring migration steps to this page instead of on the astra db pages where they don't seem to belong.
+=== Other code changes for {astra-db}
 
-* https://docs.datastax.com/en/astra-serverless/docs/connect/drivers/connect-cplusplus.html[C++ driver].
+In addition to updating connection strings, you might also need to make the following code changes:
 
-* https://docs.datastax.com/en/astra-serverless/docs/connect/drivers/connect-csharp.html[C# driver].
+* Feature compatibility between your old and new database platform.
+For example, after migrating to {astra-db}, your drivers cannot create keyspaces because xref:astra-db-serverless:cql:develop-with-cql.adoc[CQL for {astra-db}] doesn't support `CREATE KEYSPACE`.
 
-* https://docs.datastax.com/en/astra-serverless/docs/connect/drivers/connect-java.html[Java driver].
+* Enhancements, deprecations, and removals when upgrading from an older driver version.
 
-* https://docs.datastax.com/en/astra-serverless/docs/connect/drivers/connect-nodejs.html[Node.js driver].
+Depending on your application's requirements, you might need to make these changes immediately, or you might make them after switching the connection.
 
-* https://docs.datastax.com/en/astra-serverless/docs/connect/drivers/connect-python.html[Python driver].
+== Switch to the Data API
 
-Your client application is now able to connect directly to your {astra-db} database.
+If you migrated to {astra-db} or {hcd-short}, and you have the option of using the Data API instead of, or in addition to, a {cass-short} driver.
 
-== Phase 5 of migration completed
+Although the Data API can read and write to CQL tables, it is significantly different from driver code.
+To use the Data API, you must rewrite your application code or create a new application.
 
-Until this point, in case of any issues, you could have abandoned the migration and rolled back to connect directly to the origin cluster at any time.
-From this point onward, the clusters will diverge, and the target cluster becomes the source of truth for your client applications and data.
+For more information, see the following:
+
+* xref:astra-db-serverless:apireference:dataapiclient.adoc[Get started with the Data API in {astra-db}]
+* xref:astra-db-serverless:apireference:compare-dataapi-to-cql.adoc[Migrate to the Data API from CQL in {astra-db}]
+* xref:hyper-converged-database:api-reference:dataapiclient.adoc[Get started with the Data API in {hcd-short}]
+* xref:hyper-converged-database:api-reference:compare-dataapi-to-cql.adoc[Migrate to the Data API from CQL in {hcd-short}]
+
+== Migration complete
+
+Your migration is now complete, and your target cluster is the source of truth for your client applications and data.
+
+When you are ready, you can decommission your origin cluster and {product-proxy}, as these are no longer needed and clean xref:ROOT:rollback.adoc[rollback] is no longer possible.
+
+If you need to revert to the origin cluster after this point, you must perform a full migration with your old origin cluster as the target to ensure that all data is rewritten and synchronized back to the origin.
 
 == See also