什么是 Terraform？

Terraform 是 Hashicorp 公司开源的一种资源编排工具，常用于管理多云资源。利用 Terrafrom 提供的特定配置语言 HCL（Hashicorp Configuration Language）来定义资源，再由 Terraform 统一解析构建资源之间的依赖关系，生成执行计划，调用各个厂商的具体实现来完成资源的生命周期管理。

Terraform 支持多种云厂商，包括国内的阿里云、华为云、腾讯云等，还有国外的AWS、Azure、Google Cloud等。使用 Terraform，我们可以定义服务器、网络和数据库等，不需要手动操作，通过编写可维护和可重复执行的代码来管理基础设施资源，这样使得我们对基础设施资源的管理更加简单、可重复和可维护。

通常 Terraform 被用于管理 IaaS 和 PaaS 层资源，但 Terraform 也可以用于管理 SaaS 层资源。利用观测云 Terraform Provider 可以创建Pipeline、黑名单、角色和用户组等可观测性资源，实现 OaC（Observability as Code）。

- 观测云 Terraform Provider：https://registry.terraform.io/namespaces/GuanceCloud

- 观测云 Terraform Provider Github：https://github.com/GuanceCloud/terraform-provider-guance

为什么使用 Terraform？

Terraform 宗旨在于跨平台、自动化、环境一致性、变更审计和自动化测试，可以大幅减少资源管理的问题。

- 跨平台特性：目前海内外累计已有超过 40 家公有云厂商支持，另有 200 多个软件服务商为其提供支持。利用 Terraform 跨平台特性，可以非常方便的将观测云资源同其他厂商资源进行集成。

- 自动化：所有的资源变更都由 Terraform 来管理执行，不需要手动执行相同的操作，让工程师把时间浪费在美好的事情上。

- 环境一致性：通过 Terrafrom 部署环境，可以把配置复制到任何环境中，不需要担心环境非一致性带来的异常。

- 变更审计：通过代码管理资源，terraform plan 生成执行计划，可以进行版本控制，任何资源变更都变得可追踪、可审计。

- 自动化测试：资源通过代码配置管理后，在测试环境或者 CI 进行自动化测试变得可行，每一次资源变更都可以进行相同的兼容性测试。

使用 Terraform 创建观测云资源

利用观测云 Terraform provider 可以管理观测云的众多资源，我们可以使用 Terraform 来实现以下功能：

