---
title: "Configuration reference"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/config-files/config-reference/index.html"
---

**Important**


This information refers to the previous helm install method for the ITRS Analytics Platform. If you are looking to install using the more streamlined Kubernetes Off-the-Shelf (KOTS) method, see the updated [deployment options](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/deployment-options/index.html).



This topic describes advanced configuration settings for the ITRS Analytics Platform Helm chart. Advanced configuration settings are all optional. You are not required to change the settings described here for a default installation of ITRS Analytics. 

## Resource settings

For each ITRS Analytics workload there is a `resources` parameter that defines the resource requests and limits for the pods in that workload.  We recommend setting these parameters for all applications, otherwise some pods may consume all available resources on your Kubernetes cluster.

The Platform reference configs set baseline resources and limits for all workloads.  You can alter them as needed, for example:

``` yaml
kafka:
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "2Gi"
      cpu: "1"
```

## ClickHouse volume sizing

Fresh installs use `clickhouse` rather than `timescale`. Each ClickHouse workload has its own disk settings under `clickhouse.platform`, `clickhouse.metrics`, `clickhouse.logs`, and `clickhouse.traces`.

```yaml
clickhouse:
  traces:
    diskSize: "80Gi"
  metrics:
    diskSize: "500Gi"
    diskCount: 4
    storageClass: "gp3-clickhouse"
  platform:
    diskSize: "100Gi"
    storageClass: "gp3-clickhouse"
  logs:
    diskSize: "500Gi"
    storageClass: "gp3-clickhouse"
  keeper:
    replicas: 3
```

Use `diskSize` to set the size of the persistent volume for a ClickHouse workload. Each ClickHouse workload also supports `diskCount`, which can be used to distribute data across multiple disks. In practice, this is most likely to be used for traces, metrics, and logs, but it is available for all ClickHouse workloads. You can also set `storageClass` per workload when ClickHouse data needs a different storage class from `defaultStorageClass`.

When `clickhouse.metrics.diskCount` is greater than `1`, calculate the total metrics disk capacity per replica using the following formula:

```
clickhouse.metrics.diskSize * clickhouse.metrics.diskCount
```

The `clickhouse.keeper.replicas` setting controls the size of the ClickHouse Keeper cluster used by replicated ClickHouse deployments.


**Note**


The `timescale` and `loki` settings apply only to upgrades from pre-2.18 deployments that still have data to migrate. They are not used for fresh installs.



## Kafka retention settings

The `kafka.defaultRetentionMillis` parameter controls how long data is retained in Kafka topics, which defaults to
`21600000` (6 hours).

## ClickHouse on reserved nodes

For larger deployments, you may want to run ClickHouse workloads on reserved Kubernetes nodes. Medium and large HA deployments do this by using Kubernetes `labels` and `taints` on the nodes and `nodeSelector` and `tolerations` on the ClickHouse workloads.

1. Add a `label` to the ClickHouse nodes in the manifest or by using `kubectl`:
   ```yaml
   instancegroup: clickhouse-nodes
   ```

2. Add a `taint` to the ClickHouse nodes in the manifest or by using `kubectl`:
   ```yaml
   dedicated=clickhouse-nodes:NoSchedule
   ```

3. Set the following for each ClickHouse workload that should run on the reserved nodes:
   ```yaml
   clickhouse:
     metrics:
       nodeSelector:
         instancegroup: clickhouse-nodes
       tolerations:
         - key: dedicated
           operator: Equal
           value: clickhouse-nodes
           effect: NoSchedule
   ```

Apply the same pattern to `clickhouse.platform`, `clickhouse.logs`, and `clickhouse.traces` if those workloads should also run on the reserved nodes.

## Default workload placement

Use `defaultNodeSelector` and `defaultTolerations` when most operator-managed workloads should run on the same Kubernetes nodes.

