OneUptime 自建部署 Terraform Provider 配置指南：URL 指向、版本选型、离线镜像与 TLS 信任

OneUptime 自建部署 Terraform Provider 配置指南URL 指向、版本选型、离线镜像与 TLS 信任【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文面向在自建self-hostedOneUptime 实例上使用官方 Terraform Provideroneuptime/oneuptime的场景。文中将说明如何把 Provider 指向你自己的实例、如何依据平台版本选择正确的 Provider 版本、如何在无法访问公网 Terraform Registry 的隔离网络中离线镜像 Provider以及自建实例常见的 TLS 信任问题并结合仓库中 Provider 的生成与发布实现说明其背后的工作原理。核心前提云端与自建的 Provider 完全一致差异只有两处OneUptime 的 Terraform Provider 对 OneUptime Cloud 和自建实例而言是同一个 Provider——资源类型、属性定义、认证方式完全一致没有独立的自建版二进制。二者真正的差别只有两点目标地址自建时需要显式配置oneuptime_url指向你自己的实例版本选择规则云端永远使用最新 Provider自建时需要使用小于等于你平台版本的已发布 Provider 版本。这一点在仓库的 Terraform 文档索引 中有明确说明Provider 管理 monitor、status page、team、label、on-call 策略、incident、probe 等资源同时适用于 OneUptime Cloud 与自建安装。本文聚焦的 Self-Hosted Setup 正是该文档体系中专门讨论自建接入的部分。一、将 Provider 指向你的自建实例1.1 通过oneuptime_url指定实例源在provider块中oneuptime_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 会自行拼接 API 路径——这一点在 Troubleshooting 文档 中有明确说明The provider appends API paths itself。若填写了/api或额外的路径段所有 API 调用都会变成 404 或连接拒绝。从源码结构看该 Provider 并非手工维护而是由仓库中的 Scripts/TerraformProvider 生成器根据 OneUptime 的 OpenAPI 规范自动生成详见下文第五节因此其 URL 处理与 API 路径拼接逻辑是全局统一实现的这也是同一 Provider 同时服务云端与自建能够成立的原因。1.2 使用环境变量保持配置可移植oneuptime_url与api_key两个配置项都支持环境变量形式这让同一套 Terraform 配置可以在云端与自建之间无缝切换切换时只需改环境变量不改.tf文件export ONEUPTIME_URLhttps://oneuptime.example.com export ONEUPTIME_API_KEYyour-project-api-key在 Complete Guide 的配置参数表中可以看到两个属性的默认行为属性必填环境变量回退默认值api_key否可回退到环境变量ONEUPTIME_API_KEY—oneuptime_url否ONEUPTIME_URLhttps://oneuptime.com也就是说不设置oneuptime_url时默认指向云端https://oneuptime.com自建用户只要显式设置即可覆盖默认值。1.3 API Key 必须是项目级 API Key自建实例的认证凭证有一个容易踩的坑必须使用项目级project-scopedAPI Key而不是自建实例的 master key。项目 API Key 在实例 Dashboard 的Ajustes del proyecto项目设置 Claves APIAPI Keys中创建与云端完全一致自建实例的 master key 不属于任何项目用它调用 API 会以ProjectId required报错。Provider 是从 API Key 本身推导项目归属的master key 不带项目信息因此每个资源调用都会失败。相关错误细节可参考 Troubleshooting 中的 ProjectId required 一节其中对比了项目 API Key、master key 与用户级 token 三类凭证的差异。二、版本选型永远不要比你的平台版本新2.1 选择规则Provider 版本与 OneUptime 平台版本是一一跟踪的关系Provider 11.x 是由 OneUptime 11.x 的 API 生成并针对其测试的。自建部署的选型规则是使用最新已发布、且小于等于你平台版本的 Provider 版本。理由如下不要用比平台更新的 Provider新版 Provider 可能引用了你的旧平台还没有的 API 字段导致terraform plan/apply失败不要精确锁定 patch 版本并非平台的每个 patch 都会发布到 Registry 11.0.7这类精确锁定经常遇到no matching version found错误。2.2 用有界约束表达规则规则应当表达为一个有界bounded的版本约束。例如你的安装运行在平台版本11.2.xversion 11.0, 11.2Terraform 会自动选择最新已发布、且不超过 11.2的 11.x 版本自动跳过任何未发布的 patch。如果你的平台大版本跟踪比较宽松、且保持较新直接用~ 11.0悲观约束也没有问题。2.3 如何确认平台版本与已发布版本平台版本在 OneUptime 管理后台查看或从 Helm/Docker Compose 的部署参数中读取本仓库根目录的 docker-compose.yml 与 HelmChart 目录即为自建部署的配置来源已发布 Provider 版本在 Terraform Registry 的oneuptime/oneuptime版本列表页查看。2.4 升级顺序先升级 OneUptime 平台再提高 Provider 的版本约束然后执行terraform init -upgrade-upgrade会重新解析约束、更新.terraform.lock.hcl并打印选中的版本之后建议紧跟terraform plan确认没有意外变化。这也是 Registry Usage 文档 推荐的升级流程。2.5 为什么版本缺口是正常的从发布机制看Provider 是按有意义变更重新生成并发布的而不是跟随平台的每个 patch release 发布一次。仓库中的发布脚本 publish-terraform-provider.sh 展示了完整的发布流水线先由生成器产出 Go 代码、再通过 GoReleaser 交叉编译出多平台二进制、生成 SHA256SUMS 校验和与签名最后推送 tag 并发布到 Terraform Registry。整个流程只在有实际代码变更时触发脚本中有明确的 no-change 跳过逻辑因此平台发了 11.2.1Registry 上却没有 11.2.1是正常现象——这正是不能精确锁定 patch 版本的根本原因。三、离线Air-gapped环境镜像 Provider 到内网3.1 为什么需要镜像如果运行 Terraform 的主机无法访问公网的registry.terraform.ioterraform init将无法下载 Provider。解决方案是在有公网访问的机器上先把 Provider 下载并整理成 Terraform 可识别的目录布局再传输到内网。3.2 生成镜像在联网机器上执行mkdir -p /srv/terraform-mirror cd /path/to/your/terraform/config # 该目录的 required_providers 中需包含 oneuptime terraform providers mirror /srv/terraform-mirrorterraform providers mirror会根据你的版本约束为所有平台下载匹配的 Provider 发行版Linux/macOS/Windows 的 amd64 与 arm64整理成 Terraform 可直接读取的目录结构。3.3 配置 Terraform 使用镜像将镜像目录传输到内网后可以用简单的 HTTPS 文件服务器托管或直接作为文件系统路径共享。然后在 Terraform 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块即可。3.4 维护镜像每次提高版本约束后都要重新运行terraform providers mirror否则镜像中没有新版本。同时建议将.terraform.lock.hcl提交到版本库——它记录了精确选定的 Provider 版本与校验和是 CI 可复现的关键。四、TLS 注意事项信任证书而不是跳过校验自建实例几乎总是运行在自定义域名或内网域名下TLS 相关的坑集中在证书信任上Terraform 是 Go 程序它验证实例证书时使用运行 Terraform 机器的系统信任库而不是浏览器或其他程序的证书库。如果实例使用私有 CA 签发的证书必须在每一台运行 Terraform 的机器包括 CI runner上安装该 CA 证书。Debian/Ubuntu 下# 将 CA 证书复制到系统 CA 目录 # /usr/local/share/ca-certificates/ sudo update-ca-certificates刻意不提供跳过 TLS 验证的属性如果遇到x509: certificate signed by unknown authority正确的做法是修复信任关系而不是尝试关闭验证。这是安全设计上的有意取舍。实验室环境可用明文 HTTPoneuptime_url http://oneuptime.lab.internal在一次性实验室场景下可以工作但项目 API Key 会随每个请求发送任何非一次性环境都应使用 TLS。反向代理/Ingress 场景如果 OneUptime 位于反向代理或 Ingress 之后oneuptime_url应填写代理对外暴露的external origin外部源并确保代理原样转发所有/api路径不做路径改写。这与你访问实例时浏览器地址栏中的地址一致例如https://oneuptime.example.com。相关的 URL 与 TLS 排查细节可对照 Troubleshooting 中 Self-hosted: URL and TLS issues 一节。五、源码级视角Provider 如何生成与发布理解了上面的配置规则后从仓库源码看 Provider 的来龙去脉会更有帮助。5.1 Provider 由 OpenAPI 规范自动生成本仓库的 Scripts/TerraformProvider 目录实现了一个动态 Terraform Provider 生成器用 TypeScript 编写根据 OneUptime 的OpenAPI 规范自动生成完整的、可发布的 Go 语言 Terraform Provider自动从 OpenAPI 的 tag 与 endpoint 发现资源由 HTTP 方法映射 CRUD 操作POST→Create、GET→Read、PUT/PATCH→Update、DELETE→Delete从 GET endpoint 生成对应的 data source同时自动生成 Terraform Registry 所需的文档与示例。生成的核心流水线记录在 Scripts/TerraformProvider/README.md 中OpenAPI Spec → Parser → Resource Discovery → Code Generation → Build System ↓ ↓ ↓ ↓ ↓ JSON Schema → Operations → Resources/DataSources → Go Files → Terraform Provider这解释了为什么 Provider 能覆盖 100 资源类型、为什么每个资源都有同名的 data source如data oneuptime_label——它们都来自同一个 OpenAPI 规范而不是手工维护的产物。5.2 发布机制决定了版本缺口的必然性发布脚本 publish-terraform-provider.sh 体现了 Provider 版本的发布纪律先本地生成 Provider 代码并运行go vet/go test测试通过后才推送避免把坏版本发布到 Registry用 GoReleaser 交叉编译多平台二进制生成 SHA256SUMS 校验和、GPG 签名与 Terraform Registry manifest只有检测到实际代码变更时才创建 tag 并发布VERSION文件的强制时间戳被排除在变更检测之外没有变更时跳过整个发布流程No provider changes detected ... skipping publish entirely。这正是 Registry Usage 文档 所描述的按有意义变更发布、而非每个 patch 都发布的具体实现——也直接印证了自建用户在版本选型时必须用约束如~ 11.0或 11.0, 11.2而不是精确 patch 锁定的原因。六、快速自查清单在自建实例上接入 Terraform Provider 时可按以下清单核对检查项正确做法错误示例oneuptime_url仅 scheme 主机名如https://oneuptime.example.com带/api后缀或路径API Key项目 API Key项目设置 API Keys 创建master key报ProjectId required版本约束~ 11.0或 11.0, 11.2 11.0.7精确锁定私有 CA安装 CA 到系统信任库寻找跳过 TLS 验证开关离线环境terraform providers mirror~/.terraformrc镜像配置直接terraform init无法联网升级先升级平台再terraform init -upgrade先升 Provider 版本相关文档导航Self-Hosted Setup本文档源英文版 —— 自建接入的完整说明Quick Start —— 首次 apply 的完整流程自建与云端操作一致Registry Usage —— 版本如何发布、如何选版本Troubleshooting —— URL、TLS、API Key 等错误的详细排查Complete Guide —— 认证方式、项目结构与状态管理Scripts/TerraformProvider/README.md —— Provider 生成器的架构与工作原理【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考