SigNoz 操作参考 - 自定义资源与规范字段
在此查阅 SigNoz Operator 的自定义资源、spec 字段、status 条件及配置标志。如需安装 operator 并创建第一个资源，请参考 SigNoz Operator 概览。
若要查看集群中某一 Kind 的所有字段，可运行 kubectl explain，例如 kubectl explain dashboard.spec。
自定义资源
所有 Kind 均属于 resources.signoz.io/v1alpha1 API 组。
| Kind | 作用域 | SigNoz 对象 |
|---|---|---|
ProviderConfig | Namespace | SigNoz 端点及其 API key |
ClusterProviderConfig | Cluster | 同 ProviderConfig，但适用于所有 Namespace |
Dashboard | Namespace | 仪表盘 |
Rule | Namespace | 告警规则 |
SavedView | Namespace | 已保存的视图 |
PlannedMaintenance | Namespace | 计划内维护窗口 |
RoutePolicy | Namespace | 通知路由策略 |
User | Namespace | 用户 |
Role | Namespace | 角色 |
ServiceAccount | Namespace | 服务账号 |
AuthDomain | Namespace | SSO 认证域 |
operator 仓库中的 samples 目录为每种 Kind 提供了一个示例清单。
公共 Spec 字段
除 ProviderConfig 和 ClusterProviderConfig 外，每种 Kind 的 spec 根层级均包含以下字段：
| 字段 | 默认值 | 说明 |
|---|---|---|
providerConfigRef.name | 无，必填 | 要使用的 ProviderConfig 或 ClusterProviderConfig 的名称。 |
providerConfigRef.kind | ProviderConfig | ProviderConfig 或 ClusterProviderConfig。 |
interval | 10m | Operator 将 SigNoz 中的对象与 manifest 比对并回滚偏差的频率。 |
retryInterval | interval，否则 1m | 临时故障后 operator 重试的频率。若未设置，则使用 interval 的值；若两者都未设置，则使用 --default-resources-retry-interval 的值。 |
timeout | 30s | 单次 reconcile 的最长时间，包括对 SigNoz 的调用。 |
suspend | false | 设为 true 时，operator 停止处理该资源，不会修改或删除 SigNoz 中的对象。 |
reclaimPolicy | Delete | 删除自定义资源时 SigNoz 侧的处理方式：Delete 会删除 SigNoz 对象，Orphan 则保留它。 |
objectTemplate.spec | 无 | 以结构化字段表示的 SigNoz 对象，apply manifest 时由 API server 校验。 |
objectTemplate.jsonSpec | 无 | 以 JSON 请求体表示的 SigNoz 对象。operator 原样发送，因此请求体必须包含标识字段（如 name）以及 schema 版本（如 dashboard 的 "schemaVersion": "v6"）。 |
objectTemplate.spec 和 objectTemplate.jsonSpec 只能设置其中一个。interval、retryInterval 和 timeout 的默认值来自 operator 标志。
ProviderConfig 字段
ProviderConfig 和 ClusterProviderConfig 的 spec 相同：
| 字段 | 描述 |
|---|---|
endpoint.value |
SigNoz 实例的 URL，必须以 http:// 或 https:// 开头。建议使用 https://，因为 operator 会在请求头中携带 API 密钥。 |
endpoint.valueFrom | 从 secretKeyRef 或 configMapKeyRef 中读取 URL。 |
auth.header.name | 用于承载 API 密钥的 Header 名称，默认为 SIGNOZ-API-KEY。 |
auth.header.scheme | Header 值的方案前缀，例如 Bearer。Operator 发送的格式为 <scheme> <value>。 |
auth.header.value | 内联 API 密钥。建议改用 valueFrom，避免密钥明文出现在清单文件中。 |
auth.header.valueFrom | 从 secretKeyRef 或 configMapKeyRef 中读取 API 密钥。 |
tls.caSecretRef | 指定信任 CA 证书的 Secret 的 name 和 key。Operator 会与其他引用相同地从当前命名空间读取该配置。 |
tls.insecureSkipVerify | 若设为 true，Operator 将跳过服务端证书验证。 |
endpoint 和 auth.header 的 value 与 valueFrom 二者只能选其一。
对于 ProviderConfig，Operator 从其所在命名空间读取相关的 Secrets 和 ConfigMaps；对于 ClusterProviderConfig，则从 Operator 所在的命名空间 signoz-operator-system 中读取。
状态条件
所有受管理资源均报告以下统一的 Condition 类型：
| Condition | 含义 |
|---|---|
Ready | 汇总其他所有 Condition 的状态，等待此项变为就绪即可。 |
Synced | 当 SigNoz 中的对象与清单一致时为 True；Operator 尚无法确认时为 Unknown。 |
Recoverable | 表示暂时性故障，Operator 将按 retryInterval 间隔自动重试。 |
Terminal | 表示重试无法解决的故障。在人工编辑资源、修改对应的 ProviderConfig 或 Secret、或重启 Operator 之前，Operator 将停止重试。 |
Suspended |
spec.suspend 的值为 true。 |
kubectl get 命令会在 READY 和 REASON 列中显示 Ready 状态及其原因，并在 ID 列中显示 SigNoz ID。
资源原因
| 原因 | 含义 |
|---|---|
Created、Updated、Synced | SigNoz 中的对象与清单（manifest）一致。 |
Pending | SigNoz 中缺少该对象，例如有人在 UI 中将其删除。Operator 会再次创建它。 |
InvalidSpec | Operator 无法读取期望状态，例如 jsonSpec 包含无效的 JSON。 |
Rejected | SigNoz 以 400 响应拒绝了请求体。 |
ImmutableFieldChanged | 你修改了仅在 Operator 创建对象时才能设置的字段。 |
Ambiguous | 有多个 SigNoz 对象匹配该资源的标识。 |
SigNozResourceIDMismatch | resources.signoz.io/signoz-resource-id 注解中指定的对象与资源标识不匹配。 |
Unauthorized | SigNoz 以 401 或 403 响应拒绝了 API 密钥。 |
ProviderConfigNotReady | Operator 无法从 ProviderConfig 读取端点或 API 密钥。 |
BackendError | SigNoz 返回了 5xx 或 429 响应。 |
BackendUnreachable | 连接、超时或 TLS 失败。 |
Suspended | spec.suspend 的值为 true。 |
CompareFailed | Operator 无法将清单与 SigNoz 中的对象进行比较。这很可能是 Operator 的 bug。请在 operator issues 中报告。 |
ProviderConfig 原因
ProviderConfig 仅报告 Ready 状态。Ready=True 表示 Operator 可以读取端点和 API 密钥。Operator 不会向 SigNoz 发送测试请求。
| 原因 | 含义 |
|---|---|
Resolved |
Operator 读取 endpoint 和 API key。 |
SpecInvalid | spec 不合法。 |
EndpointInvalid | endpoint 不是合法的 URL。 |
SecretNotFound、ConfigMapNotFound | 引用的 Secret 或 ConfigMap 在 Operator 读取的命名空间中不存在。 |
KeyNotFound | Secret 或 ConfigMap 中没有引用的 key。 |
ValueEmpty | 引用的 key 值为空。 |
CABundleInvalid | tls.caSecretRef 中的 CA bundle 不合法。 |
ReferenceReadFailed | Operator 无法读取引用的 Secret 或 ConfigMap。 |
资源身份
当资源还没有 SigNoz ID 时，Operator 会查找身份相同的已有对象并收养它。例如，Dashboard 会匹配同名（name 相同）的 dashboard，User 会匹配相同邮箱的用户。如果设置了 reclaimPolicy: Delete，删除自定义资源时 Operator 也会删除被收养的对象。
如果匹配到的对象不止一个，请在自定义资源上设置 resources.signoz.io/signoz-resource-id 注解，指定要收养对象的 ID。
Operator 启动参数
Operator 通过启动参数（flag）读取配置。下表列出了常用参数。完整列表（包括 metrics 和 webhook 服务器的 TLS 参数）请参见 cmd/config.go。每个参数也可以通过环境变量设置，前缀为 SIGNOZ_OPERATOR_。例如，--log-level 对应 SIGNOZ_OPERATOR_LOG_LEVEL。
| 参数 | 默认值 | 说明 |
|---|---|---|
--log-level | info | 可选值为 debug、info、error 或 panic。 |
--watch-namespaces | 所有命名空间 | 要监 原始来源： signoz 评论 (0) |