Configuration options#

This page lists every field of MonitoringConfig, its type, and its default where the package ships one.

The configuration has two parts. RequiredClusterConfig fields have no default and you must provide them. DefaultableConfig fields have a value in DEFAULT_CONFIG and you override them through mergeConfig.

Configuration types#

MonitoringConfig

The fully resolved configuration consumed by MonitoringChart. It extends RequiredClusterConfig and DefaultableConfig.

MonitoringConfigInput

The input accepted by mergeConfig. It is RequiredClusterConfig plus a DeepPartial of DefaultableConfig.

DeepPartial<T>

A recursive partial in which every property, including nested properties, becomes optional.

Required cluster configuration#

These fields belong to RequiredClusterConfig and have no default.

namespace#

Field

Type

Description

namespace

string

Kubernetes namespace the stack runs in.

clusterName#

Field

Type

Description

clusterName

string

Value of the cluster external label applied to all metrics and logs. Identifies this cluster when several feed one Grafana or Thanos.

domains#

Field

Type

Description

domains.grafana

string

Grafana hostname, used for the ingress and the default root_url.

domains.ingressClassName

string (optional)

IngressClass for the Grafana ingress. When omitted, the ingress carries no ingressClassName and relies on the cluster’s default IngressClass. Set it explicitly on clusters whose ingress controller class is not marked as default.

domains.grafanaIngress

boolean (optional)

Create the Grafana ingress. Default true. Set false when Grafana is reached another way, for example through a VPN proxy in front of its Service.

domains.grafanaRootUrl

string (optional)

Grafana root_url, from which it builds links and redirects. Default https://<domains.grafana>.

s3#

Field

Type

Description

s3.endpoint

string

Full S3 endpoint with protocol (used by Loki).

s3.endpointNoProtocol

string

S3 endpoint without protocol (used by Thanos).

s3.region

string

S3 region.

s3.buckets.thanos

string

Bucket name for Thanos metrics.

s3.buckets.loki

string

Bucket name for Loki logs.

smtp#

Field

Type

Description

smtp.host

string

SMTP server hostname.

smtp.port

number

SMTP server port.

smtp.from

string

From address; also the alert recipient when smtp.recipients is unset.

smtp.username

string (optional)

SMTP username; falls back to smtp.from.

smtp.password

string (optional)

SMTP password as a literal. Renders into the synthesized manifests in clear text. Prefer smtp.passwordSecret.

smtp.passwordSecret

object (optional)

Read the password from a mounted secret instead. Takes precedence over smtp.password.

smtp.passwordSecret.name

string

Secret name in the monitoring namespace.

smtp.passwordSecret.key

string

Key within that secret holding the password.

smtp.recipients

string[] (optional)

Alert recipients. Defaults to [smtp.from].

smtp.headers

Record<string, string> (optional)

Extra mail headers on every notification, for example {"X-Mailjet-TrackClick": "0"} to keep a relay from rewriting links.

smtp.requireTls

boolean

Require TLS for the SMTP connection.

integrations#

These fields name external Crossplane and External Secrets Operator resources that the stack references but does not create. Each must already exist in your cluster. All are required strings with no default.

Field

Type

Description

integrations.s3ProviderConfig

string

Crossplane ProviderConfig name the Bucket resources reconcile against.

integrations.s3SecretStore

string

ESO ClusterSecretStore name holding the S3 credentials.

integrations.s3CredentialsKey

string

Remote key in that store providing AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

integrations.grafanaSecretStore

string

ESO ClusterSecretStore name holding the Grafana admin credentials.

integrations.grafanaCredentialsKey

string

Remote key in that store providing admin-user and admin-password.

Defaultable configuration#

These fields belong to DefaultableConfig. Each one shows the value shipped in DEFAULT_CONFIG.

versions#

Field

Type

Default

versions.prometheusStack

string

87.0.0

versions.loki

string

7.0.0

versions.alloy

string

1.10.0

versions.thanos

string

v0.41.0

versions.tempo

string

1.24.4

A version of latest omits the version field and lets the Helm controller resolve the newest chart. The Alloy traces gateway uses versions.alloy; it has no separate version field.

retention#

Field

Type

Default

retention.prometheus

string

2d

retention.prometheusS3Raw

number

30

retention.prometheusS35m

number

180

retention.prometheusS31h

number

730

retention.loki

string

744h

The prometheusS3Raw, prometheusS35m, and prometheusS31h values are Thanos retention windows in days for raw, 5-minute, and 1-hour resolutions.

storage#

Field

Type

Default

storage.prometheus

string

15Gi

storage.grafana

string

5Gi

storage.alertmanager

string

1Gi

storage.lokiBackend

string

10Gi

storage.lokiWrite

string

3Gi

storage.thanosStore

string

10Gi

storage.thanosCompactor

string

20Gi

storage.tempo

string

5Gi

storage.className

string

