OneUptime Terraform Provider 自托管部署指南URL 指向、版本约束、离线镜像与 TLS 配置【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime这篇技术指南完整讲解如何让 OneUptime 官方 Terraform Provider 对接你自己部署self-hosted的 OneUptime 实例从oneuptime_url的正确书写、项目 API Key 的获取到与平台版本严格对应的 provider 版本约束策略、离线air-gapped网络下的 provider 镜像以及私有 CA 场景的 TLS 信任配置。读完本文你将能够在自托管 OneUptime 上稳定运行terraform init / plan / apply并快速定位ProjectId required、x509: certificate signed by unknown authority、no matching version found等高频报错。自托管与云端的唯一差异URL 与版本规则OneUptime 的 Terraform Provider 本身对云端与自托管完全一致——相同的资源类型oneuptime_project、oneuptime_monitor等、相同的属性、相同的认证方式。自托管场景下真正不同的只有两点把 provider 指向你实例的地址oneuptime_url/ONEUPTIME_URLprovider 版本必须受你的平台版本约束。这一设计在仓库中也有印证provider 是由 OneUptime 的 OpenAPI 规范自动生成的生成器位于 Scripts/TerraformProvider/Core/ProviderGenerator.ts生成流程见 Scripts/TerraformProvider/README.md生成出的 Go 客户端只关心URL API Key两个配置并不会区分目标实例是云服务还是自托管。将 Provider 指向你的实例1. 在 provider 块中设置oneuptime_urloneuptime_url必须是实例的origin——只包含 scheme 和主机名不要带/api后缀也不要带任何路径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 }为什么不能写/api因为 provider 的 HTTP 客户端会自动拼接从源码看生成器产出的NewClient会先确保 URL 带 scheme再把末尾的/去掉、追加/api最后做一次url.Parse校验非法地址会直接返回invalid oneuptime_url错误见 ProviderGenerator.ts。所以https://oneuptime.example.com会被规范化为实际请求基址https://oneuptime.example.com/api而如果你多写了一个/api就会变成https://oneuptime.example.com/api/api。2. 用环境变量保持配置可移植URL 与 API Key 都支持环境变量这让同一份.tf配置可以在云端与自托管之间切换而不改代码export ONEUPTIME_URLhttps://oneuptime.example.com export ONEUPTIME_API_KEYyour-project-api-key这两个环境变量名与生成器代码一一对应provider schema 中oneuptime_url、api_key两个属性在未显式设置时会回退到ONEUPTIME_URL与ONEUPTIME_API_KEY见 ProviderGenerator.ts。需要特别注意的是API Key 是必填的若属性与环境变量都缺失provider 会在terraform plan启动阶段直接报错 API key is required for authentication。3. 必须使用项目 API Keyproject API keyAPI Key 必须是在你的实例 Dashboard 的Project Settings项目设置 API Keys中创建的项目级 API Key云端与自托管完全一样。自托管的主密钥master key不能使用——因为 provider 是从 Key 本身推导项目归属的主密钥不绑定任何项目调用任何资源都会失败并报ProjectId required详见 Troubleshooting。最佳实践是为 Terraform 单独创建一个项目 API Key并只授予你需要管理的资源类型的 Create/Read/Update/Delete 权限导入import至少需要 Read 权限。选择 Provider 版本跟随平台版本Provider 版本与 OneUptime 平台版本一一对应自托管场景的核心规则是使用小于或等于你的 OneUptime 平台版本的、已发布的最新 provider 版本。具体有三条纪律绝不要使用比平台更新的 provider——新版 provider 可能会驱动你的安装尚未具备的 API 字段导致请求失败或状态漂移不要锁定精确补丁版本——并非每个平台补丁都会发布到 Registry 11.0.7这类精确锁定经常报no matching version found用有界约束表达规则。例如平台运行在11.2.xversion 11.0, 11.2Terraform 会自动挑选已发布的不超过 11.2 的最新 11.x 版本跳过任何未发布的补丁。如果你跟踪平台大版本比较松散且保持较新~ 11.0也可以。平台版本号可以从 OneUptime 管理后台查看或从你的 Helm Chart / Docker Compose 部署值仓库中的 docker-compose.yml 与 HelmChart中找到。已发布的 provider 版本以 Terraform Registry 上的oneuptime/oneuptime版本列表为准。升级顺序重要先升级 OneUptime 平台再调高 provider 的版本约束并执行terraform init -upgrade。顺序反了旧平台会被新版 provider 用不存在的 API 字段驱动而报错。离线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 认识的目录布局中。之后把该目录拷进内网用纯 HTTPS 文件服务器托管或作为文件系统路径共享并在 CLI 配置~/.terraformrc中指向它provider_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把新版本补进镜像目录。TLS 注意事项Terraform 是 Go 程序它会用运行 Terraform 的机器的系统信任库来校验你的实例证书。如果实例用的是私有 CA 签发的证书必须在所有运行 Terraform 的机器包括 CI Runner上安装该 CA 证书。Debian/Ubuntu 上把 CA 复制到/usr/local/share/ca-certificates/然后运行update-ca-certificates。没有跳过 TLS 校验的属性这是刻意设计。如果报x509: certificate signed by unknown authority正确的做法是修复信任链而不是想方设法关掉校验。明文 HTTP 仅限实验室oneuptime_url http://oneuptime.lab.internal这样的写法在一次性测试环境可行但项目 API Key 会随每次请求发出任何非临时环境都应当用 TLS。反向代理 / Ingress 场景如果 OneUptime 在反向代理或 Ingress 后面oneuptime_url填的是代理对外暴露的 origin。务必确认代理把/api下所有路径原样转发不要改写路径前缀。自托管高频错误快速对照报错常见原因修复方式ProjectId required每次操作用了主密钥或用户级 token 而非项目 API Key在Project Settings API Keys创建项目 Key 并使用x509: certificate signed by unknown authority实例的 TLS 证书不被 Terraform 所在机器信任把 CA 证书装进该机器的系统信任库每次 API 调用 Connection refused / 404oneuptime_url写错带路径后缀、端口错误、http/https 不匹配填纯实例 origin如https://oneuptime.example.comno matching version found for oneuptime/oneuptime精确锁定了从未发布过的补丁版本改用~ 11.0或 11.0, 11.2这类有界约束provider 启动时报缺少 API Key既没写api_key属性也没有ONEUPTIME_API_KEY环境变量两者至少配置其一针对自托管 URL 与 TLS 的更完整排查细节可参考 Troubleshooting其余场景均可直接套用云端用法例如 Quick Start 的首次terraform apply在自托管下同样成立。相关页面Registry UsageRegistry 使用与版本发布机制TroubleshootingURL、TLS、Key 错误的详细排查Quick Start首次 apply自托管下用法相同【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考