版本：Nightly

常见 Helm Chart 配置项

对于每一个 Helm Chart，你都可以通过创建 values.yaml 来进行配置。当你需要应用配置时，你可以通过 helm upgrade 命令来应用配置：

helm upgrade --install ${release-name} ${chart-name} --namespace ${namespace} -f values.yaml

GreptimeDB Cluster Chart

完整的配置项可参考 GreptimeDB Cluster Chart。

GreptimeDB 运行镜像配置

顶层变量 image 用于配置集群全局的运行镜像，如下所示：

image:
  # -- The image registry
  registry: greptime-registry.cn-hangzhou.cr.aliyuncs.com
  # -- The image repository
  repository: greptime/greptimedb
  # -- The image tag
  tag: "v1.3.0-nightly-20260824"
  # -- The image pull secrets
  pullSecrets: []

如果你想为集群中的每个 Role 配置不同的镜像，可以使用 ${role}.podTemplate.main.image 字段（其中 role 可以是 meta、frontend、datanode 和 flownode），该字段会覆盖顶层变量 image 的配置，如下所示：

image:
  # -- The image registry
  registry: greptime-registry.cn-hangzhou.cr.aliyuncs.com
  # -- The image repository
  repository: greptime/greptimedb
  # -- The image tag
  tag: "v1.3.0-nightly-20260824"
  # -- The image pull secrets
  pullSecrets: []

frontend:
  podTemplate:
    main:
      image: "greptime-registry.cn-hangzhou.cr.aliyuncs.com/greptime/greptimedb:latest"

此时 frontend 的镜像将会被设置为 greptime-registry.cn-hangzhou.cr.aliyuncs.com/greptime/greptimedb:latest，而其他组件的镜像将会使用顶层变量 image 的配置。

服务端口配置

你可以使用如下字段来配置服务端口，如下所示：

httpServicePort：用于配置 HTTP 服务的端口，默认 4000；
grpcServicePort：用于配置 gRPC 服务的端口，默认 4001；
mysqlServicePort：用于配置 MySQL 服务的端口，默认 4002；
postgresServicePort：用于配置 PostgreSQL 服务的端口，默认 4003；
frontend.internalPort：用于配置内部服务的端口，默认 4010，此端口用于 GreptimeDB 组件之间的内部通信。

Datanode 存储配置

你可以通过 datanode.storage 字段来配置 Datanode 的存储，如下所示：

datanode:
  storage:
    # -- Storage class for datanode persistent volume
    storageClassName: null
    # -- Storage size for datanode persistent volume
    storageSize: 20Gi
    # -- Storage retain policy for datanode persistent volume
    storageRetainPolicy: Retain
    # -- The dataHome directory, default is "/data/greptimedb/"
    dataHome: "/data/greptimedb"

storageClassName：用于配置 StorageClass，默认使用 Kubernetes 当前默认的 StorageClass；
storageSize：用于配置 Storage 的大小，默认 20Gi。你可以使用常用的容量单位，如 50Gi 等；
storageRetainPolicy：用于配置 Storage 的保留策略，默认 Retain，如果设置为 Delete，则当集群被删除时，相应的 Storage 也会被删除；
dataHome：用于配置数据目录，默认 /data/greptimedb/；

运行资源配置

顶层变量 base.podTemplate.main.resources 用于全局配置每个 Role 的资源，如下所示：

base:
  podTemplate:
    main:
      resources:
        requests:
          memory: "1Gi"
          cpu: "1"
        limits:
          memory: "2Gi"
          cpu: "2"

如果你想为集群中的每个 Role 配置不同的资源，可以使用 ${role}.podTemplate.main.resources 字段（其中 role 可以是 meta、frontend、datanode、flownode, 等），该字段会覆盖顶层变量 base.podTemplate.main.resources 的配置，如下所示：

base:
  podTemplate:
    main:
      resources:
        requests:
          memory: "1Gi"
          cpu: "1"
        limits:
          memory: "2Gi"
          cpu: "2"

frontend:
  podTemplate:
    main:
      resources:
        requests:
          cpu: "2"
          memory: "4Gi"
        limits:
          cpu: "4"
          memory: "8Gi"

服务运行副本数配置

对于不同 Role 的副本数，可以通过 ${role}.replicas 字段进行配置对应的副本数，如下所示：

frontend:
  replicas: 3

datanode:
  replicas: 3

你可以通过配置其副本数来实现水平扩缩。

