---
myst:
  html_meta:
    "description": "Reference overview of the public API of cdk8s-monitoring: the MonitoringChart orchestrator, the configuration helpers, the configuration interfaces, and the stack constructs."
    "property=og:description": "Reference overview of the public API of cdk8s-monitoring: the MonitoringChart orchestrator, the configuration helpers, the configuration interfaces, and the stack constructs."
    "property=og:title": "API reference"
    "keywords": "cdk8s, Kubernetes, monitoring, API, constructs, MonitoringChart"
---

# API reference

This page describes the public API exported from `@bluedynamics/cdk8s-monitoring`.
The package is TypeScript-only and ships no generated API document; this curated reference is authoritative.

## Orchestrator

`MonitoringChart`
:   The top-level `Chart` that synthesizes the whole stack.
    Construct it with a resolved `MonitoringConfig`.
    Signature: `new MonitoringChart(scope, id, config, props?)`.
    It instantiates every stack construct below in sync-wave order; see {doc}`../sync-waves`.

## Configuration helpers

`mergeConfig(input)`
:   Resolves a full `MonitoringConfig` by deep-merging the caller's overrides over `DEFAULT_CONFIG`.
    Accepts a `MonitoringConfigInput` and returns a `MonitoringConfig`.
    Throws when an enabled opt-in block lacks a value it needs: `tempo.bucket`, `traefik.namespace`, `longhorn.namespace`, `embedding.frameAncestors`, or `stagingAlerts.namespaces`.

`DEFAULT_CONFIG`
:   The package-shipped `DefaultableConfig`.
    See {doc}`../configuration-options` for every value.

## Configuration interfaces

`MonitoringConfig`
:   The fully resolved configuration consumed by `MonitoringChart`.

`MonitoringConfigInput`
:   The input to `mergeConfig`: `RequiredClusterConfig` plus a `DeepPartial` of `DefaultableConfig`.

`RequiredClusterConfig`
:   The fields with no default: `namespace`, `clusterName`, `domains`, `s3`, `smtp`, `integrations`. `clusterName` sets the `cluster` external label on metrics and logs.

`IntegrationsConfig`
:   The names of external Crossplane and External Secrets Operator resources the stack references but does not create.
    Fields: `s3ProviderConfig`, `s3SecretStore`, `s3CredentialsKey`, `grafanaSecretStore`, `grafanaCredentialsKey`.
    All are required strings; see {doc}`../configuration-options` for each one.

`DefaultableConfig`
:   The fields with defaults: `versions`, `retention`, `storage`, `replicas`, `resources`, `tempo`, `traefik`, `longhorn`, `embedding`, `stagingAlerts`, `alertRouting`, `externalUrls`, and `priorityClasses`.

`TempoConfig`
:   The opt-in distributed tracing block.
    Fields: `enabled` (default `false`), `bucket` (required when enabled), `retention`, and `tailSampling`.
    See {doc}`../configuration-options` for each one.

`TempoTailSamplingConfig`
:   The tail-sampling policy for the Alloy traces gateway.
    Fields: `latencyThresholdMs` and `probabilisticPercent`.
    Error traces are always kept in addition to these.

`TraefikConfig`
:   The opt-in Traefik monitor.
    Fields: `enabled`, `namespace`, and `dashboard`.

`LonghornConfig`
:   The opt-in Longhorn monitor.
    Fields: `enabled`, `namespace`, and `alerts`.

`EmbeddingConfig`
:   The opt-in Grafana iframe embedding.
    Fields: `enabled` and `frameAncestors`.

`StagingAlertsConfig`
:   The opt-in demoted routing for staging namespaces.
    Fields: `enabled` and `namespaces`.

`AlertRoutingConfig`
:   The Alertmanager notification pacing.
    Field: `repeatInterval`.

`ExternalUrlsConfig`
:   The browser-facing URLs used in notification links.
    Fields: `alertmanager` and `prometheus`.

`PriorityClassesConfig`
:   The scheduling priority of the stack's pods by role.
    Fields: `create`, `capture`, and `query`.

`SmtpPasswordSecret`
:   The reference to the Secret that holds the SMTP password.
    Fields: `name` and `key`.

