Platform Connectors Configuration

Overview

The Platform Connectors module acts as the central communication hub for NVSentinel. It receives health events from monitors via gRPC, processes them through a transformer pipeline, stores them in the database, and propagates them to Kubernetes. This document covers all Helm configuration options for system administrators.

Configuration Reference

Resources

Defines CPU and memory resource requests and limits for the platform-connectors pod.

1
platformConnector:
2
  resources:
3
    limits:
4
      cpu: 200m
5
      memory: 512Mi
6
    requests:
7
      cpu: 200m
8
      memory: 512Mi

Logging

Sets the verbosity level for platform-connectors logs.

1
platformConnector:
2
  logLevel: info  # Options: debug, info, warn, error

Scheduling

Controls where platform-connectors pods can be scheduled.

1
platformConnector:
2
  tolerations: []
3
  affinity: \{\}

Event Processing Pipeline

Configures the event processing pipeline that processes health events before storage and Kubernetes propagation. Transformers mutate events in order before connector fan-out.

1
platformConnector:
2
  pipeline:
3
    - name: MetadataAugmentor
4
      enabled: false
5
      config: /etc/config/metadata.toml
6
    - name: OverrideTransformer
7
      enabled: false
8
      config: /etc/config/overrides.toml
9
  
10
  dedup:
11
    enabled: true
12
    suppressionWindow: "3m"
13
    cleanupInterval: "60s"
14
    includeChecks:
15
      - SysLogsXIDError
16
      - SysLogsSXIDError
17
18
  transformers:
19
    MetadataAugmentor:
20
      cacheSize: 50
21
      cacheTTLSeconds: 3600
22
      allowedLabels:
23
        - "topology.kubernetes.io/zone"
24
    
25
    OverrideTransformer:
26
      rules: []

Parameters

pipeline

Array of transformer stages to execute in order:

• name: Transformer identifier (MetadataAugmentor, OverrideTransformer)
• enabled: Enable/disable the transformer
• config: Path to transformer-specific configuration file

The chart appends the Deduplicator transformer stage from platformConnector.dedup; operators normally configure deduplication through the dedup block rather than adding it manually to pipeline.

dedup

Deduplication transformer configuration. See Deduplication Transformer Configuration.

transformers

Transformer-specific configurations, nested by transformer name.

Note: Transformers execute sequentially. MetadataAugmentor should run first to provide node metadata for subsequent transformers.

Metadata Augmentor Configuration

Enriches health events with node labels and metadata from Kubernetes.

1
platformConnector:
2
  transformers:
3
    MetadataAugmentor:
4
      cacheSize: 50
5
      cacheTTLSeconds: 3600
6
      allowedLabels:
7
        - "topology.kubernetes.io/zone"
8
        - "topology.kubernetes.io/region"
9
        - "node.kubernetes.io/instance-type"

Parameters

cacheSize

Number of node metadata entries to cache in memory.

cacheTTLSeconds

Time-to-live for cached node metadata entries in seconds.

allowedLabels

List of node label keys to include in health event enrichment. Only labels in this list are read from nodes and added to events.

Note: The complete default list is defined in distros/kubernetes/nvsentinel/values.yaml

Example

1
platformConnector:
2
  transformers:
3
    MetadataAugmentor:
4
      cacheSize: 100
5
      cacheTTLSeconds: 3600
6
      allowedLabels:
7
        - "topology.kubernetes.io/zone"
8
        - "topology.kubernetes.io/region"
9
        - "custom.company.com/rack-id"

Override Transformer Configuration

Applies CEL-based rules to modify health event properties (isFatal, isHealthy, recommendedAction).

1
platformConnector:
2
  transformers:
3
    OverrideTransformer:
4
      rules:
5
        - name: "suppress-xid-109"
6
          when: 'event.agent == "syslog-health-monitor" && "109" in event.errorCode'
7
          override:
8
            isFatal: false
9
            recommendedAction: "NONE"

Parameters

rules

Array of override rules evaluated in order (first match wins):

• name: Human-readable rule name for logging
• when: CEL expression that evaluates to boolean
• override: Properties to modify (isFatal, isHealthy, recommendedAction)

