User Guide on gNMIc Operator

Cluster

Mon, 01 Jan 0001 00:00:00 +0000

The Cluster resource defines a gNMIc collector deployment. It creates a StatefulSet, headless Service, Certificates, and manages the initial configuration for the gNMIc pods.

Basic Configuration

This CR creates a gNMIc cluster of 3 pods based on the referenced container image.

apiVersion: operator.gnmic.dev/v1alpha1
kind: Cluster
metadata:
 name: telemetry-cluster
spec:
 replicas: 3
 image: ghcr.io/openconfig/gnmic:latest

Spec Fields

Field	Type	Required	Default	Description
`replicas`	int32	Yes	1	Number of gNMIc pods to run
`image`	string	Yes		Container image for gNMIc
API
`api`	APIConfig	No		REST API and gNMI server configurations
`api.restPort`	int32	No	7890	Port for REST API
`api.gnmiPort`	int32	No		Port for gNMI server (optional)
`api.tls`	ClusterTLSConfig	No		TLS for REST API (operator ↔ pods)
`api.tls.issuerRef`	string	No		CertManager Issuer reference, used to sign the REST API certificates
`api.tls.bundleRef`	string	No		ConfigMap reference, used to add API server trust bundles to the POD (key=`ca.crt`)
`api.tls.useCSIDriver`	bool	No		If true the API certificates are generated and mounted using CertManager CSI Driver
gNMI client TLS
`clientTLS`	ClusterTLSConfig	No		TLS for gNMI client (pods → targets)
`clientTLS.issuerRef`	string	No		CertManager Issuer reference, used to sign the gNMI client certificates
`clientTLS.bundleRef`	string	No		ConfigMap reference, used to add gNMI client trust bundles to the POD (key=`ca.crt`)
`clientTLS.useCSIDriver`	bool	No		If true the gNMI client certificates are generated and mounted using CertManager CSI Driver
Target Distribution
`targetDistribution`	TargetDistributionConfig	No		Target distribution configuration
`targetDistribution.perPodCapacity`	int	No	ceil(targets/pods)	Maximum number of targets assigned to a single pod

Target Distribution

By default, the operator distributes targets evenly across pods using bounded load rendezvous hashing with an auto-calculated capacity of ceil(totalTargets / replicas).

Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

The Pipeline resource connects targets, tunnelTargetPolicies, subscriptions, outputs, and inputs together. It defines the flow of telemetry data through the cluster.

Basic Configuration

The simplest way to configure a Pipeline is using direct references to tagets,subscriptions and outputs.

apiVersion: operator.gnmic.dev/v1alpha1
kind: Pipeline
metadata:
 name: core-telemetry
spec:
 clusterRef: telemetry-cluster
 enabled: true
 targetRefs:
 - router1
 - router2
 subscriptionRefs:
 - interface-counters
 outputs:
 outputRefs:
 - prometheus-output

It can also be configured with labelSelectors:

apiVersion: operator.gnmic.dev/v1alpha1
kind: Pipeline
metadata:
 name: core-telemetry
spec:
 clusterRef: telemetry-cluster
 enabled: true
 targetSelectors:
 - matchLabels:
 role: core
 env: prod
 - matchLabels:
 role: edge
 env: prod
 subscriptionSelectors:
 - matchLabels:
 type: interface-stats
 outputs:
 outputSelectors:
 - matchLabels:
 type: prometheus
 env: prod

The above example build a pipeline that includes:

Target & TargetProfile

Mon, 01 Jan 0001 00:00:00 +0000

Target

The Target resource represents a network device to collect telemetry from. The target definition is kept as simple as possible to remain automation and scale friendly.

Basic Configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: Target
metadata:
 name: router1
 labels:
 vendor: vendorA
 role: core
 site: dc1
spec:
 address: 10.0.0.1:57400
 profile: default-profile

Spec Fields

Field	Type	Required	Description
`address`	string	Yes	Device address (host:port)
`profile`	string	Yes	Reference to TargetProfile

Using Labels

Labels are essential for pipeline selection. Any label can be used but some obvious ones include:

TargetSource

Mon, 01 Jan 0001 00:00:00 +0000

The TargetSource resource enables dynamic discovery of network devices from external sources. The operator automatically creates, updates, and deletes Target resources based on discovered devices.

Discovery Sources

TargetSource supports multiple discovery backends:

Source	Description
`http`	Fetch targets from an HTTP endpoint
`consul`	Discover targets from Consul service registry
`configMap`	Read targets from a Kubernetes ConfigMap
`podSelector`	Create targets from Kubernetes Pods
`serviceSelector`	Create targets from Kubernetes Services

HTTP Discovery

Discover targets from an HTTP endpoint that returns a JSON list of targets:

Subscription

Mon, 01 Jan 0001 00:00:00 +0000

The Subscription resource defines what telemetry data to collect from targets.

Basic Configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: Subscription
metadata:
 name: interface-counters
 labels:
 type: interfaces
spec:
 paths:
 - /interfaces/interface/state/counters
 mode: STREAM/SAMPLE
 sampleInterval: 10s

Spec Fields

Field	Type	Required	Description
`paths`	[]string	Yes	YANG paths to subscribe to
`mode`	string	No	Subscription mode: `ONCE`, `STREAM/SAMPLE`, `STREAM/ON_CHANGE`, `STREAM/TARGET_DEFINED`, `POLL`
`sampleInterval`	duration	No	Sampling interval for `STREAM/SAMPLE` mode
`encoding`	string	No	Data encoding: `json`, `json_ietf`, `proto`, `ascii`
`prefix`	string	No	Common path prefix

Subscription Modes

Stream Mode (Default)

Continuous streaming of telemetry data:

Output

Mon, 01 Jan 0001 00:00:00 +0000

The Output resource defines where telemetry data is sent. gNMIc supports many output types including Prometheus, Kafka, InfluxDB, and more.

Basic Configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: Output
metadata:
 name: prometheus-output
spec:
 type: prometheus  # The output type
 config: {} # Output specific config fields

Spec Fields

Field	Type	Required	Description
`type`	string	Yes	Output type (prometheus, kafka, influxdb, etc.)
`config`	object	No	Type-specific configuration (schemaless)
`service`	OutputServiceSpec	No	Kubernetes Service configuration. This is the service exposing the output endpoint (Prometheus only).
`serviceRef`	ServiceReference	No	Reference to a Kubernetes Service for address resolution
`serviceSelector`	ServiceSelector	No	Label selector to discover Kubernetes Services

Service

Defines the Service type, labels and annotations that will be created when the output has type=prometheus.

Input

Mon, 01 Jan 0001 00:00:00 +0000

The Input resource defines external data sources that feed telemetry data into the gNMIc cluster. This enables processing data from sources like Kafka, NATS, or other gNMIc instances.

Basic Configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: Input
metadata:
 name: kafka-input
spec:
 type: kafka
 config:
 brokers:
 - kafka:9092
 topics:
 - telemetry-raw
 group: gnmic-processors

Spec Fields

Field	Type	Required	Description
`type`	string	Yes	Input type (kafka, nats, etc.)
`config`	object	Yes	Type-specific configuration (schemaless)

Kafka Input

Consume telemetry from Kafka topics:

Processor

Mon, 01 Jan 0001 00:00:00 +0000

The Processor resource defines event transformations applied to telemetry data. Processors can filter, enrich, transform, or drop events as they flow through the gNMIc cluster.

Basic Configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: Processor
metadata:
 name: add-cluster-tag
spec:
 type: event-add-tag
 config:
 add:
 cluster: production
 region: us-east-1

Spec Fields

Field	Type	Required	Description
`type`	string	Yes	Processor type (event-add-tag, event-drop, event-strings, etc.)
`config`	object	Yes	Type-specific configuration (schemaless)

Processor Types

Event Add Tag

Add static tags to events:

apiVersion: operator.gnmic.dev/v1alpha1
kind: Processor
metadata:
 name: add-metadata
spec:
 type: event-add-tag
 config:
 add:
 environment: production
 datacenter: dc1
 overwrite: true

Event Drop

Drop events matching a condition:

TunnelTargetPolicy

Mon, 01 Jan 0001 00:00:00 +0000

The TunnelTargetPolicy resource defines rules for matching devices that connect via gRPC tunnel and associates them with configuration from a TargetProfile.

Overview

In gRPC tunnel mode, network devices initiate connections to the gNMIc collector (reverse of traditional polling). When a device connects, it identifies itself with a type and ID. The TunnelTargetPolicy defines matching rules to:

Identify which tunnel-connected devices to accept
Apply configuration (credentials, TLS settings) from a TargetProfile
Enable subscription collection on matching devices

Basic Configuration

apiVersion: operator.gnmic.dev/v1alpha1
kind: TunnelTargetPolicy
metadata:
 name: core-routers
spec:
 match:
 type: "router"
 id: "^core-.*"
 profile: router-profile

Spec Fields

Field	Type	Required	Description
`match`	TunnelTargetMatch	No	Match criteria (if not set, matches all targets)
`match.type`	string	No	Regex pattern to match target type
`match.id`	string	No	Regex pattern to match target ID
`profile`	string	Yes	Reference to a TargetProfile

Match Patterns

Both type and id fields support Go regular expressions.