奇链 奇链
← 文章 / 云原生与基础设施
signoz 6小时前 · 2026-10-09 02:28:40 · 1 阅读

在 Red Hat OpenShift 上安装 SigNoz - 自托管指南

本指南介绍如何通过 SigNoz Helm chart 安装 SigNoz 到 Red Hat OpenShift 集群，可以使用 Foundry，也可以直接使用 Helm。由于 OpenShift 强制执行安全上下文约束（SCC），安装的第一步是为 SigNoz 创建一个 SCC。

前提条件

  • 一个 OpenShift 集群。
  • 已配置好连接集群的 oc 或 kubectl CLI，且同一台机器上安装了 Helm 3。
  • 集群有足够的资源容量运行 SigNoz。容量规划可参考资源规划文档。
  • 一个由 OpenShift 支持的 provisioner 提供的存储类（storage class）。详见 Red Hat 存储文档。
HelmFoundry

安装 SigNoz

第 1 步：创建 SecurityContextConstraints

在 OpenShift 中，只有当 SCC 允许 Pod 所需的权限时，Pod 才能被准入。ClickHouse 和 ZooKeeper 以固定的用户和组 ID 运行，并挂载持久化卷。创建一个名为 signoz-scc.yaml 的文件，为它们的服务账户开放这些权限：

Copy
apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: signoz-scc
 
allowPrivilegedContainer: false
runAsUser:
  type: RunAsAny        # allow any container UID
fsGroup:
  type: RunAsAny        # allow any supplemental GID
seLinuxContext:
  type: RunAsAny        # no SELinux label constraints
volumes:
  - persistentVolumeClaim # mounted PVC
  - emptyDir              # ephemeral scratch space
  - configMap             # ConfigMap files
  - projected             # combined CM/secret/etc.
  - downwardAPI           # expose pod metadata
 
readOnlyRootFilesystem: false
allowHostDirVolumePlugin: false
 
users:
  # Bind the SCC to Required Service Accounts for SigNoz
  - system:serviceaccount:signoz:signoz-clickhouse
  - system:serviceaccount:signoz:default

请核对这些值：

  • system:serviceaccount: 后面的 signoz：即第 4 步中传给 helm install 的命名空间。
  • signoz-clickhouse：ClickHouse 使用的服务账号。前缀是你传递给 helm install 的 release 名称，因此如果 release 名称不同，请替换开头的 signoz。
  • default：ZooKeeper 运行的默认服务账号。请保持不变。

应用该配置。在运行 oc 的机器上执行以下命令：

Copy
oc apply -f signoz-scc.yaml

kubectl apply -f signoz-scc.yaml 的作用相同。

步骤 2：添加 Helm 仓库

在运行 kubectl 的机器上执行以下命令：

Copy
helm repo add signoz https://charts.signoz.io
helm repo update

步骤 3（可选）：选择存储类

SigNoz 将数据存储在持久卷中。存储类决定了集群为这些数据创建何种类型的磁盘。若跳过此步骤，SigNoz 将使用集群的默认存储类。在 OpenShift 中，请选用集群支持的 storage provisioner 对应的存储类；具体请参阅先决条件中链接的 Red Hat 存储文档。查看集群提供的存储类：

Copy
kubectl get storageclass

如需使用特定存储类，请创建名为 values.yaml 的文件：

Copy
global:
  storageClass: <storage-class>

验证以下值：

  • <storage-class>：来自 kubectl get storageclass 输出的存储类名称。

其他 chart 值可写入同一文件。参见 chart 配置参考。

步骤 4：安装 Chart

在包含 values.yaml 的目录下执行：

Copy
helm install signoz signoz/signoz \
   --namespace signoz --create-namespace \
   --wait --timeout 1h \
   -f values.yaml

如果跳过了步骤 3，请省略 -f values.yaml。--wait 参数会使命令在所有 pod 就绪后才返回。

步骤 5：验证安装

检查 pod 是否正在运行：

Copy
kubectl get pods -n signoz

输出应类似以下内容。Pod 后缀会有所不同：

NAME                                         READY   STATUS      RESTARTS   AGE
chi-signoz-clickhouse-cluster-0-0-0          1/1     Running     0          3m
signoz-0                                     1/1     Running     0          3m
signoz-clickhouse-operator-7f8c9d6b5-q4w2z   2/2     Running     0          3m
signoz-otel-collector-6d9c7b8f5c-k2x9p       1/1     Running     0          3m
signoz-telemetrystore-migrator-x7h3k         0/1     Completed   0          2m
signoz-zookeeper-0                           1/1     Running     0          3m

待所有 Pod 均进入 Running 状态后，对 SigNoz UI 执行端口转发，并在浏览器中打开 http://localhost:8080/：

kubectl port-forward -n signoz svc/signoz 8080:8080

在另一个终端中检查健康端点：

curl -X GET http://localhost:8080/api/v1/health

响应如下：

{"status":"ok"}

默认情况下，日志和 Trace 的保留期限为7 天，指标的保留期限为30 天。如需修改，请前往 SigNoz UI 的设置页面，选择常规选项卡。

