使用 OneUptime Terraform Provider 快速上手10 分钟将标签、HTTP 监控与状态页纳入基础设施即代码【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本指南以 OneUptime 官方 Quick StartApp/FeatureSet/Docs/Content/de/terraform/quick-start.md为骨架完整演示如何从零开始创建项目级 API 密钥、声明式配置 provider、Apply 一个标签Label、一个网站监控Website Monitor和一个内部状态页Status Page并在仪表盘中验证结果。读完本文你将掌握 OneUptime Terraform Provider 的完整上手链路以及配套的认证方式、版本选择、状态管理与常见排错手段。前置条件开始之前请确认环境满足以下两点Terraform 1.5 或更高版本OneUptime Provider 以 1.5.0 为最低 Terraform 版本要求。若你使用 OpenTofu其版本序列从 1.6.0 起步天然满足该下限见仓库内 Examples/opentofu/quickstart/main.tf 的注释说明。一个 OneUptime 账号与项目既可以是 OneUptime Cloud也可以是自托管实例。两种环境的 Provider 行为完全一致唯一差异是实例 URL详见后文自托管场景。OneUptime Terraform Provider 与 OpenTofu 均声明为同一来源oneuptime/oneuptime在 Terraform 下解析自 registry.terraform.io在 OpenTofu 下解析自 registry.opentofu.org两端都发布了同名 Provider。Step 1创建项目级 API 密钥Provider 使用项目级project-scopedAPI 密钥进行认证。在 OneUptime 仪表盘中操作选择你的项目。进入Projekteinstellungen项目设置 API-SchlüsselAPI 密钥。点击Create API Key创建 API 密钥。为密钥命名例如terraform并设置过期时间。授予权限。Terraform 需要对你计划管理的每一种资源类型拥有Create创建、Read读取、Update编辑、Delete删除权限——就本指南而言需要覆盖 Label、Monitor、Status Page 三类。复制生成的密钥。警告不要使用用户密钥或自托管的 master API key。Master key 不绑定任何项目用它发起的 API 调用会以ProjectId required错误失败。只有项目 API 密钥才能配合 Terraform Provider 使用。将密钥导出为环境变量避免它出现在 Terraform 文件中export ONEUPTIME_API_KEYyour-project-api-key从实现角度补充一个关键事实Provider 是从 OneUptime 项目 ID 由密钥本身推导而来的——master key 不携带项目信息因此每次资源调用都会失败。仓库内 App/FeatureSet/Docs/Content/en/terraform/troubleshooting.md 对该错误有专门章节解释创建项目 API 密钥并授予对应资源类型的 CRUD 权限即可修复。Step 2配置 Provider创建一个工作目录并写入main.tfterraform { required_providers { oneuptime { source oneuptime/oneuptime version ~ 11.0 } } } provider oneuptime { # api_key is read from the ONEUPTIME_API_KEY environment variable. # oneuptime_url defaults to https://oneuptime.com — set it only if self-hosted: # oneuptime_url https://oneuptime.example.com }Provider 块仅接受两个属性来源与默认值如下表见 complete-guide.md属性是否必填环境变量默认值api_key否可回退到环境变量ONEUPTIME_API_KEY—oneuptime_url否ONEUPTIME_URLhttps://oneuptime.com如果 provider 块和环境变量中都没有 API 密钥Provider 会在 configure 阶段任何 plan/apply 工作开始之前直接报错退出。自托管用户将oneuptime_url设为实例的裸 origin——只含 scheme 和主机名不要带/api后缀或任何路径Provider 会自行拼接 API 路径。固定 Provider 版本前请先阅读 自托管安装指南 中的版本选择规则。Step 3定义你的第一批资源向main.tf追加以下内容。它会创建一个标签、一个针对你主页的网站监控以及一个私有状态页resource oneuptime_label critical { name critical description Resources that page on-call when down color #FF5733 } resource oneuptime_monitor homepage { name Homepage description Checks that the homepage responds monitor_type Website labels [oneuptime_label.critical.id] } resource oneuptime_status_page internal { name Internal Status description Status page for internal services page_title Service Status page_description Live status of our services is_public_status_page false enable_email_subscribers false enable_sms_subscribers false } output monitor_id { value oneuptime_monitor.homepage.id }这段配置包含了 Terraform 声明式管理的三个核心要素可与仓库实际示例对照理解资源间依赖由引用自动推断labels [oneuptime_label.critical.id]使 Terraform 先创建标签、最后销毁标签无需手写depends_on。labels是无序的 ID 字符串集合调整条目顺序不会产生 diff。monitor_type决定监控语义本示例用WebsiteProvider 支持的完整类型还包括 API、Ping、Port、IP、SSL 证书、Server、Incoming Request、Manual 等见 index.md 的资源总表。monitor_steps可选未显式指定monitor_steps的Website监控会获得服务端合理的默认行为探测该 URL、不可达即判离线且服务端默认值不会造成 Terraform state 漂移——state 中该属性保持null。仓库中的 OpenTofu 快速入门示例 Examples/opentofu/quickstart/main.tf 展示了同一模式的进阶形态显式传入monitoring_interval Every 5 minutes并以变量var.website_url驱动monitor_steps中的目标地址其内嵌 criteria 定义了在线Is Online 为 True判定resource oneuptime_monitor homepage { name Homepage description Checks that ${var.website_url} responds. monitor_type Website monitoring_interval Every 5 minutes labels [oneuptime_label.quickstart.id] monitor_steps [{ monitor_destination var.website_url monitor_destination_type URL request_type GET criteria [ { name Online description Responds successfully. filter_condition All filters [ { check_on Is Online filter_type True } ] } ] }] }如果你想自己控制 URL、请求类型与上下线判定条件可以像上面这样以 HCL 直接编写monitor_steps类型化嵌套属性无需jsonencode、无需手写 ID、无需 camelCase 键完整属性与判定规则见 Monitor Steps 详解。Step 4初始化、规划与应用terraform init terraform plan terraform applyterraform init会从注册表下载 Provider 二进制支持 Linux/macOS/Windows 的 amd64 与 arm64并写入.terraform.lock.hcl——请提交该锁文件它是 CI 运行可复现的关键。随后审查 plan预期显示 3 个资源将被新增确认后输入yes。Apply 在几秒内完成并输出监控 ID。Provider 的发布物与文档由仓库中的生成器产出OneUptime 的 OpenAPI 规范经 Scripts/TerraformProvider/ 下的 TypeScript 生成器OpenAPIParser→ResourceGenerator/DataSourceGenerator→ProviderGenerator→GoModuleGenerator自动生成完整、可发布的 Go Provider——CRUD 由 HTTP 方法映射而来POST→Create、GET→Read、PUT/PATCH→Update、DELETE→Delete数据源由 GET 端点生成新 API 端点会自动成为新资源无需手工维护 Provider 代码。Step 5在仪表盘中验证回到 OneUptime 仪表盘检查Monitore监控——Homepage监控已列出并带有critical标签。Statusseiten状态页——Internal Status已出现。Projekteinstellungen Beschriftungen项目设置 标签——critical标签存在且颜色为你设置的值。再次运行terraform plan应报告No changes.。原因在于服务端计算字段slugs、当前状态、默认监控步骤不会导致漂移RFC3339 时间戳按语义比较2026-08-01T02:00:00Z与服务端规范化形式视为相等标签数组按无序集合处理。Step 6清理如果这只是一次试用删除配置创建的全部资源terraform destroy销毁会真实删除已被纳管的所有资源包括通过 import 引入的请确认后再执行。认证方式的三种进阶姿势Quick Start 使用环境变量是最推荐的方式但 Provider 还支持另外两种常见场景详见 complete-guide.md方式一环境变量推荐——凭证完全不出现在配置文件中export ONEUPTIME_API_KEYyour-project-api-key # 自托管才需要 export ONEUPTIME_URLhttps://oneuptime.example.comprovider oneuptime {}方式二变量 tfvars 文件variable oneuptime_api_key { description OneUptime project API key type string sensitive true } provider oneuptime { api_key var.oneuptime_api_key }将值写入terraform.tfvars并加入.gitignoreoneuptime_api_key your-project-api-key方式三CI/CD 密钥注入——在 CI 中以脱敏环境变量注入setup-terraform后依次执行init/plan -inputfalse/apply -auto-approve -inputfalse同一模式适用于 GitLab CI、CircleCI 与 Terraform Cloud。更进一步项目结构与资源编排建议官方推荐每个 OneUptime 项目对应一个 Terraform rootAPI 密钥是项目级的并按功能拆分文件complete-guide.mdoneuptime/ ├── main.tf # terraform {} 与 provider {} 块 ├── variables.tf # 输入变量 ├── outputs.tf # 导出的 ID ├── labels.tf # 标签、团队等共享基础块 ├── monitors.tf # 监控与监控状态 ├── status-pages.tf # 状态页与域名 ├── on-call.tf # 值班策略与升级规则 └── environments/ ├── production.tfvars └── staging.tfvars依赖图由引用自动构建标签和团队供监控引用、监控再供状态页引用depends_on只在没有属性引用但有真实顺序要求时才需要。对于仪表盘中已存在、不想重复创建的资源可以使用import块Terraform 1.5将现有资源纳入管理——导入 ID 即资源的 24 位十六进制 ObjectID可从仪表盘 URL 末段或 API 返回的_id获取terraform plan -generate-config-outgenerated.tf还能自动起草资源块见 importing-resources.md。版本选择、自托管与排错速查版本规则Provider 版本与 OneUptime 平台版本一一对应。云上用户直接用~ 11.0自托管用户应使用不大于平台版本的最新已发布 Provider 版本且不要固定精确补丁版本 11.0.7这类写法常因该补丁未发布而报no matching version found。自托管升级顺序务必是先升级 OneUptime 平台再提高 Provider 约束并运行terraform init -upgrade。离线环境可用terraform providers mirror将 Provider 镜像到内网再通过~/.terraformrc的filesystem_mirror指向它完整配置见 自托管安装指南。排错速查表节选自 troubleshooting.md症状常见原因修复所有操作报ProjectId required使用了 master key 或用户密钥而非项目 API 密钥在项目设置 API 密钥下创建项目密钥并使用403权限拒绝仅某一资源类型项目 API 密钥缺少该类型的 CRUD 权限编辑密钥权限补足该类型权限401认证失败密钥被吊销、过期或ONEUPTIME_API_KEY值错误重新生成项目 API 密钥no matching version found固定了从未发布的精确版本改用~ 11.0这类悲观约束x509: certificate signed by unknown authority自托管实例 TLS 证书不被 Terraform 主机信任在运行 Terraform 的机器上安装 CA 证书自托管每次 API 调用都 Connection refused / 404oneuptime_url配置错误带路径后缀、端口错、http/https 错设为裸实例 origin如https://oneuptime.example.commonitor_steps拒绝空列表/空 map/空字符串用[]、{}、作为占位符直接省略该属性——缺省即未设置结语至此你已经用 6 个步骤完成了 OneUptime 资源的首次声明式纳管项目 API 密钥 → Provider 配置 → 标签/监控/状态页定义 → init/plan/apply → 仪表盘验证 → destroy 清理。这套链路既适用于云上 OneUptime也适用于自托管实例配合 Complete Guide数据源与状态管理、Monitor Steps自定义判定规则、Examples各资源类型配置模板与 Importing Resources存量资源迁移即可将整套监控与可观测性基础设施纳入 IaC 体系持续演进。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考