Merge pull request #206372 from TheovanKraay/cassandra-mi-doc-updates

JamesJBarnett · web-flow · commit 2582f2cde4c1 · 2022-07-29T10:41:56.000-07:00
Cassandra MI doc updates
diff --git a/articles/managed-instance-apache-cassandra/configure-hybrid-cluster.md b/articles/managed-instance-apache-cassandra/configure-hybrid-cluster.md
@@ -11,7 +11,7 @@ ms.devlang: azurecli
 ---
 # Quickstart: Configure a hybrid cluster with Azure Managed Instance for Apache Cassandra
 
-Azure Managed Instance for Apache Cassandra provides automated deployment and scaling operations for managed open-source Apache Cassandra datacenters. This service helps you accelerate hybrid scenarios and reduce ongoing maintenance.
+Azure Managed Instance for Apache Cassandra provides automated deployment and scaling operations for managed open-source Apache Cassandra datacenters. This service helps you accelerate hybrid scenarios and reduce ongoing maintenance. 
 
 This quickstart demonstrates how to use the Azure CLI commands to configure a hybrid cluster. If you have existing datacenters in an on-premises or self-hosted environment, you can use Azure Managed Instance for Apache Cassandra to add other datacenters to that cluster and maintain them.
 
@@ -21,7 +21,7 @@ This quickstart demonstrates how to use the Azure CLI commands to configure a hy
 
 * [Azure Virtual Network](../virtual-network/virtual-networks-overview.md) with connectivity to your self-hosted or on-premises environment. For more information on connecting on premises environments to Azure, see the [Connect an on-premises network to Azure](/azure/architecture/reference-architectures/hybrid-networking/) article.
 
