Install SigNoz on Kubernetes via Kustomize - 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 with Kustomize. Foundry generates plain Kubernetes manifests for every component and applies them with kubectl, so you can inspect, version, and overlay them like any other manifests.

Prerequisites

A Kubernetes cluster.
kubectl configured to reach the cluster.
Network access from your machine to raw.githubusercontent.com, where the ClickHouse operator definitions are downloaded from.
Enough cluster capacity for SigNoz. For sizing, see resource planning.

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 as Kustomize manifests, in a namespace named signoz:

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: kustomize
    mode: kubernetes

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

To install into another namespace, add this annotation under metadata:

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/kubernetes-namespace: observability

Resource names stay based on metadata.name; only the namespace moves.

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. To see what your cluster offers:

kubectl get storageclass

To use a specific one, add this to casting.yaml. It sets the storage class on all four volume claims: the two ClickHouse volumes, ClickHouse Keeper and PostgreSQL:

spec:
  patches:
    - target: deployment/telemetrystore/clickhouse/clickhouseinstallation.yaml
      operations:
        - op: add
          path: /spec/templates/volumeClaimTemplates/0/spec/storageClassName
          value: <storage-class>
        - op: add
          path: /spec/templates/volumeClaimTemplates/1/spec/storageClassName
          value: <storage-class>
    - target: deployment/telemetrykeeper/clickhousekeeper/clickhousekeeperinstallation.yaml
      operations:
        - op: add
          path: /spec/templates/volumeClaimTemplates/0/spec/storageClassName
          value: <storage-class>
    - target: deployment/metastore/postgres/statefulset.yaml
      operations:
        - op: add
          path: /spec/volumeClaimTemplates/0/spec/storageClassName
          value: <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 generates the manifests into pours/deployment/, installs the ClickHouse operator and its definitions first, then applies SigNoz into the signoz namespace. Run the same command again after editing casting.yaml to apply the change.

pours/deployment/
├── kustomization.yaml          # Root kustomization
├── namespace.yaml              # SigNoz namespace
├── operators/
│   └── clickhouse-operator/    # Altinity ClickHouse Operator
│       ├── deployment.yaml
│       ├── clusterrole.yaml
│       ├── clusterrolebinding.yaml
│       ├── configmap.yaml
│       ├── namespace.yaml
│       ├── service.yaml
│       ├── serviceaccount.yaml
│       └── kustomization.yaml
├── telemetrystore/clickhouse/  # ClickHouse (time-series storage)
│   ├── clickhouseinstallation.yaml
│   ├── configmap.yaml
│   └── kustomization.yaml
├── telemetrykeeper/            # ClickHouse Keeper (coordination)
│   └── clickhousekeeper/
│       ├── clickhousekeeperinstallation.yaml
│       └── kustomization.yaml
├── metastore/postgres/         # PostgreSQL (metadata storage)
│   ├── statefulset.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── kustomization.yaml
├── signoz/                     # SigNoz query service
│   ├── statefulset.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── kustomization.yaml
├── ingester/                   # OTel Collector (telemetry ingestion)
│   ├── deployment.yaml
│   ├── configmap.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── kustomization.yaml
└── telemetrystore-migrator/    # Schema migration job
    ├── job.yaml
    └── kustomization.yaml

To apply with kubectl directly, generate the manifests and apply the two directories in order. The ClickHouse operator directory must be applied, and its definitions established, before the rest:

foundryctl forge -f casting.yaml
kubectl apply -k pours/deployment/operators/clickhouse-operator
kubectl wait --for=condition=Established --timeout=60s crd/clickhouseinstallations.clickhouse.altinity.com crd/clickhousekeeperinstallations.clickhouse-keeper.altinity.com
kubectl apply -k pours/deployment

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
chk-signoz-clickhouse-keeper-cluster-0-0-0                  1/1     Running     0          3m
signoz-ingester-6d9c7b8f5c-k2x9p                            1/1     Running     0          3m
signoz-metastore-0                                          1/1     Running     0          3m
signoz-signoz-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-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
```
Manifest fields (resources, tolerations, storage size): add patches under spec.patches that target the generated file, the same way as the storage class in Step 3. Each run regenerates the files under pours/, so keep every change in casting.yaml.

Kustomize overlays: Treat pours/deployment/ as a base and layer your own Kustomize overlay on top, then apply the overlay with kubectl apply -k. For example:

my-deployment/
├── base/                    # Copy of pours/deployment/
│   └── ...
└── overlays/
    └── prod/
        ├── kustomization.yaml
        └── increase-resources.yaml

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patches:
- path: increase-resources.yaml
  target:
    kind: StatefulSet
    name: signoz-signoz

The root pours/deployment/kustomization.yaml leaves out the operator tier, so apply pours/deployment/operators/clickhouse-operator first on a fresh cluster, as in the Step 4 tip. Run this from my-deployment/:

kubectl apply -k overlays/prod/

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 PersistentVolumeClaim that stays Pending usually means the cluster has no default storage class. Set one as in Step 3. A pod that reports insufficient CPU or memory needs more node capacity. The default requests are ClickHouse 500m CPU and 512Mi memory, ClickHouse Keeper 1 CPU and 1Gi, the ClickHouse operator 1 CPU and 2Gi, SigNoz 100m and 200Mi, PostgreSQL 100m and 128Mi, and the ingester 125m and 512Mi. 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.

ClickHouse resources are not recognised

kubectl apply -k pours/deployment reports unknown kinds ClickHouseInstallation or ClickHouseKeeperInstallation when the operator tier was not applied first. Apply pours/deployment/operators/clickhouse-operator, wait for the definitions, then apply again, as in the Step 4 tip.

The migration job fails

Check the migrator job logs:

kubectl logs -n signoz job/signoz-telemetrystore-migrator