DOC-5859, DOC-5836, DOC-5877 7x

modules/ROOT/pages/faqs.adoc

@@ -10,7 +10,7 @@ If you are new to {product} and its {pulsar} enhancements, these FAQs are for yo
 == Are {product} and {company} Luna Streaming the same offering?
 
 Yes.
-include::partial$luna-name.adoc[]
+include::ROOT:partial$luna-name.adoc[]
 
 == What components and features are provided by {product}?
 

modules/ROOT/pages/index.adoc

@@ -5,7 +5,7 @@
 
 {product} provides all of the core capabilities included in the Apache Community version of {pulsar}, plus a number of additional tools and features to facilitate administration and operational tasks associated with running {pulsar} in production.
 
-include::partial$luna-name.adoc[]
+include::ROOT:partial$luna-name.adoc[]
 
 == Release notes
 
@@ -64,4 +64,4 @@ In addition to the distribution of https://pulsar.apache.org/en/versions/[{pulsa
 * If you have an existing Kubernetes environment, deploy {product} with a xref:install-upgrade:quickstart-helm-installs.adoc[Helm Installation].
 * If you have a bare metal or a cloud environment, see xref:install-upgrade:quickstart-server-installs.adoc[Server/VM Installation].
 * If you want to learn about monitoring with {pulsar-short} Heartbeat, see xref:components:pulsar-monitor.adoc[{pulsar-short} Heartbeat].
-* If you have questions about {product}, see xref::faqs.adoc[{product} FAQs].
+* If you have questions about {product}, see xref:ROOT:faqs.adoc[{product} FAQs].

modules/components/pages/admin-console-tutorial.adoc

@@ -9,11 +9,11 @@ In the *{pulsar-short} Admin Console*, you can use {pulsar-short} clients to sen
 
 If you installed the Admin console with the xref:install-upgrade:quickstart-helm-installs.adoc[{company} {pulsar-short} Helm chart], access the Admin console via the `pulsar-adminconsole` external load balancer endpoint in your cloud provider:
 
-image::GCP-all-pods.png[GCP Pods]
+image::components:GCP-all-pods.png[GCP Pods]
 
 Log in with username `admin`.
 
