From 8491969abde17cf9820c8c12cf14511bbe30a756 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 11 Mar 2025 17:18:05 -0500 Subject: [PATCH 1/2] fix(clustered): Closes https://github.com/influxdata/DAR/issues/472. Catalog terminology is confusing, needs scaling recommendations: - Distinguish between Catalog store (Postgres db) and Catalog service (API and cache for the store). - Add scaling recommendations for each. - Resolve conflicting scaling info, remove duplicated scaling info from storage-engine.md. --- .../clustered/admin/backup-restore.md | 42 +++++------ .../clustered/admin/databases/delete.md | 6 +- .../clustered/admin/scale-cluster.md | 62 +++++++++------- content/influxdb3/clustered/install/_index.md | 6 +- .../clustered/install/secure-cluster/tls.md | 6 +- .../install/set-up-cluster/prerequisites.md | 8 +- .../report-query-performance-issues.md | 4 +- .../reference/internals/storage-engine.md | 74 ++++--------------- .../reference/release-notes/clustered.md | 2 +- .../best-practices/data-lifecycle.md | 14 ++-- 10 files changed, 94 insertions(+), 130 deletions(-) diff --git a/content/influxdb3/clustered/admin/backup-restore.md b/content/influxdb3/clustered/admin/backup-restore.md index a09fa77bc..e5dfebd7c 100644 --- a/content/influxdb3/clustered/admin/backup-restore.md +++ b/content/influxdb3/clustered/admin/backup-restore.md @@ -12,21 +12,21 @@ 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] @@ -34,7 +34,7 @@ snapshot. When a snapshot is restored to the Catalog, the Compactor > > 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 diff --git a/content/influxdb3/clustered/admin/databases/delete.md b/content/influxdb3/clustered/admin/databases/delete.md index e8169206f..c88fa1633 100644 --- a/content/influxdb3/clustered/admin/databases/delete.md +++ b/content/influxdb3/clustered/admin/databases/delete.md @@ -41,8 +41,8 @@ Once a database is deleted, data stored in that database cannot be recovered. After a database is deleted, you cannot reuse the same name for a new database. -#### Never directly modify the Catalog +#### Never directly modify the Catalog store -Never directly modify the [PostgreSQL-compatible Catalog](/influxdb3/clustered/reference/internals/storage-engine/#catalog). - Doing so will result in an undefined state for various components and may lead to data loss and crashes. +Never directly modify the [PostgreSQL-compatible Catalog store](/influxdb3/clustered/reference/internals/storage-engine/#catalog-store). +Doing so will result in an undefined state for various components and may lead to data loss and crashes. {{% /warn %}} diff --git a/content/influxdb3/clustered/admin/scale-cluster.md b/content/influxdb3/clustered/admin/scale-cluster.md index 2ed9e7597..2027c8799 100644 --- a/content/influxdb3/clustered/admin/scale-cluster.md +++ b/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,11 +70,12 @@ properties in your `AppInstance` resource: - Compactor - Router - Garbage collector +- Catalog service {{% note %}} -#### Scale your Catalog and Object store +#### Scale your Catalog store and Object store -Your InfluxDB [Catalog](/influxdb3/clustered/reference/internals/storage-engine/#catalog) +Your InfluxDB [Catalog store](/influxdb3/clustered/reference/internals/storage-engine/#catalog-store) and [Object store](/influxdb3/clustered/reference/internals/storage-engine/#object-store) are managed outside of your `AppInstance` resource. Scaling mechanisms for these components depend on the technology and underlying provider used for each. @@ -451,14 +453,6 @@ 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) @@ -466,7 +460,8 @@ to automatically scale your cluster as needed. - [Querier](#querier) - [Compactor](#compactor) - [Garbage collector](#garbage-collector) -- [Catalog](#catalog) +- [Catalog store](#catalog-store) +- [Catalog service](#catalog-service) - [Object store](#object-store) ### Router @@ -563,16 +558,29 @@ 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 is not designed for distributed load and should _not_ be +scaled horizontally. It is a lightweight process that typically doesn't require +significant system resources. [Vertical scaling](#vertical-scaling) should only +be considered if you observe consistently high CPU usage or if the container +regularly runs out of memory. -### Catalog +### Catalog store -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. +The Catalog store is a PostgreSQL-compatible database that persistently stores metadata. +Scaling strategies depend on your chosen PostgreSQL implementation. +All support [vertical scaling](#vertical-scaling), and most support +[horizontal scaling](#horizontal-scaling) for redundancy and failover. + +### Catalog service + +The Catalog service should maintain exactly +3 replicas for optimal redundancy. +Additional replicas are discouraged; favor vertical scaling instead if performance improvements are needed. + +> [!Note] +> 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 diff --git a/content/influxdb3/clustered/install/_index.md b/content/influxdb3/clustered/install/_index.md index 1bac6ab06..4bafb28b0 100644 --- a/content/influxdb3/clustered/install/_index.md +++ b/content/influxdb3/clustered/install/_index.md @@ -61,13 +61,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 diff --git a/content/influxdb3/clustered/install/secure-cluster/tls.md b/content/influxdb3/clustered/install/secure-cluster/tls.md index 37f80ab0a..d0a72f4c2 100644 --- a/content/influxdb3/clustered/install/secure-cluster/tls.md +++ b/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, @@ -177,8 +177,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 diff --git a/content/influxdb3/clustered/install/set-up-cluster/prerequisites.md b/content/influxdb3/clustered/install/set-up-cluster/prerequisites.md index 33315c698..3ec6e88be 100644 --- a/content/influxdb3/clustered/install/set-up-cluster/prerequisites.md +++ b/content/influxdb3/clustered/install/set-up-cluster/prerequisites.md @@ -100,7 +100,7 @@ following sizing for {{% product-name %}} components: {{% tab-content %}} -- **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) @@ -117,7 +117,7 @@ following sizing for {{% product-name %}} components: {{% tab-content %}} -- **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) @@ -134,7 +134,7 @@ following sizing for {{% product-name %}} components: {{% tab-content %}} -- **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) @@ -151,7 +151,7 @@ following sizing for {{% product-name %}} components: {{% tab-content %}} -- **Catalog (PostgreSQL-compatible database) (x1):** +- **Catalog store (PostgreSQL-compatible database) (x1):** - CPU: 4-8 cores - RAM: 16-32 GB - **Ingesters and Routers (x3):** diff --git a/content/influxdb3/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md b/content/influxdb3/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md index acbcf4fd5..b9e2496bf 100644 --- a/content/influxdb3/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md +++ b/content/influxdb3/clustered/query-data/troubleshoot-and-optimize/report-query-performance-issues.md @@ -78,8 +78,8 @@ including the following: - CPU and memory resources set on each type of InfluxDB pod - The number of pods in each InfluxDB StatefulSet and Deployment - The type of object store used and how it is hosted -- How the Catalog (PostgreSQL-compatible database) is hosted -- Indicate if either the Object store or the Catalog is shared by more than one InfluxDB +- How the Catalog store (PostgreSQL-compatible database) is hosted +- Indicate if either the Object store or the Catalog store is shared by more than one InfluxDB Clustered product - If so, describe the network-level topology of your setup diff --git a/content/influxdb3/clustered/reference/internals/storage-engine.md b/content/influxdb3/clustered/reference/internals/storage-engine.md index 2feb8006d..bae8c0e33 100644 --- a/content/influxdb3/clustered/reference/internals/storage-engine.md +++ b/content/influxdb3/clustered/reference/internals/storage-engine.md @@ -53,15 +53,6 @@ protocol and then routes it to [Ingesters](#ingester). To ensure write durability, the Router replicates data to two or more of the available Ingesters. -##### Router scaling strategies - -The Router can be scaled both [vertically](/influxdb3/clustered/admin/scale-cluster/#vertical-scaling) -and [horizontally](/influxdb3/clustered/admin/scale-cluster/#horizontal-scaling). -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 -parse incoming line protocol with lower latency. - ### Ingester The Ingester processes line protocol submitted in write requests and persists @@ -82,13 +73,6 @@ In this process, the Ingester does the following: - Maintains a short-term [write-ahead log (WAL)](/influxdb3/clustered/reference/internals/durability/) to prevent data loss in case of a service interruption. -##### Ingester scaling strategies - -The Ingester can be scaled both [vertically](/influxdb3/clustered/admin/scale-cluster/#vertical-scaling) -and [horizontally](/influxdb3/clustered/admin/scale-cluster/#horizontal-scaling). -Vertical scaling increases write throughput and is typically the most -effective scaling strategy for the Ingester. - ### Querier The Querier handles query requests and returns query results for requests. @@ -106,7 +90,8 @@ At query time, the querier: - include recently written, [yet-to-be-persisted](/influxdb3/clustered/reference/internals/durability/#data-ingest) data in query results -3. Queries the [Catalog](#catalog) to find partitions in the [Object store](#object-store) +3. Queries the [Catalog service](#catalog-service) to retrieve [Catalog store](#catalog-store) + information about partitions in the [Object store](#object-store) that contain the queried data. 4. Reads partition Parquet files that contain the queried data and scans each row to filter data that matches predicates in the query plan. @@ -114,32 +99,30 @@ At query time, the querier: specified in the query plan. 6. Returns the query result to the client. -##### Querier scaling strategies - -The Querier can be scaled both [vertically](/influxdb3/clustered/admin/scale-cluster/#vertical-scaling) -and [horizontally](/influxdb3/clustered/admin/scale-cluster/#horizontal-scaling). -Horizontal scaling increases query throughput to handle more concurrent queries. -Vertical scaling improves the Querier's ability to process computationally -intensive queries. - ### Catalog -The Catalog is a PostgreSQL-compatible relational database that stores metadata +InfluxDB's catalog system consists of two distinct components: the [Catalog store](#catalog-store) +and the [Catalog service](#catalog-service). + +> [!Note] +> The Catalog service is managed through the `AppInstance` resource, while the Catalog store +> is managed separately according to your PostgreSQL implementation. + +#### Catalog store + +The Catalog store is a PostgreSQL-compatible relational database that stores metadata related to your time series data including schema information and physical locations of partitions in the [Object store](#object-store). It fulfills the following roles: - Provides information about the schema of written data. - Tells the [Ingester](#ingester) what partitions to persist data to. -- Tells the [Querier](#querier) what partitions contain the queried data. +- Tells the [Querier](#querier) what partitions contain the queried data. -##### Catalog scaling strategies +#### Catalog service -Scaling strategies available for the Catalog depend on the PostgreSQL-compatible -database used to run the catalog. All support -[vertical scaling](/influxdb3/clustered/admin/scale-cluster/#vertical-scaling). -Most support [horizontal scaling](/influxdb3/clustered/admin/scale-cluster/#horizontal-scaling) -for redundancy and failover. +The Catalog service (iox-shared-catalog statefulset) is an IOx component that caches +and manages access to the Catalog store. ### Object store @@ -149,39 +132,14 @@ By default, InfluxDB partitions tables by day, but you can [customize the partitioning strategy](/influxdb3/clustered/admin/custom-partitions/). Data in each Parquet file is sorted, encoded, and compressed. -##### Object store scaling strategies - -Scaling strategies available for the Object store depend on the underlying -object storage services used to run the object store. -Most support [horizontal scaling](/influxdb3/clustered/admin/scale-cluster/#horizontal-scaling) -for redundancy, failover, and increased capacity. - ### Compactor The Compactor processes and compresses partitions in the [Object store](#object-store) to continually optimize storage. It then updates the [Catalog](#catalog) with locations of compacted data. -##### Compactor scaling strategies - -The Compactor can be scaled both [vertically](/influxdb3/clustered/admin/scale-cluster/#vertical-scaling) -and [horizontally](/influxdb3/clustered/admin/scale-cluster/#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 efficiently as -vertical scaling. - ### Garbage collector The Garbage collector runs background jobs that evict expired or deleted data, remove obsolete compaction files, and reclaim space in both the [Catalog](#catalog) and the [Object store](#object-store). - -##### Garbage collector scaling strategies - - -The Garbage collector is not designed for distributed load and should _not_ be -scaled horizontally. The Garbage collector does not perform CPU- or -memory-intensive work, so [vertical scaling](/influxdb3/clustered/admin/scale-cluster/#vertical-scaling) -should only be considered only if you observe very high CPU usage or -if the container regularly runs out of memory. diff --git a/content/influxdb3/clustered/reference/release-notes/clustered.md b/content/influxdb3/clustered/reference/release-notes/clustered.md index 200496b09..b330a6227 100644 --- a/content/influxdb3/clustered/reference/release-notes/clustered.md +++ b/content/influxdb3/clustered/reference/release-notes/clustered.md @@ -50,7 +50,7 @@ Prometheus CPU limit was set to an integer instead of a string. #### Database Engine - Upgrade DataFusion -- Add the ability to restore a cluster from a Catalog snapshot. +- Add the ability to restore a cluster from a Catalog store snapshot. --- diff --git a/content/influxdb3/clustered/write-data/best-practices/data-lifecycle.md b/content/influxdb3/clustered/write-data/best-practices/data-lifecycle.md index c8ee1c0bc..cfa992379 100644 --- a/content/influxdb3/clustered/write-data/best-practices/data-lifecycle.md +++ b/content/influxdb3/clustered/write-data/best-practices/data-lifecycle.md @@ -34,15 +34,15 @@ InfluxDB cluster. ## Tune garbage collection Once data falls outside of a database's retention period, the garbage collection -service can remove all artifacts associated with the data from the Catalog and Object store. +service can remove all artifacts associated with the data from the Catalog store and Object store. Tune the garbage collector cutoff period to ensure that data is removed in a timely manner. Use the following environment variables to tune the garbage collector: - `INFLUXDB_IOX_GC_OBJECTSTORE_CUTOFF`: the age at which Parquet files not - referenced in the Catalog become eligible for deletion from Object storage. + referenced in the Catalog store become eligible for deletion from Object storage. The default is `30d`. -- `INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF`: how long to retain rows in the Catalog +- `INFLUXDB_IOX_GC_PARQUETFILE_CUTOFF`: how long to retain rows in the Catalog store that reference Parquet files marked for deletion. The default is `30d`. These values tune how aggressive the garbage collector can be. A shorter duration @@ -69,7 +69,7 @@ Use the following scenarios as a guide for different use cases: When only the most recent data is important and backups are not required, use a very low cutoff point for the garbage collector. Using a low value means that the garbage collection service will promptly delete -files from the Object store and remove rows associated rows from the Catalog. +files from the Object store and remove associated rows from the Catalog store. This results in a lean Catalog with lower operational overhead and less files in the Object store. @@ -102,8 +102,8 @@ Object store (provided by your object store provider), use a low cutoff point for the garbage collector service. Your object versioning policy ensures expired files are kept for the specified backup window time. -Object versioning maintains Parquet files in Objects storage after data expires, -but allows the Catalog to remove references to the Parquet files. +Object versioning maintains Parquet files in Object storage after data expires, +but allows the Catalog store to remove references to the Parquet files. Non-current objects should be configured to be expired as soon as possible, but retained long enough to satisfy your organization's backup policy. @@ -157,7 +157,7 @@ If you cannot make use of object versioning policies but still requires a backup window, configure the garbage collector to retain Parquet files for as long as your backup period requires. -This will likely result in higher operational costs as the Catalog maintains +This will likely result in higher operational costs as the Catalog store maintains more references to associated Parquet files and the Parquet files persist for longer in the Object store. From 89ae11464b73e18b8d379ef905162d8cd5ca4e57 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 13 Mar 2025 14:04:45 -0500 Subject: [PATCH 2/2] chore(clustered): Component scaling recommendations: Add suggestions from @reidkaufmann in https://github.com/influxdata/DAR/issues/472 --- .../clustered/admin/scale-cluster.md | 78 ++++++++++++------- .../reference/internals/storage-engine.md | 31 ++++---- 2 files changed, 67 insertions(+), 42 deletions(-) diff --git a/content/influxdb3/clustered/admin/scale-cluster.md b/content/influxdb3/clustered/admin/scale-cluster.md index 2027c8799..f28faece3 100644 --- a/content/influxdb3/clustered/admin/scale-cluster.md +++ b/content/influxdb3/clustered/admin/scale-cluster.md @@ -466,19 +466,29 @@ helm upgrade \ ### 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 @@ -541,50 +551,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 is not designed for distributed load and should _not_ be -scaled horizontally. It is a lightweight process that typically doesn't require -significant system resources. [Vertical scaling](#vertical-scaling) should only -be considered if you observe consistently high CPU usage or if the container +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 -The Catalog store is a PostgreSQL-compatible database that persistently stores metadata. -Scaling strategies depend on your chosen PostgreSQL implementation. -All support [vertical scaling](#vertical-scaling), and most support -[horizontal scaling](#horizontal-scaling) for redundancy and failover. +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 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 should maintain exactly -3 replicas for optimal redundancy. -Additional replicas are discouraged; favor vertical scaling instead if performance improvements are needed. +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. diff --git a/content/influxdb3/clustered/reference/internals/storage-engine.md b/content/influxdb3/clustered/reference/internals/storage-engine.md index bae8c0e33..32fd3bd9c 100644 --- a/content/influxdb3/clustered/reference/internals/storage-engine.md +++ b/content/influxdb3/clustered/reference/internals/storage-engine.md @@ -50,8 +50,13 @@ queries, and is optimized to reduce storage cost. The Router (also known as the Ingest Router) parses incoming line protocol and then routes it to [Ingesters](#ingester). -To ensure write durability, the Router replicates data to two or more of the -available Ingesters. +The Router processes incoming write requests through the following steps: + +- Queries the [Catalog](#catalog) to determine persistence locations and verify schema compatibility +- Validates syntax and schema compatibility for each data point in the request, +and either accepts or [rejects points](/influxdb3/clustered/write-data/troubleshoot/#troubleshoot-rejected-points) +- Returns a [response](/influxdb3/clustered/write-data/troubleshoot/) to the client +- Replicates data to two or more available Ingesters for write durability ### Ingester @@ -59,11 +64,6 @@ The Ingester processes line protocol submitted in write requests and persists time series data to the [Object store](#object-store). In this process, the Ingester does the following: -- Queries the [Catalog](#catalog) to identify where data should be persisted and - to ensure the schema of the line protocol is compatible with the - [schema](/influxdb3/clustered/reference/glossary/#schema) of persisted data. -- Accepts or [rejects](/influxdb3/clustered/write-data/troubleshoot/#troubleshoot-rejected-points) - points in the write request and generates a [response](/influxdb3/clustered/write-data/troubleshoot/). - Processes line protocol and persists time series data to the [Object store](#object-store) in Apache Parquet format. Each Parquet file represents a _partition_--a logical grouping of data. @@ -93,11 +93,12 @@ At query time, the querier: 3. Queries the [Catalog service](#catalog-service) to retrieve [Catalog store](#catalog-store) information about partitions in the [Object store](#object-store) that contain the queried data. -4. Reads partition Parquet files that contain the queried data and scans each +4. Retrieves any needed Parquet files (not already cached) from the Object store. +5. Reads partition Parquet files that contain the queried data and scans each row to filter data that matches predicates in the query plan. -5. Performs any additional operations (for example: deduplicating, merging, and sorting) - specified in the query plan. -6. Returns the query result to the client. +6. Performs any additional operations (for example: deduplicating, merging, and sorting) + specified in the query plan. +7. Returns the query result to the client. ### Catalog @@ -105,6 +106,8 @@ InfluxDB's catalog system consists of two distinct components: the [Catalog stor and the [Catalog service](#catalog-service). > [!Note] +> #### Managing Catalog components +> > The Catalog service is managed through the `AppInstance` resource, while the Catalog store > is managed separately according to your PostgreSQL implementation. @@ -127,10 +130,10 @@ and manages access to the Catalog store. ### Object store The Object store contains time series data in [Apache Parquet](https://parquet.apache.org/) format. -Each Parquet file represents a partition. -By default, InfluxDB partitions tables by day, but you can -[customize the partitioning strategy](/influxdb3/clustered/admin/custom-partitions/). Data in each Parquet file is sorted, encoded, and compressed. +A partition may contain multiple parquet files which are subject to compaction. +By default, InfluxDB partitions tables by day, but you can +[customize the partitioning strategy](/influxdb3/clustered/admin/custom-partitions/) ### Compactor