Revise operator docs for Cassandra 6 onboarding

Author: pmcfadin

doc/modules/cassandra/nav.adoc

@@ -98,7 +98,6 @@
 **** xref:cassandra:managing/operating/hints.adoc[Hints]
 **** xref:cassandra:managing/operating/logging.adoc[Logging]
 ***** xref:cassandra:managing/operating/auditlogging.adoc[Audit logging]
-***** xref:cassandra:managing/operating/audit_logging.adoc[Audit logging 2]
 ***** xref:cassandra:managing/operating/fqllogging.adoc[Full query logging]
 **** xref:cassandra:managing/operating/metrics.adoc[Monitoring metrics]
 **** xref:cassandra:managing/operating/repair.adoc[Repair]

doc/modules/cassandra/pages/getting-started/cassandra-quickstart.adoc

@@ -1,32 +1,34 @@
-= Cassandra Quickstart 
+= Cassandra Quickstart
 
 == STEP 1: GET CASSANDRA USING DOCKER
 
-You'll need to have Docker Desktop for Mac, Docker Desktop for Windows, or similar software installed on your computer.
+You'll need Docker Desktop for Mac, Docker Desktop for Windows, or an
+equivalent Docker installation on Linux.
 
-Apache Cassandra is also available as a tarball or package xref:_/download.adoc[download].
+Apache Cassandra is also available as a tarball or package; see the
+xref:installing/installing.adoc[installation guide].
 
-[source, console]
+[source,console]
 ----
 include::cassandra:example$BASH/docker_pull.sh[]
 ----
 
 == STEP 2: START CASSANDRA
 
-A Docker network allows us to access the container's ports without exposing them on the host.
+A Docker network lets you reach the container ports without publishing
+them on the host.
 
-[source, console]
+[source,console]
 ----
 include::cassandra:example$BASH/docker-network-run.sh[]
 ----
 
 == STEP 3: CREATE FILES
 
-The Cassandra Query Language (CQL) is very similar to SQL but suited for the JOINless structure of Cassandra.
+Create a file named `data.cql` and paste the following CQL script in it.
+The script creates a keyspace, a table, and sample rows:
 
-Create a file named data.cql and paste the following CQL script in it. This script will create a keyspace, the layer at which Cassandra replicates its data, a table to hold the data, and insert some data into that table:
-
-[source, cql]
+[source,cql]
 ----
 include::cassandra:example$CQL/create-keyspace-store.cql[]
 
@@ -37,66 +39,76 @@ include::cassandra:example$CQL/insert-shopping-cart-data.cql[]
 
 == STEP 4: LOAD DATA WITH CQLSH
 
-The CQL shell, or `cqlsh`, is one tool to use in interacting with the database. 
-We'll use it to load some data into the database using the script you just saved.
+Use `cqlsh` to load the script into the running container.
 
-[source, console]
+[source,console]
 ----
-include::cassandra:example$BASH/docker-run-cqlsh-load-data.sh[] 
+include::cassandra:example$BASH/docker-run-cqlsh-load-data.sh[]
 ----
 
 [NOTE]
 ====
-The cassandra server itself (the first docker run command you ran) takes a few seconds to start up. 
-The above command will throw an error if the server hasn't finished its init sequence yet, so give it a few seconds to spin up.
+The Cassandra server can take a few seconds to finish starting. If the
+load step fails immediately, wait for the node to finish init and retry.
 ====
 
 == STEP 5: INTERACTIVE CQLSH
 
-Much like an SQL shell, you can also of course use `cqlsh` to run CQL commands interactively.
+You can also use `cqlsh` interactively:
 
-[source, console]
+[source,console]
 ----
 include::cassandra:example$BASH/docker-run-cqlsh-quickstart.sh[]
 ----
 
-This should get you a prompt like so:
+This should get you a prompt like this:
 
-[source, console]
+[source,console]
 ----
 include::cassandra:example$RESULTS/docker-run-cqlsh-quickstart.result[]
 ----
 
 == STEP 6: READ SOME DATA
 
-[source, cql]
+[source,cql]
 ----
