gNMIc Operator

API Reference

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

Cluster

API Version: operator.gnmic.dev/v1alpha1

ClusterSpec

Field	Type	Required	Default	Description
`replicas`	int32	Yes	-	Number of gNMIc pods
`image`	string	Yes	-	Container image
`api`	APISpec	Yes	-	API configuration
`grpcTunnel`	GRPCTunnelConfig	No	-	gRPC tunnel server configuration
`resources`	ResourceRequirements	No	-	Pod resources
`env`	[]EnvVar	No	-	Environment variables

APISpec

Field	Type	Required	Default	Description
`restPort`	int32	Yes	-	REST API port
`gnmiPort`	int32	No	-	gNMI server port
`tls`	ClusterTLSConfig	No	-	TLS configuration

ClusterTLSConfig

Field	Type	Required	Default	Description
`issuerRef`	string	No	-	cert-manager Issuer name for certificates
`useCSIDriver`	bool	No	false	Use cert-manager CSI driver instead of projected volumes
`bundleRef`	string	No	-	Additional CA bundle for client certificate verification

GRPCTunnelConfig

Field	Type	Required	Default	Description
`port`	int32	Yes	-	Port for the gRPC tunnel server
`tls`	ClusterTLSConfig	No	-	TLS configuration for the tunnel
`service`	ServiceConfig	No	-	Kubernetes service configuration

ServiceConfig

Field	Type	Required	Default	Description
`type`	ServiceType	No	LoadBalancer	Kubernetes service type (ClusterIP, NodePort, LoadBalancer)
`annotations`	map[string]string	No	-	Annotations to add to the service

ClusterStatus

Field	Type	Description
`readyReplicas`	int32	Number of ready replicas
`pipelinesCount`	int32	Number of enabled pipelines referencing this cluster
`targetsCount`	int32	Total unique targets across all pipelines
`subscriptionsCount`	int32	Total unique subscriptions across all pipelines
`inputsCount`	int32	Total unique inputs across all pipelines
`outputsCount`	int32	Total unique outputs across all pipelines
`conditions`	[]Condition	Standard Kubernetes conditions

Cluster Conditions

Type	Description
`Ready`	All replicas are ready and configured
`CertificatesReady`	TLS certificates are issued (when TLS enabled)
`ConfigApplied`	Configuration successfully applied to pods

Pipeline

API Version: operator.gnmic.dev/v1alpha1

Architecture

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

Overview

The gNMIc Operator follows the Kubernetes operator pattern to manage gNMIc telemetry collectors. It watches Custom Resources and reconciles the actual state with the desired state.

Components

This diagram illustrates how the gNMIc Operator orchestrates gNMIc deployments inside a Kubernetes cluster by reconciling Custom Resources into concrete Kubernetes primitives and gNMIc configurations.

At the core, the Cluster Controller watches a set of CRDs. It uses their desired state to create and manage resources like ConfigMaps, Secrets, Services, and a StatefulSet. The StatefulSet, together with the associated Services, materializes as multiple gNMIc pods (e.. gnmic-0, gnmic-1, gnmic-2), each responsible for a subset of targets.

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).

Installation

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

Prerequisites

Kubernetes cluster (v1.25+)
kubectl configured to access your cluster
cert-manager

Installation Methods

Method 1: Quick Install (Recommended)

Download and apply the pre-built manifest from the release:

# Install a specific version
# This includes CRDs, RBAC, webhooks, and the operator deployment
kubectl apply -f https://github.com/gnmic/operator/releases/download/v0.1.0/install.yaml

Method 2: Using Kustomize

For more control over the installation, use kustomize with an overlay:

# Create a kustomization.yaml
cat <<EOF > kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
 - https://github.com/gnmic/operator/config/default?ref=v0.1.0
images:
 - name: controller
 newName: ghcr.io/gnmic/operator
 newTag: "0.1.0"
EOF

# Apply
kubectl apply -k .

Method 3: Using Helm

# Add the Helm repository (OCI)
helm install gnmic-operator oci://ghcr.io/gnmic/operator/charts/gnmic-operator --version 0.1.0

# Or with custom values
helm install gnmic-operator oci://ghcr.io/gnmic/operator/charts/gnmic-operator \
 --version 0.1.0 \
 --namespace gnmic-system \
 --create-namespace \
 --set resources.limits.memory=512Mi

For a complete list of Helm chart configuration options, see the Helm Chart Reference.

Target Distribution

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

The gNMIc Operator uses a simple algorithm to distribute targets across pods. More placement/distribution strategies will be implemented in the future.

This page explains the algorithm and its properties.

Algorithm: Bounded Load Rendezvous Hashing

The operator uses bounded load rendezvous hashing, which combines two techniques:

Rendezvous hashing: For stability (targets stay on same pod)
Bounded load: For even distribution (no pod is overloaded)

How It Works

Step 1: Determine Capacity

If the Cluster CR specifies spec.targetDistribution.perPodCapacity, that value is used as a fixed ceiling. Otherwise capacity is calculated automatically:

Helm Chart

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

This page documents all configuration options available in the gNMIc Operator Helm chart.

Installation

# From OCI registry
helm install gnmic-operator oci://ghcr.io/gnmic/operator/charts/gnmic-operator \
 --namespace gnmic-system \
 --create-namespace

# From source
helm install gnmic-operator ./helm \
 --namespace gnmic-system \
 --create-namespace

Values

Image Configuration

Parameter	Description	Default
`image.repository`	Container image repository	`ghcr.io/gnmic/operator`
`image.tag`	Container image tag	Chart’s `appVersion`
`image.pullPolicy`	Image pull policy	`IfNotPresent`
`imagePullSecrets`	Image pull secrets	`[]`

image:
 repository: ghcr.io/gnmic/operator
 tag: "0.1.0"
 pullPolicy: IfNotPresent

imagePullSecrets:
 - name: my-registry-secret

Deployment Configuration

Parameter	Description	Default
`replicaCount`	Number of operator replicas	`1`
`nameOverride`	Override the chart name	`""`
`fullnameOverride`	Override the full resource name	`""`

replicaCount: 1
nameOverride: ""
fullnameOverride: "my-operator"

Service Account

Parameter	Description	Default
`serviceAccount.create`	Create a service account	`true`
`serviceAccount.annotations`	Annotations for the service account	`{}`
`serviceAccount.name`	Name of the service account	Generated from fullname

serviceAccount:
 create: true
 annotations:
 eks.amazonaws.com/role-arn: arn:aws:iam::123456789:role/my-role
 name: "gnmic-operator"

Pod Configuration

Parameter	Description	Default
`podAnnotations`	Annotations for the operator pod	`{}`
`podSecurityContext`	Security context for the pod	`{runAsNonRoot: true}`
`securityContext`	Security context for the container	See below
`nodeSelector`	Node selector for pod scheduling	`{}`
`tolerations`	Tolerations for pod scheduling	`[]`
`affinity`	Affinity rules for pod scheduling	`{}`

podAnnotations:
 prometheus.io/scrape: "true"

podSecurityContext:
 runAsNonRoot: true

securityContext:
 allowPrivilegeEscalation: false
 capabilities:
 drop:
 - "ALL"

nodeSelector:
 node-role.kubernetes.io/infra: ""

tolerations:
 - key: "dedicated"
 operator: "Equal"
 value: "infra"
 effect: "NoSchedule"

affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app.kubernetes.io/name: gnmic-operator
 topologyKey: kubernetes.io/hostname

Resources

Parameter	Description	Default
`resources.limits.cpu`	CPU limit	`500m`
`resources.limits.memory`	Memory limit	`256Mi`
`resources.requests.cpu`	CPU request	`10m`
`resources.requests.memory`	Memory request	`64Mi`

resources:
 limits:
 cpu: 1000m
 memory: 512Mi
 requests:
 cpu: 100m
 memory: 128Mi

Leader Election

Parameter	Description	Default
`leaderElection.enabled`	Enable leader election	`true`

Leader election ensures only one controller instance is active when running multiple 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:

Quick Start

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

This guide walks you through deploying a complete telemetry collection setup with gNMIc Operator.

Overview

We’ll create:

A TargetProfile with connection settings
A Target pointing to a network device
A Subscription defining what data to collect
An Output to send data to Prometheus
A Pipeline connecting everything together
A Cluster to run the gNMIc collectors

Step 1: Create a TargetProfile

The TargetProfile defines shared settings for connecting to devices:

apiVersion: operator.gnmic.dev/v1alpha1
kind: TargetProfile
metadata:
 name: default-profile
spec:
 # Reference to a Secret containing username/password
 credentialsRef: device-credentials
 # TLS without server certificate verification
 tls: {}
 # Connection timeout
 timeout: 10s

cat << 'EOF' | kubectl apply -f -
apiVersion: operator.gnmic.dev/v1alpha1
kind: TargetProfile
metadata:
 name: default-profile
spec:
 # Reference to a Secret containing username/password
 credentialsRef: device-credentials
 # TLS without server certificate verification
 tls: {}
 # Connection timeout
 timeout: 10s
EOF

Create the credentials secret:

Resource Model

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

Overview

The gNMIc Operator uses a set of Custom Resource Definitions (CRDs) to model telemetry infrastructure. The resources are designed to be composable and reusable.

Resource Hierarchy

Separation of Concerns

Each resource type handles a single concern:

Resource	Concern	Lifecycle
Cluster	Infrastructure	Where and how to run collectors
Pipeline	Wiring	What connects to what
Target	Device	Network device to collect from
TargetSource	Discovery	Dynamic target discovery
TargetProfile	Credentials	How to authenticate
TunnelTargetPolicy	Tunnel Matching	Rules for tunnel-connected devices
Subscription	Data	What paths to subscribe to
Output	Destination	Where to send data
Input	Source	External data sources
Processor	Transformation	How to transform data

Resource Selection

Resources are tied together in two main ways:

Scaling

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

The gNMIc Operator supports horizontal scaling of collector clusters. This page explains how scaling works and best practices for production deployments.

Scaling a Cluster

To scale a cluster, update the replicas field:

# Scale to 5 replicas
kubectl patch cluster my-cluster --type merge -p '{"spec":{"replicas":5}}'

Or edit the Cluster resource:

spec:
 replicas: 5 # Changed from 3

What Happens When You Scale

Scale Up ( 3 → 5 pods)

Kubernetes creates new pods (gnmic-3, gnmic-4).
Operator waits for pods to be ready.
Operator recomputes the distribution plan. Existing target assignments are preserved — only unassigned targets or targets displaced by capacity limits are placed on the new pods.
Configuration is applied to all pods.

Scale Down ( 5 → 3 pods)

Operator recomputes the distribution plan for the reduced replica count. Targets from removed pods flow through rendezvous hashing onto surviving pods, bounded by each pod’s capacity.
Configuration is applied to remaining pods.
Kubernetes terminates pods (gnmic-4, gnmic-3).

Target Redistribution

The operator uses bounded load rendezvous hashing to distribute targets. See Target Distribution for a detailed explanation of the algorithm.

Development Guide

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

Prerequisites

Tool	Version	Purpose
Go	1.25+	Compile the operator
Docker	20+	Build container images
kubectl	1.25+	Interact with the cluster
Kind	0.20+	Local Kubernetes cluster
Containerlab	0.54+	Lab topologies with real network devices
gNMIc CLI	0.38+	Configure lab nodes via gNMI Set

Repository Layout

.
├── api/v1alpha1/ # CRD type definitions and deepcopy methods
├── cmd/main.go # Operator entrypoint
├── config/
│ ├── crd/ # Generated CRD manifests
│ ├── default/ # Kustomize overlay that combines everything
│ ├── manager/ # Controller Deployment and Service
│ ├── rbac/ # ClusterRole, ServiceAccount, Bindings
│ ├── webhook/ # Webhook configuration
│ ├── certmanager/ # cert-manager Issuer and Certificate
│ └── samples/ # Example CRs
├── internal/
│ ├── controller/ # Reconcilers (Cluster, Pipeline, TargetState, …)
│ ├── gnmic/ # gNMIc client helpers (config builder, SSE, …)
│ ├── utils/ # Shared utilities
│ └── webhook/ # Admission webhook handlers
├── helm/ # Helm chart
├── lab/dev/ # Development lab (Containerlab topology + operator resources)
├── Dockerfile
└── Makefile

Initial Setup

Clone the repository and run the one-time setup that creates a Kind cluster, installs cert-manager, builds the operator image, loads it, and deploys it:

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:

TLS Configuration

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

The gNMIc Operator supports multiple TLS configurations for different communication paths:

TLS Type	Config Location	Purpose
API TLS	`cluster.spec.api.tls`	Operator ↔ gNMIc pod REST API
Client TLS	`cluster.spec.clientTLS`	gNMIc pod → Network target gNMI
Tunnel TLS	`cluster.spec.grpcTunnel.tls`	Network device → gNMIc pod tunnel

API TLS (Operator ↔ Pods)

This TLS configuration secures the REST API communication between the operator controller and gNMIc collector pods.

Overview

When TLS is enabled:

Server TLS: Each gNMIc pod presents a certificate to the operator
Client TLS (mTLS): The operator presents a certificate to gNMIc pods
Certificate Verification: Both sides verify the other’s certificate

Prerequisites

cert-manager must be installed in your cluster:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

A CA Issuer must be configured in the gNMIc cluster’s namespace

Quick Start

Assuming the gNMIc cluster will be created in the default namespace. Start by preparing an Issuer to secure the Cluster’s REST API.

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.

Designing Telemetry Pipelines

Tue, 17 Mar 2026 00:00:00 +0000

Managing gNMI telemetry at scale is not just a configuration problem. It’s an ownership problem. Subscriptions change often. Targets come and go. Different teams care about different slices of the network. And when your collector fleet spans multiple pods serving hundreds of devices, the last thing you want is a design where updating a Kafka output triggers a rolling restart, or where scaling from 3 to 5 pods means touching your telemetry wiring.

Introducing gNMIc Operator

Sun, 08 Feb 2026 00:00:00 +0000

Today we’re releasing gNMIc Operator: A Kubernetes operator that brings cloud-native lifecycle management to gNMIc telemetry collectors. It’s been a long road to get here, and I want to share a bit of the backstory.

An idea almost 4 years in the making TODO list

The idea was always clear: gNMIc should not only be a powerful CLI tool, but also a scalable, production-grade telemetry collector that could be orchestrated alongside the rest of your infrastructure. That led to multiple improvements to gNMIc (Clustering, Target Loaders,…), but one of them was a bit more ambitious than the others: A gNMIc Kubernetes operator.