longhorn

The tempo value sizes the Tempo write-ahead-log and local-blocks PVC; persisted trace blocks live in S3.

The className value is the StorageClass of every PVC in the stack: Prometheus, Alertmanager, Grafana, Loki backend, Loki write, Thanos Store, Thanos Compactor, and Tempo. An empty string omits storageClassName, so the cluster’s default StorageClass applies.

Warning

Kubernetes does not move an existing PVC to another class. A changed className applies only to PVCs created afterward; existing PVCs keep their class and their data.

replicas#

Field

Type

Default

replicas.prometheus

number

2

replicas.alertmanager

number

2

replicas.grafana

number

1

replicas.lokiBackend

number

2

replicas.lokiRead

number

2

replicas.lokiWrite

number

2

replicas.thanosQuery

number

2

replicas.thanosStore

number

2

replicas.tempo

number

1

The Alloy traces gateway is fixed at one replica and has no replica field; tail sampling requires a single instance to see every span of a trace.

resources#

Each resources entry is a ResourceRequirements object with requests and limits, and each of those is a ResourceAllocation with cpu and memory.

Component

Requests (cpu / memory)

Limits (cpu / memory)

resources.prometheus

100m / 1500Mi

2 / 3000Mi

resources.grafana

50m / 512Mi

200m / 1Gi

resources.alertmanager

25m / 100Mi

100m / 200Mi

resources.lokiBackend

100m / 256Mi

500m / 512Mi

resources.lokiRead

100m / 256Mi

500m / 512Mi

resources.lokiWrite

100m / 512Mi

1 / 1Gi

resources.lokiGateway

50m / 128Mi

200m / 256Mi

resources.alloy

100m / 128Mi

200m / 256Mi

resources.thanosQuery

200m / 512Mi

1000m / 1Gi

resources.thanosStore

200m / 1Gi

1000m / 2Gi

resources.thanosCompactor

500m / 2Gi

2000m / 4Gi

resources.configReloader

10m / 50Mi

50m / 100Mi

resources.thanosSidecar

10m / 50Mi

100m / 100Mi

resources.tempo

100m / 256Mi

1 / 1Gi

resources.alloyTraces

100m / 256Mi

500m / 512Mi

The configReloader entry applies to the config-reloader sidecar of Prometheus, Alertmanager, and Alloy. The thanosSidecar entry applies to the Thanos sidecar attached to Prometheus. The tempo entry applies to the monolithic Tempo workload, and alloyTraces to the Alloy traces gateway.

tempo#

The tempo block configures the opt-in distributed tracing pillar. It belongs to DefaultableConfig, so it defaults to disabled and you override only what you need. When tempo.enabled is false, no tracing resources are created.

Field

Type

Default

Description

tempo.enabled

boolean

false

Master switch; when false, no Tempo, gateway, bucket, or datasource is created.

tempo.bucket

string

''

S3 bucket for trace blocks. Required when tempo.enabled is true.

tempo.retention

string

336h

Tempo block retention, enforced by the compactor (336h is 14 days).

tempo.tailSampling.latencyThresholdMs

number

1000

Keep traces slower than this many milliseconds.

tempo.tailSampling.probabilisticPercent

number

10

Keep this percentage of the remaining traces as a representative sample.

mergeConfig throws tempo.bucket is required when tempo.enabled is true when you enable tracing without a bucket name. The gateway always keeps traces that contain an error span, in addition to the slow and probabilistic policies above.

embedding#

The embedding block controls whether browsers may load Grafana inside an <iframe>. It belongs to DefaultableConfig, so it defaults to disabled. When embedding.enabled is false, grafana.ini carries no [security] section and Grafana keeps its own default of X-Frame-Options: deny.

Field

Type

Default

Description

embedding.enabled

boolean

false

Master switch; when true, sets allow_embedding, content_security_policy, and content_security_policy_template in grafana.ini.

embedding.frameAncestors

string[]

[]

Origins allowed to frame Grafana, each an absolute origin such as https://console.example.com. They are appended to frame-ancestors 'self'.

mergeConfig throws embedding.frameAncestors must name at least one origin when embedding.enabled is true when you enable embedding without an origin.

The generated policy repeats Grafana’s own default directives and adds frame-ancestors. It omits the $FORM_ACTION_ADDITIONAL_HOSTS placeholder from Grafana’s stock template, so form_action_additional_hosts has no effect while embedding is enabled.

stagingAlerts#

The stagingAlerts block controls demoted alert routing for staging namespaces that share the cluster’s monitoring stack. It belongs to DefaultableConfig, so it defaults to disabled. When stagingAlerts.enabled is false, the Alertmanager configuration carries no staging route or receiver.

Field

Type

Default

Description

stagingAlerts.enabled

boolean

false

Master switch; when true, adds a staging route and receiver to the Alertmanager configuration.

stagingAlerts.namespaces

string[]

