Install SigNoz on Red Hat OpenShift - 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 a Red Hat OpenShift cluster using the SigNoz Helm chart, with Foundry or with Helm directly. OpenShift enforces Security Context Constraints (SCCs), so the install starts by creating one for SigNoz.

Prerequisites

An OpenShift cluster.
The oc or kubectl CLI configured to reach the cluster, and Helm 3 installed on the same machine.
Enough cluster capacity for SigNoz. For sizing, see resource planning.
A storage class with a provisioner supported on OpenShift. See the Red Hat storage documentation.

Install SigNoz

Step 1: Create the SecurityContextConstraints

OpenShift admits a pod only when an SCC allows what the pod needs. ClickHouse and ZooKeeper run with fixed user and group IDs and mount persistent volumes. Create a file named signoz-scc.yaml that allows this for their service accounts:

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: signoz-scc
 
allowPrivilegedContainer: false
runAsUser:
  type: RunAsAny        # allow any container UID
fsGroup:
  type: RunAsAny        # allow any supplemental GID
seLinuxContext:
  type: RunAsAny        # no SELinux label constraints
volumes:
  - persistentVolumeClaim # mounted PVC
  - emptyDir              # ephemeral scratch space
  - configMap             # ConfigMap files
  - projected             # combined CM/secret/etc.
  - downwardAPI           # expose pod metadata
 
readOnlyRootFilesystem: false
allowHostDirVolumePlugin: false
 
users:
  # Bind the SCC to Required Service Accounts for SigNoz
  - system:serviceaccount:signoz:signoz-clickhouse
  - system:serviceaccount:signoz:default

Verify these values:

signoz after system:serviceaccount:: the namespace you pass to helm install in Step 4.
signoz-clickhouse: the service account of ClickHouse. Its prefix is the release name you pass to helm install, so with a different release name, replace the leading signoz.
default: the service account ZooKeeper runs under. Keep it as is.

Apply it. Run this on the machine where you use oc:

oc apply -f signoz-scc.yaml

kubectl apply -f signoz-scc.yaml works the same way.

Step 2: 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 3 (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. On OpenShift, use a storage class whose provisioner is supported on your cluster; see the Red Hat storage documentation linked in Prerequisites. To see what your cluster offers:

kubectl get storageclass

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 4: 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 3. --wait makes the command return once every pod is ready.

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-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: Create the SecurityContextConstraints

OpenShift admits a pod only when an SCC allows what the pod needs. ClickHouse, ZooKeeper and PostgreSQL run with fixed user and group IDs and mount persistent volumes. Create a file named signoz-scc.yaml that allows this for their service accounts:

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: signoz-scc
 
allowPrivilegedContainer: false
runAsUser:
  type: RunAsAny        # allow any container UID
fsGroup:
  type: RunAsAny        # allow any supplemental GID
seLinuxContext:
  type: RunAsAny        # no SELinux label constraints
volumes:
  - persistentVolumeClaim # mounted PVC
  - emptyDir              # ephemeral scratch space
  - configMap             # ConfigMap files
  - projected             # combined CM/secret/etc.
  - downwardAPI           # expose pod metadata
 
readOnlyRootFilesystem: false
allowHostDirVolumePlugin: false
 
users:
  # Bind the SCC to Required Service Accounts for SigNoz
  - system:serviceaccount:signoz:signoz-telemetrystore-clickhouse
  - system:serviceaccount:signoz:signoz-metastore-postgres
  - system:serviceaccount:signoz:default

Verify these values:

signoz after system:serviceaccount:: the namespace. It is metadata.name from casting.yaml, or the namespace annotation from Step 3 when you set one.
signoz-telemetrystore-clickhouse and signoz-metastore-postgres: the service accounts of ClickHouse and PostgreSQL. Their prefix is metadata.name from casting.yaml, so with a different name, replace the leading signoz.
default: the service account ZooKeeper runs under. Keep it as is.

Apply it. Run this on the machine where you use oc:

oc apply -f signoz-scc.yaml

kubectl apply -f signoz-scc.yaml works the same way.

Step 2: 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 3: 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 4 (optional): Choose a storage class

kubectl get storageclass

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 5: 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 6: 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 4. 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.

SCC for Kubernetes monitoring (optional)

The Kubernetes monitoring agent needs host access that the SigNoz SCC does not grant, so it gets its own SCC. Create and apply it the same way before you install the agent from Next Steps:

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: signoz-k8s-infra-agent-scc
allowPrivilegedContainer: false
allowHostPorts: true
runAsUser:
  type: RunAsAny        # any container UID
fsGroup:
  type: RunAsAny        # any supplemental GID
seLinuxContext:
  type: RunAsAny        # any SELinux label
volumes:
  - persistentVolumeClaim # PVC
  - configMap             # ConfigMap files
  - projected             # combined CM/secret/etc.
  - downwardAPI           # pod metadata
  - hostPath              # host directory
  - secret                # Secret files
 
readOnlyRootFilesystem: false
allowHostDirVolumePlugin: true
# Bind this SCC only to the k8s-infra-otel-agent SA in the namespace
users:
  - system:serviceaccount:signoz:k8s-infra-otel-agent

signoz in the users entry is the namespace the agent runs in. If you install the agent into a different namespace, change it there.