DOC-4449 Astra Streaming audit and remove unnecessary duplications of Serverless content

antora.yml

@@ -14,7 +14,7 @@ asciidoc:
   attributes:
     pulsar_version: '2.10' #DO NOT INCLUDE PATCH VERSION <MAJOR>.<MINOR>.<PATCH>
     pulsar_full_version: '2.10.1'
-    product_name: 'Astra Streaming'
+    product: 'Astra Streaming'
     kafka_for_astra: 'Starlight for Kafka'
     starlight_rabbitmq: 'Starlight for RabbitMQ'
     gpt-schema-translator: 'GPT schema translator'

modules/ROOT/nav.adoc

@@ -1,21 +1,5 @@
-.Guides and examples
-* Manage permissions
-** xref:astream-org-permissions.adoc[]
-** xref:astream-custom-roles.adoc[]
-* Pulsar subscriptions
-** xref:astream-subscriptions.adoc[]
-** xref:astream-subscriptions-exclusive.adoc[]
-** xref:astream-subscriptions-shared.adoc[]
-** xref:astream-subscriptions-failover.adoc[]
-** xref:astream-subscriptions-keyshared.adoc[]
-
-//
-
-.IO connectors
-* xref:streaming-learning:pulsar-io:connectors/index.adoc[IO Connectors]
-
 .Frequently asked questions
-* xref:astream-faq.adoc[]
+* xref:ROOT:astream-faq.adoc[]
 * xref:operations:onboarding-faq.adoc[]
 
 .Release notes

modules/ROOT/pages/astream-faq.adoc

@@ -1,49 +1,46 @@
-= {product_name} FAQs
+= {product} FAQs
 :navtitle: FAQs
 :page-tag: astra-streaming,dev,admin,planner,plan,pulsar
 
-== How do I sign up for the {product_name}?
+== How do I get started with {product}?
 
-Follow our simple xref:getting-started:index.adoc[getting started guide] to sign up for Astra and get your first streaming tenant created.
+See xref:getting-started:index.adoc[].
 
-== How is {product_name} priced?
-{product_name} offers customers a *Pay As You Go*, consumption based pricing model that allows customers to use {product_name} with a cost model that scales as they grow.
+== How is {product} priced?
 
-Customers can opt to customize their deployment to meet specific requirements which will adjust their pricing up or down depending on their specific requirement. These customizations options include items such as:
+See xref:operations:astream-pricing.adoc[].
 
-* Message retention duration
-* Maximum message retention storage
-* Number of tenants
-* Region of tenant
+== Why is {product} based on Apache Pulsar?
 
-== Why did DataStax opt to base {product_name} on Apache Pulsar?
-See our https://www.datastax.com/blog/four-reasons-why-apache-pulsar-essential-modern-data-stack[blog post] that explains why we are excited about Apache Pulsar and why we decided it was the best technology to base {product_name} on.
+For information about the decision to use Apache Pulsar, see https://www.datastax.com/blog/four-reasons-why-apache-pulsar-essential-modern-data-stack[Four Reasons Why Apache Pulsar is Essential to the Modern Data Stack].
 
-== What is DataStax plan for Kesque?
-{product_name} is based heavily on technology originally created as part of Kesque. With the launch of {product_name} we will begin the process of shutting down the Kesque service and migrating customers to the new {product_name} platform.
+== What happened to Kesque?
 
-== How can I get started with {product_name}?
-To get started with {product_name}, you can create a free account at https://astra.datastax.com and create your first streaming instance immediately. No credit card required.
+{product} is based heavily on technology originally created as part of Kesque.
+With the launch of {product}, {company} began shutting down the Kesque service and migrated customers to {product}.
 
-== Who are the target customers for {product_name}?
-{product_name} has been architected to satisfy the most stringent enterprise requirements around availability, scale and latency. {product_name} was built to handle mission critical use cases for Fortune 100 companies across BFSI, Telecommunications, Technology, Retail, Oil & Gas and Healthcare.
+== Who should use {product}?
 
-The pricing model also makes {product_name} accessible to mid market and small/medium business customers who need event stream processing capabilities to run core parts of their business.
+{product} has been architected to satisfy the most stringent enterprise requirements around availability, scale, and latency.
+{product} was built to handle mission critical use cases for Fortune 100 companies across BFSI, Telecommunications, Technology, Retail, Oil and Gas, and Healthcare.
 
-And finally {product_name} offers a user friendly interface and free tier to satisfy the needs of individual developers and technologists who want to learn more about Apache Pulsar and data streaming in general.
+The pricing model also makes {product} accessible to mid market and small/medium business customers who need event stream processing capabilities to run core parts of their business.
 