- 创建 [Pipeline](https://docs.guance.com/pipeline/#pipelines)：Pipelines 是一种运行在 DataKit 上的轻量级脚本语言，用于对采集到的数据进行自定义解析和修改。通过定义解析规则，它们能够将不同种类的数据细粒度地切割并转换为结构化的格式，以满足具体的数据管理需求；

- 创建 [BlackList](https://docs.guance.com/management/overall-blacklist/)：观测云支持通过设置黑名单的方式过滤掉符合条件的不同类型的数据，即配置黑名单以后，符合条件的数据不再上报到观测云工作空间，帮助您节约数据存储费用；

- 创建 [MemberGroup](https://docs.guance.com/management/member-management/#_7)：若企业需要针对不同的团队设置不同的告警策略，以便相关团队能够第一时间获取并解决故障问题，可以通过设置团队，并相关的团队成员到该团队，然后在告警策略，设置告警通知对象为该团队；

- 创建 [Role](https://docs.guance.com/management/role-management/)：角色管理为用户提供一个直观的权限管理入口，支持自由调整不同角色对应的权限范围、为用户创建新的角色、为角色赋予权限范围，满足不同用户的权限需要。

除此之外，通过观测云 Terraform provider 也可以创建监控器和 Dashboard 相关资源，具体使用方式可参考相关 Terraform 文档。

配置 Provider

开始使用观测云 Terraform 之前，通过「[API Key 管理](https://docs.guance.com/management/api-key/)」创建 API Key，作为访问观测云的鉴权认证方式，在 Terraform `provider.tf` 文件配置如下信息：

# Key ID、region

provider "guance" {

  access_token = "svUTRWyPFClxxxxxxxxxxxxxxxBGJ3gp8O5a9Yt"

  region = "ningxia"

}

使用 Terraform 创建 Pipeline

Pipeline 作为一种轻量化脚本语言，Pipeline 提供了高效的数据处理能力；它拥有丰富的函数库，支持对多种常见数据类型的标准化操作；用户可以使用Terraform 创建Pipeline 脚本，使得脚本的创建和管理变得更加便捷。

资源创建说明文档：

https://registry.terraform.io/providers/GuanceCloud/guance/latest/docs/resources/pipeline

代码示例：`main.tf`

resource "guance_pipeline" "demo" {

  name    = "terraform_test12"

  category = "logging"

  source = [

    "nginx"

  ]

  as_default = 1

  is_force  = false

  type      = "local"

  content    = <<EOF

    add_pattern("date2", "%%{YEAR}[./]%%{MONTHNUM}[./]%%{MONTHDAY} %%{TIME}")

    # access log

    grok(_, "%%{NOTSPACE:client_ip} %%{NOTSPACE:http_ident} %%{NOTSPACE:http_auth} \\[%%{HTTPDATE:time}\\] \"%%{DATA:http_method} %%{GREEDYDATA:http_url} HTTP/%%{NUMBER:http_version}\" %%{INT:status_code} %%{INT:bytes}")

    # access log

    add_pattern("access_common", "%%{NOTSPACE:client_ip} %%{NOTSPACE:http_ident} %%{NOTSPACE:http_auth} \\[%%{HTTPDATE:time}\\] \"%%{DATA:http_method} %%{GREEDYDATA:http_url} HTTP/%%{NUMBER:http_version}\" %%{INT:status_code} %%{INT:bytes}")

    grok(_, '%%{access_common} "%%{NOTSPACE:referrer}" "%%{GREEDYDATA:agent}"')

    user_agent(agent)

    # error log

    grok(_, "%%{date2:time} \\[%%{LOGLEVEL:status}\\] %%{GREEDYDATA:msg}, client: %%{NOTSPACE:client_ip}, server: %%{NOTSPACE:server}, request: \"%%{DATA:http_method} %%{GREEDYDATA:http_url} HTTP/%%{NUMBER:http_version}\", (upstream: \"%%{GREEDYDATA:upstream}\", )?host: \"%%{NOTSPACE:ip_or_host}\"")

    grok(_, "%%{date2:time} \\[%%{LOGLEVEL:status}\\] %%{GREEDYDATA:msg}, client: %%{NOTSPACE:client_ip}, server: %%{NOTSPACE:server}, request: \"%%{GREEDYDATA:http_method} %%{GREEDYDATA:http_url} HTTP/%%{NUMBER:http_version}\", host: \"%%{NOTSPACE:ip_or_host}\"")

    grok(_,"%%{date2:time} \\[%%{LOGLEVEL:status}\\] %%{GREEDYDATA:msg}")

    group_in(status, ["warn", "notice"], "warning")

    group_in(status, ["error", "crit", "alert", "emerg"], "error")

    cast(status_code, "int")

    cast(bytes, "int")

    group_between(status_code, [200,299], "OK", status)

    group_between(status_code, [300,399], "notice", status)

    group_between(status_code, [400,499], "warning", status)

    group_between(status_code, [500,599], "error", status)

    nullif(http_ident, "-")

    nullif(http_auth, "-")

    nullif(upstream, "")

    default_time(time)

    EOF

  test_data = <<EOF

    127.0.0.1 - - [24/Mar/2021:13:54:19 +0800] "GET /basic_status HTTP/1.1" 200 97 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_1_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.72 Safari/537.36"

    EOF

  extend = {

    "app_id"      = ["test"],

    "measurement" = ["nginx_access_log"]

  }

}

执行创建：

# terrform 常用命令 https://developer.hashicorp.com/terraform/cli/commands/plan

terraform init    # 初始化

terraform plan    # 校验执行计划

terraform apply  # 创建资源

terraform destroy # 删除资源

使用 Terraform 创建 BlackList

观测云支持通过设置黑名单的方式过滤掉符合条件的不同类型的数据，即配置黑名单以后，符合条件的数据不再上报到观测云工作空间，帮助您节约数据存储费用。

资源创建说明文档：

https://registry.terraform.io/providers/GuanceCloud/guance/latest/docs/resources/blacklist

代码示例：`main.tf`

resource "guance_blacklist" "demo" {

  type  = "logging"

  source = "nginx"

  filters = [

    {

      name      = "status"

      operation = "in"

      condition = "and"

      values    = ["error"]

    }

  ]

}

执行创建：

# terrform 常用命令 https://developer.hashicorp.com/terraform/cli/commands/plan

terraform init    # 初始化

terraform plan    # 校验执行计划

terraform apply  # 创建资源

terraform destroy # 删除资源

使用 Terraform 创建 MemberGroup

观测云支持将不同的空间成员，添加到一个团队中，可以在监控的告警策略管理和通知对象管理中应用已新建的团队，以便相关团队能够第一时间获取并解决故障问题。

资源创建说明文档：

https://registry.terraform.io/providers/GuanceCloud/guance/latest/docs/resources/membergroup

代码示例：`main.tf`

variable "email" {

  type = string

}

data "guance_members" "demo" {

  search = var.email

}

resource "guance_membergroup" "demo" {

  name          = "oac-demo2"

  account_uuids = data.guance_members.demo.members[*].uuid

}

output "member" {

  value = data.guance_members.demo.members

}

执行创建：

# terrform 常用命令 https://developer.hashicorp.com/terraform/cli/commands/plan

terraform init    # 初始化

terraform plan    # 校验执行计划

terraform apply  # 创建资源

terraform destroy # 删除资源

使用 Terraform 创建 Role

若您需要对企业中的员工设置不同的观测云访问权限，以达到不同员工之间的权限隔离，您可以使用观测云的角色管理功能。角色管理为用户提供一个直观的权限管理入口，支持自由调整不同角色对应的权限范围、为用户创建新的角色、为角色赋予权限范围，满足不同用户的权限需要。

资源创建说明文档：

https://registry.terraform.io/providers/GuanceCloud/guance/latest/docs/resources/role

代码示例：`main.tf`

resource "guance_role" "role" {

  name = "tf-test-role1"

  desc = "test role"

  keys = ["snapshot.delete", "workspace.readMember"]

}

执行创建：

# terrform 常用命令 https://developer.hashicorp.com/terraform/cli/commands/plan

terraform init    # 初始化

terraform plan    # 校验执行计划

terraform apply  # 创建资源

terraform destroy # 删除资源

总结

前面是一些常用功能的示例，观测云 Terraform Provider 正在不断开发中，未来我们会支持更多的观测云资源。同时，我们也非常欢迎大家一同参与贡献，为中国可观测性基础设施添砖加瓦。