-include::cassandra:example$CQL/select-data-from-shopping-cart.cql[]  
+include::cassandra:example$CQL/select-data-from-shopping-cart.cql[]
 ----
 
 == STEP 7: WRITE SOME MORE DATA
 
-[source, cql]
+[source,cql]
 ----
 include::cassandra:example$CQL/insert-more-data-shopping-cart.cql[]
 ----
 
-== STEP 8: CLEAN UP
+== STEP 8: CHECK STATUS
+
+Before you clean up, confirm the node is healthy. `nodetool status`
+should show the node as `UN`:
 
-[source, console]
+[source,console]
 ----
-include::cassandra:example$BASH/docker-kill-and-remove.sh[]
+$ nodetool status
+Datacenter: dc1
+=======================
+Status=Up/Down
+|/ State=Normal/Leaving/Joining/Moving
+--  Address      Load       Tokens  Owns (effective)  Host ID                               Rack
+UN  127.0.0.1   123.45 KiB  1       100.0%            01234567-89ab-cdef-0123-456789abcdef  rack1
 ----
 
-== CONGRATULATIONS!
-
-Hey, that wasn't so hard, was it?
-
-To learn more, we suggest the following next steps:
-
-* Read through the xref:master@_:ROOT:cassandra-basics.adoc[Cassandra Basics] to learn main concepts and how Cassandra works at a high level.
-* Browse through the xref:master@_:ROOT:case-studies.adoc[Case Studies] to learn how other users in our worldwide community are getting value out of Cassandra.
+== STEP 9: CLEAN UP
 
+[source,console]
+----
+include::cassandra:example$BASH/docker-kill-and-remove.sh[]
+----
 
+This removes the container and the `cassandra` Docker network created
+for the quickstart.
 
+== CONGRATULATIONS!
 
+To learn more, read the xref:master@_:ROOT:cassandra-basics.adoc[Cassandra
+Basics] and xref:master@_:ROOT:case-studies.adoc[Case Studies].

doc/modules/cassandra/pages/getting-started/mtlsauthenticators.adoc

@@ -1,12 +1,27 @@
 = Getting started with mTLS authenticators
 
-When a certificate based authentication protocol like TLS is used for client and
-Internode connections, `MutualTlsAuthenticator` & `MutualTlsInternodeAuthenticator`
-can be used for the authentication by leveraging the client certificates from the
-SSL handshake.
+When certificate-based authentication such as TLS is used for client and
+internode connections, `MutualTlsAuthenticator` and
+`MutualTlsInternodeAuthenticator` can authenticate clients by using the
+client certificate from the SSL handshake.
 
-After SSL handshake, identity from the client certificates is extracted and only
-authorized users will be granted access.
+After the SSL handshake, the identity from the client certificate is
+extracted and only authorized users are granted access.
+
+== Certificate prerequisites
+
+Before enabling either authenticator, generate the certificate material
+you intend to use:
+
+* one CA certificate that issues the node and client certificates
+* one server certificate and key for each node
+* one client certificate and key for each user or service account
+* a truststore that contains the issuing CA
+* a keystore for each node
+
+If you use the default SPIFFE validator, the SPIFFE ID must be present
+in the certificate SAN. If you use a custom CN-based validator, the
+subject CN must match the identity you want to map to a role.
 
 == What is an Identity
 
@@ -18,7 +33,7 @@ certificate conventions used in the deployment environment.
 
 There is a default implementation of `MutualTlsCertificateValidator` with
 https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/[SPIFFE] as the identity
-of the certificates.This requires spiffe to be present in the SAN of the certificate.
+of the certificates. This requires SPIFFE to be present in the SAN of the certificate.
 
 Instead of using `SPIFFE` based validator, a custom `CN` based validator that implements `MutualTlsCertificateValidator`
 could be configured by the operator if required.
@@ -28,18 +43,18 @@ could be configured by the operator if required.
 Note that the following steps uses SPIFFE identity as an example, If you are using
 a custom validator, use appropriate identity in place of `spiffe://testdomain.com/testIdentifier/testValue`.
 
-*STEP 1: Add authorized users to system_auth.identity_to_roles table*
+*STEP 1: Add authorized users to `system_auth.identity_to_roles` table*
 
 Note that only users with permissions to create/modify roles can add/remove identities.