[]

Namespaces whose alerts route to the staging receiver, matched against the namespace label.

mergeConfig throws stagingAlerts.namespaces must name at least one namespace when stagingAlerts.enabled is true when you enable the block without a namespace.

The staging receiver mails the same address as the production receiver with a [STAGING] subject prefix. The noise-drop routes for alertnames such as Watchdog keep precedence over the staging route.

deadMansSwitch#

The deadMansSwitch block forwards the always-firing Watchdog alert to an external heartbeat service. It belongs to DefaultableConfig, so it defaults to disabled. When deadMansSwitch.enabled is false, Watchdog goes to the null receiver.

Field

Type

Default

Description

deadMansSwitch.enabled

boolean

false

Master switch; when true, routes Watchdog to a deadmansswitch webhook receiver.

deadMansSwitch.urlSecret.name

string

''

Secret in the monitoring namespace that holds the webhook URL; Prometheus Operator mounts it into Alertmanager.

deadMansSwitch.urlSecret.key

string

''

Key of the webhook URL in that Secret; Alertmanager reads it with url_file.

deadMansSwitch.repeatInterval

string

5m

repeat_interval of the Watchdog route: how often the webhook is posted.

mergeConfig throws deadMansSwitch.urlSecret needs a name and a key when deadMansSwitch.enabled is true when you enable the block without both.

The URL never appears in the synthesized manifests.

alertRouting#

The alertRouting block paces Alertmanager notifications. It belongs to DefaultableConfig.

Field

Type

Default

Description

alertRouting.repeatInterval

string

12h

Alertmanager repeat_interval: how often a still-firing alert group is mailed again.

The routes, receivers, and inhibition rules around this interval are listed in Alerts and routing.

externalUrls#

The externalUrls block sets the browser-facing addresses that notifications link to. It belongs to DefaultableConfig.

Field

Type

Default

Description

externalUrls.alertmanager

string

''

Alertmanager externalUrl, used for the link to Alertmanager in every notification.

externalUrls.prometheus

string

''

Prometheus externalUrl, used for each alert’s source link (/graph?g0.expr=…). A Thanos Query in front of Prometheus understands the same links.

An empty string keeps the operator default, which is the in-cluster Service address and does not open from a browser. The setting changes only the links; the pods keep serving under the route prefix /.

Grafana carries an Alertmanager datasource, so the active alerts and silences are visible in Grafana as well.

traefik#

The traefik block adds opt-in monitoring for a Traefik ingress controller. It belongs to DefaultableConfig, so it defaults to disabled. When traefik.enabled is false, no Traefik resources are created.

Field

Type

Default

Description

traefik.enabled

boolean

false

Master switch; when true, creates the traefik-metrics PodMonitor.

traefik.namespace

string

traefik

Namespace Traefik runs in, used as the PodMonitor namespace selector.

traefik.dashboard

boolean

true

Ship the Traefik Grafana dashboard as the traefik-dashboard ConfigMap.

The PodMonitor selects pods labeled app.kubernetes.io/name: traefik and scrapes their metrics port at /metrics every 30 seconds. mergeConfig throws traefik.namespace is required when traefik.enabled is true when you enable the block with an empty namespace.

longhorn#

The longhorn block adds opt-in monitoring for Longhorn storage. It belongs to DefaultableConfig, so it defaults to disabled. When longhorn.enabled is false, no Longhorn resources are created.

Field

Type

Default

Description

longhorn.enabled

boolean

false

Master switch; when true, creates the longhorn-metrics ServiceMonitor.

longhorn.namespace

string

longhorn-system

Namespace Longhorn runs in, used as the ServiceMonitor namespace selector.

longhorn.alerts

boolean

true

Ship the longhorn-volume-health PrometheusRule.

The ServiceMonitor selects services labeled app: longhorn-manager and scrapes their manager port. The alert rules are listed in Alerts and routing. mergeConfig throws longhorn.namespace is required when longhorn.enabled is true when you enable the block with an empty namespace.

priorityClasses#

The priorityClasses block sets the priorityClassName of every pod in the stack. It belongs to DefaultableConfig.

Field

Type

Default

Description

priorityClasses.create

boolean

true

Create the high-priority PriorityClass (value 10000) in wave 0.

priorityClasses.capture

string

high-priority

Class for pods that ingest data or route alerts.

priorityClasses.query

string

high-priority

Class for pods that only serve queries.

The two roles cover these workloads:

Role

Workloads

capture

Prometheus, Alertmanager, Prometheus Operator, node-exporter, kube-state-metrics, Loki write, Loki backend, Loki gateway, Alloy, Tempo, Alloy traces gateway

query

Grafana, Thanos Query, Thanos Store, Thanos Compactor, Loki read

When you set priorityClasses.create to false, the classes named in capture and query must already exist in the cluster. Kubernetes rejects pods that name a missing PriorityClass.

See also#