feat: Introduce iperf3 Kubernetes network monitor

Add core components for continuous cluster network validation: - Python exporter (`exporter/`) to run iperf3 tests and expose Prometheus metrics. - Helm chart (`charts/iperf3-monitor/`) for deploying the exporter as a Deployment and iperf3 server as a DaemonSet. - CI/CD workflow (`.github/workflows/release.yml`) for building/publishing images and charts on tag creation. - Initial documentation, license, and `.gitignore`.
2026-03-08 05:22:35 +00:00 · 2025-06-18 20:22:36 +05:30
parent 8db1a22bca
commit f3968a609e
16 changed files with 4061 additions and 0 deletions
--- a/charts/iperf3-monitor/Chart.yaml
+++ b/charts/iperf3-monitor/Chart.yaml
@@ -0,0 +1,30 @@
+apiVersion: v2
+name: iperf3-monitor
+version: 0.1.0
+appVersion: "0.1.0"
+description: A Helm chart for deploying a Kubernetes-native iperf3 network performance monitoring service with Prometheus and Grafana.
+type: application
+keywords:
+  - iperf3
+  - network
+  - performance
+  - monitoring
+  - kubernetes
+  - prometheus
+  - grafana
+home: https://github.com/malarinv/iperf3-monitor # Replace with your repo URL
+sources:
+  - https://github.com/malarinv/iperf3-monitor # Replace with your repo URL
+maintainers:
+  - name: Malar Invention # Replace with your name
+    email: malarkannan.invention@gmail.com # Replace with your email
+icon: https://raw.githubusercontent.com/malarinv/iperf3-monitor/main/icon.png # Optional icon URL
+annotations:
+  artifacthub.io/changes: |
+    - Add initial Helm chart structure.
+  artifacthub.io/category: networking
+dependencies:
+  - name: prometheus-community/kube-prometheus-stack # Example dependency if you package the whole stack
+    version: ">=30.0.0" # Specify a compatible version range
+    repository: https://prometheus-community.github.io/helm-charts
+    condition: serviceMonitor.enabled # Only include if ServiceMonitor is enabled (assuming Prometheus Operator)
--- a/charts/iperf3-monitor/templates/_helpers.tpl
+++ b/charts/iperf3-monitor/templates/_helpers.tpl
@@ -0,0 +1,55 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "iperf3-monitor.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "iperf3-monitor.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{/*
+Create chart's labels
+*/}}
+{{- define "iperf3-monitor.labels" -}}
+helm.sh/chart: {{ include "iperf3-monitor.name" . }}-{{ .Chart.Version | replace "+" "_" }}
+{{ include "iperf3-monitor.selectorLabels" . }}
+{{- if .Chart.AppVersion -}}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end -}}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{/*
+Selector labels
+*/}}
+{{- define "iperf3-monitor.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "iperf3-monitor.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "iperf3-monitor.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+    {{- default (include "iperf3-monitor.fullname" .) .Values.serviceAccount.name -}}
+{{- else -}}
+    {{- default "default" .Values.serviceAccount.name -}}
+{{- end -}}
+{{- end -}}
--- a/charts/iperf3-monitor/templates/exporter-deployment.yaml
+++ b/charts/iperf3-monitor/templates/exporter-deployment.yaml
@@ -0,0 +1,49 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "iperf3-monitor.fullname" . }}-exporter
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+    app.kubernetes.io/component: exporter
+spec:
+  replicas: {{ .Values.exporter.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "iperf3-monitor.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: exporter
+  template:
+    metadata:
+      labels:
+        {{- include "iperf3-monitor.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: exporter
+    spec:
+      serviceAccountName: {{ include "iperf3-monitor.serviceAccountName" . }}
+      containers:
+      - name: iperf3-exporter
+        image: "{{ .Values.exporter.image.repository }}:{{ .Values.exporter.image.tag | default .Chart.AppVersion }}"
+        imagePullPolicy: {{ .Values.exporter.image.pullPolicy }}
+        ports:
+        - containerPort: {{ .Values.service.targetPort }}
+          name: metrics
+        env:
+        - name: SOURCE_NODE_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: spec.nodeName
+        - name: IPERF_TEST_INTERVAL
+          value: "{{ .Values.exporter.testInterval }}"
+        - name: IPERF_TEST_PROTOCOL
+          value: "{{ .Values.exporter.testProtocol }}"
+        - name: IPERF_SERVER_PORT
+          value: "5201" # Hardcoded as per server DaemonSet
+        - name: IPERF_SERVER_NAMESPACE
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.namespace
+        - name: IPERF_SERVER_LABEL_SELECTOR
+          value: "app.kubernetes.io/name={{ include \"iperf3-monitor.name\" . }},app.kubernetes.io/instance={{ .Release.Name }},app.kubernetes.io/component=server"
+        {{- with .Values.exporter.resources }}
+        resources:
+          {{- toYaml . | nindent 10 }}
+        {{- end }}
+```
--- a/charts/iperf3-monitor/templates/rbac.yaml
+++ b/charts/iperf3-monitor/templates/rbac.yaml
@@ -0,0 +1,34 @@
+{{- if .Values.rbac.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "iperf3-monitor.serviceAccountName" . }}
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "iperf3-monitor.fullname" . }}-role
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+rules:
+  - apiGroups: [""]
+    resources: ["pods"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: {{ include "iperf3-monitor.fullname" . }}-rb
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+subjects:
+  - kind: ServiceAccount
+    name: {{ include "iperf3-monitor.serviceAccountName" . }}
+    namespace: {{ .Release.Namespace }}
+roleRef:
+  kind: ClusterRole
+  name: {{ include "iperf3-monitor.fullname" . }}-role
+  apiGroup: rbac.authorization.k8s.io
+{{- end -}}
--- a/charts/iperf3-monitor/templates/server-daemonset.yaml
+++ b/charts/iperf3-monitor/templates/server-daemonset.yaml
@@ -0,0 +1,45 @@
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: {{ include "iperf3-monitor.fullname" . }}-server
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  selector:
+    matchLabels:
+      {{- include "iperf3-monitor.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: server
+  template:
+    metadata:
+      labels:
+        {{- include "iperf3-monitor.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: server
+    spec:
+      # Run on the host network to measure raw node-to-node performance
+      hostNetwork: true
+      {{- with .Values.server.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.server.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: iperf3-server
+          image: "{{ .Values.server.image.repository }}:{{ .Values.server.image.tag }}"
+          imagePullPolicy: {{ .Values.server.image.pullPolicy }}
+          args: ["-s"] # Start in server mode
+          ports:
+            - containerPort: 5201
+              name: iperf3-tcp
+              protocol: TCP
+            - containerPort: 5201
+              name: iperf3-udp
+              protocol: UDP
+          {{- with .Values.server.resources }}
+          resources:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+```
--- a/charts/iperf3-monitor/templates/service.yaml
+++ b/charts/iperf3-monitor/templates/service.yaml
@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "iperf3-monitor.fullname" . }}-exporter-svc
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+    app.kubernetes.io/component: exporter
+spec:
+  type: {{ .Values.service.type }}
+  selector:
+    {{- include "iperf3-monitor.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: exporter
+  ports:
+    - name: metrics
+      port: {{ .Values.service.port }}
+      targetPort: {{ .Values.service.targetPort }}
+      protocol: TCP
--- a/charts/iperf3-monitor/templates/servicemonitor.yaml
+++ b/charts/iperf3-monitor/templates/servicemonitor.yaml
@@ -0,0 +1,20 @@
+{{- if .Values.serviceMonitor.enabled -}}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "iperf3-monitor.fullname" . }}-sm
+  labels:
+    {{- include "iperf3-monitor.labels" . | nindent 4 }}
+    release: prometheus-operator # Standard label for Prometheus Operator discovery
+    app.kubernetes.io/component: exporter
+spec:
+  selector:
+    matchLabels:
+      {{- include "iperf3-monitor.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: exporter
+  endpoints:
+    - port: metrics
+      interval: {{ .Values.serviceMonitor.interval }}
+      scrapeTimeout: {{ .Values.serviceMonitor.scrapeTimeout }}
+      path: /metrics
+{{- end -}}
--- a/charts/iperf3-monitor/values.yaml
+++ b/charts/iperf3-monitor/values.yaml
@@ -0,0 +1,120 @@
+# Default values for iperf3-monitor.
+# This is a YAML-formatted file.
+# Declare variables to be passed into your templates.
+
+# -- Override the name of the chart.
+nameOverride: ""
+
+# -- Override the fully qualified app name.
+fullnameOverride: ""
+
+exporter:
+  # -- Configuration for the exporter container image.
+  image:
+    # -- The container image repository for the exporter.
+    repository: ghcr.io/malarinv/iperf3-prometheus-exporter # Replace with your repo URL
+    # -- The container image tag for the exporter. If not set, the chart's appVersion is used.
+    tag: ""
+    # -- The image pull policy for the exporter container.
+    pullPolicy: IfNotPresent
+
+  # -- Number of exporter pod replicas. Typically 1 is sufficient.
+  replicaCount: 1
+
+  # -- Interval in seconds between complete test cycles (i.e., testing all server nodes).
+  testInterval: 300
+
+  # -- Timeout in seconds for a single iperf3 test run.
+  testTimeout: 10
+
+  # -- Protocol to use for testing (tcp or udp).
+  testProtocol: tcp
+
+  # -- CPU and memory resource requests and limits for the exporter pod.
+  # @default -- A small default is provided if commented out.
+  resources:
+    {}
+    # requests:
+    #   cpu: "100m"
+    #   memory: "128Mi"
+    # limits:
+    #   cpu: "500m"
+    #   memory: "256Mi"
+
+server:
+  # -- Configuration for the iperf3 server container image (DaemonSet).
+  image:
+    # -- The container image repository for the iperf3 server.
+    repository: networkstatic/iperf3
+    # -- The container image tag for the iperf3 server.
+    tag: latest
+
+  # -- CPU and memory resource requests and limits for the iperf3 server pods (DaemonSet).
+  # These should be very low as the server is mostly idle.
+  # @default -- A small default is provided if commented out.
+  resources:
+    {}
+    # requests:
+    #   cpu: "50m"
+    #   memory: "64Mi"
+    # limits:
+    #   cpu: "100m"
+    #   memory: "128Mi"
+
+  # -- Node selector for scheduling iperf3 server pods.
+  # Use this to restrict the DaemonSet to a subset of nodes.
+  # @default -- {} (schedule on all nodes)
+  nodeSelector: {}
+
+  # -- Tolerations for scheduling iperf3 server pods on tainted nodes (e.g., control-plane nodes).
+  # This is often necessary to include master nodes in the test mesh.
+  # @default -- Tolerates control-plane and master taints.
+  tolerations:
+    - key: "node-role.kubernetes.io/control-plane"
+      operator: "Exists"
+      effect: "NoSchedule"
+    - key: "node-role.kubernetes.io/master"
+      operator: "Exists"
+      effect: "NoSchedule"
+
+rbac:
+  # -- If true, create ServiceAccount, ClusterRole, and ClusterRoleBinding for the exporter.
+  # Set to false if you manage RBAC externally.
+  create: true
+
+serviceAccount:
+  # -- The name of the ServiceAccount to use for the exporter pod.
+  # Only used if rbac.create is false. If not set, it defaults to the chart's fullname.
+  name: ""
+
+serviceMonitor:
+  # -- If true, create a ServiceMonitor resource for integration with Prometheus Operator.
+  # Requires a running Prometheus Operator in the cluster.
+  enabled: true
+
+  # -- Scrape interval for the ServiceMonitor. How often Prometheus scrapes the exporter metrics.
+  interval: 60s
+
+  # -- Scrape timeout for the ServiceMonitor. How long Prometheus waits for metrics response.
+  scrapeTimeout: 30s
+
+# -- Configuration for the exporter Service.
+service:
+  # -- Service type. ClusterIP is typically sufficient.
+  type: ClusterIP
+  # -- Port on which the exporter service is exposed.
+  port: 9876
+  # -- Target port on the exporter pod.
+  targetPort: 9876
+
+# -- Optional configuration for a network policy to allow traffic to the iperf3 server DaemonSet.
+# This is often necessary if you are using a network policy controller.
+networkPolicy:
+  # -- If true, create a NetworkPolicy resource.
+  enabled: false
+  # -- Specify source selectors if needed (e.g., pods in a specific namespace).
+  from: []
+  # -- Specify namespace selectors if needed.
+  namespaceSelector: {}
+  # -- Specify pod selectors if needed.
+  podSelector: {}