SigNoz 操作器 - 在 Kubernetes 中管理 SigNoz 资源

SigNoz Operator 允许你通过 Kubernetes 管理 SigNoz 实例内的资源。你可以将 SigNoz 对象声明为 Kubernetes 自定义资源（Custom Resources）。Operator 支持仪表盘、告警规则、保存的视图、计划维护窗口、路由策略、用户、角色、服务账号以及 SSO 认证域。将这些资源存放到 Git 仓库中，与业务代码并列管理，并通过 kubectl apply、Argo CD 或 Flux 进行应用，操作流程与你部署其他清单（Manifests）的方式一致。

Operator 不负责安装 SigNoz。若要在 Kubernetes 上安装 SigNoz，请使用 Foundry 或 SigNoz Helm 图表。

前提条件

• 拥有 Kubernetes 集群及 kubectl 访问权限，且具备安装 CRD（CustomResourceDefinitions）的权限。
• 如果使用 Helm 安装，需具备 Helm 3 环境。
• 一个 SigNoz 实例（Cloud 或 Self-Hosted 均可）。
• 一个 SigNoz 服务账号 的 API 密钥。Operator 的执行权限受限于该服务账号的角色配置。请为该服务账号分配一个能够管理你计划声明的所有资源类型的角色。

工作原理

每个受管资源都关联一个 ProviderConfig。ProviderConfig 存储了 SigNoz 实例的 URL 以及包含 API 密钥的 Secret 引用。Operator 读取这两项配置，并通过 SigNoz API 创建相应的对象。

此后，Operator 会按固定间隔比对 SigNoz 中的对象与本地清单的状态。如果有人在 Kubernetes 外部（例如在 SigNoz UI 中）修改了对象，Operator 会将变更回滚。当你删除自定义资源时，Operator 会同步删除 SigNoz 中的对应对象。

Operator 通过 HTTP 或 HTTPS 协议调用 SigNoz API，具体协议由 endpoint URL 配置决定。建议使用 HTTPS，因为 API 密钥会包含在请求头中发送。SigNoz 实例可以部署在同一集群、其他集群或 Kubernetes 外部环境中。单个 Operator 可以同时管理 SigNoz Cloud 和自建实例。

使用 Operator 管理 SigNoz 资源

步骤 1：安装 Operator

两种安装方式都会在 signoz-operator-system 命名空间中部署 CRDs、RBAC（基于角色的访问控制）规则以及 Operator 本身。

Helmkubectl

添加 SigNoz Helm 仓库并安装 signoz-operator chart：

Copy

helm repo add signoz https://charts.signoz.io
helm repo update
helm install signoz-operator signoz/signoz-operator \
  --namespace signoz-operator-system --create-namespace

应用随每个 Operator 版本发布的 manifest：

Copy

kubectl apply -f https://github.com/SigNoz/signoz-operator/releases/latest/download/signoz-operator.yaml

如果使用独立流程安装 CRDs，请从同一版本中获取 signoz-operator.crds.yaml 文件，该文件仅包含 CRDs。

等待 Operator 启动：

Copy

kubectl -n signoz-operator-system rollout status deployment/signoz-operator

Operator 正常运行时，命令会输出 deployment "signoz-operator" successfully rolled out。

步骤 2：连接 Operator 与 SigNoz

请在你计划创建 SigNoz 资源的命名空间中执行本步骤和下一步的命令。这些命令默认使用当前命名空间，如需指定其他命名空间，请添加 -n <namespace>。

创建存储 API 密钥的 Secret：

Copy

kubectl create secret generic signoz-api --from-literal=token=<your-signoz-api-key>

Warning

请勿在 Secret manifest 中将 API 密钥提交到 Git。若通过 GitOps 管理 Secret，需使用加密工具或密钥管理工具（如 SOPS、Sealed Secrets 或 External Secrets Operator）对其进行加密或同步。

将此清单保存为 signoz-provider.yaml。它会创建一个名为 prod 的 ProviderConfig，从 Secret 中读取密钥：

signoz-provider.yaml

apiVersion: resources.signoz.io/v1alpha1
kind: ProviderConfig
metadata:
  name: prod
spec:
  endpoint:
    value: <your-signoz-url>
  auth:
    header:
      # 请求头名称默认为 SIGNOZ-API-KEY
      valueFrom:
        secretKeyRef:
          name: signoz-api
          key: token

请核对以下值：

• <your-signoz-api-key>：你的 SigNoz service account 的密钥。
• <your-signoz-url>：你在浏览器中打开 SigNoz 时使用的 URL，例如 SigNoz Cloud 的 https://<your-workspace>.<region>.signoz.cloud。如果是自托管实例，请使用 operator 可以访问到 SigNoz 的 URL。