环境变量配置

你既可以通过 base.podTemplate.main.env 字段配置全局的环境变量，也可以通过 ${role}.podTemplate.main.env 字段为每个 Role 配置不同的环境变量，如下所示：

base:
  podTemplate:
    main:
      env:
        - name: GLOBAL_ENV
          value: "global_value"

frontend:
  podTemplate:
    main:
      env:
        - name: FRONTEND_ENV
          value: "frontend_value"

注入配置文件

对于不同 Role 的服务，你可以通过 ${role}.configData 字段注入自定义的 TOML 配置文件，如下所示：

datanode:
  configData: |
    [[region_engine]]
    [region_engine.mito]
    # Number of region workers
    num_workers = 8

你可以通过 config.md 了解 GreptimeDB 的配置项。

除了使用 ${role}.configData 字段注入配置文件，你还可以通过 ${role}.configFile 来指定相应的文件，如下所示：

frontend:
  configFile: "configs/frontend.toml"

此时需要确保对应的配置文件路径与执行 helm upgrade 命令时所处的目录一致。

备注

用户注入的配置文件默认优先级低于由 GreptimeDB Operator 所接管的配置项，某些配置项仅能通过 GreptimeDB Operator 进行配置，而这些配置项默认会暴露在 values.yaml 中。

如下默认配置将由 GreptimeDB Operator 管理：

Logging 配置；
Datanode 的 Node ID；

鉴权配置

Helm Chart 默认不启用 User Provider 模式的鉴权，你可以通过 auth.enabled 字段启用 User Provider 模式的鉴权并配置相应的用户信息，如下所示：

auth:
  enabled: true
  users:
    - username: "admin"
      password: "admin"
      permission: "readwrite"
    - username: "grafana"
      password: "grafana_pwd"
      permission: "readonly"
    - username: "telegraf"
      password: "telegraf_pwd"
      permission: "writeonly"

GreptimeDB 支持三种权限模式：

模式	缩写	允许的操作	典型场景
`readwrite`	`rw`	读取 + 写入	管理员、开发环境
`readonly`	`ro`	仅读取	仪表盘、报表系统、只读副本
`writeonly`	`wo`	仅写入	数据采集器、IoT 设备、日志收集

备注

未指定权限模式的用户默认拥有 readwrite 权限，与此前版本行为一致。

日志配置

顶层变量 logging 用于配置全局日志级别，如下所示：

# -- Global logging configuration
logging:
  # -- The log level for greptimedb, only support "debug", "info", "warn", "debug"
  level: "info"

  # -- The log format for greptimedb, only support "json" and "text"
  format: "text"

  # -- The logs directory for greptimedb
  logsDir: "/data/greptimedb/logs"

  # -- Whether to log to stdout only
  onlyLogToStdout: false

  # -- indicates whether to persist the log with the datanode data storage. It **ONLY** works for the datanode component.
  persistentWithData: false

  # -- The log filters, use the syntax of `target[span\{field=value\}]=level` to filter the logs.
  filters: []

其中：

logging.level：用于配置全局日志级别，支持 debug、info、warn、error 四个级别；
logging.format：用于配置全局日志格式，支持 json 和 text 两种格式；
logging.logsDir：用于配置全局日志目录，默认位于 /data/greptimedb/logs；
logging.onlyLogToStdout：用于配置是否仅输出到标准输出，默认不启用；
logging.persistentWithData：用于配置是否将日志持久化到数据存储，仅适用于 datanode 组件，默认不启用；
logging.filters：用于配置全局日志过滤器，支持 target[span\{field=value\}]=level 的语法，特步地，如果你希望对某些组件启动 debug 级别的日志，可以配置如下：
```
logging:
  level: "info"
  format: "json"
  filters:
  - mito2=debug
```

每一个 Role 的日志配置都可以通过 ${role}.logging 字段进行配置，其字段与顶层 logging 一致，并会覆盖顶层变量 logging 的配置，比如：

frontend:
  logging:
    level: "debug"

启用 Flownode

Helm Chart 默认不启用 Flownode，你可以通过 flownode.enabled 字段启用 Flownode，如下所示：

flownode:
  enabled: true

flownode 的其他字段的配置与其他 Role 的配置一致，比如：

flownode:
  enabled: true
  replicas: 1
  podTemplate:
    main:
      resources:
        requests:
          memory: "1Gi"
          cpu: "1"
        limits:
          memory: "2Gi"
          cpu: "2"