-== What is CDC for Astra DB?
+And finally {product} offers a user-friendly interface and free tier to satisfy the needs of individual developers and technologists who want to learn more about Apache Pulsar and data streaming in general.
 
-Change Data Capture (CDC) for Astra DB uses a Pulsar IO source connector that processes changes from the Cassandra Change Agent via a Pulsar topic. For more, see https://docs.datastax.com/en/astra/docs/astream-cdc.html[CDC for Astra DB].
+== What is CDC for {astra_db}?
+
+Change Data Capture (CDC) for {astra_db} uses a Pulsar IO source connector that processes changes from the Cassandra Change Agent via a Pulsar topic.
+For more information, see xref:developing:astream-cdc.adoc[].
 
 == What are tenants, namespaces, topics, and sinks?
 
 *Tenants* are an isolated administrative unit for which an authorization scheme can be set and a set of clusters can be defined.
 Each tenant can have multiple *namespaces*, a logical container for creating and managing a hierarchy of topics.
 A *topic* is a named channel for transmitting messages from producers to consumers.
-A *sink* feeds data from {product_name} to an external system, such as Cassandra or Elastic Search.
+A *sink* feeds data from {product} to an external system, such as {cassandra} or Elasticsearch.
 
 == See also
 
-* xref:getting-started:index.adoc[Getting started with Astra Streaming]
-* Browse the xref:apis:index.adoc[]
+* xref:getting-started:index.adoc[]
+* xref:apis:index.adoc[]

modules/ROOT/pages/astream-org-permissions.adoc

@@ -1,95 +1,59 @@
-= User permissions
+= Manage roles and permissions
 :page-tag: astra-streaming,security,secure,pulsar
 
-Default and xref:astream-custom-roles.adoc[custom roles] allow admins to manage unique permissions for users based on your organization and database requirements.
+You manage role-based access control (RBAC) for {product} through your {astra_db} organization.
+For information about {astra_db} RBAC, including default roles, custom roles, permissions, and user management, see xref:astra-db-serverless:administration:manage-database-access.adoc[].
 
-You can manage roles using the {astra_ui} or the https://docs.datastax.com/en/astra/docs/manage/devops/devops-roles.html[DevOps API].
+== {product} permissions
 
-== {product_name} Organization permissions
+Permissions specific to {product} include the following:
 
-[cols=3*,options=header]
-|===
-|Console name
-|Description
-|DevOps API parameter
+* *Manage Streaming* (`org-stream-manage`): View, add, edit, or remove Astra Streaming configurations.
 
-|Read Audits
-|Enables read and download audits.
-|org-audits-read
+=== Default roles for {product}
 
-|Write IP Access List
-|Create or modify an access list using the DevOps API or the Astra console.
-|accesslist-write
+There are no default {astra_db} roles specifically scoped to {product}.
+However, the following default roles have the *Manage Streaming* permission:
 
-|Delete Custom Role
-|Delete of custom role.
-|org-role-delete
+* *Organization Administrator*
+* *Administrator Service Account*
+* *API Administrator Service Account*
+* *API Administrator User*
 
-|Manage Streaming
-|Create a Streaming Service using the DevOps API or the Astra console.
-|org-stream-manage
+For information about permissions assigned to default roles, see xref:astra-db-serverless:administration:manage-database-access.adoc[].
 
-|Write Organization
-|Create new organizations or delete an existing organization. Hides manage org and org settings.
-|org-write
+=== Custom roles for {product}
 
-|Read Billing
-|Enables links and access to billing details page.
-|org-billing-read
+If you xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[create custom roles] for {product}, those roles must have the following permissions, at minimum:
 
-|Read IP Access List
-|Enables links and access to access list page.
-|accesslist-read
+* *Manage Streaming* (`org-stream-manage`): View and manage {product} in the {astra_ui}.
+* *View DB* (`org-db-view`): View the {astra_ui} in general.
 
-|Read User
-|Access to viewing users of an organization.
-|org-user-read
+Additional permissions might be required, depending on the tasks the role needs to perform.
 
-|Read Organization
-|View organization in the Astra console.
-|org-read
+[TIP]
+====
+To control access to specific streaming tenants, you can set granular xref:astra-db-serverless:administration:manage-database-access.adoc#role-scopes[resource scopes] on custom roles.
+====
 
-|Read Custom Role
-|See a custom role and its associated permissions.
-|org-role-read
+== Authentication and authorization in Pulsar and {astra_db}
 