-If you're running a xref:install-upgrade:quickstart-server-installs.adoc[server or VM] deployment, see xref:admin-console-vm.adoc[Admin Console on Server/VM] for instructions on deploying and accessing the Admin console.
+If you're running a xref:install-upgrade:quickstart-server-installs.adoc[server or VM] deployment, see xref:components:admin-console-vm.adoc[Admin Console on Server/VM] for instructions on deploying and accessing the Admin console.
 
 [#features]
 == {pulsar-short} Admin Console features
@@ -22,11 +22,11 @@ To try out your service, use the built-in WebSocket test clients on the {pulsar-
 
 To see currently available namespaces, go to *Namespaces*, or select the button in the upper right corner.
 
-image::luna-streaming-select-namespace.png[Select Namespace]
+image::components:luna-streaming-select-namespace.png[Select Namespace]
 
 Messages published to namespaces are automatically replicated to all node(s) in the cluster.
 
-image::luna-streaming-admin-console.png[{product} Admin Console]
+image::components:luna-streaming-admin-console.png[{product} Admin Console]
 
 For interactive code samples, go to *Code Samples*.
 
@@ -42,7 +42,7 @@ This action creates a connection from the {pulsar-short} Admin Console that's ru
 Scroll down to the Consume tab. In this simple example, which verifies that the service is running properly, add a `hello world` message and click Send.
 For example:
 
-image::test-message.png[Send a message using a test client]
+image::components:test-message.png[Send a message using a test client]
 
 In doing so, you published a message to your server, and in the Test Client you're listening to your own topic.
 
@@ -145,4 +145,4 @@ Alternatively, you can save the URL authentication parameters in your `client.co
 
 == Next steps
 
-For more on building and running a standalone {pulsar-short} Admin console, see the xref:admin-console-vm.adoc[Admin Console on Server/VM] or the {pulsar-short} Admin console repo {pulsar-admin-console-repo}#dev[readme].
+For more on building and running a standalone {pulsar-short} Admin console, see the xref:components:admin-console-vm.adoc[Admin Console on Server/VM] or the {pulsar-short} Admin console repo {pulsar-admin-console-repo}#dev[readme].

modules/components/pages/admin-console-vm.adoc

@@ -55,7 +55,7 @@ You can modify the configuration for the Admin Console in `pulsar-admin-console/
 
 You need to configure `pulsar_url` to point to one of your brokers or a proxy/loadbalancer in front of the brokers (can be {pulsar-short} proxy). The Admin Console server must be able to directly reach each broker by the IP/hostname that is returned by the {pulsar-short} CLI command `pulsar-admin brokers list <clustername>`.
 
-[NOTE]
+[TIP]
 ====
 The cluster name can be retrieved with the CLI command `pulsar-admin clusters list`.
 ====

modules/components/pages/heartbeat-vm.adoc

@@ -39,4 +39,4 @@ export PULSAR_OPS_MONITOR_CFG=/Users/username/go/src/github.com/datastax/pulsar-
 
 == Next steps
 
-Learn more about monitoring your cluster with Heartbeat, see xref:pulsar-monitor.adoc[].
+Learn more about monitoring your cluster with Heartbeat, see xref:components:pulsar-monitor.adoc[].

modules/components/pages/pulsar-beam.adoc

@@ -7,7 +7,7 @@ The {pulsar-beam-repo}[{pulsar-beam}] project is an HTTP-based streaming and que
 
 With {pulsar-beam}, you can send messages over HTTP, push messages to a webhook or cloud function, chain webhooks and functions together, or stream messages through server-sent events (SSE).
 
-[NOTE]
+[TIP]
 ====
 include::ROOT:partial$luna-name.adoc[]
 ====
@@ -22,7 +22,7 @@ In this guide, you'll install a minimal {company} {pulsar-short} Helm chart that
 
 == Install the {company} {pulsar-short} Helm chart
 
-include::partial$install-helm.adoc[]
+include::components:partial$install-helm.adoc[]
 
 == Forward service port
 
@@ -36,7 +36,7 @@ kubectl port-forward -n datastax-pulsar service/pulsar-proxy 8085:8085
 The forwarding service will map the URL:PORT https://127.0.0.1:8085 to {pulsar-short} proxy running in the new cluster.
 Because {pulsar-beam} was enabled, the proxy knows to forward on to the {pulsar-beam} service.
 
-[source,shell]
+[source,console]
 ----
 Forwarding from 127.0.0.1:8085 -> 8085
 Forwarding from [::1]:8085 -> 8085
@@ -74,7 +74,7 @@ curl --request POST \
 
 The message consumer will output the data of the new message just produced.
 
-[source,shell]
+[source,console]
 ----
 id: {9 0 0 0 <nil> 0xc002287ad0}
 data: Hi there
@@ -155,12 +155,12 @@ The payload is base64 encoded. Simply decode the string to see the actual messag
 
 == Clean up
 
-include::partial$cleanup-terminal-and-helm.adoc[]
+include::components:partial$cleanup-terminal-and-helm.adoc[]
 
 == Next steps
 
 Here are links to resources and guides you might be interested in:
 
 * {pulsar-beam-repo}[Learn more] about the {pulsar-beam} project
 * https://kafkaesque-io.github.io/pulsar-beam-swagger[{pulsar-beam} API]
-* xref:pulsar-sql.adoc[]
+* xref:components:pulsar-sql.adoc[]

modules/components/pages/pulsar-sql.adoc

@@ -9,7 +9,7 @@ Stream processing, real-time analytics, and highly customized dashboards are jus
 {pulsar-short} offers a pre-made plugin for Trino that is included in its distribution.
 Additionally, {pulsar-short} has built-in options to create Trino workers and automatically configure the communications between {pulsar-short}'s ledger and Trino.
 
-[NOTE]
+[TIP]
 ====
 include::ROOT:partial$luna-name.adoc[]
 ====
@@ -33,7 +33,7 @@ The Trino CLI uses the "X-TRINO-USER" header for authentications.
 
 == Install the {company} {pulsar-short} Helm chart
 
-include::partial$install-helm.adoc[]
+include::components:partial$install-helm.adoc[]
 
 == Forward service port
 
@@ -60,13 +60,13 @@ kubectl port-forward -n datastax-pulsar service/pulsar-broker 8080:8080
 . In a browser, navigate to \http://localhost:8081.
 You will be greeted by Trino's login.
 +
-image::trino-sql-login.png[Trino SQL login]
+image::components:trino-sql-login.png[Trino SQL login]
 
 . There is no authentication enabled, so input whatever user name you prefer and select **Log In**.
 You will be greeted by a blank dashboard.
 This confirms Trino is up and running.
 +
-image::trino-sql-dashboard.png[Trino SQL dashboard]
+image::components:trino-sql-dashboard.png[Trino SQL dashboard]
 
 [#create-topic]
 == Fill a topic with the data-generator source
@@ -94,12 +94,8 @@ The CLI will use the environment variable's value as configuration for interacti
 ./bin/pulsar-admin sources create --name generator --destination-topic-name public/default/mytopic --source-type data-generator
 ----
 +
-[NOTE]
-====
-The topic name will become a table name in Trino, so SQL naming rules apply.
-
+The topic name becomes the Trino table name, so SQL naming rules apply.
 Names can contain only alphanumeric characters and must begin with an alphabetic character or an underscore (_).
-====
 
 . Confirm the topic was created:
 +
@@ -284,9 +280,9 @@ Connection established......
 
 == Clean up
 
-include::partial$cleanup-terminal-and-helm.adoc[]
+include::components:partial$cleanup-terminal-and-helm.adoc[]
 
 == Next steps
 
-* xref:pulsar-beam.adoc[]
-* xref:admin-console-tutorial.adoc[]
+* xref:components:pulsar-beam.adoc[]
+* xref:components:admin-console-tutorial.adoc[]

modules/connectors/pages/index.adoc

@@ -2,18 +2,15 @@
 :navtitle: {pulsar-short} I/O connectors reference
 :page-aliases: operations:io-connectors.adoc
 
-[NOTE]
+[TIP]
 ====
 include::ROOT:partial$luna-name.adoc[]
 ====
 
 {product} offers fully-managed versions of https://pulsar.apache.org/docs/en/io-overview/[{pulsar-reg} sink and source connectors].
 
-[TIP]
-====
 There are three versions of the {product} distribution.
 The `lunastreaming-all` version includes all connectors.
-====
 
 [#sink-connectors]
 == Sink connectors

modules/install-upgrade/pages/cluster-sizing-reference.adoc

@@ -146,4 +146,4 @@ a|* CPU: 4 vCPU
 
 == Next steps
 
-For more on cluster sizing, see xref:production-cluster-sizing.adoc[].
+For more on cluster sizing, see xref:install-upgrade:production-cluster-sizing.adoc[].

modules/install-upgrade/pages/production-cluster-sizing.adoc

@@ -6,7 +6,7 @@ Remember, a {pulsar-short} *instance* is made of one or many clusters.
 Of course, the sizing of a cluster depends on factors like use case and expected load, so this document is not intended to be a one-size-fits-all guide. Rather, we'd like to demonstrate how we consider and spec the initial size of a {pulsar-short} cluster, and assist you on your journey to unlocking the scaling power of {pulsar-short}.
 
 This page summarizes the requirements, assumptions, definitions, and methodologies that inform our cluster sizing recommendations.
-If you're looking for specific deployment topology recommendations, see xref:cluster-sizing-reference.adoc[].
+If you're looking for specific deployment topology recommendations, see xref:install-upgrade:cluster-sizing-reference.adoc[].
 
 include::operations:partial$operator-scaling.adoc[]
 
@@ -61,7 +61,7 @@ Scale the workers based on overall usage (both CPU and memory).
 * xref:luna-streaming:components:heartbeat-vm.adoc[{pulsar-short} Heartbeat] - This is an optional component that monitors the health of {pulsar-short} cluster and emits metrics about the cluster that are helpful for observing and debugging issues.
 * Prometheus/Grafana/Alert manager stack - This is the default observability stack for a cluster. The {company} {pulsar-short} Helm chart includes pre-made dashboards in Grafana and pre-wires all the metrics scraping.
 
-image::pulsar-components.png[]
+image::install-upgrade:pulsar-components.png[]
 
 [#message-retention]
 == Message retention
@@ -155,7 +155,7 @@ But (very important) we want the message replication factor to be an odd number,
 
 . Multiply replication factor (3) by average message payload size (1) by average message throughput (100000), then factor in TTL (3) and retention period (3600) (when applicable).
 +
-[source,plaintext]
+[source,console]
 ----
 Total message size (raw) =
 3 *             // replication factor
@@ -168,9 +168,9 @@ Total message size (raw) =
 +
 We now know our cluster needs 3 Tb of storage for {bookkeeper-short} ledger data.
 
-. Calculate the number of {bookkeeper-short} nodes with an individual ledger disk capacity.
+. Calculate the number of {bookkeeper-short} nodes with an individual ledger disk capacity:
 +
-[source,plain,subs="+attributes"]
+[source,console,subs="+attributes"]
 ----
 {bookkeeper-short} count(raw)=ceiling(3/(4 * 0.85)) = 1
 ----
@@ -180,7 +180,7 @@ For fault tolerance, we adjust this to a number that is divisible by the number
 
 . Given the replication factor of 3, we will need at least 1 broker to write messages to the bookies. That gives us a broker-to-{bookkeeper-short} ratio of 1:3. Now we can calculate the total number of brokers across 3 zones.
 +
-[source,plain]
+[source,console]
 ----
 broker count(raw)=ceiling(1/3) = 1
 ----
@@ -235,4 +235,4 @@ Now that we know how many server instances of broker and bookie are required to
 
 == Next steps
 
-See xref:cluster-sizing-reference.adoc[] for specific deployment topologies and hardware recommendations.
+See xref:install-upgrade:cluster-sizing-reference.adoc[] for specific deployment topologies and hardware recommendations.

modules/install-upgrade/pages/quickstart-helm-installs.adoc

@@ -1,6 +1,6 @@
 = Quick Start for Helm Chart installs
 
-[IMPORTANT]
+[TIP]
 ====
 include::ROOT:partial$luna-name.adoc[]
 ====
@@ -34,13 +34,13 @@ It is designed for production use, but can also be used in local development env
 
 The resulting configuration includes support for:
 
-* xref:install-upgrade:quickstart-helm-installs.adoc#tls[TLS]
-* xref:install-upgrade:quickstart-helm-installs.adoc#authentication[Authentication]
+* <<tls,TLS>>
+* <<authentication,Authentication>>
 * WebSocket proxy
 * Standalone Functions Workers
 * {pulsar-short} I/O connectors
-* xref:install-upgrade:quickstart-helm-installs.adoc#_tiered_storage_configuration[Tiered storage] including Tardigarde distributed cloud storage
-* xref:install-upgrade:quickstart-helm-installs.adoc#_pulsar_sql_configuration[{pulsar-short} SQL workers]
+* <<tiered_storage_configuration,Tiered storage>> including Tardigarde distributed cloud storage
+* <<pulsar-sql-configuration,{pulsar-short} SQL workers>>
 * {pulsar-short} Admin Console for managing the cluster
 * {pulsar-short} Heartbeat
 * Burnell for API-based token generation
@@ -272,7 +272,10 @@ Example of checking the pods' status:
 [source,shell]
 ----
 kubectl get pods
+----
 
+[source,console]
+----
 NAME                                                  READY   STATUS     RESTARTS  AGE
 prometheus-pulsar-kube-prometheus-sta-prometheus-0    2/2     Running    1         10m
 pulsar-adminconsole-9669f6d98-dxjvp                   2/2     Running    3         12m
@@ -387,12 +390,14 @@ kube-prometheus-stack:
     create: yes
 ----
 
+[#tiered-storage-configuration]
 ==== Tiered Storage Configuration
 
 Tiered storage (offload to blob storage) can be configured in the `storageOffload` section of the `values.yaml` file. Instructions for AWS S3 and Google Cloud Storage are provided in the file.
 
 In addition, you can configure any S3 compatible storage. There is explicit support for https://tardigrade.io[Tardigrade], which is a provider of secure, decentralized storage. You can enable the Tardigarde S3 gateway in the `extra` configuration. The instructions for configuring the gateway are provided in the `tardigrade` section of the `values.yaml` file.
 
+[#pulsar-sql-configuration]
 ==== {pulsar-short} SQL Configuration
 
 If you enable {pulsar-short} SQL, the cluster provides https://trino.io/[Trino] access to the data stored in {bookkeeper-short} (and tiered storage, if enabled). Trino is exposed on the service named `<release>-sql`.
@@ -403,9 +408,13 @@ The easiest way to access the Trino command line is to log into the bastion host
 
 Where the value for the `server` option should be the service name plus port. Once you are connected, you can enter Trino commands. Example:
 
-[source,console]
+[source,shell]
 ----
 trino> SELECT * FROM system.runtime.nodes;
+----
+
+[source,console]
+----
                node_id                |         http_uri         | node_version | coordinator | state
 --------------------------------------+--------------------------+--------------+-------------+--------
  64b7c5a1-9a72-4598-b494-b140169abc55 | http://10.244.5.164:8080 | 0.206        | true        | active
@@ -423,11 +432,22 @@ It is recommended that you match the Trino CLI version to the version running as
 
 The Trino CLI supports basic authentication, so if you enabled that on the Ingress (using annotations), you can have secure Trino access. Example:
 
-[source,sql]
+Connect:
+
+[source,shell]
 ----
 trino --server https://trino.example.com --user admin --password
-Password:
+----
+
+Enter password when prompted, and then get catalogs:
+
+[source,shell]
+----
 trino> show catalogs;
+----
+
+[source,console]
+----
  Catalog
 ---------
  pulsar