docs: use revision-based etcd auto compaction

docs/faq-and-others/faq.md

@@ -231,6 +231,23 @@ That said, **etcd remains fully supported and actively maintained**. It is not d
 
 The decision ultimately comes down to your team's skill set and existing infrastructure. See [Metadata Storage Configuration](/user-guide/deployments-administration/manage-metadata/configuration.md) for setup instructions for each backend.
 
+### What should I do if etcd reports `NOSPACE`?
+
+`NOSPACE` means etcd has reached its backend storage quota. A common cause is retaining too many historical versions because automatic compaction is disabled or its retention is too long. Frequent `ALTER TABLE` requests repeatedly update table metadata (table info), accumulating historical values even when the number of tables stays unchanged.
+
+GreptimeDB does not need these historical versions to look back at table metadata. For the Bitnami etcd Helm chart, use revision-based auto compaction:
+
+```yaml
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
+```
+
+Every 5 minutes, etcd compacts up to `current revision - 100`. See [Manage etcd](/user-guide/deployments-administration/manage-metadata/manage-etcd.md#install) for the full configuration.
+
+If `NOSPACE` has already occurred, compact old revisions, [defragment the database](https://etcd.io/docs/v3.6/op-guide/maintenance/#defragmentation) to reclaim disk space, and disarm the alarm after usage falls below the quota. If current data alone approaches the quota, review capacity as well.
+
+For production deployments, prefer managed MySQL or PostgreSQL (RDS) for metadata storage. This avoids etcd-specific `NOSPACE` errors caused by retaining too many historical versions and reduces maintenance work such as configuring auto compaction and running defragmentation. See [Metadata Storage Configuration](/user-guide/deployments-administration/manage-metadata/configuration.md) for setup instructions.
+
 ### How do I manage GreptimeDB?
 
 GreptimeDB uses **standard SQL as its management interface**. You can [create tables](/user-guide/deployments-administration/manage-data/basic-table-operations.md), [alter schemas](/reference/sql/alter.md), set [TTL policies](/user-guide/manage-data/overview.md#manage-data-retention-with-ttl-policies), and configure [indexes](/user-guide/manage-data/data-index.md) — all through SQL. No config files to write, no proprietary APIs to call.

docs/user-guide/deployments-administration/manage-metadata/manage-etcd.md

@@ -47,8 +47,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -59,6 +59,8 @@ extraEnvVars:
     value: "10000"
 ```
 
+This configuration uses revision-based auto compaction. Every 5 minutes, etcd checks the current revision and compacts up to `current revision - 100`. The retained history window depends on the write rate; clients that read or watch older revisions must handle compaction errors. Compaction makes space available for reuse within etcd; reclaiming disk space requires defragmentation.
+
 Install etcd cluster:
 
 ```bash
@@ -144,8 +146,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -276,8 +278,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -385,8 +387,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -473,8 +475,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES

i18n/zh/docusaurus-plugin-content-docs/current/faq-and-others/faq.md

@@ -231,6 +231,23 @@ GreptimeDB 的 metasrv 组件支持 etcd、MySQL 和 PostgreSQL 作为元数据
 
 最终取决于团队的技术栈和已有基础设施。各后端的配置方式参见[元数据存储配置](/user-guide/deployments-administration/manage-metadata/configuration.md)。
 
+### 使用 etcd 时遇到 `NOSPACE` 错误怎么办？
+
+`NOSPACE` 表示 etcd 的后端数据库已达到空间配额。常见原因是未开启自动压缩（compaction），或历史版本保留过多。例如，大量 `ALTER TABLE` 请求会反复更新表元数据（table info），即使表的数量没有增加，也会积累大量历史版本。
+
+GreptimeDB 不需要通过这些历史版本回溯表元数据。使用 Bitnami 的 etcd Helm chart 时，建议配置基于 revision 的自动压缩：
+
+```yaml
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
+```
+
+etcd 每 5 分钟压缩至 `当前 revision - 100`。完整配置参见[管理 etcd](/user-guide/deployments-administration/manage-metadata/manage-etcd.md#安装)。
+
+如果已触发 `NOSPACE`，需要压缩历史版本、进行[碎片整理（defragmentation）](https://etcd.io/docs/v3.6/op-guide/maintenance/#defragmentation)以回收磁盘空间，并在空间占用降至配额以下后解除告警。如果当前有效数据本身已接近配额，还需要评估容量。
+
+生产环境建议优先使用托管 MySQL 或 PostgreSQL（RDS）作为元数据存储，避免 etcd 因保留过多历史版本而触发 `NOSPACE`，同时减少自动压缩和碎片整理等维护工作。配置方式参见[元数据存储配置](/user-guide/deployments-administration/manage-metadata/configuration.md)。
+
 ### 如何管理 GreptimeDB？
 
 GreptimeDB 使用**标准 SQL 作为管理接口**。你可以通过 SQL 完成[表的基本操作如建表删表](/user-guide/deployments-administration/manage-data/basic-table-operations.md)、[修改 Schema](/reference/sql/alter.md)、设置 [TTL 策略](/user-guide/manage-data/overview.md#使用-ttl-策略保留数据)、配置[索引](/user-guide/manage-data/data-index.md)等操作，不用写配置文件，也不用调专有 API。

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-metadata/manage-etcd.md

@@ -47,8 +47,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -59,6 +59,8 @@ extraEnvVars:
     value: "10000"
 ```
 
+此配置使用基于 revision 的自动压缩。etcd 每 5 分钟检查一次当前 revision，并压缩至 `当前 revision - 100`。保留的历史时间窗口取决于写入速率；读取或监听旧 revision 的客户端需要处理历史版本已被压缩的错误。压缩释放的空间可供 etcd 内部复用；要回收磁盘空间，还需要进行碎片整理（defragmentation）。
+
 安装 etcd 集群:
 
 ```bash
@@ -144,8 +146,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -276,8 +278,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -385,8 +387,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -473,8 +475,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES

i18n/zh/docusaurus-plugin-content-docs/version-1.2/faq-and-others/faq.md

@@ -225,6 +225,23 @@ GreptimeDB 的 metasrv 组件支持 etcd、MySQL 和 PostgreSQL 作为元数据
 
 最终取决于团队的技术栈和已有基础设施。各后端的配置方式参见[元数据存储配置](/user-guide/deployments-administration/manage-metadata/configuration.md)。
 
+### 使用 etcd 时遇到 `NOSPACE` 错误怎么办？
+
+`NOSPACE` 表示 etcd 的后端数据库已达到空间配额。常见原因是未开启自动压缩（compaction），或历史版本保留过多。例如，大量 `ALTER TABLE` 请求会反复更新表元数据（table info），即使表的数量没有增加，也会积累大量历史版本。
+
+GreptimeDB 不需要通过这些历史版本回溯表元数据。使用 Bitnami 的 etcd Helm chart 时，建议配置基于 revision 的自动压缩：
+
+```yaml
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
+```
+
+etcd 每 5 分钟压缩至 `当前 revision - 100`。完整配置参见[管理 etcd](/user-guide/deployments-administration/manage-metadata/manage-etcd.md#安装)。
+
+如果已触发 `NOSPACE`，需要压缩历史版本、进行[碎片整理（defragmentation）](https://etcd.io/docs/v3.6/op-guide/maintenance/#defragmentation)以回收磁盘空间，并在空间占用降至配额以下后解除告警。如果当前有效数据本身已接近配额，还需要评估容量。
+
+生产环境建议优先使用托管 MySQL 或 PostgreSQL（RDS）作为元数据存储，避免 etcd 因保留过多历史版本而触发 `NOSPACE`，同时减少自动压缩和碎片整理等维护工作。配置方式参见[元数据存储配置](/user-guide/deployments-administration/manage-metadata/configuration.md)。
+
 ### 如何管理 GreptimeDB？
 
 GreptimeDB 使用**标准 SQL 作为管理接口**。你可以通过 SQL 完成[表的基本操作如建表删表](/user-guide/deployments-administration/manage-data/basic-table-operations.md)、[修改 Schema](/reference/sql/alter.md)、设置 [TTL 策略](/user-guide/manage-data/overview.md#使用-ttl-策略保留数据)、配置[索引](/user-guide/manage-data/data-index.md)等操作，不用写配置文件，也不用调专有 API。

i18n/zh/docusaurus-plugin-content-docs/version-1.2/user-guide/deployments-administration/manage-metadata/manage-etcd.md

@@ -47,8 +47,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -59,6 +59,8 @@ extraEnvVars:
     value: "10000"
 ```
 
+此配置使用基于 revision 的自动压缩。etcd 每 5 分钟检查一次当前 revision，并压缩至 `当前 revision - 100`。保留的历史时间窗口取决于写入速率；读取或监听旧 revision 的客户端需要处理历史版本已被压缩的错误。压缩释放的空间可供 etcd 内部复用；要回收磁盘空间，还需要进行碎片整理（defragmentation）。
+
 安装 etcd 集群:
 
 ```bash
@@ -144,8 +146,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -276,8 +278,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -385,8 +387,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -473,8 +475,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES

versioned_docs/version-1.2/faq-and-others/faq.md

@@ -225,6 +225,23 @@ That said, **etcd remains fully supported and actively maintained**. It is not d
 
 The decision ultimately comes down to your team's skill set and existing infrastructure. See [Metadata Storage Configuration](/user-guide/deployments-administration/manage-metadata/configuration.md) for setup instructions for each backend.
 
+### What should I do if etcd reports `NOSPACE`?
+
+`NOSPACE` means etcd has reached its backend storage quota. A common cause is retaining too many historical versions because automatic compaction is disabled or its retention is too long. Frequent `ALTER TABLE` requests repeatedly update table metadata (table info), accumulating historical values even when the number of tables stays unchanged.
+
+GreptimeDB does not need these historical versions to look back at table metadata. For the Bitnami etcd Helm chart, use revision-based auto compaction:
+
+```yaml
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
+```
+
+Every 5 minutes, etcd compacts up to `current revision - 100`. See [Manage etcd](/user-guide/deployments-administration/manage-metadata/manage-etcd.md#install) for the full configuration.
+
+If `NOSPACE` has already occurred, compact old revisions, [defragment the database](https://etcd.io/docs/v3.6/op-guide/maintenance/#defragmentation) to reclaim disk space, and disarm the alarm after usage falls below the quota. If current data alone approaches the quota, review capacity as well.
+
+For production deployments, prefer managed MySQL or PostgreSQL (RDS) for metadata storage. This avoids etcd-specific `NOSPACE` errors caused by retaining too many historical versions and reduces maintenance work such as configuring auto compaction and running defragmentation. See [Metadata Storage Configuration](/user-guide/deployments-administration/manage-metadata/configuration.md) for setup instructions.
+
 ### How do I manage GreptimeDB?
 
 GreptimeDB uses **standard SQL as its management interface**. You can [create tables](/user-guide/deployments-administration/manage-data/basic-table-operations.md), [alter schemas](/reference/sql/alter.md), set [TTL policies](/user-guide/manage-data/overview.md#manage-data-retention-with-ttl-policies), and configure [indexes](/user-guide/manage-data/data-index.md) — all through SQL. No config files to write, no proprietary APIs to call.

versioned_docs/version-1.2/user-guide/deployments-administration/manage-metadata/manage-etcd.md

@@ -47,8 +47,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -59,6 +59,8 @@ extraEnvVars:
     value: "10000"
 ```
 
+This configuration uses revision-based auto compaction. Every 5 minutes, etcd checks the current revision and compacts up to `current revision - 100`. The retained history window depends on the write rate; clients that read or watch older revisions must handle compaction errors. Compaction makes space available for reuse within etcd; reclaiming disk space requires defragmentation.
+
 Install etcd cluster:
 
 ```bash
@@ -144,8 +146,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -276,8 +278,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -385,8 +387,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES
@@ -473,8 +475,8 @@ resources:
     cpu: '2'
     memory: 8Gi
 
-autoCompactionMode: "periodic"
-autoCompactionRetention: "1h"
+autoCompactionMode: "revision"
+autoCompactionRetention: "100"
 
 extraEnvVars:
   - name: ETCD_QUOTA_BACKEND_BYTES