对象存储配置

objectStorage 字段用于配置云对象存储（例如 AWS S3 和 Azure Blob Storage 等）作为 GreptimeDB 存储层。

AWS S3

objectStorage:
  credentials:
    # AWS access key ID
    accessKeyId: ""
    # AWS secret access key
    secretAccessKey: ""
  s3:
    # AWS S3 bucket name
    bucket: ""
    # AWS S3 region
    region: ""
    # The root path in bucket is 's3://<bucket>/<root>/data/...'
    root: ""
    # The AWS S3 endpoint, see more detail: https://docs.aws.amazon.com/general/latest/gr/s3.html
    endpoint: ""

使用 IAM Roles for Service Accounts（IRSA）访问 S3

除了提供静态访问密钥外，你还可以使用 IAM Roles for Service Accounts（IRSA）来授予 GreptimeDB 访问 S3 的权限。这种方式更加安全，因为无需管理长期有效的凭证。

IRSA 与 EKS Pod Identity 是两种不同的机制。下面这份配置属于 IRSA，通过在 Service Account 上标注 role ARN 完成授权；Pod Identity 则需要建立 pod identity association，并不使用该注解。

首先，为 datanode 的 Service Account 配置 IAM 角色注解。只有 datanode 会读写 S3：

datanode:
  podTemplate:
    serviceAccount:
      create: true
      annotations:
        eks.amazonaws.com/role-arn: ${YOUR_IAM_ROLE_ARN}

请确保 IAM 角色具有对目标 S3 存储桶的读写权限：

s3:PutObject
s3:ListBucket
s3:GetObject
s3:DeleteObject

然后，配置对象存储时无需填写凭证：

objectStorage:
  s3:
    bucket: "${YOUR_S3_BUCKET}"
    region: "${YOUR_S3_REGION}"
    root: "greptimedb"

备注

使用 IRSA 时，请完全省略 objectStorage.credentials 部分。datanode Pod 将通过与 Service Account 关联的 IAM 角色自动获取临时凭证。

Google Cloud Storage

objectStorage:
  credentials:
    # GCP serviceAccountKey JSON-formatted base64 value 
    serviceAccountKey: ""
  gcs:
    # Google Cloud Storage bucket name
    bucket: ""
    # Google Cloud OAuth 2.0 Scopes, example: "https://www.googleapis.com/auth/devstorage.read_write"
    scope: ""
    # The root path in bucket is 'gcs://<bucket>/<root>/data/...'
    root: ""
    # Google Cloud Storage endpoint, example: "https://storage.googleapis.com"
    endpoint: ""

Azure Blob

objectStorage:
  credentials:
    # Azure account name
    accountName: ""
    # Azure account key
    accountKey: ""
  azblob:
    # Azure Blob container name
    container: ""
    # The root path in container is 'blob://<bucket>/<root>/data/...'
    root: ""
    # Azure Blob endpoint, see: "https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-query-endpoint-srp?tabs=dotnet#query-for-the-blob-storage-endpoint"
    endpoint: ""

AliCloud OSS

objectStorage:
  credentials:
    # AliCloud access key ID
    accessKeyId: ""
    # AliCloud access key secret
    accessKeySecret: ""
  oss:
    # AliCloud OSS bucket name
    bucket: ""
    # AliCloud OSS region
    region: ""
    # The root path in bucket is 'oss://<bucket>/<root>/data/...'
    root: ""
    # The AliCloud OSS endpoint
    endpoint: ""

Volcengine TOS

TOS (Torch Object Storage) 是火山引擎提供的海量、安全、低成本、易用、高可靠、高可用的对象存储服务。

objectStorage:
  credentials:
    # Volcengine access key ID
    accessKeyId: ""
    # Volcengine secret access key
    secretAccessKey: ""
  s3:
    # Volcengine TOS bucket name
    bucket: ""
    # Volcengine TOS region
    region: ""
    # The root path in bucket is 'tos://<bucket>/<root>/data/...'
    root: ""
    # The Volcengine TOS endpoint, see more detail: https://www.volcengine.com/docs/6349/107356
    endpoint: ""
    # Enable virtual host style so that OpenDAL will send API requests in virtual host style instead of path style.
    enableVirtualHostStyle: true

Prometheus 监控配置

如果你已经安装了 prometheus-operator，你可以通过 prometheusMonitor.enabled 字段创建 Prometheus PodMonitor 来监控 GreptimeDB，如下所示：

