使用 Argo CD 部署 SigNoz —— Kubernetes 上的 GitOps

选择 SigNoz Cloud 以获得便捷性，或自行托管以获得控制权——随着需求的增长，你可以自由切换。

本指南介绍如何使用 Argo CD 在 Kubernetes 上部署 SigNoz。你将把 SigNoz Helm 图表声明为一个 Argo CD 应用。Argo CD 会渲染该图表并将其应用到集群。

为什么选择 Argo CD？

Argo CD 是一个 GitOps 工具。GitOps 意味着声明式清单定义集群的期望状态，而控制器则使集群与该状态保持一致。这种方式为你带来以下优势：

• 一个应用资源即可描述整个 SigNoz 安装过程
• 通过修改该资源实现升级和回滚
• 当有人手动编辑实时资源时，能自动进行纠正

前置条件

• Kubernetes 版本 >= 1.22
• 目前支持 x86-64、amd64 和 arm64 架构
• Helm 版本 >= 3.8
• 你必须拥有对集群的 kubectl 访问权限

• 下表描述了在 Kubernetes 上安装 SigNoz 所需的硬件要求：

  组件	最低要求	推荐配置
  内存	8 GB	16 GB
  CPU	4 核	8 核
  存储	30 GB	80 GB

• 集群中运行着 Argo CD。请参见 Argo CD 入门指南。
• 你的机器上安装了 argocd CLI，或可以访问 Argo CD Web UI。

安装步骤

创建 Argo CD 应用

应用资源将 Argo CD 指向 SigNoz Helm 图表。创建一个名为 signoz-application.yaml 的文件：

signoz-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: signoz
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://charts.signoz.io
    chart: signoz
    targetRevision: 0.142.1
  destination:
    server: https://kubernetes.default.svc
    namespace: signoz
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

请核实这些值：

• targetRevision：SigNoz chart 的版本号。当前版本可在 SigNoz charts releases 中查询。
• destination.namespace：SigNoz 所在的命名空间。由于设置了 CreateNamespace=true，首次同步时会自动创建，无需手动建立。

这个 chart 会安装 SigNoz、SigNoz OpenTelemetry Collector、ClickHouse 和 ZooKeeper。

应用 Application

这个 YAML 文件是声明式的配置来源。CLI 和 UI 两种方式无需 YAML 也能创建同样的 Application，如果你更喜欢命令式操作，可以直接用它们。

kubectlArgo CD CLIArgo CD UICopy

kubectl apply -f signoz-application.yaml

Copy

argocd app create signoz \
  --repo https://charts.signoz.io \
  --helm-chart signoz \
  --revision 0.142.1 \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace signoz \
  --sync-option CreateNamespace=true

按照 Argo CD 文档中通过 UI 创建应用的步骤操作，仓库 URL 填 https://charts.signoz.io，chart 填 signoz，revision 填 chart 版本号，目标命名空间设为 signoz。

在 SYNC OPTIONS 下勾选 AUTO-CREATE NAMESPACE。不勾选的话，Argo CD 不会自动创建目标命名空间，首次同步就会失败。

同步 Application

上面的 Application 使用默认的手动同步策略，所以在你手动触发同步之前，Argo CD 不会安装 chart：

Copy

argocd app sync signoz

在 UI 中，打开 signoz 应用，点击 SYNC，再点击 SYNCHRONIZE。

首次同步需要下载 SigNoz、ClickHouse 和 ZooKeeper 的容器镜像，网络较慢时可能需要几分钟。如果想改为每次变更都自动同步，参见 Sync automatically。

验证

确认 Application 状态为 Synced 和 Healthy。在 UI 中，应用页面会在 APP HEALTH 和 SYNC STATUS 下显示这些状态。使用 CLI 则运行：

Copy

argocd app get signoz

Name:               argocd/signoz
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          signoz
Source:
- Repo:             https://charts.signoz.io
  Target:           0.142.1
Sync Policy:        Manual
Sync Status:        Synced to 0.142.1
Health Status:      Healthy

确保 Pod 正常启动：

kubectl get pods -n signoz

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-5c76779b95-cft7h   2/2     Running     0          3m
signoz-otel-collector-947685648-9n9z6         1/1     Running     0          3m
signoz-telemetrystore-migrator-dzhzc          0/1     Completed   0          3m
signoz-zookeeper-0                            1/1     Running     0          3m

signoz-telemetrystore-migrator Pod 执行一次架构迁移后状态变为 Completed。Kubernetes 随后会移除该 Pod，因此列表中不一定总是显示它。

