Skip to content

NATS Exporter#
Description NATS Exporter publishes EDA alarms or query results to NATS or JetStream.
Author Nokia
Supported OS N/A
Catalog nokia-eda/catalog
Language Go

Overview#

The NATS Exporter app lets you publish EDA alarms or query results into a NATS or JetStream server. It supports two kinds of resources:

  • Publisher and ClusterPublisher: define how to connect to a NATS or JetStream server.
  • Export and ClusterExport: define what data to publish and which publishers should receive it.

Use namespace-scoped resources when you want to export data only from a single user namespace. Use cluster-scoped resources in the EDA base namespace when you want centralized exports across namespaces.

Installation#

The NATS Exporter app can be installed using EDA Store or by running an AppInstaller workflow with kubectl:

apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: nats-exporter-install
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: nats.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        type: alias
        value: latest

cat << 'EOF' | kubectl apply -f -
apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: nats-exporter-install
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: nats.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        type: alias
        value: latest

EOF

Install Settings#

The app supports install-time sizing through spec.apps[].appSettings in the AppInstaller workflow spec.

Available settings:

  • exporterCPULimit: CPU limit for the NATS exporter pod. Default: "1"
  • exporterMemoryLimit: memory limit for the NATS exporter pod. Default: "1Gi"

These settings control the pod resource limits for the exporter deployment in the EDA base namespace.

The shipped deployment currently keeps resource requests fixed at:

  • CPU request: 500m
  • memory request: 500Mi

Example Install With Settings#

apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: nats-exporter-install-sized
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: nats.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        value: v4.0.0
      appSettings:
        exporterCPULimit: "2"
        exporterMemoryLimit: 2Gi

cat << 'EOF' | kubectl apply -f -
apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: nats-exporter-install-sized
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: nats.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        value: v4.0.0
      appSettings:
        exporterCPULimit: "2"
        exporterMemoryLimit: 2Gi

EOF

Getting Started#

After the app is installed, create:

  • a Publisher or ClusterPublisher to define the destination NATS connection
  • an Export or ClusterExport to define the data to publish

Use the nats.eda.nokia.com/v1 API for new resources. The older v1alpha1 API is still served for compatibility, but it is now deprecated and is marked for removal in a future release.

Namespace rules:

  • Publisher and Export are namespace-scoped. Create them in a user namespace such as eda.
  • ClusterPublisher and ClusterExport are intended for the EDA base namespace. The controller only activates cluster-scoped resources from its own namespace.

Publisher Resources#

A publisher defines how the app connects to the NATS or JetStream server.

Important fields:

  • spec.address: comma-separated NATS server addresses
  • spec.type: NATS or Jetstream
  • spec.clientName: NATS client name
  • spec.credentialsSecretName: optional Secret containing username and password
  • spec.maxPendingAcks and spec.maxWait: JetStream-specific publish tuning
  • spec.tls: optional TLS settings

TLS options:

  • tls.fromFiles: read caFile, certFile, and keyFile from mounted files
  • tls.fromSecret: read tls.crt, tls.key, and optional ca.crt from a Secret in the same namespace as the publisher
  • tls.trustBundle: read trust-bundle.pem from a ConfigMap in the same namespace as the publisher

The publisher status reports whether the connection is currently established through status.connected, status.error, and status.lastChecked.

Example Publisher#

apiVersion: nats.eda.nokia.com/v1
kind: Publisher
metadata:
  name: nats-publisher
  namespace: eda
spec:
  address: nats.example.svc.cluster.local:4222
  type: NATS
  clientName: eda-nats-client
  credentialsSecretName: nats-credentials
  tls:
    fromSecret: nats-client-tls
    trustBundle: nats-ca-bundle

cat << 'EOF' | kubectl apply -f -
apiVersion: nats.eda.nokia.com/v1
kind: Publisher
metadata:
  name: nats-publisher
  namespace: eda
spec:
  address: nats.example.svc.cluster.local:4222
  type: NATS
  clientName: eda-nats-client
  credentialsSecretName: nats-credentials
  tls:
    fromSecret: nats-client-tls
    trustBundle: nats-ca-bundle

EOF

Export Resources#

An export defines what data is exported and where it is sent.

Supported sources:

  • spec.exports.alarms: stream alarms from EDA
  • spec.exports.query: stream query results from the state DB

Each destination references a publisher and defines how to derive the NATS subject:

  • subject: use a fixed subject
  • subjectFromJsPath: true: derive the subject from the JsPath of each update
  • subjectPrefix: prepend a prefix when subjectFromJsPath is enabled

When a static subject is configured, the exporter also sends a sync message after the initial state sync for on-change streams.

Alarm Source#

Use spec.exports.alarms to stream alarms.

Important fields:

  • include: list of alarm types to include, or ["*"] for all alarms
  • exclude: optional list of alarm types to suppress

For namespace-scoped Export, alarms come only from the export namespace.

Query Source#

Use spec.exports.query[] to publish arbitrary state DB data.

Important fields:

  • path: JsPath to query. For Export, omit the .namespace prefix because the controller adds the export namespace automatically.
  • fields: optional list of fields to include. If omitted, all fields are exported.
  • where: optional EQL filter
  • mode: on-change, periodic, or both
  • period: required for periodic and both; minimum 10 seconds
  • includeTimestamps: include the export timestamp in the published message

Published messages contain:

  • path: the resolved JsPath without keys
  • entries[].keys: path keys flattened into a map
  • entries[].fields: exported object fields
  • optional timestamp

Example Export#

apiVersion: nats.eda.nokia.com/v1
kind: Export
metadata:
  name: interface-events
  namespace: eda
spec:
  description: Publish interface state changes to NATS
  enabled: true
  exports:
    query:
      - path: .node.srl.interface
        fields:
          - oper-state
          - admin-state
        where: admin-state = enable
        mode: on-change
        includeTimestamps: true
  destinations:
    - name: nats-publisher
      subjectFromJsPath: true
      subjectPrefix: eda

cat << 'EOF' | kubectl apply -f -
apiVersion: nats.eda.nokia.com/v1
kind: Export
metadata:
  name: interface-events
  namespace: eda
spec:
  description: Publish interface state changes to NATS
  enabled: true
  exports:
    query:
      - path: .node.srl.interface
        fields:
          - oper-state
          - admin-state
        where: admin-state = enable
        mode: on-change
        includeTimestamps: true
  destinations:
    - name: nats-publisher
      subjectFromJsPath: true
      subjectPrefix: eda

EOF

Cluster-Scoped Resources#

Use ClusterPublisher and ClusterExport when you want centralized exports from the EDA base namespace.

Cluster-specific behavior:

  • ClusterPublisher must be created in the EDA base namespace
  • ClusterExport can stream data across namespaces
  • spec.exports.alarms.namespaces limits which namespaces contribute alarms
  • spec.exports.query[].path should include the full .namespace. prefix when you want cross-namespace query exports

Example ClusterPublisher#

apiVersion: nats.eda.nokia.com/v1
kind: ClusterPublisher
metadata:
  name: jetstream-central
  namespace: eda-system
spec:
  address: jetstream.example.svc.cluster.local:4222
  type: Jetstream
  clientName: eda-jetstream-client
  credentialsSecretName: jetstream-credentials
  maxPendingAcks: 4000
  maxWait: 5

cat << 'EOF' | kubectl apply -f -
apiVersion: nats.eda.nokia.com/v1
kind: ClusterPublisher
metadata:
  name: jetstream-central
  namespace: eda-system
spec:
  address: jetstream.example.svc.cluster.local:4222
  type: Jetstream
  clientName: eda-jetstream-client
  credentialsSecretName: jetstream-credentials
  maxPendingAcks: 4000
  maxWait: 5

EOF

Example ClusterExport#

apiVersion: nats.eda.nokia.com/v1
kind: ClusterExport
metadata:
  name: alarm-export
  namespace: eda-system
spec:
  description: Publish alarms from selected namespaces
  enabled: true
  exports:
    alarms:
      namespaces:
        - eda
        - tenant-a
      include:
        - "*"
      exclude:
        - NATSServerConnectionFailed
  destinations:
    - name: jetstream-central
      subject: eda.alarms

cat << 'EOF' | kubectl apply -f -
apiVersion: nats.eda.nokia.com/v1
kind: ClusterExport
metadata:
  name: alarm-export
  namespace: eda-system
spec:
  description: Publish alarms from selected namespaces
  enabled: true
  exports:
    alarms:
      namespaces:
        - eda
        - tenant-a
      include:
        - "*"
      exclude:
        - NATSServerConnectionFailed
  destinations:
    - name: jetstream-central
      subject: eda.alarms

EOF

Connectivity Alarm#

The app raises an EDA alarm when a configured NATS destination cannot be reached.

Alarm details:

  • Alarm type: NATSServerConnectionFailed
  • Severity: major
  • Resource kind: Publisher or ClusterPublisher
  • Resource: publisher name

Typical causes:

  • wrong NATS server address or port
  • invalid username or password secret
  • TLS secret, trust bundle, or certificate paths are incorrect
  • the NATS or JetStream service is down or unreachable

The alarm is cleared automatically when the publisher reconnects successfully.

Configuration Notes#

When creating resources, follow these rules:

  • publisher address is required
  • JetStream maxPendingAcks and maxWait must be at least 1
  • if TLS client certificate or key is set, the matching key or certificate must also be set
  • every export must define at least one source and at least one destination
  • every destination must set either subject or subjectFromJsPath