prometheusMonitor:
  # -- Create PodMonitor resource for scraping metrics using PrometheusOperator
  enabled: false
  # -- Interval at which metrics should be scraped
  interval: "30s"
  # -- Add labels to the PodMonitor
  labels:
    release: prometheus

Debug Pod 配置

debug pod 中安装了各种工具（例如 mysql-client、psql-client 等）。你可以 exec 进入调试 debug pod 进行调试。使用 debugPod.enabled 字段创建它，如下所示：

debugPod:
  # -- Enable debug pod
  enabled: false

  # -- The debug pod image
  image:
    registry: docker.io
    repository: greptime/greptime-tool
    tag: "20250606-04e3c7d"

  # -- The debug pod resource
  resources:
    requests:
      memory: 64Mi
      cpu: 50m
    limits:
      memory: 256Mi
      cpu: 200m

配置 Metasrv 后端存储

使用 MySQL 和 PostgreSQL 作为后端存储

你可以通过 meta.backendStorage 字段配置 Metasrv 的后端存储。

以 MySQL 为例。

meta:
  backendStorage:
    mysql:
      # -- MySQL host
      host: "mysql.default.svc.cluster.local"
      # -- MySQL port
      port: 3306
      # -- MySQL database
      database: "metasrv"
      # -- MySQL table
      table: "greptime_metakv"
      # -- MySQL credentials
      credentials:
        # -- MySQL credentials secret name
        secretName: "meta-mysql-credentials"
        # -- MySQL credentials existing secret name
        existingSecretName: ""
        # -- MySQL credentials username
        username: "root"
        # -- MySQL credentials password
        password: "test"

mysql.host: MySQL 主机。
mysql.port: MySQL 端口。
mysql.database: MySQL 数据库。
mysql.table: MySQL 表。
mysql.credentials.secretName: MySQL 凭证 secret 名称。
mysql.credentials.existingSecretName: MySQL 凭证 secret 名称。如果你希望使用已有的 secret，你需要确保该 secret 包含 username 和 password 两个 key。
mysql.credentials.username: MySQL 凭证用户名。如果 mysql.credentials.existingSecretName 被设置，该字段将被忽略。该用户名会写入 mysql.credentials.secretName 指定的 Secret 的 username key 中。
mysql.credentials.password: MySQL 凭证密码。如果 mysql.credentials.existingSecretName 被设置，该字段将被忽略。该密码会写入 mysql.credentials.secretName 指定的 Secret 的 password key 中。

meta.backendStorage.postgresql 的大部分字段与 meta.backendStorage.mysql 的相同。例如：

meta:
  backendStorage:
    postgresql:
      # -- PostgreSQL host
      host: "postgres.default.svc.cluster.local"
      # -- PostgreSQL port
      port: 5432
      # -- PostgreSQL database
      database: "metasrv"
      # -- PostgreSQL table
      table: "greptime_metakv"
      # -- PostgreSQL Advisory lock id used for election, shouldn't be used in other clusters or applications.
      electionLockID: 1
      # -- PostgreSQL credentials
      credentials:
        # -- PostgreSQL credentials secret name
        secretName: "meta-postgresql-credentials"
        # -- PostgreSQL credentials existing secret name
        existingSecretName: ""
        # -- PostgreSQL credentials username
        username: "root"
        # -- PostgreSQL credentials password
        password: "root"

postgresql.host: PostgreSQL 主机。
postgresql.port: PostgreSQL 端口。
postgresql.database: PostgreSQL 数据库。
postgresql.table: PostgreSQL 表。
postgresql.electionLockID: PostgreSQL 中用于选举的锁 ID。
postgresql.credentials.secretName: PostgreSQL 凭证 secret 名称。
postgresql.credentials.existingSecretName: PostgreSQL 凭证 secret 名称。如果你希望使用已有的 secret，你需要确保该 secret 包含 username 和 password 两个 key。
postgresql.credentials.username: PostgreSQL 凭证用户名。如果 postgresql.credentials.existingSecretName 被设置，该字段将被忽略。该用户名会写入 postgresql.credentials.secretName 指定的 Secret 的 username key 中。
postgresql.credentials.password: PostgreSQL 凭证密码。如果 postgresql.credentials.existingSecretName 被设置，该字段将被忽略。该密码会写入 postgresql.credentials.secretName 指定的 Secret 的 password key 中。

