Install SigNoz on Any Kubernetes Cluster - Self-Host Guide

Choose SigNoz Cloud for ease, or self-host for control—with the freedom to switch as your needs grow.

This guide explains how to install SigNoz on any Kubernetes cluster, on another cloud or on your own servers using the SigNoz Helm chart, with Foundry or with Helm directly.

Prerequisites

You must have a Kubernetes cluster
kubectl configured to reach the cluster, and Helm 3 installed on the same machine.
Enough cluster capacity for SigNoz. For sizing, see resource planning.

Install SigNoz

Step 1: Add the Helm repository

Run this on the machine where you use kubectl:

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

Step 2 (optional): Choose a storage class

SigNoz keeps its data on persistent volumes. A storage class decides what kind of disk your cluster creates for them. Without this step, SigNoz uses your cluster's default storage class. To see what your cluster offers:

kubectl get storageclass

Pick a class that allows volume expansion, so you can grow the SigNoz volumes later by changing the claim size.

If the default storage class is the only option and it does not allow expansion yet, turn it on. Run this on the machine where you use kubectl:

DEFAULT_STORAGE_CLASS=$(kubectl get storageclass -o=jsonpath='{.items[?(@.metadata.annotations.storageclass\.kubernetes\.io/is-default-class=="true")].metadata.name}')
 
kubectl patch storageclass "$DEFAULT_STORAGE_CLASS" -p '{"allowVolumeExpansion": true}'

kubectl get storageclass then shows ALLOWVOLUMEEXPANSION as true for that class.

To use a specific one, create a file named values.yaml:

global:
  storageClass: <storage-class>

Verify these values:

<storage-class>: A storage class name from the kubectl get storageclass output.

Any other chart value goes in the same file. See the chart configuration reference.

Step 3: Install the chart

Run this from the directory that contains values.yaml:

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

Leave out -f values.yaml if you skipped Step 2. --wait makes the command return once every pod is ready.

Step 4: Verify the installation

Check that the pods are running:

kubectl get pods -n signoz

The output should look similar to the following. Pod suffixes vary:

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

Once all pods are running, port-forward the SigNoz UI and open http://localhost:8080/ in your browser:

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

In another terminal, check the health endpoint:

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

The response is:

{"status":"ok"}

By default, retention period is set to 7 days for logs and traces, and 30 days for metrics. To change this, navigate to the General tab on the Settings page of SigNoz UI.

For more details, refer to the retention period guide.

Send data to SigNoz

Your applications send traces, metrics, and logs to the SigNoz collector. Inside the cluster, the collector listens at:

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

Use this address as the OTLP endpoint in your instrumentation, for example as the value of OTEL_EXPORTER_OTLP_ENDPOINT. For gRPC, use port 4317 instead.

The second signoz in the address is the namespace. If you installed SigNoz into a different namespace, use that one.

For applications outside the cluster, see the self-hosted ingestion guide.

Customize the installation

Every change follows the same loop: edit values.yaml, then upgrade the release:

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

Chart values: see the chart configuration reference for every setting.
Chart version: add --version <chart-version> to helm install and helm upgrade. Versions are listed in the SigNoz charts releases.

Verify these values:

<chart-version>: A chart version from the SigNoz charts releases, for example 0.144.0.

Troubleshooting

helm install times out

--wait waits for every pod to become ready. When the command times out, list the pods with kubectl get pods -n signoz and follow the two items below.

Pods stay Pending

Describe the pod to see why it is unscheduled:

kubectl describe pod -n signoz <pod-name>

Replace <pod-name> with a pod name from the kubectl get pods -n signoz output.

A pod that reports insufficient CPU or memory needs more node capacity. See resource planning.

After the fix, kubectl get pods -n signoz shows the pod as Running.

A pod keeps restarting

Check its logs:

kubectl logs -n signoz <pod-name>

To see the logs from before the last restart, add --previous.

Install SigNoz

Foundry is an open-source CLI that runs your self-hosted observability stack as code. One declarative config provisions the infrastructure, installs the SigNoz backend, and sets up OpenTelemetry collection on bare metal, containers, or Kubernetes. Learn more about Foundry.

Step 1: Install foundryctl

Run this on the machine where you use kubectl:

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

For manual install (Windows PowerShell, air-gapped, etc.) or PATH setup, see the foundry getting-started guide.

Step 2: Create casting.yaml

Create a file named casting.yaml. It describes the installation: SigNoz from the Helm chart, in a namespace named signoz:

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

The telemetrykeeper lines select ZooKeeper, which the Helm chart uses to coordinate ClickHouse.

For all options, see the casting file reference and the Kubernetes Helm example.