应用该清单：

Copy

kubectl apply -f signoz-provider.yaml

operator 会从 ProviderConfig 所在的命名空间读取 Secret。请确保 Secret 和 ProviderConfig 位于同一个命名空间。

第 3 步：创建 Dashboard

所有受管理的资源类型在 spec 根级别都有一组相同的字段。SigNoz 对象放在 spec.objectTemplate 下，可以用类型化字段表示，也可以直接写 JSON。

将下面任一清单保存为 service-overview.yaml：

Typed fieldsJSON

应用清单时，API server 会校验这些字段。

service-overview.yaml

apiVersion: resources.signoz.io/v1alpha1
kind: Dashboard
metadata:
  name: service-overview
spec:
  providerConfigRef:
    name: prod
  interval: 5m
  objectTemplate:
    spec:
      name: service-overview
      schemaVersion: v6
      tags:
        - key: team
          value: platform
      spec:
        display:
          name: Service overview
          description: Golden signals for the demo service
        panels: {}
        layouts: []
        variables: []

使用此表单粘贴 Dashboard JSON。Operator 会原样将该 JSON 发送给 SigNoz，因此 JSON 必须包含 name 和 "schemaVersion": "v6"。从 SigNoz UI 的 JSON 编辑器下载的 dashboard 仅包含 spec、tags 和 image。粘贴前请添加上述两个字段。

service-overview.yaml

apiVersion: resources.signoz.io/v1alpha1
kind: Dashboard
metadata:
  name: service-overview
spec:
  providerConfigRef:
    name: prod
  interval: 5m
  objectTemplate:
    jsonSpec: |
      {
        "name": "service-overview",
        "schemaVersion": "v6",
        "tags": [{"key": "team", "value": "platform"}],
        "spec": {
          "display": {
            "name": "Service overview",
            "description": "Golden signals for the demo service"
          },
          "panels": {},
          "layouts": [],
          "variables": []
        }
      }

• providerConfigRef.name 指定第二步中创建的 ProviderConfig。
• interval 设置 Operator 对比 SigNoz 中的 dashboard 与此 manifest 的频率。

应用该 manifest：

Copy

kubectl apply -f service-overview.yaml

Operator 仓库中的samples 目录为每种 kind 提供了一个示例 manifest。关于 kind 列表以及所有 kind 共有的字段，请参阅SigNoz Operator 参考文档。

验证

1. 确保 ProviderConfig 已就绪：

   Copy

   kubectl get providerconfig prod -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

   当 Operator 能够读取 endpoint 和 API key 时，该命令输出 True。

2. 确保 dashboard 已就绪：

   Copy

   kubectl get dashboards

   Copy

   NAME               READY   REASON    ID                                     AGE
   service-overview   True    Created   0198c0e1-4f2a-7c9e-b3d5-6a1f8e2d4c07   12s

   READY 为 True，ID 显示 SigNoz 分配给该 dashboard 的 ID。REASON 还可能显示 Updated 或 Synced。

3. 在 SigNoz 中，打开仪表盘。服务概览仪表盘在列表中带有 team:platform 标签。创建者是 Operator 的服务账户。

   

在脚本和 CI 流水线中，等待 Ready 状态。它汇总了其他所有状态：

Copy

kubectl wait --for=condition=Ready dashboard/service-overview --timeout=2m

故障排查

资源显示 Unauthorized

SigNoz 以 401 或 403 响应拒绝了 API 密钥。

1. 确保 Secret 包含完整的密钥，且未有人在 SigNoz 中吊销该密钥。
2. 确保服务账户具有允许在此类资源上执行操作的角色。
3. 等待下一次重试。Operator 会以 retryInterval 进行重试，并无需重启即可捕获更改后的 Secret。

资源显示 ProviderConfigNotReady

Operator 无法从 ProviderConfig 中读取端点或 API 密钥。运行以下命令，并查看 Ready 状态的 reason 和 message：

Copy

kubectl describe providerconfig prod

如果原因类似于 SecretNotFound 或 KeyNotFound，则表示 ProviderConfig 命名空间中的 Secret 或其内的密钥缺失。

资源显示 BackendUnreachable

Operator 无法连接到端点。请确保端点 URL 正确，且 Operator Pod 可以访问该端点。对于使用私有 CA 的自托管实例，在 ProviderConfig 中信任该 CA。

资源显示 Rejected 或 InvalidSpec

SigNoz 返回 400 拒绝了该请求，或 jsonSpec 不是合法的 JSON。Operator 不会重试这类错误。对资源执行 kubectl describe，根据错误信息修正相应字段，然后重新 apply 这个 manifest。

Prov