Merge pull request #5885 from influxdata/jts/dar-472-catalog-terminology

fix(clustered): Closes influxdata/DAR#472. …

Author: jstirnaman

content/influxdb3/clustered/admin/backup-restore.md

@@ -12,29 +12,29 @@ weight: 105
 influxdb3/clustered/tags: [backup, restore]
 ---
 
-InfluxDB Clustered automatically stores snapshots of the InfluxDB Catalog that
+InfluxDB Clustered automatically stores snapshots of the InfluxDB Catalog store that
 you can use to restore your cluster to a previous state. The snapshotting
 functionality is optional and is disabled by default.
 Enable snapshots to ensure you can recover
 in case of emergency.
 
 With InfluxDB Clustered snapshots enabled, each hour, InfluxDB uses the `pg_dump`
-utility included with the InfluxDB Garbage Collector to export an SQL blob or
-“snapshot” from the InfluxDB Catalog and store it in the object store.
-The Catalog is a PostgreSQL-compatible relational database that stores metadata
+utility included with the InfluxDB Garbage collector to export an SQL blob or
+“snapshot” from the InfluxDB Catalog store to the Object store.
+The Catalog store is a PostgreSQL-compatible relational database that stores metadata
 for your time series data, such as schema data types, Parquet file locations, and more.
 