使用 etcd 作为后端存储

NOTE

chart 版本之间的配置结构已发生变化:

旧版本: meta.etcdEndpoints
新版本: meta.backendStorage.etcd.endpoints

请参考 chart 仓库中配置 values.yaml 以获取最新的结构。

你可以通过 meta.backendStorage.etcd 字段配置 etcd 作为后端存储。

meta:
  backendStorage:
    etcd:
      # -- Etcd endpoints
      endpoints: ["etcd.etcd-cluster.svc.cluster.local:2379"]
      # -- Etcd store key prefix
      storeKeyPrefix: ""

etcd.endpoints: etcd 服务地址。
etcd.storeKeyPrefix: etcd 存储 key 前缀。所有 key 都会被存储在这个前缀下。如果你希望使用一个 etcd 集群为多个 GreptimeDB 集群提供服务，你可以为每个 GreptimeDB 集群配置不同的存储 key 前缀。这仅用于测试和调试目的。

启用 Region Failover

你可以通过 meta.enableRegionFailover 字段启用 Region Failover。在启用 Region Failover 之前，请确保你的部署满足 Region Failover 文档中的先决条件。如果你的配置不满足条件，Operator 将无法部署集群组件。

meta: 
  enableRegionFailover: true

启用 IPv6

通过 enableIPv6 字段可开启 IPv6 网络协议支持。设置为 true 时，系统将启用 IPv6 地址分配与通信功能，默认为 false（不启用）。启用前请确保底层基础环境已配置支持 IPv6 网络。

enableIPv6: true

启用 GC

重分区依赖共享对象存储和 GC。你可以通过下面的示例同时开启 metasrv 和 datanode 的 GC：

meta:
  configData: |
    [gc]
    enable = true
    gc_cooldown_period = "5m"

datanode:
  configData: |
    [[region_engine]]
    [region_engine.mito]
    [region_engine.mito.gc]
    enable = true
    lingering_time = "10m"
    unknown_file_lingering_time = "1d"

请确保 datanode 的 lingering_time 大于 meta 的 gc_cooldown_period，以避免正在使用的文件过早被删除。

启用 Region Failover 在本地 WAL

在本地 WAL 上启用 Region Failover，你需要设置 meta.enableRegionFailover: true 和在 meta.configData 字段中添加 allow_region_failover_on_local_wal = true。

WARNING

在本地 WAL 启用 Region Failover 可能会导致数据丢失。另外，确保你的 Operator 版本大于或等于 v0.2.2。

meta: 
  enableRegionFailover: true
  configData: |
    allow_region_failover_on_local_wal = true

专用 WAL 卷

配置专用 WAL 卷时，可以为 GreptimeDB Datanode 的 WAL（预写日志）目录使用单独的磁盘，并指定自定义的 StorageClass。

dedicatedWAL:
  enabled: true
  raftEngine:
    fs:
      storageClassName: io2 # 使用 AWS ebs io2 存储以获得更好的性能
      name: wal
      storageSize: 20Gi
      mountPath: /wal

启用 Remote WAL

在启用前，请务必查阅 Remote WAL 配置文档，以了解完整的配置项说明及相关注意事项。

remoteWal:
  enabled: true
  kafka:
    brokerEndpoints: ["kafka.kafka-cluster.svc:9092"]
meta:
  configData: |
    [wal]
    provider = "kafka"
    replication_factor = 1
    auto_prune_interval = "30m"
datanode:
  configData: |
    [wal]
    provider = "kafka"
    overwrite_entry_start_id = true

常见 Helm Chart 配置项

GreptimeDB Cluster Chart​

GreptimeDB 运行镜像配置​

服务端口配置​

Datanode 存储配置​

运行资源配置​

服务运行副本数配置​

环境变量配置​

注入配置文件​

鉴权配置​

日志配置​

启用 Flownode​

对象存储配置​

AWS S3​

使用 IAM Roles for Service Accounts（IRSA）访问 S3​

Google Cloud Storage​

Azure Blob​

AliCloud OSS​

Volcengine TOS​

Prometheus 监控配置​

Debug Pod 配置​

配置 Metasrv 后端存储​

使用 MySQL 和 PostgreSQL 作为后端存储​

使用 etcd 作为后端存储​

启用 Region Failover​

启用 IPv6​

启用 GC​

启用 Region Failover 在本地 WAL​

专用 WAL 卷​

启用 Remote WAL​