← 文章 / 云原生与基础设施

signoz 1小时前 · 2026-10-09 07:58:40 · 0 阅读

在 AWS EKS 集群上安装 SigNoz - 自托管指南

本指南介绍如何使用 SigNoz Helm chart，通过 Foundry 或直接用 Helm，在 Amazon Elastic Kubernetes Service (EKS) 集群上安装 SigNoz。

前提条件

搭建好 EKS 集群（详见 AWS 官方文档），并按照"Managed nodes - Linux"指南操作。
kubectl 已配置好并可以连接集群，且同一台机器上安装了 Helm 3。
集群有足够的资源运行 SigNoz。容量规划请参考 resource planning。
如果 K8s 版本为 1.23 及以上，必须安装 Amazon EBS CSI driver，并为 Amazon EKS 集群 IAM 角色授予相应的卷权限。详情请参考 Amazon EBS CSI 迁移文档。

HelmFoundry

安装 SigNoz

第 1 步：添加 Helm 仓库

在使用 kubectl 的机器上运行：

Copy

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

第 2 步（可选）：选择 storage class

SigNoz 的数据存储在持久化卷（persistent volume）上，而 storage class 决定了集群为这些卷创建什么类型的磁盘。如果不做这一步，SigNoz 会使用集群默认的 storage class。EKS 集群自带 gp2 storage class。如果想使用 gp3 卷，需要先按照 Amazon EBS CSI driver 文档创建一个 gp3 storage class。查看集群中可用的 storage class：

Copy

kubectl get storageclass

如需指定某个 storage class，创建一个名为 values.yaml 的文件：

Copy

global:
  storageClass: <storage-class>

请确认以下取值：

<storage-class>：kubectl get storageclass 输出中的某个 storage class 名称，例如 gp3。

其他 chart 配置项也写在这个文件里。详见 chart 配置参考。

第 3 步：安装 chart

在包含 values.yaml 文件的目录下运行此命令：

Copy

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

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

第 4 步：验证安装

检查 pod 是否正在运行：

Copy

kubectl get pods -n signoz

输出结果应类似于以下内容。Pod 的后缀可能会不同：

Copy

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 运行正常后，通过端口转发访问 SigNoz UI，并在浏览器中打开 http://localhost:8080/：

Copy

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

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

Copy

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

响应内容如下：

Copy

{"status":"ok"}

Info

默认情况下，日志和 Trace 的保留期为 7 天，指标为 30 天。如需更改，请前往 SigNoz UI 的 Settings（设置）页面，点击 General（常规）标签页。

更多详情，请参阅保留期指南。

向 SigNoz 发送数据

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

Copy

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

将此地址作为插桩（Instrumentation）配置中的 OTLP 端点，例如设置为 OTEL_EXPORTER_OTLP_ENDPOINT 的值。如果使用 gRPC，请将端口改为 4317。

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

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

自定义安装

任何更改都遵循同样的流程：编辑 values.yaml，然后升级 release：

Copy

helm upgrade signoz signoz/signoz --namespace signoz -f values.yaml

Chart 配置：如需查看所有设置，请参阅Chart 配置参考。
Chart 版本：在 helm install 和 helm upgrade 命令中添加 --version <chart-version>。可用版本列在SigNoz charts 发布页。

请核对以下值：

<chart-version>：指来自SigNoz charts 发布页的某个 Chart 版本，例如 0.144.0。

故障排查

helm install 超时

--wait 会等待所有 Pod 就绪。若命令超时，请运行 kubectl get pods -n signoz 列出 Pod，并按下面两项检查。

Pod 一直处于 Pending 状态

通过查看 Pod 描述信息来排查为何无法调度：

Copy

kubectl describe pod -n signoz <pod-name>

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

在 EKS 中，若 PersistentVolumeClaim 一直处于 Pending 状态，通常是因为缺少 Amazon EBS CSI 驱动。请按前置条件中的说明安装该驱动。若 Pod 报告 CPU 或内存不足，则说明节点容量不够，请参阅资源规划。

