全新 Terraform provider：通过代码管理 ClickHouse 数据库用户、角色和权限

最新推荐文章于 2025-11-24 14:42:36 发布

原创最新推荐文章于 2025-11-24 14:42:36 发布 · 897 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#oracle #数据库

本文字数：6656；估计阅读时间：17 分钟

作者：Ryan Sickles

本文在公众号【ClickHouseInc】首发

我们非常高兴地宣布，全新的 Terraform provider —— clickhousedbops —— 现已正式发布，帮助客户以编程方式管理数据库用户、角色以及授予权限。这一新的 provider 同时支持运行在 ClickHouse Cloud 和自托管环境下的 ClickHouse 实例。

目前，已经有许多 ClickHouse Cloud 的客户选择使用 Terraform 来自动化配置和管理 ClickHouse 服务，从而获得极大的易用性优势。过去，我们的 ClickHouse Terraform provider 已经支持管理和部署服务、私有端点以及透明数据加密（Transparent Data Encryption）密钥。现在，客户可以借助 clickhousedbops provider，进一步扩展 Terraform 的使用场景。在配置好与 ClickHouse 实例的直接连接后，客户可以创建数据库，并在数据库中的表或列上定义用户、角色及其权限。

使用 Terraform provider 入门

步骤 1：预配 ClickHouse Cloud 服务

假设你是工程团队的负责人，希望搭建一个新的 ClickHouse 数据库，以便团队存储和分析业务部门的电子邮件和电话日志数据。由于你已经通过 Terraform 管理其他基础设施，也希望以相同方式来管理 ClickHouse。

你需要先登录 ClickHouse Cloud 账户。登录后，可以在 ClickHouse Cloud 组织中创建一个 API Token 和密钥，以便 Terraform 进行连接。

接下来，你想要用 Terraform 定义一个名为 “Log Analytics” 的新的 ClickHouse Cloud 服务。你可以新建一个 main.tf 文件来配置 ClickHouse provider，并在同一个文件中定义位于 AWS us-east-1 区域、名为 “Log Analytics” 的 ClickHouse Cloud 服务资源。