-Client certificates with the identities in this table will be trusted by C*.
+Client certificates with the identities in this table will be trusted by Cassandra.
 [source, plaintext]
 ----
 ADD IDENTITY 'spiffe://testdomain.com/testIdentifier/testValue' TO ROLE 'read_only_user'
 ----
 
 *STEP 2: Configure Cassandra.yaml with right properties*
 
-`client_encryption_options` configuration for mTLS connections
+Configure `client_encryption_options` for mTLS connections.
 [source, plaintext]
 ----
 client_encryption_options:
@@ -51,8 +66,9 @@ client_encryption_options:
   truststore_password: cassandra
   require_client_auth: true // to enable mTLS
 ----
-Configure mTLS authenticator and the validator for client connections . If you are
-implementing a custom validator, use that instead of Spiffe validator
+Configure the mTLS authenticator and validator for client connections.
+If you are implementing a custom validator, use that instead of the
+SPIFFE validator.
 [source, plaintext]
 ----
 authenticator:
@@ -63,35 +79,46 @@ authenticator:
 
 *STEP 3: Bounce the cluster*
 
-After the bounce, C* will accept mTLS connections from the clients and if their
-identity is present in the `identity_to_roles` table, access will be granted.
+After the bounce, Cassandra accepts mTLS connections from clients. If
+the identity is present in the `identity_to_roles` table, access is
+granted.
+
+== Verifying mTLS
+
+Verify the setup with the same client toolchain you will use in
+production. Connect with the client certificate and key, run a simple
+query, and confirm that the mapped role can access the cluster. Repeat
+the connection attempt with a certificate whose identity is not present
+in `identity_to_roles`; the connection should be rejected.
 
 == Configuring mTLS with password fallback authenticator for client connections
 
-Operators that wish to migrate cannot immediately change the configuration to require
-mTLS authentication as it will break existing non-mTLS based clients of the cluster.
-In order to make a smooth transition from non-mTLS based authentication to mTLS authentication,
-the operator can run Cassandra in optional mTLS mode and configure authenticator to be
-`MutualTlsWithPasswordFallbackAuthenticator` which can accept both certificate based
-and password based connections.
+Operators that want to migrate cannot immediately require mTLS
+authentication because that would break existing non-mTLS clients. To
+make a smooth transition, run Cassandra in optional mTLS mode and
+configure the authenticator to be
+`MutualTlsWithPasswordFallbackAuthenticator`, which accepts both
+certificate-based and password-based connections.
 
-Below are the steps to configure C* in optional mTLS mode with fallback authenticator.
-Note that the following steps uses SPIFFE identity as an example, If you are using
-a custom validator, use appropriate identity in place of `spiffe://testdomain.com/testIdentifier/testValue`.
+Below are the steps to configure Cassandra in optional mTLS mode with
+the fallback authenticator. Note that the following steps use SPIFFE
+identity as an example. If you are using a custom validator, use the
+appropriate identity in place of
+`spiffe://testdomain.com/testIdentifier/testValue`.
 
-*STEP 1: Add authorized users to system_auth.identity_to_roles table*
+*STEP 1: Add authorized users to `system_auth.identity_to_roles` table*
 
 Note that only users with permissions to create/modify roles can add/remove identities.
-Client certificates with the identities in this table will be trusted by C*.
+Client certificates with the identities in this table will be trusted by Cassandra.
 [source, plaintext]
 ----
 ADD IDENTITY 'spiffe://testdomain.com/testIdentifier/testValue' TO ROLE 'read_only_user'
 ----
 
 *STEP 2: Configure Cassandra.yaml with right properties*
 
-`client_encryption_options` configuration for mTLS connections, Note that require_client_auth configuration
-is optional.
+Configure `client_encryption_options` for mTLS connections. Note that
+`require_client_auth` is optional here.
 [source, plaintext]
 ----
 client_encryption_options:
@@ -103,8 +130,9 @@ client_encryption_options:
   truststore_password: cassandra
   require_client_auth: optional // to enable mTLS in optional mode
 ----