CEL Expression Context

CEL expressions have access to the event object with the following fields:

Entity fields: Each entity in entitiesImpacted has:

• entityType - Type of entity (e.g., “GPU”, “NIC”)
• entityValue - Entity identifier (e.g., GPU UUID, PCI address)

Examples

Suppress known errors:

1
transformers:
2
  OverrideTransformer:
3
    rules:
4
      - name: "suppress-xid-109"
5
        when: 'event.agent == "syslog-health-monitor" && "109" in event.errorCode'
6
        override:
7
          isFatal: false
8
          recommendedAction: "NONE"

Deduplication Transformer Configuration

Suppresses repeated health events within a burst window before they are written to the datastore or propagated to Kubernetes. The dedup key is derived from:

(nodeName, checkName, canonical entitiesImpacted, canonical errorCode, processingStrategy, isHealthy)

message, pid, timestamps, and other fields outside the key do not distinguish events. If a producer needs those fields to create distinct faults, it should include them in entitiesImpacted or errorCode. processingStrategy is included so a STORE_ONLY observation cannot suppress a later EXECUTE_REMEDIATION event for the same fault identity.

1
platformConnector:
2
  dedup:
3
    enabled: true
4
    suppressionWindow: "3m"
5
    cleanupInterval: "60s"
6
    includeChecks:
7
      - SysLogsXIDError
8
      - SysLogsSXIDError

Parameters

enabled

Enables the deduplication transformer. When disabled, every event that reaches platform-connectors keeps its original processing strategy.

suppressionWindow

Go duration string that controls how long repeated events with the same key are downgraded to STORE_AND_ANALYSE. After the window expires, the next matching event remains EXECUTE_REMEDIATION.

cleanupInterval

Go duration string that controls how often the in-memory tracker removes expired keys that have not recurred.

includeChecks

List of checkName values eligible for platform-connector deduplication. Keep this focused on high-volume repeated signal streams, such as SysLogsXIDError and SysLogsSXIDError; every other check passes through unchanged.

Healthy Event Behavior

Healthy events are not downgraded by deduplication. Before they continue downstream, they clear any matching unhealthy entries from the in-memory tracker. This keeps recovery and baseline events reliable even when a previous healthy event did not update every downstream consumer, while repeated unhealthy fault observations are still deduplicated.

Operational Notes

• Dedup state is in-memory only and is cleared on platform-connectors pod restart.
• The dedup counter is exposed as nvsentinel_platform_connector_dedup_store_and_analyse_total\{check,node,err_code\}.
• entitiesImpacted and errorCode are canonicalized as sets for keying; ordering differences do not create distinct events.

Kubernetes Connector

Configures the Kubernetes API client for creating node conditions and events.

1
platformConnector:
2
  k8sConnector:
3
    enabled: true
4
    maxNodeConditionMessageLength: 1024
5
    qps: 5.0
6
    burst: 10

Parameters

enabled

Enables Kubernetes connector for creating node conditions and events.

maxNodeConditionMessageLength

Maximum length of node condition messages in characters.

qps

Queries per second allowed to the Kubernetes API server.

burst

Maximum burst of queries allowed to the Kubernetes API server.

Example

1
platformConnector:
2
  k8sConnector:
3
    enabled: true
4
    maxNodeConditionMessageLength: 1024
5
    qps: 10.0
6
    burst: 20

Kubernetes Authentication

Platform Connectors uses in-cluster Kubernetes authentication by default. In that mode it authenticates with the pod ServiceAccount and no extra flags are required.

For host-managed deployments, pass a kubeconfig file explicitly:

$
platform-connectors \
>
  --socket=/var/run/nvsentinel.sock \
>
  --config=/etc/config/config.json \
>
  --kubeconfig=/var/lib/kubelet/kubeconfig

When --kubeconfig is set:

• The Kubernetes connector uses that kubeconfig instead of InClusterConfig()
• MetadataAugmentor uses the same kubeconfig for node metadata lookups

When --kubeconfig is unset, existing in-cluster behavior is unchanged.

The bundled Helm chart continues to rely on in-cluster authentication and does not need to set this flag.