OneUptime Terraform Provider 自托管部署完全指南URL 指向、版本选择、离线镜像与 TLS 配置【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本篇指南面向所有将 OneUptime 自托管部署在企业内部并通过 Terraform 以基础设施即代码方式管理监控资源的工程团队。OneUptime 的 Terraform Provider 在云版本与自托管版本之间完全同构——资源、属性、行为完全一致唯一需要调整的只有实例地址oneuptime_url与版本选择规则。读完本文你将掌握如何把 Provider 指向自有实例、按平台版本精确选择 Provider 版本、在完全离线的内网中镜像 Provider以及正确处理 TLS 信任链从而让 Terraform 在你的私有 OneUptime 环境上顺畅地管理监控器、状态页、标签等全部资源。本文对应的官方文档为 App/FeatureSet/Docs/Content/en/terraform/self-hosted.md并配合仓库中的 Terraform Provider 生成器、发布脚本 与本地安装脚本进行源码级佐证。核心前提云与自托管共享同一个 ProviderOneUptime 的 Terraform Provider 只有一份同时面向云端与自托管同一套资源与数据源oneuptime_monitor、oneuptime_status_page、oneuptime_label、oneuptime_team、oneuptime_on_call_policy等命名空间完全一致资源清单与用途可参考 App/FeatureSet/Docs/Content/en/terraform/index.md。同一套认证模型均使用在Project Settings API Keys下创建的项目级 API Key。仅两点不同一是 Provider 连接的目标 URL二是版本选择的上界规则。这意味着你在云端环境里写好的.tf配置迁到自托管环境时几乎不需要改动——只需在 provider 块中补充oneuptime_url并按平台版本收紧版本约束即可。从源码结构看这一点也被生成器架构所印证Provider 完全由 GenerateProvider.ts 从 OneUptime 的 OpenAPI 规范自动生成并不存在单独的自托管版或云版产物生成的 Go 代码里唯一与部署形态相关的输入就是运行时通过 provider 参数传入的 URL。将 Provider 指向你的实例配置oneuptime_url在provider块中设置oneuptime_url值为你实例的origin源——只包含 scheme 与主机名正确示例https://oneuptime.example.com不要带/api后缀不要带任何路径如/dashboard不要带端口以外的额外内容除非实例运行在非标准端口Provider 会在内部自行拼接所有 API 路径关于 URL 拼接的规则可参考 troubleshooting 中 Self-hosted: URL and TLS issues 一节。最小可运行配置如下terraform { required_providers { oneuptime { source oneuptime/oneuptime version ~ 11.0 } } } provider oneuptime { oneuptime_url https://oneuptime.example.com # api_key 从 ONEUPTIME_API_KEY 环境变量读取或显式指定 # api_key var.oneuptime_api_key }环境变量方式两个核心配置均支持环境变量这能让同一套配置在云与自托管根环境之间保持可移植无需修改.tf文件export ONEUPTIME_URLhttps://oneuptime.example.com export ONEUPTIME_API_KEYyour-project-api-key其中ONEUPTIME_API_KEY是项目 API Key创建位置与云端完全一致Project Settings API Keys。注意自托管的 master key 不可用。master key 不绑定任何项目用它发起的每次资源调用都会报ProjectId required。这是 OneUptime 两类凭据的本质区别项目 API Key 绑定单一项目Provider 直接从 Key 中推导项目而 master key / 用户级 token 不携带项目信息因此无法驱动 Provider。详见 troubleshooting 中的 ProjectId required 一节。若你的环境允许建议在.tf中使用var.oneuptime_api_key并从环境变量或变量文件注入避免密钥进入版本库。选择合适的 Provider 版本版本跟踪规则Provider 的版本号跟随 OneUptime 平台版本Provider 11.x 由 OneUptime 11.x 生成并针对其测试。这一机制在源码中有直接体现——GenerateProvider.ts 在生成 Provider 时直接读取仓库根目录的 VERSION 文件并将该版本号写入生成的 Provider当前仓库的 VERSION 为13.0.7随后由发布脚本按此版本打 tag 发布。因此每次平台发版Provider 的生成与发布都自动同步。对于自托管环境选版本的口诀是使用最新已发布且小于或等于你的 OneUptime 平台版本的 Provider 版本。两条硬性禁忌绝不使用比平台更新的 Provider——它可能驱动你当前安装尚未具备的 API 字段导致 plan/apply 异常。绝不锁定精确 patch 版本——并非每个平台 patch 都会发布到 Registry 11.0.7这种精确锁定经常因no matching version found失败。用有界约束表达选择规则把规则表达为有界版本约束。例如你的安装运行平台版本11.2.xversion 11.0, 11.2Terraform 会在此区间内自动选择最新已发布的 11.x 版本自动跳过任何未发布的 patch。如果你对平台大版本跟进较宽松、且保持较新~ 11.0也同样适用悲观约束总是能解析到一个真实存在的已发布版本这正是 registry 文档 所强调的。查找平台版本在 OneUptimeadmin dashboard中查看。或从你的Helm / Docker Compose部署配置值中读取——仓库根目录的 docker-compose.yml 与 HelmChart 中的镜像 tag 即平台版本。升级顺序重要先升级 OneUptime 平台本身再上调 Provider 的版本约束最后执行terraform init -upgrade让 Terraform 重新解析约束并更新.terraform.lock.hcl。顺序颠倒先用新 Provider 连旧平台会踩到Provider 驱动了平台还没有的 API 字段的坑。升级 Provider 后建议紧跟terraform plan确认无意外变更。离线Air-gapped环境镜像 Provider如果运行 Terraform 的主机无法访问registry.terraform.io需要将 Provider 镜像到内网。完整流程如下。第一步在有网机器上拉取镜像mkdir -p /srv/terraform-mirror cd /path/to/your/terraform/config # 一个 required_providers 中包含 oneuptime 的目录 terraform providers mirror /srv/terraform-mirrorterraform providers mirror会按你的版本约束下载 Provider 的发行包覆盖所有平台并按 Terraform 可识别的目录布局落盘。注意这一步需要在一个包含required_providers声明的配置目录中执行约束决定了拉取哪些版本。第二步传输并提供镜像将/srv/terraform-mirror目录整体传输到内网通过普通 HTTPS 文件服务器对外提供或直接作为文件系统路径共享。第三步配置 CLI 指向镜像在运行 Terraform 的每台机器上编辑 CLI 配置~/.terraformrcprovider_installation { filesystem_mirror { path /srv/terraform-mirror include [registry.terraform.io/oneuptime/oneuptime] } direct { exclude [registry.terraform.io/oneuptime/oneuptime] } }此时terraform init会从镜像安装 OneUptime Provider其余 Provider 仍按原方式获取若希望完全强制走镜像、禁止任何直连删掉direct块即可。维护要点每次上调版本约束后都要重新执行一次terraform providers mirror让镜像包含新版本。从源码佐证看Terraform 的镜像机制依赖 Provider 的注册表插件目录布局——本地安装脚本 中可见插件被安装到~/.terraform.d/plugins/registry.terraform.io/oneuptime/oneuptime/version/os_arch/这与filesystem_mirror期望的目录结构一致也解释了为什么镜像内容可以无缝替换网络下载。TLS 注意事项Terraform 是 Go 程序校验实例证书时使用运行 Terraform 机器的系统信任库。自托管场景常见的 TLS 坑与对策如下私有 CA 证书如果实例使用私有 CA 签发的证书必须在**每一台运行 Terraform 的机器含 CI Runner**上安装该 CADebian/Ubuntu将 CA 复制到/usr/local/share/ca-certificates/后执行update-ca-certificates。其他发行版/系统使用其对应的系统信任库更新方式。没有跳过 TLS 校验开关Provider刻意不提供跳过 TLS 验证的属性。如果看到x509: certificate signed by unknown authority正确做法是修复信任链安装 CA而不是想办法绕过校验。这也是 OneUptime Provider 的安全设计底线——详见 troubleshooting 中该错误行的处理建议。明文 HTTP 仅限实验室明文 HTTP 可用于实验环境oneuptime_url http://oneuptime.lab.internal但项目 API Key 会随每次请求发送因此任何超出一次性实验室用途的环境都必须启用 TLS。反向代理 / Ingress 场景如果 OneUptime 位于反向代理或 Ingress 之后oneuptime_url必须填写代理对外暴露的外部 origin确保代理原样转发所有/api路径不做改写、不丢弃路径前缀否则 Provider 的 API 调用会 404。常见错误速查自托管相关将 troubleshooting 中与自托管强相关的条目摘录如下便于按症状快速定位症状可能原因修复ProjectId required每次操作都报使用了 master key 或用户 key 而非项目 API Key在Project Settings API Keys创建项目 Key 并使用x509: certificate signed by unknown authority实例证书不被 Terraform 所在主机信任在该机器上安装 CA 证书所有 API 调用Connection refused/ 404oneuptime_url错误带了路径后缀、端口错误、http/https 不符设置为裸 origin如https://oneuptime.example.comno matching version found for oneuptime/oneuptime精确锁定了一个从未发布的 patch 版本改用悲观约束~ 11.0Provider produced inconsistent result after apply旧版 Provider 处理服务端计算字段有误升级到当前 11.x Provider 并terraform init -upgrade关于版本号全貌Provider 版本追踪平台版本且并非每个平台 patch 都会发布到 Registry生成器只在有意义的变化时重新生成并发布具体发布流程见 publish-terraform-provider.sh这正是不要 pin 精确 patch这一规则的根源。发布机制与版本历史的详细说明见 registry 文档。相关文档导航Registry 使用说明 —— 版本如何发布、版本号规则与发布说明故障排查 —— URL、TLS、Key 错误的详细剖析快速开始 —— 第一次 apply自托管下完全相同的流程完整指南 —— 认证选项、项目布局、依赖与数据源示例配置 —— 各主要资源类型的可直接复制配置Terraform Provider 生成器 —— 理解 Provider 由 OpenAPI 规范自动生成的底层机制【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考