使用 Flux CD 部署 SigNoz - 在 Kubernetes 上实现 GitOps

SigNoz Cloud 胜在易用，自建部署则更可控，两者皆可随需求变化随时切换。

本指南将讲解如何在 Kubernetes 中部署 SigNoz，并集成 Flux CD。你需要将 SigNoz 的 Helm Release 提交到 Git 仓库，Flux 读取该提交后自动将配置应用到集群。

Flux CD 有何价值？

Flux CD 是一款 GitOps 工具。GitOps 意味着 Git 仓库持有集群的期望状态，控制器负责让集群与该状态保持一致。这种方式带来以下优势：

• Git 历史完整记录 SigNoz 部署的每次变更
• 通过提交代码完成升级或回滚，无需在本地执行 helm 命令
• 当有人手动修改生产资源时，系统可自动纠偏

前置条件

• Kubernetes 版本 >= 1.22
• 当前支持 x86-64、amd64 和 arm64 架构
• Helm 版本 >= 3.8
• 需具备 kubectl 访问集群的权限

• 下表列出了在 Kubernetes 上安装 SigNoz 的硬件需求：

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

• 集群中已安装 Flux CD 2.3 或更高版本。请先运行 flux bootstrap。参考 Flux bootstrap 文档。
• 本地已安装 flux CLI，版本 2.3 或更高。
• 拥有 Flux 管理的 Git 仓库的写入权限。

flux bootstrap 命令会在 flux-system 命名空间中创建一个名为 flux-system 的 GitRepository。以下步骤均引用该资源。

仓库目录结构

本指南采用双目录结构：一个存放所有应用共享的 Helm 仓库定义，另一个存放 SigNoz 的 Release 配置。

复制

clusters/
└── demo/
    ├── flux-system/               # 由 flux bootstrap 创建
    └── infrastructure/
        ├── kustomization.yaml
        ├── sources.yaml
        └── signoz.yaml
infrastructure/
├── sources/
│   └── signoz.yaml
└── signoz/
    ├── kustomization.yaml
    ├── namespace.yaml
    └── helmrelease.yaml

将 demo 替换为你集群目录的名称。

安装步骤

添加 SigNoz Helm 仓库

HelmRepository 资源用于告知 Flux 从哪里下载 SigNoz 图表。请将其放入 flux-system 命名空间，以便所有集群和发布都能使用。

infrastructure/sources/signoz.yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: signoz
  namespace: flux-system
spec:
  interval: 1h
  url: https://charts.signoz.io

创建 HelmRelease

HelmRelease 资源描述了 SigNoz 的安装配置。Flux 会安装该图表，并在此处指定的版本上保持发布状态。

首先，创建命名空间：

infrastructure/signoz/namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: signoz

然后创建发布对象：

infrastructure/signoz/helmrelease.yaml

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: signoz
  namespace: signoz
spec:
  interval: 1h
  timeout: 15m
  chart:
    spec:
      chart: signoz
      version: "0.142.1"
      sourceRef:
        kind: HelmRepository
        name: signoz
        namespace: flux-system
  upgrade:
    cleanupOnFail: true
    remediation:
      retries: 3
  rollback:
    cleanupOnFail: true

请核对以下配置值：

• version：SigNoz 图表的版本号。可在 SigNoz charts 发布页 查看最新版本。
• sourceRef.namespace：上述创建的 HelmRepository 所在的命名空间。由于 HelmRelease 运行在 signoz 命名空间中，此处必须指定为 flux-system。

Flux 从 2.3 版本开始提供 helm.toolkit.fluxcd.io/v2 API。较旧版本的集群会拒绝此清单文件。如果使用的是 Flux 2.0 到 2.2，请先升级 Flux。

SigNoz 图表会安装多个组件，且 ClickHouse 启动耗时较长。timeout: 15m 的设置可为初次安装提供充足的时间余量。

将这两个文件添加到一个 Kustomize 文件中，以便 Flux 一同应用它们：

infrastructure/signoz/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - namespace.yaml
  - helmrelease.yaml

让 Flux 指向相应目录

Flux 需要两个 Kustomization：一个用于 Helm 仓库定义，另一个用于 SigNoz。后者依赖前者，因为必须先存在 HelmRepository，chart 才能下载。

clusters/demo/infrastructure/sources.yaml

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: sources
  namespace: flux-system
spec:
  interval: 10m
  retryInterval: 2m
  path: ./infrastructure/sources
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system

clusters/demo/infrastructure/signoz.yaml

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: signoz
  namespace: flux-system
spec:
  interval: 5m
  path: ./infrastructure/signoz
  prune: true
  wait: true
  timeout: 15m
  sourceRef:
    kind: GitRepository
    name: flux-system
  dependsOn:
    - name: sources

在集群目录中列出这两个文件：