Annotations under metadata set where SigNoz is installed and which chart is used. The defaults are:

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/kubernetes-namespace: signoz            # namespace to install into, created if missing
    foundry.signoz.io/kubernetes-helm-chart: signoz           # chart name, archive URL, or local path
    foundry.signoz.io/kubernetes-helm-repo-url: https://charts.signoz.io
    foundry.signoz.io/kubernetes-helm-chart-version: latest   # or a pinned version such as 0.144.0

The casting file reference describes each one.

Step 3 (optional): Choose a storage class

kubectl get storageclass

Pick a class that allows volume expansion, so you can grow the SigNoz volumes later by changing the claim size.

If the default storage class is the only option and it does not allow expansion yet, turn it on. Run this on the machine where you use kubectl:

DEFAULT_STORAGE_CLASS=$(kubectl get storageclass -o=jsonpath='{.items[?(@.metadata.annotations.storageclass\.kubernetes\.io/is-default-class=="true")].metadata.name}')
 
kubectl patch storageclass "$DEFAULT_STORAGE_CLASS" -p '{"allowVolumeExpansion": true}'

kubectl get storageclass then shows ALLOWVOLUMEEXPANSION as true for that class.

To use a specific one, add this to casting.yaml:

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

Verify these values:

<storage-class>: A storage class name from the kubectl get storageclass output.

Step 4: Deploy

Run this from the directory that contains casting.yaml:

foundryctl cast -f casting.yaml

This installs the SigNoz Helm chart into the signoz namespace and creates the namespace when it is missing. Run the same command again after editing casting.yaml to apply the change.

To run Helm directly, generate the values file and pass it to Helm:

foundryctl forge -f casting.yaml   # writes 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

Step 5: Verify the installation

Check that the pods are running:

kubectl get pods -n signoz

The output should look similar to the following. Pod suffixes vary:

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                          1/1     Running     0          3m
signoz-telemetrystore-clickhouse-operator-7f8c9d6b5-q4w2z   2/2     Running     0          3m
signoz-telemetrystore-migrator-x7h3k                        0/1     Completed   0          2m

Once all pods are running, port-forward the SigNoz UI and open http://localhost:8080/ in your browser:

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

In another terminal, check the health endpoint:

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

The response is:

{"status":"ok"}

By default, retention period is set to 7 days for logs and traces, and 30 days for metrics. To change this, navigate to the General tab on the Settings page of SigNoz UI.

For more details, refer to the retention period guide.

Send data to SigNoz

Your applications send traces, metrics, and logs to the SigNoz collector. Inside the cluster, the collector listens at:

http://signoz-ingester.signoz.svc.cluster.local:4318

Use this address as the OTLP endpoint in your instrumentation, for example as the value of OTEL_EXPORTER_OTLP_ENDPOINT. For gRPC, use port 4317 instead.

The second signoz in the address is the namespace. If you installed SigNoz into a different namespace, use that one.

For applications outside the cluster, see the self-hosted ingestion guide.

Customize the installation

Every change follows the same loop: edit casting.yaml, then run foundryctl cast -f casting.yaml again.

Component settings (image, replicas, environment): set them in the component's spec. For example, to pin SigNoz to a specific release:
```
spec:
  signoz:
    spec:
      image: signoz/signoz:v0.144.0
```
Chart values (resources, tolerations, persistence size): add patches under spec.patches against deployment/values.yaml, the same way as the storage class in Step 3. Each run regenerates the files under pours/, so keep every change in casting.yaml.

Troubleshooting

foundryctl fails

Re-run the failing command with --debug for verbose logs.

Pods stay Pending

Describe the pod to see why it is unscheduled:

kubectl describe pod -n signoz <pod-name>

Replace <pod-name> with a pod name from the kubectl get pods -n signoz output.

A pod that reports insufficient CPU or memory needs more node capacity. See resource planning.

After the fix, kubectl get pods -n signoz shows the pod as Running.

A pod keeps restarting

Check its logs:

kubectl logs -n signoz <pod-name>

To see the logs from before the last restart, add --previous.

Install SigNoz on Any Kubernetes Cluster - Self-Host Guide

Prerequisites

Install SigNoz

Step 1: Add the Helm repository

Step 2 (optional): Choose a storage class

Step 3: Install the chart

Step 4: Verify the installation

Send data to SigNoz

Customize the installation

Troubleshooting

helm install times out

Pods stay Pending

A pod keeps restarting

Install SigNoz

Step 1: Install foundryctl

Step 2: Create casting.yaml

Step 3 (optional): Choose a storage class

Step 4: Deploy

Step 5: Verify the installation

Send data to SigNoz

Customize the installation

Troubleshooting

foundryctl fails

Pods stay Pending

A pod keeps restarting

Next Steps