OneUptime Terraform Provider 快速入门10 分钟用 IaC 管理标签、监控器与状态页【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 是开源的监控与可观测性平台而其官方 Terraform Provider 让你可以把标签、监控器、状态页等资源当作代码来管理。这篇指南以官方 Quick Start 文档为主线带你从零开始创建项目级 API Key、配置 provider、编写main.tf最终在十分钟内完成一次terraform apply并在控制台中验证结果。读完你就能用基础设施即代码的方式把 OneUptime 的资源纳入 CI/CD 与版本管理流程。前置条件开始之前请确认你的环境满足以下条件Terraform 1.5 或更高版本OneUptime Provider 的最低支持版本为 1.5.0。一个 OneUptime 账号与项目可以是云服务oneuptime.com也可以是自托管的 OneUptime 实例。项目级 API Key 的创建权限需要在 OneUptime 控制台的Project Settings API Keys中创建密钥。如果你使用 OpenTofu 而非 Terraform CLI也完全可行——OneUptime Provider 是标准的插件协议 6 provider已同时发布到 Terraform Registry 与 OpenTofu Registry。OpenTofu 的版本系列从 1.6.0 开始因此为 Terraform 编写的required_version 1.5.0约束对每个 OpenTofu 版本同样成立。仓库中的 Examples/opentofu 目录提供了可直接用tofu命令运行的完整示例。第一步创建项目 API KeyProvider 使用项目级project-scopedAPI Key进行认证。在 OneUptime 控制台按以下步骤创建在控制台中选择你的项目。进入Project Settings API Keys。点击Create API Key。为密钥命名例如terraform并设置过期时间。授予权限。Terraform 需要你计划管理的每一种资源类型上的Create、Read、Update (Edit)、Delete权限——本指南中即 Label、Monitor、Status Page 三类。复制生成的密钥。重要警告不要使用用户级密钥或自托管环境中的 master API key。Master key 不限定于任何项目用它们调用 API 会得到ProjectId required错误。只有项目 API Key 能配合 Terraform Provider 工作。将密钥导出为环境变量避免它出现在 Terraform 文件中export ONEUPTIME_API_KEYyour-project-api-key自托管用户如需指定实例地址可同时导出ONEUPTIME_URLprovider 也支持通过该环境变量读取实例地址见后文 provider 配置表。第二步配置 Provider创建一个工作目录写入main.tfterraform { required_providers { oneuptime { source oneuptime/oneuptime version ~ 11.0 } } } provider oneuptime { # api_key 从 ONEUPTIME_API_KEY 环境变量读取。 # oneuptime_url 默认为 https://oneuptime.com —— 自托管时才需要设置 # oneuptime_url https://oneuptime.example.com }几个值得注意的要点版本约束使用悲观约束~ 11.0而非精确锁定。Provider 版本与 OneUptime 平台版本同步发布但并非每个平台补丁版本都会发布到 Registry。如果写成version 11.0.3一旦该补丁未发布就会得到no matching version found for oneuptime/oneuptime错误。自托管用户设置oneuptime_url为实例地址并在锁定 provider 版本前查阅 Self-Hosted Setup 的版本指导——自托管部署必须将 provider 版本保持在平台版本之下。Provider 块支持的两个属性如下属性必填环境变量默认值api_key否回退到环境变量ONEUPTIME_API_KEY—oneuptime_url否ONEUPTIME_URLhttps://oneuptime.com如果 provider 块与环境变量都没有提供 API Keyprovider 会在配置阶段任何 plan 或 apply 之前就报错退出。第三步定义你的第一批资源把以下内容追加到main.tf。它会创建一个标签label、一个检查你首页的网站监控器monitor、一个内部状态页status pageresource 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 }这段配置蕴含了几个关键机制资源依赖由引用自动推断oneuptime_monitor.homepage引用了oneuptime_label.critical.idTerraform 会自动先创建标签、后创建监控器销毁时顺序相反。显式depends_on很少需要只有存在无属性引用的真实排序需求时才添加。labels是字符串 ID 的无序集合调整条目的排列顺序不会产生任何 diff。Website类型的监控器如果不显式指定monitor_steps服务端会注入合理的默认检查对 URL 发起请求不可达即判定离线。想自己控制 URL、请求类型和在线/离线判定标准就设置monitor_steps嵌套属性——详见 Monitor Steps。仓库中的 Examples/opentofu/quickstart/main.tf 给出了更完整的快速开始变体它显式声明了monitor_steps、monitoring_interval Every 5 minutes并把状态页也挂上了标签值得对照参考。第四步Init、Plan、Applyterraform init terraform plan terraform applyterraform init会从 Registry 拉取oneuptime/oneuptimeprovider~ 11.0允许所有 11.x 版本。terraform plan显示将要新增的 3 个资源。terraform apply审查计划后输入yes确认几秒钟内完成并输出monitor_id。小贴士快速开始示例还导出了monitor_slug、status_page_id、label_id等输出见 Examples/opentofu/quickstart/outputs.tf方便在自动化脚本中引用这些服务端生成的值。第五步在控制台验证在 OneUptime 控制台中确认Monitors—Homepage监控器已列出并带有critical标签。Status Pages— 出现Internal Status状态页。Project Settings Labels—critical标签存在颜色为你设置的值。再次运行terraform plan应报告No changes.。服务端计算字段slug、当前状态、默认监控步骤不会引起漂移标签数组按无序集合比较、时间戳按语义比较RFC3339 同一时刻的不同规范化形式视为相等、服务端默认的monitor_steps被接受且不会回写为状态变更。这正是 Troubleshooting 中 Provider produced inconsistent result after apply 问题的解法核心——旧版本 provider 会在这些字段上误报不一致升级到当前 11.x 即可消除。第六步清理资源如果这只是一次试用删除配置创建的全部资源terraform destroy深入Provider 背后的生成机制OneUptime 的 Terraform Provider 并非手写而是由仓库中的 TypeScript 生成器从 OneUptime 的 OpenAPI 规范自动生成的。理解这一点有助于你判断文档行为的边界。生成流水线位于 Scripts/TerraformProvider/GenerateProvider.ts生成 OpenAPI 规范从 OneUptime 代码库生成openapi.json。解析与资源发现OpenAPIParser从 OpenAPI 标签与端点中自动发现资源与数据源跳过任何端点都会在 CI 日志中告警。生成 Go 代码ProviderGenerator生成主 provider 文件与认证配置ResourceGenerator按 CRUD 映射POST→Create、GET→Read、PUT/PATCH→Update、DELETE→Delete生成每个资源文件DataSourceGenerator从 GET 端点生成只读数据源DocumentationGenerator自动生成 Registry 文档与示例。编译验证运行go mod tidy并执行go build编译检查——编译失败会硬性中止流水线防止把损坏的代码发布到 Registry。生成后的完整结构Terraform/terraform-provider-oneuptime/包括main.go、internal/provider/provider、client、schema、100 个资源文件与数据源文件、docs/与examples/。这意味着新增 API 端点会自动成为新的 Terraform 资源provider 始终与 API 演进同步。值得注意的认证细节生成器支持 API Key 与用户名/密码两类认证环境变量ONEUPTIME_API_KEY、ONEUPTIME_URL等均受支持。但官方 Quick Start 明确要求只用项目 API Key——这与 provider 的认证模型直接相关provider 从密钥本身推导项目归属master key 不携带项目信息因此所有资源调用都会以ProjectId required失败。更多资源与下一步Quick Start 只是起点官方文档目录 App/FeatureSet/Docs/Content/en/terraform 提供了完整的学习路径Complete Guide — 认证选项、项目布局、依赖、数据源、远程状态与版本升级。Examples — 覆盖每种主要资源类型的真实配置。Monitor Steps — 深入讲解monitor_steps嵌套属性step 属性、criteria/filters 结构、过滤参考。Importing Resources — 采纳已在控制台创建的资源。Self-Hosted Setup — 自托管实例的oneuptime_url、TLS 信任与版本对齐。Troubleshooting — 常见错误速查ProjectId required、402/403、版本约束、TLS 问题等。OpenTofu — 用 OpenTofu 驱动同一 provider。可运行的参考配置在 Examples/opentofu含 quickstart 与可复用的modules/monitoring-and-incident-response模块provider 的生成器源码与测试在 Scripts/TerraformProvider。把标签、监控器、状态页交给 Terraform 管理之后你就能在 pull request 中审查监控配置的变更、在 CI 中自动应用并借助远程状态让团队共享同一套监控即代码基线。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考