-The Catalog snapshots act as recovery points for your InfluxDB cluster that
-reference all Parquet files that existed in the object store at the time of the
-snapshot. When a snapshot is restored to the Catalog, the Compactor
+The Catalog store snapshots act as recovery points for your InfluxDB cluster that
+reference all Parquet files that existed in the Object store at the time of the
+snapshot. When a snapshot is restored to the Catalog store, the Compactor
 “[soft deletes](#soft-delete)” any Parquet files not listed in the snapshot.
 
 > [!Note]
 > InfluxDB won't [hard delete](#hard-delete) Parquet files listed in _any_ hourly or daily snapshot.
 > 
 > For example, if you have Parquet files A, B, C, and D, and you restore to a
 > snapshot that includes B and C, but not A and D, then A and D are soft-deleted, but remain in object
-> storage until they are no longer referenced in any Catalog snapshot.
+> storage until they are no longer referenced in any Catalog store snapshot.
 - [Soft delete](#soft-delete)
 - [Hard delete](#hard-delete)
 - [Recovery Point Objective (RPO)](#recovery-point-objective-rpo)
@@ -75,8 +75,8 @@ The InfluxDB Clustered snapshot strategy RPO allows for the following maximum da
  ## Recovery Time Objective (RTO)
 
 RTO is the maximum amount of downtime allowed for an InfluxDB cluster after a failure.
-RTO varies depending on the size of your Catalog database, network speeds
-between the client machine and the Catalog database, cluster load, the status
+RTO varies depending on the size of your Catalog store, network speeds
+between the client machine and the Catalog store, cluster load, the status
 of your underlying hosting provider, and other factors.
 
 ## Data written just before a snapshot may not be present after restoring
@@ -94,14 +94,14 @@ present after restoring to that snapshot.
 ### Automate object synchronization to an external S3-compatible bucket
 
 Syncing objects to an external S3-compatible bucket ensures an up-to-date backup
-in case your object store becomes unavailable. Recovery point snapshots only
-back up the InfluxDB Catalog. If data referenced in a Catalog snapshot does not
-exist in the object store, the recovery process does not restore the missing data.
+in case your Object store becomes unavailable. Recovery point snapshots only
+back up the InfluxDB Catalog store. If data referenced in a Catalog store snapshot does not
+exist in the Object store, the recovery process does not restore the missing data.
 
 ### Enable short-term object versioning
 
 If your object storage provider supports it, consider enabling short-term
-object versioning on your object store--for example, 1-2 days to protect against errant writes or deleted objects.
+object versioning on your Object store--for example, 1-2 days to protect against errant writes or deleted objects.
 With object versioning enabled, as objects are updated, the object store
 retains distinct versions of each update that can be used to “rollback” newly
 written or updated Parquet files to previous versions.
@@ -140,7 +140,7 @@ spec:
 
 #### INFLUXDB_IOX_CREATE_CATALOG_BACKUP_DATA_SNAPSHOT_FILES
 
-Enable hourly Catalog snapshotting. The default is `'false'`. Set to `'true'`:
+Enable hourly Catalog store snapshotting. The default is `'false'`. Set to `'true'`:
 
 ```yaml
 INFLUXDB_IOX_CREATE_CATALOG_BACKUP_DATA_SNAPSHOT_FILES: 'true'
@@ -217,22 +217,20 @@ written on or around the beginning of the next hour.
 ## Restore to a recovery point
 
 Use the following process to restore your InfluxDB cluster to a recovery point
-using Catalog snapshots:
+using Catalog store snapshots:
 
 1.  **Install prerequisites:**  
 
     - `kubectl` CLI for managing your Kubernetes deployment.  
-    - `psql` CLI to interact with the PostgreSQL-compatible Catalog database with
-      the appropriate Data Source Name (DSN) and connection credentials.  
-    - A client to interact with your InfluxDB cluster’s object store.
-      Supported clients depend on your object storage provider.
+    - `psql` CLI configured with your Data Source Name and credentials for interacting with the PostgreSQL-compatible Catalog store database.
+    - A client from your object storage provider for interacting with your InfluxDB cluster's Object store.
 
 2.  **Retrieve the recovery point snapshot from your object store.**
 
     InfluxDB Clustered stores hourly and daily snapshots in the
     `/catalog_backup_file_lists` path in object storage. Download the snapshot
-    that you would like to use as the recovery point. If your primary object
-    store is unavailable, download the snapshot from your replicated object store.
+    that you would like to use as the recovery point. If your primary Object
+    store is unavailable, download the snapshot from your replicated Object store.
 
     > [!Important]
     > When creating and storing a snapshot, the last artifact created is the

content/influxdb3/clustered/admin/scale-cluster.md

@@ -22,19 +22,12 @@ resources available to each component.
 - [Scaling strategies](#scaling-strategies)
   - [Vertical scaling](#vertical-scaling)
   - [Horizontal scaling](#horizontal-scaling)
+- [Scale your cluster as a whole](#scale-your-cluster-as-a-whole)
 - [Scale components in your cluster](#scale-components-in-your-cluster)
   - [Horizontally scale a component](#horizontally-scale-a-component)
   - [Vertically scale a component](#vertically-scale-a-component)
   - [Apply your changes](#apply-your-changes)
-- [Scale your cluster as a whole](#scale-your-cluster-as-a-whole)
 - [Recommended scaling strategies per component](#recommended-scaling-strategies-per-component)
-  - [Ingester](#ingester)
-  - [Querier](#querier)
-  - [Router](#router)
-  - [Compactor](#compactor)
-  - [Garbage collector](#garbage-collector)
-  - [Catalog](#catalog)
-  - [Object store](#object-store)
 
 ## Scaling strategies
 
@@ -59,6 +52,14 @@ throughput a system can manage, but also provides additional redundancy and fail
 
 {{< html-diagram/scaling-strategy "horizontal" >}}
 
+## Scale your cluster as a whole
+
+Scaling your entire InfluxDB Cluster is done by scaling your Kubernetes cluster
+and is managed outside of InfluxDB. The process of scaling your entire Kubernetes
+cluster depends on your underlying Kubernetes provider. You can also use 
+[Kubernetes autoscaling](https://kubernetes.io/docs/concepts/cluster-administration/cluster-autoscaling/)
+to automatically scale your cluster as needed.
+
 ## Scale components in your cluster
 
 The following components of your InfluxDB cluster are scaled by modifying
@@ -69,6 +70,7 @@ properties in your `AppInstance` resource:
 - Compactor
 - Router
 - Garbage collector
+- Catalog service
 
 > [!Note]
 > #### Scale your Catalog and Object store
@@ -448,39 +450,42 @@ helm upgrade \
 {{% /code-tab-content %}}
 {{< /code-tabs-wrapper >}}
 
-## Scale your cluster as a whole
-
-Scaling your entire InfluxDB Cluster is done by scaling your Kubernetes cluster
-and is managed outside of InfluxDB. The process of scaling your entire Kubernetes
-cluster depends on your underlying Kubernetes provider. You can also use 
-[Kubernetes autoscaling](https://kubernetes.io/docs/concepts/cluster-administration/cluster-autoscaling/)
-to automatically scale your cluster as needed.
-
 ## Recommended scaling strategies per component
 
 - [Router](#router)
 - [Ingester](#ingester)
 - [Querier](#querier)
 - [Compactor](#compactor)
 - [Garbage collector](#garbage-collector)
-- [Catalog](#catalog)
+- [Catalog store](#catalog-store)
+- [Catalog service](#catalog-service)
 - [Object store](#object-store)
 
 ### Router
 
-The Router can be scaled both [vertically](#vertical-scaling) and
+The [Router](/influxdb3/clustered/reference/internals/storage-engine/#router) can be scaled both [vertically](#vertical-scaling) and
 [horizontally](#horizontal-scaling).
-Horizontal scaling increases write throughput and is typically the most
+
+- **Recommended**: Horizontal scaling increases write throughput and is typically the most
 effective scaling strategy for the Router.
-Vertical scaling (specifically increased CPU) improves the Router's ability to
+- Vertical scaling (specifically increased CPU) improves the Router's ability to
 parse incoming line protocol with lower latency.
 
+#### Router latency
+
+Latency of the Router’s write endpoint is directly impacted by:
+
+- Ingester latency--the router calls the Ingester during a client write request
+- Catalog latency during schema validation
+
 ### Ingester
 
-The Ingester can be scaled both [vertically](#vertical-scaling) and
+The [Ingester](/influxdb3/clustered/reference/internals/storage-engine/#ingester) can be scaled both [vertically](#vertical-scaling) and
 [horizontally](#horizontal-scaling).
-Vertical scaling increases write throughput and is typically the most effective
-scaling strategy for the Ingester.
+
+- **Recommended**: Vertical scaling is typically the most effective scaling strategy for the Ingester.
+Compared to horizontal scaling, vertical scaling not only increases write throughput but also lessens query, catalog, and compaction overheads as well as Object store costs.
+- Horizontal scaling can help distribute write load but comes with additional coordination overhead.
 
 #### Ingester storage volume
 
@@ -543,37 +548,62 @@ ingesterStorage:
 
 ### Querier
 
-The Querier can be scaled both [vertically](#vertical-scaling) and
+The [Querier](/influxdb3/clustered/reference/internals/storage-engine/#querier) can be scaled both [vertically](#vertical-scaling) and
 [horizontally](#horizontal-scaling).
-Horizontal scaling increases query throughput to handle more concurrent queries.
-Vertical scaling improves the Querier’s ability to process computationally
-intensive queries.
+
+- **Recommended**: [Vertical scaling](#vertical-scaling) improves the Querier's ability to process concurrent or computationally 
+intensive queries, and increases the effective cache capacity.
+- Horizontal scaling increases query throughput to handle more concurrent queries. 
+Consider horizontal scaling if vertical scaling doesn't adequately address
+concurrency demands or reaches the hardware limits of your underlying nodes.
 
 ### Compactor
 
-The Compactor can be scaled both [vertically](#vertical-scaling) and
-[horizontally](#horizontal-scaling).
-Because compaction is a compute-heavy process, vertical scaling (especially
-increasing the available CPU) is the most effective scaling strategy for the
-Compactor. Horizontal scaling increases compaction throughput, but not as
+- **Recommended**: Maintain **1 Compactor pod** and use [vertical scaling](#vertical-scaling) (especially
+increasing the available CPU) for the Compactor.
+- Because compaction is a compute-heavy process, horizontal scaling increases compaction throughput, but not as
 efficiently as vertical scaling.
 
 ### Garbage collector
 
-The Garbage collector can be scaled [vertically](#vertical-scaling). It is a
-light-weight process that typically doesn't require many system resources, but
-if you begin to see high resource consumption on the garbage collector, you can
-scale it vertically to address the added workload.
+The [Garbage collector](/influxdb3/clustered/reference/internals/storage-engine/#garbage-collector) is a lightweight process that typically doesn't require
+significant system resources. 
+
+- Don't horizontally scale the Garbage collector; it isn't designed for distributed load.
+- Consider [vertical scaling](#vertical-scaling) only if you observe consistently high CPU usage or if the container
+regularly runs out of memory.
+
+### Catalog store
 
-### Catalog
+The [Catalog store](/influxdb3/clustered/reference/internals/storage-engine/#catalog-store) is a PostgreSQL-compatible database that stores critical metadata for your InfluxDB cluster.
+An underprovisioned Catalog store can cause write outages and system-wide performance issues.
 
-Scaling strategies available for the Catalog depend on the PostgreSQL-compatible
-database used to run the catalog. All support [vertical scaling](#vertical-scaling).
-Most support [horizontal scaling](#horizontal-scaling) for redundancy and failover.
+- Scaling strategies depend on your specific PostgreSQL implementation
+- All PostgreSQL implementations support [vertical scaling](#vertical-scaling)
+- Most implementations support [horizontal scaling](#horizontal-scaling) for improved redundancy and failover
+
+
+### Catalog service
+
+The [Catalog service](/influxdb3/clustered/reference/internals/storage-engine/#catalog-service) (iox-shared-catalog statefulset) caches 
+and manages access to the Catalog store.
+
+- **Recommended**: Maintain **exactly 3 replicas** of the Catalog service for optimal redundancy. Additional replicas are discouraged.
+- If performance improvements are needed, use [vertical scaling](#vertical-scaling).
+
+> [!Note]
+> #### Managing Catalog components
+> 
+> The [Catalog service](/influxdb3/clustered/reference/internals/storage-engine/#catalog-service) is managed through the
+> `AppInstance` resource, while the [Catalog store](/influxdb3/clustered/reference/internals/storage-engine/#catalog-store) 
+> is managed separately according to your PostgreSQL implementation.
 
 ### Object store
 
-Scaling strategies available for the Object store depend on the underlying
-object storage services used to run the object store. Most support
+The [Object store](/influxdb3/clustered/reference/internals/storage-engine/#object-store)
+contains time series data in Parquet format.
+
+Scaling strategies depend on the underlying object storage services used.
+Most services support
 [horizontal scaling](#horizontal-scaling) for redundancy, failover, and
 increased capacity.

content/influxdb3/clustered/install/_index.md

@@ -62,13 +62,13 @@ Updating your InfluxDB cluster is as simple as re-applying your app-instance wit
 
 The word safely here means being able to redeploy your cluster while still being able to use the tokens you’ve created, and being able to write/query to the database you’ve previously created.
 
-All of the important state in InfluxDB 3 lives in the Catalog (the Postgres equivalent database) and the Object Store (the S3 compatible store). These should be treated with the utmost care. 
+All of the important state in InfluxDB 3 lives in the Catalog store (the Postgres equivalent database) and the Object Store (the S3 compatible store). These should be treated with the utmost care. 
 
-If a full redeploy of your cluster needs to happen, the namespace containing the Influxdb instance can be deleted **_as long as your Catalog and Object Store are not in this namespace_**. Then, the influxdb AppInstance can be redeployed. It is possible the operator may need to be removed and reinstalled. In that case, deleting the namespace that the operator is deployed into and redeploying is acceptable.
+If a full redeploy of your cluster needs to happen, the namespace containing the Influxdb instance can be deleted **_as long as your Catalog store and Object Store are not in this namespace_**. Then, the influxdb AppInstance can be redeployed. It is possible the operator may need to be removed and reinstalled. In that case, deleting the namespace that the operator is deployed into and redeploying is acceptable.
 
 ### Backing up your data
 
-The Catalog and Object store contain all of the important state for InfluxDB 3. They should be the primary focus of backups. Following the industry standard best practices for your chosen Catalog implementation and Object Store implementation should provide sufficient backups.  In our Cloud products, we do daily backups of our Catalog, in addition to automatic snapshots, and we preserve our Object Store files for 100 days after they have been soft-deleted.
+The Catalog store and Object store contain all of the important state for InfluxDB 3. They should be the primary focus of backups. Following the industry standard best practices for your chosen Catalog store implementation and Object Store implementation should provide sufficient backups.  In our Cloud products, we do daily backups of our Catalog, in addition to automatic snapshots, and we preserve our Object Store files for 100 days after they have been soft-deleted.
 
 ### Recovering your data
 

content/influxdb3/clustered/install/secure-cluster/tls.md

@@ -17,7 +17,7 @@ following:
 
 - Ingress to your cluster
 - Connection to your Object store
-- Connection to your Catalog (PostgreSQL-compatible) database
+- Connection to your Catalog store (PostgreSQL-compatible) database
 
 > [!Note]
 > If using self-signed certs,
@@ -176,8 +176,8 @@ objectStore:
 Refer to your PostreSQL-compatible database provider's documentation for
 installing TLS certificates and ensuring secure connections.
 
-If currently using an unsecure connection to your Catalog database, update your
-Catalog data source name (DSN) to **remove the `sslmode=disable` query parameter**:
+If currently using an unsecure connection to your Catalog store database, update your
+Catalog store data source name (DSN) to **remove the `sslmode=disable` query parameter**:
 
 {{% code-callout "\?sslmode=disable" "magenta delete" %}}
 ```txt

content/influxdb3/clustered/install/set-up-cluster/prerequisites.md

@@ -99,7 +99,7 @@ following sizing for {{% product-name %}} components:
 {{% tab-content %}}
 <!--------------------------------- BEGIN AWS --------------------------------->
 
-- **Catalog (PostgreSQL-compatible database) (x1):**
+- **Catalog store (PostgreSQL-compatible database) (x1):**
   - _[See below](#postgresql-compatible-database-requirements)_
 - **Ingesters and Routers (x3):**
   - EC2 m6i.2xlarge (8 CPU, 32 GB RAM)
@@ -116,7 +116,7 @@ following sizing for {{% product-name %}} components:
 {{% tab-content %}}
 <!--------------------------------- BEGIN GCP --------------------------------->
 
-- **Catalog (PostgreSQL-compatible database) (x1):**
+- **Catalog store (PostgreSQL-compatible database) (x1):**
   - _[See below](#postgresql-compatible-database-requirements)_
 - **Ingesters and Routers (x3):**
   - GCE c2-standard-8 (8 CPU, 32 GB RAM)
@@ -133,7 +133,7 @@ following sizing for {{% product-name %}} components:
 {{% tab-content %}}
 <!-------------------------------- BEGIN Azure -------------------------------->
 
-- **Catalog (PostgreSQL-compatible database) (x1):**
+- **Catalog store (PostgreSQL-compatible database) (x1):**
   - _[See below](#postgresql-compatible-database-requirements)_
 - **Ingesters and Routers (x3):**
   - Standard_D8s_v3 (8 CPU, 32 GB RAM)
@@ -150,7 +150,7 @@ following sizing for {{% product-name %}} components:
 {{% tab-content %}}
 <!------------------------------- BEGIN ON-PREM ------------------------------->
 
-- **Catalog (PostgreSQL-compatible database) (x1):**
+- **Catalog store (PostgreSQL-compatible database) (x1):**
   - CPU: 4-8 cores
   - RAM: 16-32 GB
 - **Ingesters and Routers (x3):**