-## <a id="create-account"></a>Configure a hybrid cluster
+## <a id="configure-hybrid"></a>Configure a hybrid cluster
 
 1. Sign in to the [Azure portal](https://portal.azure.com/) and navigate to your Virtual Network resource.
 
@@ -195,38 +195,68 @@ This quickstart demonstrates how to use the Azure CLI commands to configure a hy
    > [!IMPORTANT]
    > If your existing Apache Cassandra cluster only has a single data center, and this is the first time a data center is being added, ensure that the `endpoint_snitch` parameter in `cassandra.yaml` is set to `GossipingPropertyFileSnitch`.
 
+   > [!IMPORTANT]
+   > If your existing application code is using QUORUM for consistency, you should ensure that **prior to changing the replication settings in the step below**, your existing application code is using **LOCAL_QUORUM** to connect to your existing cluster (otherwise live updates will fail after you change replication settings in the below step). Once the replication strategy has been changed, you can revert to QUORUM if preferred. 
+   
+
 1. Finally, use the following CQL query to update the replication strategy in each keyspace to include all datacenters across the cluster:
 
    ```bash
    ALTER KEYSPACE "ks" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3};
    ```
 
-   You also need to update the password tables:
+   You also need to update several system tables:
 
    ```bash
    ALTER KEYSPACE "system_auth" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3}
+   ALTER KEYSPACE "system_distributed" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3}
+   ALTER KEYSPACE "system_traces" WITH REPLICATION = {'class': 'NetworkTopologyStrategy', 'on-premise-dc': 3, 'managed-instance-dc': 3}
    ```
 
    > [!IMPORTANT]
-   > If you are using hybrid cluster as a method of migrating historic data into the new Azure Managed Instance Cassandra data centers, ensure that you disable automatic repairs:
-   > ```azurecli-interactive
-   >     az managed-cassandra cluster update --cluster-name --resource-group--repair-enabled false
-   > ```
-   > Then run `nodetool repair --full` on all the nodes in your existing cluster's data center. You should run this **only after all of the prior steps have been taken**. This should ensure that all historical data is replicated to your new data centers in Azure Managed Instance for Apache Cassandra. If you have a very large amount of data in your existing cluster, it may be necessary to run the repairs at the keyspace or even table level - see [here](https://cassandra.apache.org/doc/latest/cassandra/operating/repair.html) for more details on running repairs in Cassandra. Prior to changing the replication settings, you should also make sure that any application code that connects to your existing Cassandra cluster is using LOCAL_QUORUM. You should leave it at this setting during the migration (it can be switched back afterwards if required). After the migration is completed, you can enable automatic repair again, and point your application code to the new Cassandra Managed Instance data center's seed nodes (and revert the quorum settings if preferred).  
-   > 
-   > Finally, to decommission your old data center:
-   > 
-   > - Run `ALTER KEYSPACE` for each keyspace, removing the old data center.
-   > - We recommend running `nodetool repair` for each keyspace as well, before the below step.
-   > - Run [nodetool decommision](https://cassandra.apache.org/doc/latest/cassandra/operating/topo_changes.html#removing-nodes) for each on premise data center node. 
+   > If the data center(s) in your existing cluster do not enforce [client-to-node encryption (SSL)](https://cassandra.apache.org/doc/3.11/cassandra/operating/security.html#client-to-node-encryption), and you intend for your application code to connect directly to Cassandra Managed Instance, you will also need to enable SSL in your application code. 
+
+
+## <a id="hybrid-real-time-migration"></a>Use hybrid cluster for real-time migration
+
+The above instructions provide guidance for configuring a hybrid cluster. However, this is also a great way of achieving a seamless zero-downtime migration. If you have an on-premise or other Cassandra environment that you want to decommission with zero downtime, in favour of running your workload in Azure Managed Instance for Apache Cassandra, the following steps must be completed in this order:
+
+1. Configure hybrid cluster - follow the instructions above.
+1. Temporarily disable automatic repairs in Azure Managed Instance for Apache Cassandra for the duration of the migration:
+
+    ```azurecli-interactive
+        az managed-cassandra cluster update --cluster-name --resource-group--repair-enabled false
+    ```
+
+1. Run `nodetool repair --full` on each node in your existing cluster's data center. You should run this **only after all of the prior steps have been taken**. This should ensure that all historical data is replicated to your new data centers in Azure Managed Instance for Apache Cassandra. For most installations you can only run one or two in parallel to not overload the cluster. You can monitor a particular repair run by checking `nodetool netsats` and `nodetool compactionstats` against the specific node. If you have a very large amount of data in your existing cluster, it may be necessary to run the repairs at the keyspace or even table level - see [here](https://cassandra.apache.org/doc/latest/cassandra/operating/repair.html) for more details on running repairs in Cassandra. 
+
+
 
    > [!NOTE]
    > To speed up repairs we advise (if system load permits it) to increase both stream throughput and compaction throughput as in the example below:
    >```azure-cli
    >   az managed-cassandra cluster invoke-command --resource-group $resourceGroupName --cluster-name $clusterName --host $host --command-name nodetool --arguments "setstreamthroughput"="" "7000"=""
    >    
-   >   az managed-cassandra cluster invoke-command --resource-group $resourceGroupName --cluster-name $clusterName --host $host --command-name nodetool --arguments "setcompactionthroughput"="" "960"=""   
-   >```
+   >   az managed-cassandra cluster invoke-command --resource-group $resourceGroupName --cluster-name $clusterName --host $host --command-name nodetool --arguments "setcompactionthroughput"="" "960"=""
+
+1. Cut over your application code to point to the seed nodes in your new Azure Managed Instance for Apache Cassandra data center(s).
+
+    > [!IMPORTANT]
+    > As also mentioned in the hybrid setup instructions, if the data center(s) in your existing cluster do not enforce [client-to-node encryption (SSL)](https://cassandra.apache.org/doc/3.11/cassandra/operating/security.html#client-to-node-encryption), you will need to enable this in your application code, as Cassandra Managed Instance enforces this. 
+
+1. Run nodetool repair **again** on all the nodes in your existing cluster's data center, in the same manner as in step 3 above (to ensure any deltas are replicated following application cut over).
+
+1. Run ALTER KEYSPACE for each keyspace, in the same manner as done earlier, but now removing your old data center(s).
+
+1. Run [nodetool decommission](https://cassandra.apache.org/doc/latest/cassandra/tools/nodetool/decommission.html) for each old data center node.
+
+1. Switch your application code back to quorum (if required/preferred).
+
+1. Re-enable automatic repairs:
+
+    ```azurecli-interactive
+        az managed-cassandra cluster update --cluster-name --resource-group--repair-enabled true
+    ```
 
 ## Troubleshooting
 
diff --git a/articles/managed-instance-apache-cassandra/create-cluster-portal.md b/articles/managed-instance-apache-cassandra/create-cluster-portal.md
@@ -132,20 +132,7 @@ If you don't have an Azure subscription, create a [free account](https://azure.m
 
 ## Update Cassandra configuration
 
-The service allows update to a limited set of Cassandra configurations on a datacenter via the portal or by [using CLI commands](manage-resources-cli.md#update-yaml). The following YAML settings are supported:
-
-- column_index_size_in_kb
-- allocate_tokens_for_keyspace
-- compaction_throughput_mb_per_sec
-- read_request_timeout_in_ms
-- range_request_timeout_in_ms
-- aggregated_request_timeout_in_ms
-- write_request_timeout_in_ms
-- request_timeout_in_ms
-- internode_compression
-- batchlog_replay_throttle_in_kb
-
-To update settings in the portal:
+The service allows update to Cassandra YAML configuration on a datacenter via the portal or by [using CLI commands](manage-resources-cli.md#update-yaml). To update settings in the portal:
 
 1. Find `Cassandra Configuration` under settings. Highlight the data center whose configuration you want to change, and click update:
 
@@ -160,7 +147,34 @@ To update settings in the portal:
    :::image type="content" source="./media/create-cluster-portal/update-config-3.png" alt-text="Screenshot of the updated Cassandra config." lightbox="./media/create-cluster-portal/update-config-3.png" border="true":::
 
    > [!NOTE]
-   > Only overridden Cassandra configuration values are shown in the portal. 
+   > Only overridden Cassandra configuration values are shown in the portal.
+
+   > [!IMPORTANT]
+   > Ensure the Cassandra yaml settings you provide are appropriate for the version of Cassandra you have deployed. See [here](https://github.com/apache/cassandra/blob/cassandra-3.11/conf/cassandra.yaml) for Cassandra v3.11 settings and [here](https://github.com/apache/cassandra/blob/cassandra-4.0/conf/cassandra.yaml) for v4.0. The following YAML settings are **not** allowed to be updated:
+   >
+   > - cluster_name
+   > - seed_provider
+   > - initial_token
+   > - autobootstrap
+   > - client_ecncryption_options
+   > - server_encryption_options
+   > - transparent_data_encryption_options
+   > - audit_logging_options
+   > - authenticator
+   > - authorizer
+   > - role_manager
+   > - storage_port
+   > - ssl_storage_port
+   > - native_transport_port
+   > - native_transport_port_ssl
+   > - listen_address
+   > - listen_interface
+   > - broadcast_address
+   > - hints_directory
+   > - data_file_directories
+   > - commitlog_directory
+   > - cdc_raw_directory
+   > - saved_caches_directory 
 
 ## Troubleshooting
 
diff --git a/articles/managed-instance-apache-cassandra/manage-resources-cli.md b/articles/managed-instance-apache-cassandra/manage-resources-cli.md
@@ -222,18 +222,7 @@ az managed-cassandra datacenter update \
 
 ### <a id="update-yaml"></a>Update Cassandra configuration
 
-Change Cassandra configuration on a datacenter by using the [az managed-cassandra datacenter update](/cli/azure/managed-cassandra/datacenter#az-managed-cassandra-datacenter-update) command. You will need to base64 encode the YAML fragment by using an [online tool](https://www.base64encode.org/). The following YAML settings are supported:
-
-- column_index_size_in_kb
-- allocate_tokens_for_keyspace
-- compaction_throughput_mb_per_sec
-- read_request_timeout_in_ms
-- range_request_timeout_in_ms
-- aggregated_request_timeout_in_ms
-- write_request_timeout_in_ms
-- request_timeout_in_ms
-- internode_compression
-- batchlog_replay_throttle_in_kb
+Change Cassandra configuration on a datacenter by using the [az managed-cassandra datacenter update](/cli/azure/managed-cassandra/datacenter#az-managed-cassandra-datacenter-update) command. You will need to base64 encode the YAML fragment by using an [online tool](https://www.base64encode.org/). 
 
 For example, the following YAML fragment:
 
@@ -261,6 +250,35 @@ az managed-cassandra datacenter update \
     --base64-encoded-cassandra-yaml-fragment $yamlFragment
 ```
 
+> [!IMPORTANT]
+> Ensure the Cassandra yaml settings you provide are appropriate for the version of Cassandra you have deployed. See [here](https://github.com/apache/cassandra/blob/cassandra-3.11/conf/cassandra.yaml) for Cassandra v3.11 settings and [here](https://github.com/apache/cassandra/blob/cassandra-4.0/conf/cassandra.yaml) for v4.0. The following YAML settings are **not** allowed to be updated:
+>
+> - cluster_name
+> - seed_provider
+> - initial_token
+> - autobootstrap
+> - client_ecncryption_options
+> - server_encryption_options
+> - transparent_data_encryption_options
+> - audit_logging_options
+> - authenticator
+> - authorizer
+> - role_manager
+> - storage_port
+> - ssl_storage_port
+> - native_transport_port
+> - native_transport_port_ssl
+> - listen_address
+> - listen_interface
+> - broadcast_address
+> - hints_directory
+> - data_file_directories
+> - commitlog_directory
+> - cdc_raw_directory
+> - saved_caches_directory
+
+
+
 ### <a id="get-datacenters-cluster"></a>Get the datacenters in a cluster
 
 Get datacenters in a cluster by using the [az managed-cassandra datacenter list](/cli/azure/managed-cassandra/datacenter#az-managed-cassandra-datacenter-list) command:
