Install with Helm

The fusescope chart deploys the FuseScope backend and UI, the FuseScope OpenTelemetry collector, the telemetry schema migrator, ClickHouse with ZooKeeper and, optionally, PostgreSQL.

Use this page when you install FuseScope for the first time, or upgrade it.

Before you start

You need:

• A Kubernetes cluster with a default storage class, so the chart can create persistent volumes. Any managed cluster (EKS, GKE, AKS) works. To try FuseScope on your own machine, create a local cluster with kind or minikube; both come with a default storage class.
• Room for ClickHouse. The pods request little CPU and memory at rest, but ClickHouse uses several GB of memory once data flows. For a trial, give the cluster at least 4 CPUs and 8 GB of memory, and 20 GB of disk for the default ClickHouse volume.
• kubectl, configured for the cluster: kubectl get nodes should list its nodes.
• Helm 3.

Install

1. Add the chart repository:

   helm repo add fusescope https://fuseone-io.github.io/fusescope-charts
   helm repo update

2. Install the chart:

   helm install fusescope fusescope/fusescope \
     --namespace fusescope --create-namespace \
     -f values.yaml

   values.yaml is optional; see key values below.

3. Open the UI. Without an ingress, forward the service port:

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

   Browse to http://localhost:8080 and create the first admin user on the sign-up page.

Check that it worked

1. List the pods:

   kubectl get pods -n fusescope

   Every pod should show Running, except the schema migrator jobs, which show Completed. The first start takes a few minutes while images download and ClickHouse initializes.

2. If a pod stays in Pending, describe it to see why, often a missing storage class or too little memory:

   kubectl describe pod -n fusescope <pod-name>

3. Open the UI and sign in. The Home page shows which signals are arriving. None are until you send data, which is the next step.

With the release named fusescope, the chart creates these services:

Service	Ports	Purpose
fusescope	8080	UI and API
fusescope-otel-collector	4317, 4318	OTLP gRPC and OTLP/HTTP ingestion

Key values

Value	Default	Description
global.storageClass	null	Storage class for every PVC. null uses the cluster default.
clickhouse.persistence.size	20Gi	ClickHouse data volume.
clickhouse.layout.shardsCount / replicasCount	1 / 1	ClickHouse cluster layout.
clickhouse.coldStorage.enabled	false	Keep data older than each signal’s move period in S3, GCS or an S3-compatible bucket. Recommended for production installs that keep more than 7 days; see cold storage.
clickhouse.enabled	true	Set to false and fill externalClickhouse.* to use an existing ClickHouse.
postgresql.enabled	false	Deploy PostgreSQL and use it as the metadata store.
signoz.replicaCount	1	Backend replicas. Use more than one only with PostgreSQL.
signoz.persistence.size	1Gi	Volume for the SQLite database. Not created when PostgreSQL is enabled.
signoz.env	see chart	Environment variables of the backend.
signoz.config	{}	Contents of the configuration file.
signoz.ingress.*	disabled	Ingress for the UI and API.
otelCollector.ingress.*	disabled	Ingress for OTLP/HTTP ingestion.
otelCollector.replicaCount	1	Collector replicas.

The signoz.* keys configure the FuseScope backend; they keep an internal name. The full list, with comments, is in the chart’s values.yaml.

Environment variables

Keys under signoz.env are upper-cased, so signoz_global_external__url becomes SIGNOZ_GLOBAL_EXTERNAL__URL, which sets global.external_url. A value is either a plain string or a valueFrom reference:

signoz:
  env:
    signoz_global_external__url: https://fusescope.example.com
    MY_SECRET:
      valueFrom:
        secretKeyRef:
          name: my-secret
          key: my-key

See environment variables for the naming rules.

Configuration file

Note

signoz.config is available from chart version 0.148.0.

The chart renders signoz.config into a ConfigMap, mounts it at /etc/fusescope/config.yaml and starts the backend with --config. Pods restart when it changes. Use it for settings that do not fit environment variables, such as SSO domains:

signoz:
  config:
    authdomain:
      domains:
        - name: example.com
          config:
            kind: oidc
            spec:
              issuer: https://keycloak.example.com/realms/example
              clientId: fusescope
              clientSecret: ${OIDC_CLIENT_SECRET}
  env:
    OIDC_CLIENT_SECRET:
      valueFrom:
        secretKeyRef:
          name: fusescope-oidc
          key: client-secret

Expose FuseScope

A values file for a public installation with an NGINX ingress and cert-manager:

signoz:
  ingress:
    enabled: true
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
      - host: fusescope.example.com
        paths:
          - path: /
            pathType: ImplementationSpecific
            port: 8080
    tls:
      - secretName: fusescope-tls
        hosts:
          - fusescope.example.com
  env:
    signoz_global_external__url: https://fusescope.example.com
    signoz_alertmanager_signoz_external__url: https://fusescope.example.com

global.external_url is the URL users reach FuseScope on. Set the Alertmanager external URL too so links in alert notifications point to it. To accept OTLP from outside the cluster, see OTLP ingress.

Browsers send Real User Monitoring data to /rum/ on this same host, which the path / above already routes to the backend. See Self-hosted FuseScope for CORS, body size and the client IP behind an ingress.

Upgrade and uninstall

helm repo update
helm upgrade fusescope fusescope/fusescope -n fusescope -f values.yaml

The schema migrator runs as a pre-upgrade hook and applies ClickHouse schema changes before the new version starts.

helm -n fusescope uninstall fusescope

Next step

Send data from an application: see Instrument applications, and Kubernetes to collect the cluster’s own logs and metrics. Within a minute of the first requests, your service appears under Services.