在本地机器上打开 SigNoz UI：

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

访问 http://localhost:8080。首次访问时，SigNoz 会提示创建管理员账户。

运行以下命令以确认 API 有响应：

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

{"status":"ok"}

自定义安装配置

在 Application 现有 spec.source 下方添加 helm.valuesObject 配置块。请勿替换整个文件。Argo CD 会在下次同步时将参数传递给 Helm。

signoz-application.yaml

spec:
  source:
    repoURL: https://charts.signoz.io
    chart: signoz
    targetRevision: 0.142.1
    helm:
      valuesObject:
        clickhouse:
          persistence:
            size: 100Gi
        signoz:
          ingress:
            enabled: true
            className: nginx
            hosts:
              - host: signoz.example.com
                paths:
                  - path: /
                    pathType: Prefix
                    port: 8080

该 Chart 会自动为你创建 Ingress，因此无需额外编写单独的 Ingress 清单文件。

完整的参数列表请参考Chart 参数文件。

将参数存储在 Git 仓库中

若希望以文件形式管理参数，需在你已创建的 Application 中声明两个源。Argo CD 会从 SigNoz 仓库读取 Chart，从你自己的仓库读取参数文件。单一源 Application 无法实现此功能，因为 helm.valueFiles 只能解析 Chart 所在源内的文件。

signoz-application.yaml

spec:
  sources:
    - repoURL: https://charts.signoz.io
      chart: signoz
      targetRevision: 0.142.1
      helm:
        valueFiles:
          - $values/signoz/values.yaml
    - repoURL: https://github.com/<your-org>/<your-repo>
      targetRevision: main
      ref: values

请核对以下参数：

• <your-org> 和 <your-repo>：你自己的 Git 仓库所属的组织名和仓库名，Argo CD 将从该仓库读取参数文件。
• targetRevision: main：存放参数文件的仓库分支。
• ref: values：为第二个源指定名称。valueFiles 中的 $values 前缀即指向此名称。
• $values/signoz/values.yaml：参数文件在你仓库中的路径。

采用此形式时，请将 spec.source 替换为 spec.sources。详细用法参见Argo CD 文档中关于从外部 Git 仓库引用 Helm 参数文件的说明。

自动同步

在已有的 spec: 下添加 automated 同步策略，让 Argo CD 自动应用每次变更，无需手动同步。不要替换整个文件。

signoz-application.yaml

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

prune 会删除 chart 中不再定义的资源，selfHeal 会自动还原对线上资源的手动修改。

升级 SigNoz

要升级到新的 chart 版本，修改 Application 中的 targetRevision：

Copy

spec:
  source:
    chart: signoz
    targetRevision: <new-chart-version>

把 <new-chart-version> 替换为目标版本，例如 0.142.1。已发布的版本可以在 SigNoz charts releases 页面查看。

应用变更后执行同步：

Copy

kubectl apply -f signoz-application.yaml
argocd app sync signoz

如果启用了自动同步策略，Argo CD 会自动完成升级。

要回滚，把 targetRevision 改回之前的版本并重新 apply 即可。也可以使用 argocd app rollback 命令，但它只适用于手动同步策略；在自动同步策略下会报以下错误：

Copy

rollback cannot be initiated when auto-sync is enabled

故障排查

Application 一直处于 OutOfSync 状态

默认同步策略是手动的，Argo CD 只会渲染 chart 而不会应用它。手动执行同步：

Copy

argocd app sync signoz

端口 8081 连接导致的 ComparisonError

当 argocd-repo-server pod 尚未就绪时，Argo CD 会报这个错：

Copy

ComparisonError  Failed to load target state: failed to generate manifest for source 1 of 1:
rpc error: code = Unavailable desc = connection error: dial tcp 10.97.5.137:8081: connect: connection refused

等 Argo CD 的 pod 就绪后再刷新 Application：

Copy

kubectl -n argocd wait --for=condition=Ready pod --all --timeout=10m
argocd app get signoz --refresh

Pod 一直处于 Pending 状态

集群的 CPU、内存或存储资源不足。SigNoz 最低要求 4 核 CPU 和 8 GB 内存。此外，集群还需具备默认的 StorageClass，以支持持久卷。

kubectl describe pod -n signoz <pod-name>

valueFiles 中的配置不生效

Argo CD 会在 repoURL 指定的仓库内解析 helm.valueFiles 的路径，而非