OneUptime 自托管实例接入 Terraform Provider 完整指南URL 配置、版本选择、离线镜像与 TLS【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文是一份针对 OneUptime 自托管部署的 Terraform Provider 使用指南核心解决四个问题如何让 provider 指向你自己的 OneUptime 实例、如何为自托管平台选择正确的 provider 版本、如何在气隙air-gapped网络中离线镜像 provider、以及自托管环境下的 TLS 信任配置。读完本文你将能独立为自托管 OneUptime 搭建一套可复现、可升级的 IaC 工作流。背景云上与自托管的唯一差异OneUptime 的 Terraform Provider 本身在云端oneuptime.com与自托管部署之间是完全一致的——资源类型相同、属性相同、行为相同。两者的差异只有两点连接地址oneuptime_url不同版本选择规则不同自托管需要让 provider 版本与你的平台版本匹配。这个结论在 Self-Hosted Setup 文档 中被明确表述也是后续所有配置的原则性前提你不需要为自托管准备另一套 provider 或另一份资源配置只需调整连接参数与版本约束。将 provider 指向你的自托管实例在 Terraform 配置中通过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 }这两个配置项也都支持环境变量从而让同一套配置在云端与自托管之间可移植export ONEUPTIME_URLhttps://oneuptime.example.com export ONEUPTIME_API_KEYyour-project-api-key源码级验证provider 如何解析 URL从 provider 生成器源码 Scripts/TerraformProvider/Core/ProviderGenerator.ts 可以看出底层实现逻辑schema 定义oneuptime_url的官方描述为 “The oneuptime URL (without /api path). Defaults to oneuptime.com if not specified. The provider automatically appends /api to the URL.”不含/api路径未指定时默认oneuptime.comprovider 会自动拼接/api。api_key被标记为Sensitive: true这正是官方建议用环境变量注入而不是写死在.tf文件里的原因。客户端构造生成的client.go中的NewClient如果oneuptime_url不以http://或https://开头会自动补上https://随后去掉末尾/并追加/api最终得到请求基准地址。环境变量回退当oneuptime_url属性为 null 时读取ONEUPTIME_URL仍未设置则回退到oneuptime.com。api_key为 null 时读取ONEUPTIME_API_KEY两者都缺失则直接报Missing API Key错误。请求头每次请求都会携带Content-Type: application/json、User-Agent: terraform-provider-oneuptime/version以及APIKey头——这也解释了后文“API Key 随每个请求发送”的 TLS 建议。也就是说你在oneuptime_url里填的地址会先被规范化补 scheme、拼/api再发起请求任何多余路径或后缀都可能造成连接失败。API Key必须是项目级 API Key这里使用的 API Key 是项目 API Keyproject API key在实例控制台的Project Settings API Keys中创建与云端完全一致。自托管的 master key主密钥不能使用用它调用会报ProjectId required错误因为 master key 不归属于任何项目provider 无法从密钥推导出目标项目详见 Troubleshooting 中对 “ProjectId required” 的专节说明。完整创建步骤命名、设置过期时间、授予 Create/Read/Update/Delete 权限参见 Quick Start。为自托管平台选择 provider 版本Provider 版本跟随 OneUptime 平台版本演进。自托管的版本选择规则是使用不大于你的 OneUptime 平台版本的、最新已发布的 provider 版本。两个必须避免的陷阱绝不使用比平台更新的 provider——它可能驱动你的安装版本尚不存在的 API 字段不要固定精确补丁版本——并非每个平台补丁都会发布到 registry 11.0.7这种精确锁定通常会报no matching version found。正确做法是把规则表达为一个有界约束bounded constraint。例如你的平台运行在11.2.xversion 11.0, 11.2Terraform 会自动选择不超过 11.2 的最新已发布 11.x 版本自动跳过未发布的补丁。如果对平台大版本跟踪较宽松且保持较新~ 11.0这类悲观约束pessimistic constraint也完全够用。如何获取平台版本与已发布版本平台版本在 OneUptime 管理后台查看或从你的 Helm / Docker Compose 部署值中读取已发布 provider 版本官方文档指向 registry.terraform.io 上的 oneuptime provider 版本列表页以文档原文为准本文不赘述外部链接。升级顺序重要先升级 OneUptime 平台再提升 provider 约束并执行terraform init -upgrade。顺序颠倒会导致 provider 驱动平台尚不支持的字段而失败。气隙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块则强制只走镜像。每次提升版本约束后都要重新执行mirror命令否则镜像里的版本不满足新约束。TLS 注意事项Terraform 是 Go 程序它会针对运行 Terraform 机器的**系统信任库system trust store**校验实例证书。如果实例使用私有 CA 签发的证书必须在每台运行 Terraform 的机器以及 CI runner上安装该 CA 证书。Debian/Ubuntu 的做法是复制 CA 到/usr/local/share/ca-certificates/并执行update-ca-certificates。没有 “skip TLS verification” 属性有意为之如果看到x509: certificate signed by unknown authority正确做法是修复信任而不是关闭校验。从 ProviderGenerator.ts 生成的 schema 也可以确认provider 属性只有oneuptime_url和api_key不存在任何跳过证书校验的开关。纯 HTTP 仅限实验环境oneuptime_url http://oneuptime.lab.internal在实验室可用但项目 API Key 会随每个请求发送任何超出临时实验范围的环境都应使用 TLS。反向代理 / Ingress 场景如果 OneUptime 位于反向代理或 Ingress 之后oneuptime_url应填写代理暴露的外部 origin同时确保代理原样转发所有/api路径不要改写路径前缀因为 provider 会自行拼接/api路径。自托管常见连接错误的快速对照结合 Troubleshooting 中的症状表自托管最常遇到的问题包括症状原因修复ProjectId required使用了 master key 或用户级 token在 Project Settings API Keys 创建项目 API Key每次 API 调用 Connection refused / 404oneuptime_url错误带路径后缀、端口错、http/https 不符填裸 origin如https://oneuptime.example.comx509: certificate signed by unknown authority实例证书不在 Terraform 主机信任库安装 CA 证书勿尝试关闭校验no matching version found精确锁定从未发布的补丁版本使用~ 11.0或有界约束从零到 apply 的自托管最小示例将上述要点串成一个完整可运行的自托管示例结合 Quick Start 的资源写法terraform { required_providers { oneuptime { source oneuptime/oneuptime version 11.0, 11.2 # 根据你的平台版本调整上界 } } } provider oneuptime { oneuptime_url https://oneuptime.example.com # 自托管填实例 origin } 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] }执行流程与云端完全一致export ONEUPTIME_API_KEYyour-project-api-key terraform init terraform plan terraform apply完成后可在控制台验证 Monitor、Status Page、Label 均已创建再次terraform plan应报告No changes.服务端计算字段如 slug、当前状态、默认监控步骤不会造成漂移。测试完可用terraform destroy清理。如果追求 OpenTofu 兼容性仓库还提供 OpenTofu 文档 和 OpenTofu 示例配置。关联文档导航Registry Usage — provider 版本的发布机制与 release notesTroubleshooting — URL、TLS、密钥类错误的详细排查Quick Start — 首次 apply 的完整流程自托管同样适用Complete Guide — 认证选项、项目布局、依赖关系、data source、remote stateMonitor Steps — 精细控制监控项检查内容Importing Resources — 采纳控制台中已创建的资源Examples — 各类主要资源类型的完整配置模板。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime 自托管实例接入 Terraform Provider 完整指南：URL 配置、版本选择、离线镜像与 TLS
OneUptime 自托管实例接入 Terraform Provider 完整指南URL 配置、版本选择、离线镜像与 TLS【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文是一份针对 OneUptime 自托管部署的 Terraform Provider 使用指南核心解决四个问题如何让 provider 指向你自己的 OneUptime 实例、如何为自托管平台选择正确的 provider 版本、如何在气隙air-gapped网络中离线镜像 provider、以及自托管环境下的 TLS 信任配置。读完本文你将能独立为自托管 OneUptime 搭建一套可复现、可升级的 IaC 工作流。背景云上与自托管的唯一差异OneUptime 的 Terraform Provider 本身在云端oneuptime.com与自托管部署之间是完全一致的——资源类型相同、属性相同、行为相同。两者的差异只有两点连接地址oneuptime_url不同版本选择规则不同自托管需要让 provider 版本与你的平台版本匹配。这个结论在 Self-Hosted Setup 文档 中被明确表述也是后续所有配置的原则性前提你不需要为自托管准备另一套 provider 或另一份资源配置只需调整连接参数与版本约束。将 provider 指向你的自托管实例在 Terraform 配置中通过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 }这两个配置项也都支持环境变量从而让同一套配置在云端与自托管之间可移植export ONEUPTIME_URLhttps://oneuptime.example.com export ONEUPTIME_API_KEYyour-project-api-key源码级验证provider 如何解析 URL从 provider 生成器源码 Scripts/TerraformProvider/Core/ProviderGenerator.ts 可以看出底层实现逻辑schema 定义oneuptime_url的官方描述为 “The oneuptime URL (without /api path). Defaults to oneuptime.com if not specified. The provider automatically appends /api to the URL.”不含/api路径未指定时默认oneuptime.comprovider 会自动拼接/api。api_key被标记为Sensitive: true这正是官方建议用环境变量注入而不是写死在.tf文件里的原因。客户端构造生成的client.go中的NewClient如果oneuptime_url不以http://或https://开头会自动补上https://随后去掉末尾/并追加/api最终得到请求基准地址。环境变量回退当oneuptime_url属性为 null 时读取ONEUPTIME_URL仍未设置则回退到oneuptime.com。api_key为 null 时读取ONEUPTIME_API_KEY两者都缺失则直接报Missing API Key错误。请求头每次请求都会携带Content-Type: application/json、User-Agent: terraform-provider-oneuptime/version以及APIKey头——这也解释了后文“API Key 随每个请求发送”的 TLS 建议。也就是说你在oneuptime_url里填的地址会先被规范化补 scheme、拼/api再发起请求任何多余路径或后缀都可能造成连接失败。API Key必须是项目级 API Key这里使用的 API Key 是项目 API Keyproject API key在实例控制台的Project Settings API Keys中创建与云端完全一致。自托管的 master key主密钥不能使用用它调用会报ProjectId required错误因为 master key 不归属于任何项目provider 无法从密钥推导出目标项目详见 Troubleshooting 中对 “ProjectId required” 的专节说明。完整创建步骤命名、设置过期时间、授予 Create/Read/Update/Delete 权限参见 Quick Start。为自托管平台选择 provider 版本Provider 版本跟随 OneUptime 平台版本演进。自托管的版本选择规则是使用不大于你的 OneUptime 平台版本的、最新已发布的 provider 版本。两个必须避免的陷阱绝不使用比平台更新的 provider——它可能驱动你的安装版本尚不存在的 API 字段不要固定精确补丁版本——并非每个平台补丁都会发布到 registry 11.0.7这种精确锁定通常会报no matching version found。正确做法是把规则表达为一个有界约束bounded constraint。例如你的平台运行在11.2.xversion 11.0, 11.2Terraform 会自动选择不超过 11.2 的最新已发布 11.x 版本自动跳过未发布的补丁。如果对平台大版本跟踪较宽松且保持较新~ 11.0这类悲观约束pessimistic constraint也完全够用。如何获取平台版本与已发布版本平台版本在 OneUptime 管理后台查看或从你的 Helm / Docker Compose 部署值中读取已发布 provider 版本官方文档指向 registry.terraform.io 上的 oneuptime provider 版本列表页以文档原文为准本文不赘述外部链接。升级顺序重要先升级 OneUptime 平台再提升 provider 约束并执行terraform init -upgrade。顺序颠倒会导致 provider 驱动平台尚不支持的字段而失败。气隙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块则强制只走镜像。每次提升版本约束后都要重新执行mirror命令否则镜像里的版本不满足新约束。TLS 注意事项Terraform 是 Go 程序它会针对运行 Terraform 机器的**系统信任库system trust store**校验实例证书。如果实例使用私有 CA 签发的证书必须在每台运行 Terraform 的机器以及 CI runner上安装该 CA 证书。Debian/Ubuntu 的做法是复制 CA 到/usr/local/share/ca-certificates/并执行update-ca-certificates。没有 “skip TLS verification” 属性有意为之如果看到x509: certificate signed by unknown authority正确做法是修复信任而不是关闭校验。从 ProviderGenerator.ts 生成的 schema 也可以确认provider 属性只有oneuptime_url和api_key不存在任何跳过证书校验的开关。纯 HTTP 仅限实验环境oneuptime_url http://oneuptime.lab.internal在实验室可用但项目 API Key 会随每个请求发送任何超出临时实验范围的环境都应使用 TLS。反向代理 / Ingress 场景如果 OneUptime 位于反向代理或 Ingress 之后oneuptime_url应填写代理暴露的外部 origin同时确保代理原样转发所有/api路径不要改写路径前缀因为 provider 会自行拼接/api路径。自托管常见连接错误的快速对照结合 Troubleshooting 中的症状表自托管最常遇到的问题包括症状原因修复ProjectId required使用了 master key 或用户级 token在 Project Settings API Keys 创建项目 API Key每次 API 调用 Connection refused / 404oneuptime_url错误带路径后缀、端口错、http/https 不符填裸 origin如https://oneuptime.example.comx509: certificate signed by unknown authority实例证书不在 Terraform 主机信任库安装 CA 证书勿尝试关闭校验no matching version found精确锁定从未发布的补丁版本使用~ 11.0或有界约束从零到 apply 的自托管最小示例将上述要点串成一个完整可运行的自托管示例结合 Quick Start 的资源写法terraform { required_providers { oneuptime { source oneuptime/oneuptime version 11.0, 11.2 # 根据你的平台版本调整上界 } } } provider oneuptime { oneuptime_url https://oneuptime.example.com # 自托管填实例 origin } 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] }执行流程与云端完全一致export ONEUPTIME_API_KEYyour-project-api-key terraform init terraform plan terraform apply完成后可在控制台验证 Monitor、Status Page、Label 均已创建再次terraform plan应报告No changes.服务端计算字段如 slug、当前状态、默认监控步骤不会造成漂移。测试完可用terraform destroy清理。如果追求 OpenTofu 兼容性仓库还提供 OpenTofu 文档 和 OpenTofu 示例配置。关联文档导航Registry Usage — provider 版本的发布机制与 release notesTroubleshooting — URL、TLS、密钥类错误的详细排查Quick Start — 首次 apply 的完整流程自托管同样适用Complete Guide — 认证选项、项目布局、依赖关系、data source、remote stateMonitor Steps — 精细控制监控项检查内容Importing Resources — 采纳控制台中已创建的资源Examples — 各类主要资源类型的完整配置模板。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考