更多详情参见保留期限指南。

向 SigNoz 发送数据

你的应用程序将 Trace、指标和日志发送至 SigNoz 收集器。在集群内部，收集器的监听地址为：

http://signoz-otel-collector.signoz.svc.cluster.local:4318

在埋点配置中，将此地址作为 OTLP 端点，例如用作 OTEL_EXPORTER_OTLP_ENDPOINT 的值。若使用 gRPC，请改用端口 4317。

地址中的第二个 signoz 代表命名空间。如果你将 SigNoz 安装在了其他命名空间，请使用对应的命名空间。

对于集群外部的应用，请参阅自托管数据摄入指南。

自定义安装

所有配置变更均遵循相同流程：编辑 values.yaml，然后执行 Helm 升级：

helm upgrade signoz signoz/signoz --namespace signoz -f values.yaml
  • Chart 参数：所有配置项参见Chart 配置参考。
  • Chart 版本：在 helm install 和 helm upgrade 命令中加上 --version <chart-version>。可用版本请查看 SigNoz charts releases。

请确认以下值：

故障排查

helm install 超时

--wait 参数会等待所有 Pod 变为就绪状态。如果命令超时，先用 kubectl get pods -n signoz 查看 Pod 列表，再按下面两种情况处理。

Pod 一直处于 Pending 状态

用 describe 命令查看 Pod 无法调度的原因：

Copy
kubectl describe pod -n signoz <pod-name>

把 <pod-name> 替换为 kubectl get pods -n signoz 输出中的 Pod 名称。

如果提示 CPU 或内存不足，说明节点资源不够，请参考资源规划文档。

问题解决后，kubectl get pods -n signoz 会显示该 Pod 处于 Running 状态。

Pod 不断重启

查看其日志：

Copy
kubectl logs -n signoz <pod-name>

加上 --previous 参数可以查看上次重启之前的日志。

安装 SigNoz

What is Foundry?

Foundry 是一个开源 CLI 工具，能以代码方式运行你的自托管可观测性技术栈。只需一份声明式配置，即可在裸机、容器或 Kubernetes 上完成基础设施创建、SigNoz 后端安装，以及 OpenTelemetry 采集配置。了解更多关于 Foundry 的信息。

第 1 步：创建 SecurityContextConstraints

OpenShift 只在 SCC 允许 Pod 所需权限时才会接纳该 Pod。ClickHouse、ZooKeeper 和 PostgreSQL 以固定的用户和组 ID 运行，并挂载持久化卷。创建一个名为 signoz-scc.yaml 的文件，为它们的服务账号授予相应权限：

Copy
apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: signoz-scc
 
allowPrivilegedContainer: false
runAsUser:
  type: RunAsAny        # 允许任意容器 UID
fsGroup:
  type: RunAsAny        # 允许任意辅助 GID
seLinuxContext:
  type: RunAsAny        # 无 SELinux 标签限制
volumes:
  - persistentVolumeClaim # 挂载的 PVC
  - emptyDir              # 临时工作空间
  - configMap             # ConfigMap 文件
  - projected             # 组合的 CM/secret 等
  - downwardAPI           # 暴露 Pod 元数据
 
readOnlyRootFilesystem: false
allowHostDirVolumePlugin: false
 
users:
  # 将 SCC 绑定到 SigNoz 所需的 Service Account
  - system:serviceaccount:signoz:signoz-telemetrystore-clickhouse
  - system:serviceaccount:signoz:signoz-metastore-postgres
  - system:serviceaccount:signoz:default

请核对以下数值：

  • system:serviceaccount: 后的 signoz 代表命名空间。它取自 casting.yaml 中的 metadata.name，或第 3 步中设置的命名空间注解。
  • signoz-telemetrystore-clickhouse 和 signoz-metastore-postgres 分别是 ClickHouse 和 PostgreSQL 的服务账号。其前缀取自 casting.yaml 中的 metadata.name，若名称不同，请替换开头的 signoz。
  • default 是 ZooKeeper 运行的服务账号，请保持不变。

应用该配置。在运行 oc 的机器上执行以下命令：

Copy
oc apply -f signoz-scc.yaml

kubectl apply -f signoz-scc.yaml 具有相同效果。

步骤 2：安装 foundryctl

在运行 kubectl 的机器上执行以下命令：

Copy
curl -fsSL https://signoz.io/foundry.sh | bash

如需手动安装（如 Windows PowerShell、物理隔离环境）或配置 PATH，请参阅 foundry 入门指南。

步骤 3：创建 casting.yaml

创建一个名为 casting.yaml 的文件。它描述安装详情：通过 Helm chart 部署 SigNoz，命名空间设为 signoz：

Copy
apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: helm
    mode: kubernetes
  telemetrykeeper:
    kind: zookeeper

telemetrykeeper 相关的配置行对应 ZooKeeper，Helm chart 用它来协调 ClickHouse。

完整选项请参阅

原始来源： signoz

评论 (0)