注意：我们不推荐在 terraform 文件中直接存储凭据，请参考文档创建一个单独的变量文件。[https://developer.hashicorp.com/terraform/language/values/variables]

Main.tf 文件

terraform {
  required_providers {
    clickhouse = {
      source  = "ClickHouse/clickhouse"
    }
   }
}

locals {
  # Please don't do this :)
  password = "test"
}

# Configuration-based authentication, replace with your own values
provider "clickhouse" {
  organization_id = ""
  token_key       = ""
  token_secret    = ""
}

resource "clickhouse_service" "service" {
  name           = "Log Analytics"
  cloud_provider = "aws"
  region         = "us-east-1"
  idle_scaling   = true
  min_replica_memory_gb  = 8
  max_replica_memory_gb  = 16
  num_replicas = 3
  idle_timeout_minutes = 5

  # for this example this service will be open to all internet connections
  ip_access = [
    {
      source      = "0.0.0.0/0"
      description = "Test IP"
    }
  ]
  password_hash = sha256(local.password)
}

第二步：管理用户、角色和权限

现在你已经定义好了新的服务，希望在新建的 “Log Analytics” 服务中，向名为 “logs” 的数据库中添加你的团队。以下是团队需要通过 Terraform 配置的要求：

你的团队包含 3 位用户 —— Ryan、Jill 和 Carol。
Ryan 只需要对数据库中的 email_logs 表执行分析查询，无需访问其他表的数据。
Jill 和 Carol 只需要对数据库中的 phone_logs 表执行分析查询，同样不需要访问其他表的数据。

为满足这些需求，你决定使用 Terraform 和新的 Clickhousedbops provider 来配置这些用户、角色及权限。首先，需要在同一个 main.tf 文件的 required_providers 区块中添加该 Terraform provider。

terraform {
  required_providers {
    clickhouse = {
      source  = "ClickHouse/clickhouse"
    }
    clickhousedbops = {
      source  = "ClickHouse/clickhousedbops"
    }
   }
}
...

接下来，你可以根据需求配置 provider 以及数据库、用户、角色和权限资源，并将这些资源追加到同一个 main.tf 文件的结尾。

provider "clickhousedbops" {
  protocol = "nativesecure"      
  host = clickhouse_service.service.endpoints.nativesecure.host
  port = clickhouse_service.service.endpoints.nativesecure.port
  auth_config = {
    strategy = "password"
    username = "default"
    password = local.password
  }
}
resource "clickhousedbops_database" "logs" {
  name = "logs"
  comment = "Database for logs"
}

resource "clickhousedbops_user" "ryan" {
  name = "ryan"
  # You'll want to generate the password and feed it here instead of hardcoding.
  password_sha256_hash_wo = sha256("test1")
  password_sha256_hash_wo_version = 1
}


resource "clickhousedbops_user" "jill" {
  name = "jill"
  # You'll want to generate the password and feed it here instead of hardcoding.
  password_sha256_hash_wo = sha256("test2")
  password_sha256_hash_wo_version = 1
}

resource "clickhousedbops_user" "carol" {
  name = "carol"
  # You'll want to generate the password and feed it here instead of hardcoding.
  password_sha256_hash_wo = sha256("test3")
  password_sha256_hash_wo_version = 1
}

resource "clickhousedbops_role" "reader_email_logs" {
  name = "reader_email_logs"
}

resource "clickhousedbops_role" "reader_phone_logs" {
  name = "reader_phone_logs"
}

resource "clickhousedbops_grant_privilege" "grant_select_on_email_logs_to_user" {
  privilege_name    = "SELECT"
  database_name     = "logs"
  table_name        = "email_logs"
  grantee_role_name = clickhousedbops_role.reader_email_logs.name
  grant_option      = true
}

resource "clickhousedbops_grant_privilege" "grant_select_on_phone_logs_to_user" {
  privilege_name    = "SELECT"
  database_name     = "logs"
  table_name        = "phone_logs"
  grantee_role_name = clickhousedbops_role.reader_phone_logs.name
  grant_option      = true
}

resource "clickhousedbops_grant_role" "role_to_user_ryan" {
  role_name         = clickhousedbops_role.reader_email_logs.name
  grantee_user_name = clickhousedbops_user.ryan.name
}

resource "clickhousedbops_grant_role" "role_to_user_jill" {
  role_name         = clickhousedbops_role.reader_phone_logs.name
  grantee_user_name = clickhousedbops_user.jill.name
}

resource "clickhousedbops_grant_role" "role_to_user_carol" {
  role_name         = clickhousedbops_role.reader_phone_logs.name
  grantee_user_name = clickhousedbops_user.carol.name
}

第三步：部署到 ClickHouse Cloud

最后，为了把你的 terraform 配置部署到 ClickHouse Cloud 组织中，需要先运行 “terraform init” 下载所需的 provider，然后执行 “terraform apply”。几分钟后，ClickHouse 服务及数据库资源就会创建完成。

% terraform apply
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # clickhouse_service.service will be created
  + resource "clickhouse_service" "service" {
      + backup_configuration        = (known after apply)
      + cloud_provider              = "aws"
      + endpoints                   = (known after apply)
      + iam_role                    = (known after apply)
      + id                          = (known after apply)
      + idle_scaling                = true
      + idle_timeout_minutes        = 5
...
clickhouse_service.service: Creating...
clickhouse_service.service: Still creating... [10s elapsed]
...
clickhouse_service.service: Creation complete after 6m36s 
...
clickhousedbops_role.reader_email_logs: Creating...
clickhousedbops_role.reader_phone_logs: Creating...
clickhousedbops_database.logs: Creating...
clickhousedbops_user.ryan: Creating...
clickhousedbops_user.carol: Creating...
clickhousedbops_user.jill: Creating...
...
Apply complete! Resources: 12 added, 0 changed, 0 destroyed.

完成之后，你可以通过 ClickHouse Client CLI 以默认用户身份登录，在 logs 数据库中创建两个表 —— email_logs 和 phone_logs —— 并分别导入需要的数据，然后确认正确的用户以及对应的角色和权限是否已经生效。

提示：可以连接数据库并运行 SQL 命令 “SELECT * FROM system.role_grants”，查看数据库中所有用户及角色的权限情况。

恭喜你，已经成功使用这两个官方支持的 ClickHouse Terraform provider，完成了 ClickHouse Cloud 服务、数据库、用户、角色及数据库权限的配置工作。

Terraform 管理自托管 ClickHouse

假设你目前并不是 ClickHouse Cloud 的客户（这里也提供免费试用哦！[https://clickhouse.com/]）。这个全新的 clickhousedbops provider 同样支持那些希望通过 Terraform 管理自己云端或本地自托管 ClickHouse 数据库的用户、角色和权限授予的客户。

为了支持这些开源的 ClickHouse 部署，如果用户有多个副本，可以在每个 clickhousedbops 资源定义中设置一个 “cluster_name” 变量（以数据库资源为例[https://registry.terraform.io/providers/ClickHouse/clickhousedbops/latest/docs/resources/role#optional]），这样就能在该集群的所有副本上创建所需资源。如果不设置这个参数，资源将仅在被查询命中的一个副本上创建。我们建议在操作包含多个副本的集群时，总是配置这个参数。

注意：在使用 ClickHouse Cloud 集群时，必须将该字段保持为空。而对于自托管的 ClickHouse 实例，如果存在多个副本且没有使用 'replicated' 存储管理 user_directory，则只应在非数据库资源中设置该字段。

你可以像下面这样定义你的 clickhousedbops 数据库资源：

resource "clickhousedbops_database" "logs" {
  name = "logs"
  cluster_name = "cluster1"
  comment = "Database for logs"
}

欢迎尝试并反馈

我们希望新的 Terraform 支持可以让管理 ClickHouse 基础设施变得更加简单、更加可靠。欢迎感兴趣的用户尝试我们的 terraform provider，并通过在 GitHub 的 ClickHouse 或 Clickhousedops 仓库提交 issue 的方式直接反馈。

征稿启示

面向社区长期正文，文章内容包括但不限于关于 ClickHouse 的技术研究、项目实践和创新做法等。建议行文风格干货输出&图文并茂。质量合格的文章将会发布在本公众号，优秀者也有机会推荐到 ClickHouse 官网。请将文章稿件的 WORD 版本发邮件至：Tracy.Wang@clickhouse.com