- `defaultNodeSelector` applies a shared `nodeSelector` to any workload that does not define its own `nodeSelector`.
- `defaultTolerations` applies shared `tolerations` to any workload that does not define its own `tolerations`.
- A workload-specific `nodeSelector` overrides `defaultNodeSelector` for that workload, and workload-specific `tolerations` override `defaultTolerations`.
- These settings work independently. Defining a workload-specific `nodeSelector` does not affect `defaultTolerations`, and defining workload-specific `tolerations` does not affect `defaultNodeSelector`.
- If neither a default setting nor a workload-specific setting is defined, the workload is deployed without `nodeSelector` or `tolerations`.

For example:

```yaml
defaultNodeSelector:
  role: iax
defaultTolerations:
  - key: dedicated
    operator: Equal
    value: iax
    effect: NoSchedule

platformd:
  nodeSelector:
    role: iax-control
```

Use workload-specific settings only when a workload must run on a different node pool from the shared default.


**Note**


When you use `nodeSelector` or `defaultNodeSelector` with high-availability workloads such as Kafka, `etcd`, `pgplatform`, and ClickHouse, make sure the selector matches at least as many nodes as the replica count. For zone-level redundancy, make sure the matching nodes also span multiple availability zones.

The `nodeSelector` can neutralize topology spread constraints. When `nodeSelector` limits a workload to fewer eligible nodes than the replica count, Kubernetes evaluates topology spread only across those eligible nodes. If only one node matches the selector, all replicas can be scheduled onto that node without raising a scheduling error.



For example, Kafka can be configured with three replicas and a topology spread constraint on `kubernetes.io/hostname`. If `nodeSelector: { role: iax }` is set but only one node has the `role=iax` label, all three replicas can be scheduled onto that single node. If that node fails, all three replicas are lost at the same time.

If you add or change `nodeSelector` for stateful workloads such as Kafka, `etcd`, `pgplatform`, or ClickHouse, during an upgrade, make sure the selected nodes are in the same availability zone as the existing persistent volumes. Otherwise, the pods can remain in `Pending` state with a volume node affinity conflict.

To resolve this, update the `nodeSelector` so the workload is scheduled onto nodes in the same availability zone as the existing PVC. Deleting and recreating the PVC can also remove the conflict, but doing so deletes the existing persistent data and results in data loss.

## Ingestion services

ITRS Analytics supports ingesting data via two gRPC endpoints, which are both serviced from the same external host name (as defined by `ingestion.externalHostname`) and port (`443`). 

You can tune ingestion by setting `ingestion` and `ingestion.traces` resources and producer settings, for example:

```yaml
ingestion:
  externalHostname: "iax-ingestion.mydomain.internal"
  ingress:
    className: "nginx"
    annotations:
      nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
  traces:
    sampler:
      expectedSpanRate: 20000
    producerProperties:
      buffer.memory: 67108864
```

If your deployment ingests OpenTelemetry traces, review the `ingestion.traces` settings, including `ingestion.traces.resources`, and adjust them for your expected span rate. Higher span rates require more resources.

### OpenTelemetry ingestion service 

While raw traces are currently not stored, the OpenTelemetry ingestion service in the ITRS Analytics platform captures the following metrics (where `<span>` is the span name):
- `<span>_count`
- `<span>_error_count`
- `<span>_latency`

When pointing your instrumentation to the ITRS Analytics OpenTelemetry API, make sure to: 

- Provide the correct endpoint. The service uses the same hostname and port to ingest OpenTelemetry data as it does other data.
- Add API keys with the following parameter values: 
    - `otel-client-username: ingestion-api`
    - `otel-client-password: ingestion`

 For more information, refer to the [instrumentation guide from Open Telemetry](https://opentelemetry.io/docs/concepts/instrumenting/).

## Kubernetes log collection

ITRS Analytics is configured to collect logs for Kubernetes pods and containers in the configured namespaces, or
the ITRS Analytics namespace by default. This behavior is controlled by the following setting:
```yaml
collection:
  logs:
    enabled: true
    # Restrict collection to specific namespaces. If empty, only the ITRS Analytics installation namespace
    # will be collected. To collect all, specify "*".
    namespaces: []
```


**Note**


For the log collection process to function properly, the `obcerv-operator` Kubernetes service account must have
appropriate permissions to create resources with read and write access to `hostPath` volumes. The process for granting
these permissions may vary depending on your Kubernetes distribution.