-|Read External Auth
-|See security settings related to external authentication providers.
-|org-external-auth-read
+Pulsar has the concept of https://pulsar.apache.org/docs/security-authorization/[clients with role tokens].
+In Pulsar, authentication is the process of verifying a provided token (JWT), and authorization is the process of determining if the role claimed in that token is allowed to complete the requested action.
 
-|Read Token
-|Read token details.
-|org-token-read
+{product} uses the {company} version of Apache Pulsar (xref:luna-streaming::index.adoc[Luna Streaming]).
+The https://github.com/datastax/pulsar[Luna project] is an open fork of the Pulsar project that maintains feature parity with OSS Pulsar. {product}, as a managed service, abstracts some features/options of Pulsar to ensure continuous, reliable service.
 
-|Delete Custom Role
-|Delete of custom role.
-|org-role-delete
+On a shared cluster, your {astra_db} organization has one or more tenants on a shared Pulsar cluster.
+Each of your tenants is secured by Pulsar authentication and authorization models, as well as your {astra_db} organization's authentication and authorization ({astra_db} RBAC).
 
-|Notification Write
-|Enable or disable notifications in organization notification settings.
-|org-notification-write
-|Write Billing
-|Enables links and ability to add or edit billing payment info.
-|org-billing-write
+{product} shared clusters are created and administered by {product} administrators.
+Each tenant is assigned a custom role and permissions limited to that tenant only.
+All tokens created within a tenant are assigned roles similar to the assigning tenant.
 
-|Write User
-|Add, create, or remove a user using the DevOps API or the Astra console.
-|org-user-write
+For programmatic access, you use {astra_db} application tokens or Pulsar JWT, depending on the operation you need to perform.
+For more information, see xref:operations:astream-token-gen.adoc[].
 
-|Write Custom Role
-|Create custom role.
-|org-role-write
+== See also
 
-|Write External Auth
-|Update security settings related to external auth providers.
-|org-external-auth-write
-
-|Write Token
-|Create application token.
-|org-token-write
-
-|===
-
-== Astra DB Permissions
-
-For documentation about Astra DB user permissions, see https://docs.datastax.com/en/astra/docs/user-permissions.html[Astra DB User Permissions].
+* xref:operations:astream-pricing.adoc[]

modules/ROOT/pages/astream-subscriptions-exclusive.adoc

@@ -2,19 +2,22 @@
 :navtitle: Exclusive
 :page-tag: pulsar-subscriptions,quickstart,admin,dev,pulsar
 
-*Subscriptions* in Pulsar describe which consumers are consuming data from a topic and how they want to consume that data. +
+_Subscriptions_ in Pulsar describe which consumers are consuming data from a topic and how they want to consume that data.
 
-An *exclusive* subscription describes a basic publish-subscribe pattern where a *single consumer* subscribes to a *single topic* and consumes from it. +
+An _exclusive subscription_ describes a basic publish-subscribe (pub-sub) pattern where a single consumer subscribes to a single topic and consumes from it.
 
-This document explains how to use Pulsar's exclusive subscription model to manage your topic consumption.
+This page explains how to use Pulsar's exclusive subscription model to manage your topic consumption.
 