修复后，kubectl get pods -n signoz 应显示该 Pod 状态为 Running。

Pod 不断重启

查看其日志：

Copy

kubectl logs -n signoz <pod-name>

若需查看上一次重启前的日志，请添加 --previous 参数。

安装 SigNoz

Foundry 是什么？

Foundry 是一个开源 CLI，让你以代码方式运行自托管的可观测性栈。一份声明式配置即可完成基础设施搭建、SigNoz 后端安装，以及 OpenTelemetry 采集配置，支持裸机、容器或 Kubernetes 环境。了解更多请访问 Foundry。

步骤 1：安装 foundryctl

在你平时使用 kubectl 的机器上运行：

Copy

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

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

步骤 2：创建 casting.yaml

创建一个名为 casting.yaml 的文件，用于描述这次安装：通过 Helm chart 安装 SigNoz，部署到名为 signoz 的 namespace：

Copy

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

telemetrykeeper 这几行指定使用 ZooKeeper，Helm chart 用它来协调 ClickHouse。

所有可用选项请参阅 casting file 参考文档和 Kubernetes Helm 示例。

修改 namespace 或固定 chart 版本

metadata 下的 annotations 用于指定 SigNoz 的安装位置和所用 chart。默认值如下：

Copy

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/kubernetes-namespace: signoz            # 安装到的 namespace，不存在会自动创建
    foundry.signoz.io/kubernetes-helm-chart: signoz           # chart 名称、压缩包 URL 或本地路径
    foundry.signoz.io/kubernetes-helm-repo-url: https://charts.signoz.io
    foundry.signoz.io/kubernetes-helm-chart-version: latest   # 也可以固定版本，如 0.144.0

casting file 参考文档对各配置项有详细说明。

步骤 3（可选）：选择 storage class

SigNoz 将数据存储在持久卷（persistent volumes）上。存储类（storage class）决定了集群为这些数据创建何种类型的磁盘。如果跳过此步骤，SigNoz 将使用集群的默认存储类。EKS 集群自带 gp2 存储类。若需使用 gp3 卷，请先按照 Amazon EBS CSI 驱动文档中的说明创建 gp3 存储类。查看集群支持的存储类：

Copy

kubectl get storageclass

若要指定使用某个存储类，在 casting.yaml 中添加以下内容：

Copy

spec:
  patches:
    - target: deployment/values.yaml
      operations:
        - op: add
          path: /global
          value:
            storageClass: <storage-class>

请确认以下值：

<storage-class>：kubectl get storageclass 输出中的存储类名称，例如 gp3。

步骤 4：部署

在包含 casting.yaml 的目录下运行：

Copy

foundryctl cast -f casting.yaml

该命令会将 SigNoz Helm chart 安装到 signoz 命名空间，并在命名空间不存在时自动创建。编辑 casting.yaml 后，重新运行相同命令即可应用更改。

手动运行 Helm

若要直接运行 Helm，请生成 values 文件并传递给 Helm：

Copy

foundryctl forge -f casting.yaml   # 生成 pours/deployment/values.yaml
helm repo add signoz https://charts.signoz.io
helm repo update
helm upgrade --install signoz signoz/signoz \
   --namespace signoz --create-namespace \
   -f pours/deployment/values.yaml

步骤 5：验证安装

检查 Pod 是否正在运行：

Copy

kubectl get pods -n signoz

输出结果应类似于以下内容。Pod 后缀可能有所不同：

NAME                                                        READY   STATUS      RESTARTS   AGE
chi-signoz-telemetrystore-clickhouse-cluster-0-0-0          1/1     Running     0          3m
signoz-0                                                    1/1     Running     0          3m
signoz-ingester-6d9c7b8f5c-k2x9p                            1/1     Running     0          3m
signoz-metastore-postgres-0                                 1/1     Running     0          3m
signoz-telemetrykeeper-zookeeper-0

 原始来源： signoz 
    
  评论 (0)