-Configure fallback authenticator and the validator for client connections . If you are
-implementing a custom validator, use that instead of Spiffe validator
+Configure the fallback authenticator and validator for client
+connections. If you are implementing a custom validator, use that
+instead of the SPIFFE validator.
 [source, plaintext]
 ----
 authenticator:
@@ -115,13 +143,13 @@ authenticator:
 
 *STEP 3: Bounce the cluster*
 
-After the bounce, C* will accept both mTLS connections and password based connections from
-the clients. This configuration should be used during transition phase and the require_client_auth
-configuration should be set to true when all the clients start making mTLS connections to the cluster.
+After the bounce, Cassandra accepts both mTLS and password-based
+connections. Use this configuration only during the transition phase.
+Set `require_client_auth` to `true` after all clients use mTLS.
 
 == Configuring mTLS authenticator for Internode connections
 
-Internode authenticator trusts certificates whose identities are present in
+The internode authenticator trusts certificates whose identities are present in
 `internode_authenticator.parameters.trusted_peer_identities` if configured.
 
 Otherwise, it trusts connections which have the same identity as the node.
@@ -132,13 +160,13 @@ connections from other nodes who have the same identity will be trusted if
 `trusted_peer_identities` is not configured.
 
 For example, if a node has `testIdentity` embedded in the certificate in
-outbound keystore, It trusts connections from other nodes when their certificates
-have `testIdentity` embedded in them.
+the outbound keystore, it trusts connections from other nodes when
+their certificates have `testIdentity` embedded in them.
 
 There is an optional configuration `node_identity` that can be used to verify identity
 extracted from the keystore to avoid any configuration errors.
 
-*STEP 1: Configure server_encryption_options in cassandra.yaml*
+*STEP 1: Configure `server_encryption_options` in `cassandra.yaml`*
 
 [source, plaintext]
 ----
@@ -156,8 +184,9 @@ server_encryption_options:
 
 *STEP 2: Configure Internode Authenticator and Validator*
 
-Configure mTLS Internode authenticator and validator. If you are
-implementing a custom validator, use that instead of Spiffe validator
+Configure the mTLS internode authenticator and validator. If you are
+implementing a custom validator, use that instead of the SPIFFE
+validator.
 [source, plaintext]
 ----
 internode_authenticator:
@@ -168,19 +197,22 @@ internode_authenticator:
 ----
 
 *STEP 3: Bounce the cluster*
-Once all nodes in the cluster are restarted, all internode communications will be authenticated by mTLS.
+Once all nodes in the cluster are restarted, all internode
+communications are authenticated by mTLS.
 
 == Migration from existing password based authentication
 * For client connections, since the migration will not happen overnight,
-the operators can run cassandra in optional mTLS mode and use
-`MutualTlsWithPasswordFallbackAuthenticator` which will accept both mTLS & password
-based connections, based on the type of connection client is making. These settings
-can be configured in `cassandra.yaml`. Once all the clients migrate to using mTLS,
-turn off optional mode and set the authenticator to be `MutualTlsAuthenticator`. From
-that point only mTLS client connections will be accepted.
+  operators can run Cassandra in optional mTLS mode and use
+  `MutualTlsWithPasswordFallbackAuthenticator`, which accepts both mTLS
+  and password-based connections. Configure the settings in
+  `cassandra.yaml`. Once all clients migrate to mTLS, turn off optional
+  mode and set the authenticator to `MutualTlsAuthenticator`. From that
+  point only mTLS client connections are accepted.
 
 * For Internode connections, while doing rolling upgrades from non-mTLS based configuration
-to mTLS based configuration, set `server_encryption_options.optional:true` for the new nodes to
-be able to connect to old nodes which are still using non-mTLS based configuration during upgrade.
-After this, change the internode authenticator to be `MutualTlsInternodeAuthenticator` and turn off the optional
-mode by setting `server_encryption_options.optional:false`.
+  to mTLS based configuration, set `server_encryption_options.optional: true`
+  for the new nodes so they can connect to old nodes that are still
+  using non-mTLS based configuration during upgrade. After this, change
+  the internode authenticator to `MutualTlsInternodeAuthenticator` and
+  turn off the optional mode by setting
+  `server_encryption_options.optional: false`.