-include::partial$subscription-prereq.adoc[]
+include::ROOT:partial$subscription-prereq.adoc[]
 
 [#example]
 == Exclusive subscription example
 
-This example uses the `pulsarConsumer` object in `SimplePulsarConsumer.java` below. +
-
+. To configure a Pulsar exclusive subscription, define a `pulsarConsumer` object in `SimplePulsarConsumer.java`, as you would for other subscription types.
+However, you don't need to declare a `subscriptionType`.
+Whereas other subscription types required you to declare a specific `subscriptionType`, Pulsar creates an exclusive subscription by default if you don't declare a `subscriptionType`.
++
+.SimplePulsarConsumer.java
 [source,java]
 ----
 pulsarConsumer = pulsarClient.newConsumer(Schema.JSON(DemoBean.class))
@@ -27,43 +30,47 @@ pulsarConsumer = pulsarClient.newConsumer(Schema.JSON(DemoBean.class))
     .subscriptionName("SimplePulsarConsumer")
     .subscribe();
 ----
++
+If you want to explicitly define an exclusive subscription, you can add `.subscriptionType(SubscriptionType.Exclusive)` to the consumer.
 
-[NOTE]
-====
-Pulsar creates an exclusive subscription by default when no `subscriptionType` is declared.
-====
-
-. Open the `pulsar-subscription-example` repo in the IDE of your choice and run `SimplePulsarConsumer.java` to begin consuming messages. +
-The confirmation message and a cursor appear to indicate the consumer is ready.
+. In the `pulsar-subscription-example` project, run `SimplePulsarConsumer.java` to begin consuming messages.
++
+The confirmation message and a cursor appear to indicate the consumer is ready:
 +
-[source,bash]
+.Result
+[source,console]
 ----
 [main] INFO com.datastax.pulsar.Configuration - Configuration has been loaded successfully
 ...
 [pulsar-client-io-1-1] INFO org.apache.pulsar.client.impl.ConsumerImpl - [persistent://<tenant_name>/<namespace>/in][SimplePulsarConsumer] Subscribed to topic on <service_url> -- consumer: 0
 ----
 
-. In a new terminal window, run `SimplePulsarProducer.java` to begin producing messages.
+. In a new terminal window, run `SimplePulsarProducer.java` to begin producing messages:
 +
-[source,bash]
+.Result
+[source,console]
 ----
 [main] INFO com.datastax.pulsar.SimplePulsarProducer - Message 93573631 sent
 [main] INFO com.datastax.pulsar.SimplePulsarProducer - Message 16931522 sent
 [main] INFO com.datastax.pulsar.SimplePulsarProducer - Message 68306175 sent
 ----
-
-. The consumer begins consuming the produced messages.
 +
-[source,bash]
+In the `SimplePulsarConsumer` terminal, the consumer begins consuming the produced messages:
++
+.Result
+[source,console]
 ----
 [main] INFO com.datastax.pulsar.SimplePulsarConsumer - Message received: {"show_id":93573631,"cast":"LeBron James, Anthony Davis, Kyrie Irving, Damian Lillard, Klay Thompson...","country":"United States","date_added":"July 16, 2021","description":"NBA superstar LeBron James teams up with Bugs Bunny and the rest of the Looney Tunes for this long-awaited sequel.","director":"Malcolm D. Lee","duration":"120 min","listed_in":"Animation, Adventure, Comedy","rating":"PG","release_year":2021,"title":"Space Jam: A New Legacy","type":"Movie"}
 [main] INFO com.datastax.pulsar.SimplePulsarConsumer - Message received: {"show_id":16931522,"cast":"LeBron James, Anthony Davis, Kyrie Irving, Damian Lillard, Klay Thompson...","country":"United States","date_added":"July 16, 2021","description":"NBA superstar LeBron James teams up with Bugs Bunny and the rest of the Looney Tunes for this long-awaited sequel.","director":"Malcolm D. Lee","duration":"120 min","listed_in":"Animation, Adventure, Comedy","rating":"PG","release_year":2021,"title":"Space Jam: A New Legacy","type":"Movie"}
 [main] INFO com.datastax.pulsar.SimplePulsarConsumer - Message received: {"show_id":68306175,"cast":"LeBron James, Anthony Davis, Kyrie Irving, Damian Lillard, Klay Thompson...","country":"United States","date_added":"July 16, 2021","description":"NBA superstar LeBron James teams up with Bugs Bunny and the rest of the Looney Tunes for this long-awaited sequel.","director":"Malcolm D. Lee","duration":"120 min","listed_in":"Animation, Adventure, Comedy","rating":"PG","release_year":2021,"title":"Space Jam: A New Legacy","type":"Movie"}
 ----
 
-. Open a new terminal window and try to run `SimplePulsarConsumer.java`.
+. In a new terminal window, try to run another instance of `SimplePulsarConsumer.java`.
++
+The second consumer can't subscribe to the topic because the subscription is exclusive:
 +
-[source,bash]
+.Result
+[source,console]
 ----
 [main] INFO com.datastax.pulsar.Configuration - Configuration has been loaded successfully
 ...
@@ -73,16 +80,9 @@ Exception in thread "main" java.lang.IllegalStateException: Cannot connect to pu
 Caused by: org.apache.pulsar.client.api.PulsarClientException$ConsumerBusyException: {"errorMsg":"Exclusive consumer is already connected","reqId":2964994443801550457, "remote":"<service_url>", "local":"/192.168.0.95:55777"}
 ----
 
-The second consumer can't subscribe to the topic because the subscription is *exclusive*. +
-
-In the example above, the consumer didn't declare a subscription type, so Pulsar created an exclusive subscription by default. +
-To explicitly define an exclusive subscription, add `.subscriptionType(SubscriptionType.Exclusive)` to the consumer.
-
-== What's next
-
-For more on subscriptions, see: 
+== See also
 
 * xref:astream-subscriptions.adoc[Subscriptions in Pulsar]
 * xref:astream-subscriptions-shared.adoc[Shared subscriptions]
 * xref:astream-subscriptions-failover.adoc[Failover subscriptions]
-* xref:astream-subscriptions-keyshared.adoc[Key_shared subscriptions]
+* xref:astream-subscriptions-keyshared.adoc[Key shared subscriptions]