clusters/demo/infrastructure/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - sources.yaml
  - signoz.yaml

提交并触发调和

提交文件并推送到 Flux 所监视的分支：

Copy

git add clusters infrastructure
git commit -m "Add SigNoz"
git push

Flux 会在下一个周期自动拉取这次提交。如果想立即生效，可以执行：

Copy

flux reconcile kustomization flux-system --with-source

首次安装需要下载 SigNoz、ClickHouse 和 ZooKeeper 的容器镜像，网速较慢时可能需要几分钟。

验证

确认所有 Flux 资源的状态都是 READY True：

Copy

flux get all -A

Copy

NAMESPACE  	NAME                 	REVISION       	SUSPENDED	READY	MESSAGE
flux-system	helmrepository/signoz	sha256:4f5322fd	False    	True 	stored artifact: revision 'sha256:4f5322fd'
 
NAMESPACE  	NAME                   	REVISION	SUSPENDED	READY	MESSAGE
flux-system	helmchart/signoz-signoz	0.142.1 	False    	True 	pulled 'signoz' chart with version '0.142.1'
 
NAMESPACE	NAME              	REVISION	SUSPENDED	READY	MESSAGE
signoz   	helmrelease/signoz	0.142.1 	False    	True 	Helm install succeeded for release signoz/signoz.v1

Flux 会在 HelmRepository 所在的命名空间内创建 HelmChart 资源，而不是在 release 的命名空间中。可以使用 flux get all -A 来查看所有这三个资源。

确保 Pod 正在运行：

Copy

kubectl get pods -n signoz

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-5c76779b95-2t845   2/2     Running     0          3m
signoz-otel-collector-5dffd768fc-dc6rb        1/1     Running     0          3m
signoz-telemetrystore-migrator-lx48v          0/1     Completed   0          3m
signoz-zookeeper-0                            1/1     Running     0          3m

signoz-telemetrystore-migrator Pod 执行一次模式迁移后即报告状态为 Completed。Kubernetes 随后会移除该 Pod，因此列表中并不总是显示它。

在你的机器上打开 SigNoz UI：

Copy

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

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

为确保 API 正常响应，请运行：

Copy

curl http://localhost:8080/api/v1/health

Copy

{ "status": "ok" }

自定义安装

在 HelmRelease 现有的 spec: 下方添加一个 values 代码块。切勿替换整个文件。Flux 会在下次协调（reconcile）时将 values 传递给 Helm。

infrastructure/signoz/helmrelease.yaml

spec:
  values:
    clickhouse:
      persistence:
        size: 100Gi
    signoz:
      ingress:
        enabled: true
        className: nginx
        hosts:
          - host: signoz.example.com
            paths:
              - path: /
                pathType: Prefix
                port: 8080

该 chart 会自动为你创建 Ingress。不要单独编写 Ingress 清单文件。

完整的 values 列表请参见chart values 文件。

将密码排除在 Git 之外

使用 valuesFrom 从 Kubernetes Secret 中读取值。targetPath 字段用于指定要填充的 chart 值名称。

spec:
  valuesFrom:
    - kind: Secret
      name: signoz-clickhouse-credentials
      valuesKey: password
      targetPath: clickhouse.password

使用 SOPS 等工具存储 Secret 本体，并在 SigNoz 的 Flux Kustomization 中添加 decryption 块。

升级 SigNoz

要迁移到新的 chart 版本，请编辑 HelmRelease 中的 version 字段，然后提交并推送：

  chart:
    spec:
      chart: signoz
      version: "<new-chart-version>"

将 <new-chart-version> 替换为所需的版本号，例如 0.142.1。可在 SigNoz charts 发布页查阅已发布的版本。

Flux 将在下次 reconcile 时执行 Helm 升级。若要回滚，撤销该提交即可。HelmRelease 中的 upgrade.cleanupOnFail 配置会指示 Flux 在重试前删除升级失败时创建的资源。

故障排查

flux install 报告部署未就绪

flux install 和 flux bootstrap 命令会等待控制器启动最多 5 分钟。在连接较慢的情况下，容器镜像拉取耗时较长，命令会输出以下信息：

✗ helm-controller: deployment not ready
✗ install failed

集群内的安装过程仍在继续。等待控制器就绪后，运行 flux check：

kubectl -n flux-system wait --for=condition=Available deployment --all --timeout=20m
flux check

HelmRelease 停留在 “Running 'install' action”

当 Helm 等待 pod 就绪时，Flux 会报告此消息。检查 pod 以定位原因：

kubectl get pods -n signoz
kubectl describe pod -n signoz <pod-name>

若 pod 长期处于 Pending 状态，说明集群 CPU、内存或存储资源不足。SigNoz 最低要求 4 个 CPU 核心和 8 GB 内存。此外，集群还需具备默认的 StorageClass 以支持持久卷