Deploying SigNoz with Argo CD - GitOps on Kubernetes

This guide explains how to deploy SigNoz on Kubernetes with Argo CD. You declare the SigNoz Helm chart as an Argo CD Application. Argo CD renders the chart and applies it to the cluster.

Prerequisites

• Kubernetes version >= 1.22
• Currently supports x86-64, amd64 and arm64 architectures
• Helm version >= 3.8
• You must have kubectl access to your cluster

• The following table describes the hardware requirements that are needed to install SigNoz on Kubernetes:

  Component	Minimal Requirements	Recommended
  Memory	8 GB	16 GB
  CPU	4 cores	8 cores
  Storage	30 GB	80 GB

• Argo CD running in your cluster. See the Argo CD getting started guide.
• The argocd CLI on your machine, or access to the Argo CD web UI.

Installation steps

Create the Argo CD Application

The Application resource points Argo CD at the SigNoz Helm chart. Create a file named 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

Verify these values:

• targetRevision: The SigNoz chart version. Find the current version in the SigNoz charts releases.
• destination.namespace: The namespace for SigNoz. The CreateNamespace=true option creates it on the first sync, so you do not have to create it yourself.

The chart installs SigNoz, the SigNoz OpenTelemetry Collector, ClickHouse, and ZooKeeper.

Apply the Application

The YAML file is the declarative source of truth. The CLI and UI tabs create the same Application without it, so use them when you prefer an imperative setup.

kubectl apply -f signoz-application.yaml

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

Sync the Application

The Application above uses the default manual sync policy, so Argo CD does not install the chart until you sync it:

argocd app sync signoz

In the UI, open the signoz application and click SYNC, then SYNCHRONIZE.

The first sync downloads the container images for SigNoz, ClickHouse, and ZooKeeper. On a slow connection this takes several minutes. To sync on every change instead, see Sync automatically.

Validate

Make sure that the Application reports Synced and Healthy. In the UI, the application page shows this under APP HEALTH and SYNC STATUS. With the CLI, run:

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

Make sure that the pods run:

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

The signoz-telemetrystore-migrator pod runs the schema migration once and then reports Completed. Kubernetes removes the pod later, so the list does not always show it.

Open the SigNoz UI on your machine:

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

Go to http://localhost:8080. SigNoz asks you to create an admin account on the first visit.

To make sure that the API answers, run:

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

{"status":"ok"}

Customize the installation

Add a helm.valuesObject block under the existing spec.source in the Application. Do not replace the file. Argo CD passes the values to Helm on the next sync.

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

The chart creates the Ingress for you. Do not write a separate Ingress manifest.

For the full list of values, see the chart values file.

Keep values in a Git repository

To manage values as files, declare two sources in the Application you already created. Argo CD reads the chart from the SigNoz repository and the values file from your own repository. A single-source Application cannot do this, because helm.valueFiles resolves only inside the source that holds the chart.

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

Verify these values:

• <your-org> and <your-repo>: The organization and name of your own Git repository, the one Argo CD reads the values file from.
• targetRevision: main: The branch of your repository that holds the values file.
• ref: values: Names the second source. The $values prefix in valueFiles points at it.
• $values/signoz/values.yaml: The path to your values file inside your own repository.

Replace spec.source with spec.sources when you use this form. See the Argo CD documentation for Helm value files from an external Git repository.

Sync automatically

Add an automated sync policy under the existing spec: so that Argo CD applies every change without a manual sync. Do not replace the file.

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

prune removes resources that the chart no longer defines. selfHeal reverts manual edits to the live resources.

Upgrade SigNoz

To move to a new chart version, edit targetRevision in the Application:

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

Replace <new-chart-version> with the version you want, for example 0.142.1. Find the published versions in the SigNoz charts releases.

Apply the change, then sync:

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

With an automated sync policy, Argo CD upgrades the release on its own.

To roll back, set targetRevision to the previous version and apply the Application again. The argocd app rollback command is an alternative, but it works only with a manual sync policy. With an automated sync policy it stops with this error:

rollback cannot be initiated when auto-sync is enabled

argocd app sync signoz

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

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

kubectl describe pod -n signoz <pod-name>

Next Steps

• Collect Telemetry from your K8s Clusters
• Use OpenTelemetry Operator for automatic instrumentation
• Manage SigNoz resources as Kubernetes custom resources with the SigNoz Operator