`DeepPartial<T>`
:   A recursive partial type used to type selective overrides.

The sub-interfaces `VersionConfig`, `RetentionConfig`, `StorageConfig`, `ReplicaConfig`, `ResourceConfig`, `S3Config`, `SmtpConfig`, `DomainConfig`, `ResourceRequirements`, and `ResourceAllocation` are documented field by field in {doc}`../configuration-options`, as are the fields of every interface above.

## Stack constructs

`MonitoringChart` creates each of these, and the package exports them individually so an integration chart can compose them directly when needed.

`NamespaceConstruct`
:   Creates the monitoring namespace.
    Wave 0.

`PriorityClassConstruct`
:   Creates the `high-priority` `PriorityClass` with value `10000`.
    Wave 0.
    `MonitoringChart` creates it only when `priorityClasses.create` is true.

`ThanosS3BucketConstruct`
:   Creates the Crossplane `Bucket` for Thanos metrics.
    Wave 1.

`LokiS3BucketConstruct`
:   Creates the Crossplane `Bucket` for Loki logs.
    Wave 1.

`ThanosS3CredentialsConstruct`
:   Creates the `ExternalSecret` that renders the Thanos `objstore.yml`.
    Wave 1.

`LokiS3CredentialsConstruct`
:   Creates the `ExternalSecret` that renders the Loki S3 credentials.
    Wave 1.

`GrafanaPasswordSecret`
:   Creates the `ExternalSecret` for the stable Grafana admin password.
    Wave 1.

`PrometheusStackConstruct`
:   Creates the kube-prometheus-stack `HelmChart` (Prometheus, Grafana, Alertmanager).
    Wave 2.

`LokiConstruct`
:   Creates the Loki `HelmChart` in SimpleScalable mode.
    Wave 2.

`AlloyConstruct`
:   Creates the Alloy `HelmChart` DaemonSet for log collection.
    Wave 3.

`ThanosQueryConstruct`
:   Creates the Thanos Query `Deployment` and `Service`s.
    Wave 3.

`ThanosStoreConstruct`
:   Creates the Thanos Store Gateway `StatefulSet` and `Service`s.
    Wave 3.

`ThanosCompactorConstruct`
:   Creates the Thanos Compactor `StatefulSet` and `Service`.
    Wave 3.

The following four constructs are created only when `config.tempo.enabled` is true.

`TempoS3BucketConstruct`
:   Creates the Crossplane `Bucket` for trace storage.
    Wave 1.

`TempoS3CredentialsConstruct`
:   Creates the `ExternalSecret` that renders the Tempo S3 credentials as `tempo-s3-credentials`.
    Wave 1.

`TempoConstruct`
:   Creates the monolithic Grafana Tempo `HelmChart` backed by S3.
    Wave 3.

`AlloyTracesConstruct`
:   Creates the single-replica Alloy `HelmChart` deployment that acts as the OTLP tail-sampling gateway.
    Wave 3.

When tracing is enabled, `PrometheusStackConstruct` also adds a Tempo datasource to Grafana, wired for traces-to-logs and traces-to-metrics correlation.

The following two constructs are created only when their configuration block is enabled.

`TraefikMonitorConstruct`
:   Creates the `traefik-metrics` `PodMonitor` and, unless `traefik.dashboard` is false, the `traefik-dashboard` `ConfigMap`.
    Props: `monitoringNamespace` and `traefik`.
    `MonitoringChart` creates it when `traefik.enabled` is true.

`LonghornMonitorConstruct`
:   Creates the `longhorn-metrics` `ServiceMonitor` and, unless `longhorn.alerts` is false, the `longhorn-volume-health` `PrometheusRule`.
    Props: `monitoringNamespace` and `longhorn`.
    `MonitoringChart` creates it when `longhorn.enabled` is true.

## Re-exported helper

`KubeConfigMap`
:   Re-exported from the generated Kubernetes imports.
    Integration charts use it to build Grafana dashboard `ConfigMap`s without depending on the generated imports directly.
    See {doc}`../../how-to/add-app-dashboards`.

## See also

- {doc}`../configuration-options` — every configuration field and default.
- {doc}`../sync-waves` — the order in which the constructs are applied.