feat(exporter): implement subprocess execution with active stall watchdog and TCP metrics (#26)

- Replace in-process iperf3 C binding with subprocess execution
- Add active I/O stall detection and connect-timeout
- Expose TCP retransmissions, mean RTT (ms), and exporter cycle timestamp
- Upgrade Dockerfile to Python 3.12 running as non-root user (nobody)
- Fix testTimeout/testDuration environment variable mapping in Helm chart
- Remove dead TrueCharts prometheus-operator chart dependency
- Add unit tests for exporter metric parsing and stall handling
- Switch tooling from devbox to mise

Co-authored-by: Malarbase <malarbase@gmail.com>

.github/workflows/ci.yaml

@@ -9,6 +9,26 @@ env:
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
+  test-exporter:
+    name: Run Exporter Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -r exporter/requirements.txt
+
+      - name: Run unit tests
+        run: |
+          python -m unittest exporter/test_exporter.py
+
   validate-chart:
     name: Validate Helm Chart
     runs-on: ubuntu-latest
@@ -19,7 +39,16 @@ jobs:
       - name: Set up Helm
         uses: azure/setup-helm@v3
         with:
-          version: v3.10.0
+          version: v3.10.0 # Using a specific version, can be updated
+
+      - name: Add Helm repositories
+        run: |
+          helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts/ --force-update
+          helm repo add prometheus-community https://prometheus-community.github.io/helm-charts --force-update
+          helm repo update
+
+      - name: Build Helm chart dependencies
+        run: helm dependency build ./charts/iperf3-monitor
 
       - name: Helm Lint
         run: helm lint ./charts/iperf3-monitor

.github/workflows/release.yml

@@ -17,11 +17,33 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v3
 
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -r exporter/requirements.txt
+
+      - name: Run unit tests
+        run: |
+          python -m unittest exporter/test_exporter.py
+
       - name: Set up Helm
         uses: azure/setup-helm@v3
         with:
           version: v3.10.0
 
+      - name: Add Helm repositories
+        run: |
+          helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts/ --force-update
+          helm repo add prometheus-community https://prometheus-community.github.io/helm-charts --force-update
+          helm repo update
+
+      - name: Build Helm chart dependencies
+        run: helm dependency build ./charts/iperf3-monitor
+
       - name: Helm Lint
         run: helm lint ./charts/iperf3-monitor
 
@@ -54,6 +76,11 @@ jobs:
         uses: docker/metadata-action@v4
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            # This ensures that for a git tag like "v0.1.0",
+            # an image tag "0.1.0" is generated.
+            # It will also generate "latest" for the most recent semver tag.
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v4
@@ -86,6 +113,15 @@ jobs:
           sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq &&\
           sudo chmod +x /usr/bin/yq
 
+      - name: Add Helm repositories
+        run: |
+          helm repo add bjw-s https://bjw-s-labs.github.io/helm-charts/ --force-update
+          helm repo add prometheus-community https://prometheus-community.github.io/helm-charts --force-update
+          helm repo update
+
+      - name: Build Helm chart dependencies
+        run: helm dependency build ./charts/iperf3-monitor
+
       - name: Set Chart Version from Tag
         run: |
           VERSION=$(echo "${{ github.ref_name }}" | sed 's/^v//')

.gitignore

@@ -37,3 +37,7 @@ Thumbs.db
 # Helm
 !charts/iperf3-monitor/.helmignore
 charts/iperf3-monitor/charts/
+
+# Rendered Kubernetes manifests (for local testing)
+rendered-manifests.yaml
+rendered-manifests-updated.yaml

README.md

@@ -74,37 +74,123 @@ 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-monitor
-    # -- 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
+# Exporter Configuration (`controllers.exporter`)
+# The iperf3 exporter is managed under the `controllers.exporter` section,
+# leveraging the `bjw-s/common-library` for robust workload management.
+controllers:
+  exporter:
+    # -- Enable the exporter controller.
+    enabled: true
+    # -- Set the controller type for the exporter.
+    # Valid options are "deployment" or "daemonset".
+    # Use "daemonset" for N-to-N node monitoring where an exporter runs on each node (or selected nodes).
+    # Use "deployment" for a centralized exporter (typically with replicaCount: 1).
+    # @default -- "deployment"
+    type: deployment
+    # -- Number of desired exporter pods. Only used if type is "deployment".
+    # @default -- 1
+    replicas: 1
 
-  # -- Number of exporter pod replicas. Typically 1 is sufficient.
-  replicaCount: 1
+    # -- Application-specific configuration for the iperf3 exporter.
+    # These values are used to populate environment variables for the exporter container.
+    appConfig:
+      # -- Interval in seconds between complete test cycles (i.e., testing all server nodes).
+      testInterval: 300
+      # -- Log level for the iperf3 exporter (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).
+      logLevel: INFO
+      # -- Timeout in seconds for a single iperf3 test run.
+      testTimeout: 10
+      # -- Protocol to use for testing (tcp or udp).
+      testProtocol: tcp
+      # -- iperf3 server port to connect to. Should match the server's listening port.
+      serverPort: "5201"
+      # -- Label selector to find iperf3 server pods.
+      # This is templated. Default: 'app.kubernetes.io/name=<chart-name>,app.kubernetes.io/instance=<release-name>,app.kubernetes.io/component=server'
+      serverLabelSelector: 'app.kubernetes.io/name={{ include "iperf3-monitor.name" . }},app.kubernetes.io/instance={{ .Release.Name }},app.kubernetes.io/component=server'
 
-  # -- Interval in seconds between complete test cycles (i.e., testing all server nodes).
-  testInterval: 300
+    # -- Pod-level configurations for the exporter.
+    pod:
+      # -- Annotations for the exporter pod.
+      annotations: {}
+      # -- Labels for the exporter pod (the common library adds its own defaults too).
+      labels: {}
+      # -- Node selector for scheduling exporter pods. Useful for DaemonSet or specific scheduling with Deployments.
+      # Example:
+      # nodeSelector:
+      #   kubernetes.io/os: linux
+      nodeSelector: {}
+      # -- Tolerations for scheduling exporter pods.
+      # Example:
+      # tolerations:
+      # - key: "node-role.kubernetes.io/control-plane"
+      #   operator: "Exists"
+      #   effect: "NoSchedule"
+      tolerations: []
+      # -- Affinity rules for scheduling exporter pods.
+      # Example:
+      # affinity:
+      #   nodeAffinity:
+      #     requiredDuringSchedulingIgnoredDuringExecution:
+      #       nodeSelectorTerms:
+      #       - matchExpressions:
+      #         - key: "kubernetes.io/arch"
+      #           operator: In
+      #           values:
+      #           - amd64
+      affinity: {}
+      # -- Security context for the exporter pod.
+      # securityContext:
+      #   fsGroup: 65534
+      #   runAsUser: 65534
+      #   runAsGroup: 65534
+      #   runAsNonRoot: true
+      securityContext: {}
+      # -- Automount service account token for the pod.
+      automountServiceAccountToken: true
 
-  # -- 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"
+    # -- Container-level configurations for the main exporter container.
+    containers:
+      exporter: # Name of the primary container
+        image:
+          repository: ghcr.io/malarinv/iperf3-monitor
+          tag: "" # Defaults to .Chart.AppVersion
+          pullPolicy: IfNotPresent
+        # -- Custom environment variables for the exporter container.
+        # These are merged with the ones generated from appConfig.
+        # env:
+        #   MY_CUSTOM_VAR: "my_value"
+        env: {}
+        # -- Ports for the exporter container.
+        ports:
+          metrics: # Name of the port
+            port: 9876 # Container port for metrics
+            protocol: TCP
+            enabled: true
+        # -- CPU and memory resource requests and limits.
+        # resources:
+        #   requests:
+        #     cpu: "100m"
+        #     memory: "128Mi"
+        #   limits:
+        #     cpu: "500m"
+        #     memory: "256Mi"
+        resources: {}
+        # -- Probes configuration for the exporter container.
+        # probes:
+        #   liveness:
+        #     enabled: true # Example: enable liveness probe
+        #     spec: # Customize probe spec if needed
+        #       initialDelaySeconds: 30
+        #       periodSeconds: 15
+        #       timeoutSeconds: 5
+        #       failureThreshold: 3
+        probes:
+          liveness:
+            enabled: false
+          readiness:
+            enabled: false
+          startup:
+            enabled: false
 
 server:
   # -- Configuration for the iperf3 server container image (DaemonSet).

charts/iperf3-monitor/Chart.lock

@@ -1,9 +1,9 @@
 dependencies:
 - name: kube-prometheus-stack
   repository: https://prometheus-community.github.io/helm-charts
-  version: 75.3.6
-- name: prometheus-operator
-  repository: oci://tccr.io/truecharts
-  version: 11.5.1
-digest: sha256:3000e63445f8ba8df601cb483f4f77d14c5c4662bff2d16ffcf5cf1f7def314b
-generated: "2025-06-20T17:25:44.538372209+05:30"
+  version: 91.5.3
+- name: common
+  repository: https://bjw-s-labs.github.io/helm-charts/
+  version: 4.1.2
+digest: sha256:a3a063101484521564d3e8922c1c1fe7ae8040fe28c2ae246a40d0c00b860e65
+generated: "2026-09-26T09:52:53.951178644+05:30"

charts/iperf3-monitor/Chart.yaml

@@ -21,14 +21,20 @@ maintainers:
 icon: https://raw.githubusercontent.com/malarinv/iperf3-monitor/main/icon.png # Optional icon URL
 annotations:
   artifacthub.io/changes: |
-    - Add initial Helm chart structure.
+    - kind: changed
+      description: Refactor exporter to subprocess with active stall watchdog and connect-timeout
+    - kind: added
+      description: Expose TCP retransmits, mean RTT (ms), and cycle timestamp metrics
+    - kind: changed
+      description: Run exporter container as non-root on Python 3.12
+    - kind: fixed
+      description: Support testDuration, connectTimeoutMs, and stallThresholdSeconds in Helm values
   artifacthub.io/category: networking
 dependencies:
   - name: 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: "dependencies.install, serviceMonitor.enabled, !dependencies.useTrueChartsPrometheusOperator"
-  - name: prometheus-operator
-    version: ">=8.11.1"
-    repository: "oci://tccr.io/truecharts"
-    condition: "dependencies.install, serviceMonitor.enabled, dependencies.useTrueChartsPrometheusOperator"
+    condition: "dependencies.install, serviceMonitor.enabled"
+  - name: common
+    version: "4.1.2"
+    repository: "https://bjw-s-labs.github.io/helm-charts/"

charts/iperf3-monitor/grafana/iperf3-dashboard.json

@@ -0,0 +1,194 @@
+{
+"__inputs": [],
+"__requires": [
+{
+"type": "grafana",
+"id": "grafana",
+"name": "Grafana",
+"version": "8.0.0"
+},
+{
+"type": "datasource",
+"id": "prometheus",
+"name": "Prometheus",
+"version": "1.0.0"
+}
+],
+"annotations": {
+"list": [
+{
+"builtIn": 1,
+"datasource": {
+"type": "grafana",
+"uid": "-- Grafana --"
+},
+"enable": true,
+"hide": true,
+"iconColor": "rgba(0, 211, 255, 1)",
+"name": "Annotations & Alerts",
+"type": "dashboard"
+}
+]
+},
+"editable": true,
+"fiscalYearStartMonth": 0,
+"gnetId": null,
+"graphTooltip": 0,
+"id": null,
+"links": [],
+"panels": [
+{
+"datasource": {
+"type": "prometheus",
+"uid": "prometheus"
+},
+"gridPos": {
+"h": 9,
+"w": 24,
+"x": 0,
+"y": 0
+},
+"id": 2,
+"targets": [
+{
+"expr": "avg(iperf_network_bandwidth_mbps) by (source_node, destination_node)",
+"format": "heatmap",
+"legendFormat": "{{source_node}} -> {{destination_node}}",
+"refId": "A"
+}
+],
+"cards": { "cardPadding": null, "cardRound": null },
+"color": {
+"mode": "spectrum",
+"scheme": "red-yellow-green",
+"exponent": 0.5,
+"reverse": false
+},
+"dataFormat": "tsbuckets",
+"yAxis": { "show": true, "format": "short" },
+"xAxis": { "show": true }
+},
+{
+"title": "Bandwidth Over Time (Source: $source_node, Dest: $destination_node)",
+"type": "timeseries",
+"datasource": {
+"type": "prometheus",
+"uid": "prometheus"
+},
+"gridPos": {
+"h": 8,
+"w": 12,
+"x": 0,
+"y": 9
+},
+"targets": [
+{
+"expr": "iperf_network_bandwidth_mbps{source_node=~\"^$source_node$\", destination_node=~\"^$destination_node$\", protocol=~\"^$protocol$\"}",
+"legendFormat": "Bandwidth",
+"refId": "A"
+}
+],
+"fieldConfig": {
+"defaults": {
+"unit": "mbps"
+}
+}
+},
+{
+"title": "Jitter Over Time (Source: $source_node, Dest: $destination_node)",
+"type": "timeseries",
+"datasource": {
+"type": "prometheus",
+"uid": "prometheus"
+},
+"gridPos": {
+"h": 8,
+"w": 12,
+"x": 12,
+"y": 9
+},
+"targets": [
+{
+"expr": "iperf_network_jitter_ms{source_node=~\"^$source_node$\", destination_node=~\"^$destination_node$\", protocol=\"udp\"}",
+"legendFormat": "Jitter",
+"refId": "A"
+}
+],
+"fieldConfig": {
+"defaults": {
+"unit": "ms"
+}
+}
+}
+],
+"refresh": "30s",
+"schemaVersion": 36,
+"style": "dark",
+"tags": ["iperf3", "network", "kubernetes"],
+"templating": {
+"list": [
+{
+"current": {},
+"datasource": {
+"type": "prometheus",
+"uid": "prometheus"
+},
+"definition": "label_values(iperf_network_bandwidth_mbps, source_node)",
+"hide": 0,
+"includeAll": false,
+"multi": false,
+"name": "source_node",
+"options": [],
+"query": "label_values(iperf_network_bandwidth_mbps, source_node)",
+"refresh": 1,
+"regex": "",
+"skipUrlSync": false,
+"sort": 1,
+"type": "query"
+},
+{
+"current": {},
+"datasource": {
+"type": "prometheus",
+"uid": "prometheus"
+},
+"definition": "label_values(iperf_network_bandwidth_mbps{source_node=~\"^$source_node$\"}, destination_node)",
+"hide": 0,
+"includeAll": false,
+"multi": false,
+"name": "destination_node",
+"options": [],
+"query": "label_values(iperf_network_bandwidth_mbps{source_node=~\"^$source_node$\"}, destination_node)",
+"refresh": 1,
+"regex": "",
+"skipUrlSync": false,
+"sort": 1,
+"type": "query"
+},
+{
+"current": { "selected": true, "text": "tcp", "value": "tcp" },
+"hide": 0,
+"includeAll": false,
+"multi": false,
+"name": "protocol",
+"options": [
+{ "selected": true, "text": "tcp", "value": "tcp" },
+{ "selected": false, "text": "udp", "value": "udp" }
+],
+"query": "tcp,udp",
+"skipUrlSync": false,
+"type": "custom"
+}
+]
+},
+"time": {
+"from": "now-1h",
+"to": "now"
+},
+"timepicker": {},
+"timezone": "browser",
+"title": "Kubernetes iperf3 Network Performance",
+"uid": "k8s-iperf3-dashboard",
+"version": 1,
+"weekStart": ""
+}

charts/iperf3-monitor/templates/_helpers.tpl

@@ -47,9 +47,9 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 Create the name of the service account to use
 */}}
 {{- define "iperf3-monitor.serviceAccountName" -}}
-{{- if .Values.serviceAccount.create -}}
+{{- if .Values.rbac.create -}}
     {{- default (include "iperf3-monitor.fullname" .) .Values.serviceAccount.name -}}
 {{- else -}}
     {{- default "default" .Values.serviceAccount.name -}}
 {{- end -}}
-{{- end -}}
+{{- end -}}

charts/iperf3-monitor/templates/exporter-controller.yaml

@@ -0,0 +1,144 @@
+{{- /*
+This template is responsible for rendering the 'exporter' controller (Deployment or DaemonSet)
+by calling the bjw-s common library.
+
+The primary values for the exporter are expected under .Values.controllers.exporter.
+Modifications to environment variables and service account are handled here before
+passing the configuration to the common library.
+*/}}
+
+{{- /*
+Prepare a local, modifiable copy of the .Values. This allows us to adjust the
+exporter controller's configuration (like env vars and SA) specifically for this chart's needs
+before the common library processes it.
+Convert to map[string]interface{} via toYaml/fromYaml to ensure compatibility with 'dig'.
+*/}}
+{{- $localValues := .Values | toYaml | fromYaml | deepCopy -}}
+{{- $chart := .Chart -}}
+{{- $release := .Release -}}
+{{- $appName := include "iperf3-monitor.name" . -}}
+{{- $fullName := include "iperf3-monitor.fullname" . -}}
+
+{{- /*
+Define the key for the exporter controller, typically "exporter" as per our values.yaml.
+*/}}
+{{- $exporterControllerKey := "exporter" -}}
+
+{{- /*
+Attempt to get the exporter controller's configuration block.
+Proceed with modifications only if the exporter controller is defined.
+*/}}
+{{- $exporterControllerConfig := get $localValues.controllers $exporterControllerKey -}}
+{{- if $exporterControllerConfig -}}
+
+  {{- /*
+  Construct the base set of environment variables required by the iperf3-exporter application.
+  These are derived from the 'appConfig' section of the exporter's controller configuration.
+  */}}
+  {{- $baseExporterEnv := dict -}}
+  {{- if $exporterControllerConfig.appConfig -}}
+    {{- $_ := set $baseExporterEnv "SOURCE_NODE_NAME" (dict "valueFrom" (dict "fieldRef" (dict "fieldPath" "spec.nodeName"))) -}}
+    {{- $_ := set $baseExporterEnv "IPERF_TEST_INTERVAL" ($exporterControllerConfig.appConfig.testInterval | default "300" | toString) -}}
+    {{- $_ := set $baseExporterEnv "IPERF_TEST_PROTOCOL" ($exporterControllerConfig.appConfig.testProtocol | default "tcp") -}}
+    {{- $_ := set $baseExporterEnv "LOG_LEVEL" ($exporterControllerConfig.appConfig.logLevel | default "INFO") -}}
+    {{- $_ := set $baseExporterEnv "IPERF_SERVER_PORT" ($exporterControllerConfig.appConfig.serverPort | default "5201" | toString) -}}
+    {{- $_ := set $baseExporterEnv "IPERF_SERVER_NAMESPACE" (dict "valueFrom" (dict "fieldRef" (dict "fieldPath" "metadata.namespace"))) -}}
+    {{- $testDuration := $exporterControllerConfig.appConfig.testDuration | default $exporterControllerConfig.appConfig.testTimeout | default "5" | toString -}}
+    {{- $_ := set $baseExporterEnv "IPERF_TEST_DURATION" $testDuration -}}
+    {{- $_ := set $baseExporterEnv "IPERF_TEST_TIMEOUT" $testDuration -}}
+    {{- $_ := set $baseExporterEnv "IPERF_CONNECT_TIMEOUT_MS" ($exporterControllerConfig.appConfig.connectTimeoutMs | default "3000" | toString) -}}
+    {{- $_ := set $baseExporterEnv "IPERF_STALL_THRESHOLD_SECONDS" ($exporterControllerConfig.appConfig.stallThresholdSeconds | default "5" | toString) -}}
+    {{- $serverLabelSelectorDefault := printf "app.kubernetes.io/name=%s,app.kubernetes.io/instance=%s,app.kubernetes.io/component=server" $appName $release.Name -}}
+    {{- $serverLabelSelector := tpl ($exporterControllerConfig.appConfig.serverLabelSelector | default $serverLabelSelectorDefault) . -}}
+    {{- $_ := set $baseExporterEnv "IPERF_SERVER_LABEL_SELECTOR" $serverLabelSelector -}}
+  {{- end -}}
+
+  {{- /*
+  Merge the base environment variables with any user-defined environment variables.
+  User-defined variables (from .Values.controllers.exporter.containers.exporter.env)
+  will take precedence in case of conflicting keys.
+  */}}
+  {{- $userExporterEnv := $exporterControllerConfig.containers.exporter.env | default dict -}}
+  {{- $finalExporterEnv := mergeOverwrite $baseExporterEnv $userExporterEnv -}}
+
+  {{- /*
+  Ensure the container structure exists and update its 'env' field with the final set.
+  The common library expects this under controllers.<key>.containers.<containerName>.env
+  */}}
+  {{- if not $exporterControllerConfig.containers -}}
+    {{- $_ := set $exporterControllerConfig "containers" dict -}}
+  {{- end -}}
+  {{- if not $exporterControllerConfig.containers.exporter -}}
+    {{- $_ := set $exporterControllerConfig.containers "exporter" dict -}}
+  {{- end -}}
+  {{- $_ := set $exporterControllerConfig.containers.exporter "env" $finalExporterEnv -}}
+
+  {{- /*
+  Ensure the container image tag is set, defaulting to Chart.AppVersion if empty,
+  as the common library validation requires it during 'helm template'.
+
+  NOTE: BJW-S common library typically handles defaulting image.tag to Chart.appVersion
+  if image.tag is empty or null in values. The custom logic below prepending "v"
+  is specific to this chart and might be redundant if the common library's default
+  is preferred. For now, we keep it as it was the reason for previous errors if tag was not set.
+  However, if common library handles it, this block could be removed and image.tag in values.yaml set to "" or null.
+  Forcing the tag to be set (even if to chart.appVersion) ensures the common library doesn't complain.
+  The issue encountered during `helm template` earlier (empty output) was resolved by
+  explicitly setting the tag (e.g. via --set or by ensuring values.yaml has it).
+  The common library's internal validation likely needs *a* tag to be present in the values passed to it,
+  even if that tag is derived from AppVersion. This block ensures that.
+  */}}
+  {{- $exporterContainerCfg := get $exporterControllerConfig.containers "exporter" -}}
+  {{- if $exporterContainerCfg -}}
+    {{- if not $exporterContainerCfg.image.tag -}}
+      {{- if $chart.AppVersion -}}
+        {{- $_ := set $exporterContainerCfg.image "tag" (printf "%s" $chart.AppVersion) -}} # Removed "v" prefix
+      {{- else -}}
+        {{- fail (printf "Error: Container image tag is not specified for controller '%s', container '%s', and Chart.AppVersion is also empty." $exporterControllerKey "exporter") -}}
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+
+  {{- /*
+  Configure the Service Account for the exporter controller.
+  This ensures the controller pod uses the ServiceAccount that is intended by this chart's
+  RBAC configuration (.Values.rbac.create and .Values.serviceAccount.name).
+  */}}
+  {{- $serviceAccountNameFromValues := $localValues.serviceAccount.name | default (printf "%s-exporter" $fullName) -}}
+  {{- if not $exporterControllerConfig.serviceAccount -}}
+    {{- $_ := set $exporterControllerConfig "serviceAccount" dict -}}
+  {{- end -}}
+  {{- $_ := set $exporterControllerConfig.serviceAccount "name" $serviceAccountNameFromValues -}}
+  {{- $_ := set $exporterControllerConfig.serviceAccount "create" $localValues.rbac.create -}}
+  {{- $_ := set $exporterControllerConfig.serviceAccount "automountServiceAccountToken" ($exporterControllerConfig.pod.automountServiceAccountToken | default true) -}}
+
+  {{- /*
+  Replace the original exporter controller config in our $localValues copy
+  with the modified version (that now includes the correct env and SA settings).
+  */}}
+  {{- $_ := set $localValues.controllers $exporterControllerKey $exporterControllerConfig -}}
+{{- end -}}
+
+{{- /*
+Ensure .Values.global exists and is a map, as the common library expects it.
+*/}}
+{{- if not (get $localValues "global") -}}
+  {{- $_ := set $localValues "global" dict -}}
+{{- else if not (kindIs "map" (get $localValues "global")) -}}
+  {{- $_ := set $localValues "global" dict -}}
+{{- end -}}
+
+{{- /*
+Ensure defaultPodOptionsStrategy exists, as common lib expects it at the root of Values.
+*/}}
+{{- if not (get $localValues "defaultPodOptionsStrategy") -}}
+  {{- $_ := set $localValues "defaultPodOptionsStrategy" "overwrite" -}}
+{{- end -}}
+
+{{- /*
+Call the common library's main render function for controllers.
+This function iterates through all controllers defined under $localValues.controllers
+(in our case, just "exporter") and renders them using their specified type and configuration.
+The context passed must mirror the global Helm context, including 'Values', 'Chart', 'Release', 'Capabilities', and 'Template'.
+*/}}
+{{- include "bjw-s.common.render.controllers" (dict "Values" $localValues "Chart" $chart "Release" $release "Capabilities" .Capabilities "Template" .Template) | nindent 0 -}}

charts/iperf3-monitor/templates/exporter-deployment.yaml

@@ -1,50 +0,0 @@
-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: LOG_LEVEL
-          value: "{{ .Values.exporter.logLevel }}"
-        - 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 }}

charts/iperf3-monitor/templates/grafana-dashboard-configmap.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ .Release.Name }}-grafana-dashboard
+  labels:
+    grafana_dashboard: "1"
+    app.kubernetes.io/name: {{ include "iperf3-monitor.name" . }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
+data:
+  iperf3-dashboard.json: |
+    {{ .Files.Get "grafana/iperf3-dashboard.json" | nindent 4 }}

charts/iperf3-monitor/templates/rbac.yaml

@@ -7,9 +7,10 @@ metadata:
     {{- include "iperf3-monitor.labels" . | nindent 4 }}
 ---
 apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
+kind: Role
 metadata:
   name: {{ include "iperf3-monitor.fullname" . }}-role
+  namespace: {{ .Release.Namespace }}
   labels:
     {{- include "iperf3-monitor.labels" . | nindent 4 }}
 rules:
@@ -18,9 +19,10 @@ rules:
     verbs: ["get", "list", "watch"]
 ---
 apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
+kind: RoleBinding
 metadata:
   name: {{ include "iperf3-monitor.fullname" . }}-rb
+  namespace: {{ .Release.Namespace }}
   labels:
     {{- include "iperf3-monitor.labels" . | nindent 4 }}
 subjects:
@@ -28,7 +30,7 @@ subjects:
     name: {{ include "iperf3-monitor.serviceAccountName" . }}
     namespace: {{ .Release.Namespace }}
 roleRef:
-  kind: ClusterRole
+  kind: Role # Changed from ClusterRole
   name: {{ include "iperf3-monitor.fullname" . }}-role
   apiGroup: rbac.authorization.k8s.io
 {{- end -}}

charts/iperf3-monitor/templates/service.yaml

@@ -11,7 +11,7 @@ spec:
     {{- include "iperf3-monitor.selectorLabels" . | nindent 4 }}
     app.kubernetes.io/component: exporter
   ports:
-    - name: metrics
-      port: {{ .Values.service.port }}
-      targetPort: {{ .Values.service.targetPort }}
-      protocol: TCP
+    - name: metrics # Assuming 'metrics' is the intended name, aligns with values structure
+      port: {{ .Values.service.main.ports.metrics.port }}
+      targetPort: {{ .Values.service.main.ports.metrics.targetPort }}
+      protocol: {{ .Values.service.main.ports.metrics.protocol | default "TCP" }}

charts/iperf3-monitor/values.yaml

@@ -8,42 +8,121 @@ 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-monitor
-    # -- 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
+controllers:
+  exporter:
+    # -- Enable the exporter controller.
+    enabled: true
+    # -- Set the controller type for the exporter.
+    # Valid options are "deployment" or "daemonset".
+    # @default -- "deployment"
+    type: deployment
+    # -- Number of desired exporter pods. Only used if type is "deployment".
+    # @default -- 1
+    replicas: 1
 
-  # -- Number of exporter pod replicas. Typically 1 is sufficient.
-  replicaCount: 1
+    # -- Application-specific configuration for the iperf3 exporter.
+    # These values are used to populate environment variables for the exporter container.
+    appConfig:
+      # -- Interval in seconds between complete test cycles (i.e., testing all server nodes).
+      testInterval: 300
+      # -- Log level for the iperf3 exporter (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).
+      logLevel: INFO
+      # -- Timeout in seconds for a single iperf3 test run (kept for backward compatibility).
+      testTimeout: 5
+      # -- Duration in seconds for a single iperf3 test run.
+      testDuration: 5
+      # -- Connect timeout in milliseconds for control connection setup.
+      connectTimeoutMs: 3000
+      # -- Stall threshold in seconds (abort test if data transfer halts during test).
+      stallThresholdSeconds: 5
+      # -- Protocol to use for testing (tcp or udp).
+      testProtocol: tcp
+      # -- iperf3 server port to connect to. Should match the server's listening port.
+      # @default -- "5201" (hardcoded in the original chart for server daemonset)
+      serverPort: "5201"
+      # -- Label selector to find iperf3 server pods.
+      # This will be templated in the actual deployment.
+      # Example default (if not overridden by template logic): 'app.kubernetes.io/component=server'
+      serverLabelSelector: 'app.kubernetes.io/name={{ include "iperf3-monitor.name" . }},app.kubernetes.io/instance={{ .Release.Name }},app.kubernetes.io/component=server'
 
-  # -- Interval in seconds between complete test cycles (i.e., testing all server nodes).
-  testInterval: 300
 
-  # -- Log level for the iperf3 exporter (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).
-  logLevel: INFO
+    # -- Pod-level configurations for the exporter, leveraging bjw-s common library structure.
+    pod:
+      # -- Annotations for the exporter pod.
+      annotations: {}
+      # -- Labels for the exporter pod.
+      labels:
+        app.kubernetes.io/component: exporter # Ensure pods get the component label for service selection
+      # -- Node selector for scheduling exporter pods.
+      nodeSelector: {}
+      # -- Tolerations for scheduling exporter pods.
+      tolerations: []
+      # -- Affinity rules for scheduling exporter pods.
+      affinity: {}
+      # -- Security context for the exporter pod.
+      securityContext: {}
+        # fsGroup: 65534
+        # runAsUser: 65534
+        # runAsGroup: 65534
+        # runAsNonRoot: true
+      # -- Automount service account token for the pod.
+      automountServiceAccountToken: true # Default from common lib
 
-  # -- Timeout in seconds for a single iperf3 test run.
-  testTimeout: 10
+    # -- Container-level configurations for the main exporter container.
+    containers:
+      exporter: # This is the primary container, name it 'exporter'
+        image:
+          # -- The container image repository for the exporter.
+          repository: ghcr.io/malarinv/iperf3-monitor
+          # -- The container image tag for the exporter. If not set, the chart's appVersion is used.
+          tag: "" # Defaults to .Chart.AppVersion via common library
+          # -- The image pull policy for the exporter container.
+          pullPolicy: IfNotPresent
 
-  # -- Protocol to use for testing (tcp or udp).
-  testProtocol: tcp
+        # -- Environment variables for the exporter container.
+        # The actual env map will be constructed in the main chart template
+        # and passed to the common library. This section is for user overrides
+        # if they want to directly set other env vars using common lib's env schema.
+        env: {}
+          # Example:
+          # MY_CUSTOM_VAR: "my_value"
+          # ANOTHER_VAR:
+          #   valueFrom:
+          #     secretKeyRef:
+          #       name: mysecret
+          #       key: mykey
 
-  # -- 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"
+        # -- Ports for the exporter container.
+        # Expected by Kubernetes and bjw-s common library as a list of objects.
+        ports:
+          - name: metrics # Name of the port, referenced by Service's targetPort
+            # -- Port number for the metrics endpoint on the container.
+            containerPort: 9876
+            # -- Protocol for the metrics port.
+            protocol: TCP
+            # -- Whether this port definition is enabled. Specific to bjw-s common library.
+            enabled: true
 
+        # -- CPU and memory resource requests and limits for the exporter container.
+        resources:
+          {}
+          # requests:
+          #   cpu: "100m"
+          #   memory: "128Mi"
+          # limits:
+          #   cpu: "500m"
+          #   memory: "256Mi"
+
+        # -- Probes configuration for the exporter container.
+        probes:
+          liveness:
+            enabled: false
+          readiness:
+            enabled: false
+          startup:
+            enabled: false
+
+# Server configuration (iperf3 server daemonset)
 server:
   # -- Configuration for the iperf3 server container image (DaemonSet).
   image:
@@ -53,8 +132,6 @@ 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:
@@ -65,13 +142,9 @@ server:
     #   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 for scheduling iperf3 server pods on tainted nodes.
   tolerations:
     - key: "node-role.kubernetes.io/control-plane"
       operator: "Exists"
@@ -80,60 +153,60 @@ server:
       operator: "Exists"
       effect: "NoSchedule"
 
+# RBAC and ServiceAccount settings
+# These are for the exporter. The exporter deployment (managed by common library)
+# will need to use the ServiceAccount specified here or one created by the library.
 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.
+  # -- The name of the ServiceAccount to use/create for the exporter pod.
+  # If rbac.create is true, this SA is created. The exporter pod must use this SA.
   name: "iperf3-monitor"
 
+# Service Monitor configuration for Prometheus
 serviceMonitor:
-  # -- If true, create a ServiceMonitor resource for integration with Prometheus Operator.
-  # Requires a running Prometheus Operator in the cluster.
+  # -- If true, create a ServiceMonitor resource.
   enabled: true
-
-  # -- Scrape interval for the ServiceMonitor. How often Prometheus scrapes the exporter metrics.
+  # -- Scrape interval for the ServiceMonitor.
   interval: 60s
-
-  # -- Scrape timeout for the ServiceMonitor. How long Prometheus waits for metrics response.
+  # -- Scrape timeout for the ServiceMonitor.
   scrapeTimeout: 30s
 
-# -- Configuration for the exporter Service.
+# Service configuration for the exporter
+# This defines how the exporter is exposed.
+# The common library can also manage services, or we can use our own template.
+# This structure is compatible with bjw-s common library's service management if we choose to use it.
 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
+  main: # A key for the service, 'main' is a common convention.
+    # -- Enable the exporter service.
+    enabled: true
+    # -- Service type.
+    type: ClusterIP # ClusterIP is typical for internal services scraped by Prometheus.
+    # -- Ports configuration for the service.
+    ports:
+      metrics: # Name of the service port, should align with a container port name.
+        # -- Port number on which the service is exposed.
+        port: 9876
+        # -- Target port on the exporter pod. Can be a number or name.
+        # Refers to the 'metrics' port defined in controllers.exporter.containers.exporter.ports.
+        targetPort: metrics
+        protocol: TCP
 
-# -- 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.
+# Network Policy (optional)
 networkPolicy:
   # -- If true, create a NetworkPolicy resource.
   enabled: false
-  # -- Specify source selectors if needed (e.g., pods in a specific namespace).
+  # -- Source selectors for ingress rules.
   from: []
-  # -- Specify namespace selectors if needed.
+  # -- Namespace selectors for ingress rules.
   namespaceSelector: {}
-  # -- Specify pod selectors if needed.
+  # -- Pod selectors for ingress rules.
   podSelector: {}
 
-# -----------------------------------------------------------------------------
-# Dependency Configuration
-# -----------------------------------------------------------------------------
+# Dependency Configuration (for Prometheus Operator)
 dependencies:
-  # -- Set to true to install Prometheus operator dependency if serviceMonitor.enabled is also true.
-  # -- Set to false to disable the installation of Prometheus operator dependency,
-  # -- regardless of serviceMonitor.enabled. This is useful if you have Prometheus
-  # -- Operator installed and managed separately in your cluster.
-  install: true
-
-  # -- Set to true to use the TrueCharts Prometheus Operator instead of kube-prometheus-stack.
-  # This chart's ServiceMonitor resources require a Prometheus Operator to be functional.
-  # If serviceMonitor.enabled is true and dependencies.install is true,
-  # one of these two dependencies will be pulled based on this flag.
-  useTrueChartsPrometheusOperator: false
+  # -- Set to false by default. Set to true to install a Prometheus operator dependency (used if serviceMonitor.enabled=true).
+  # -- If false (default), and serviceMonitor.enabled is true, you must have a compatible Prometheus Operator already running in your cluster.
+  install: false

devbox.json

@@ -1,14 +0,0 @@
-{
-  "$schema":  "https://raw.githubusercontent.com/jetify-com/devbox/0.13.7/.schema/devbox.schema.json",
-  "packages": [],
-  "shell": {
-    "init_hook": [
-      "echo 'Welcome to devbox!' > /dev/null"
-    ],
-    "scripts": {
-      "test": [
-        "echo \"Error: no test specified\" && exit 1"
-      ]
-    }
-  }
-}

devbox.lock

@@ -1,4 +0,0 @@
-{
-  "lockfile_version": "1",
-  "packages": {}
-}

exporter/Dockerfile

@@ -1,46 +1,24 @@
 # Stage 1: Build stage with dependencies
-FROM python:3.9-slim as builder
+FROM python:3.12-slim AS builder
 
-# Declare TARGETARCH for use in this stage
-ARG TARGETARCH
 WORKDIR /app
 
-# Install iperf3 and build dependencies
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends gcc iperf3 libiperf-dev && \
-    rm -rf /var/lib/apt/lists/*
-
-# Determine the correct libiperf source directory based on TARGETARCH
-# and copy libiperf.so.0 to a canonical temporary location /tmp/lib/ within the builder stage.
-RUN echo "Builder stage TARGETARCH: ${TARGETARCH}" && \
-    LIBIPERF_SRC_DIR_SEGMENT="" && \
-    if [ "${TARGETARCH}" = "amd64" ]; then \
-        LIBIPERF_SRC_DIR_SEGMENT="x86_64-linux-gnu"; \
-    elif [ "${TARGETARCH}" = "arm64" ]; then \
-        LIBIPERF_SRC_DIR_SEGMENT="aarch64-linux-gnu"; \
-    else \
-        echo "Unsupported TARGETARCH in builder: ${TARGETARCH}" && exit 1; \
-    fi && \
-    mkdir -p /tmp/lib && \
-    cp "/usr/lib/${LIBIPERF_SRC_DIR_SEGMENT}/libiperf.so.0" /tmp/lib/libiperf.so.0
-
 # Install Python dependencies
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
 
 # Stage 2: Final runtime stage
-FROM python:3.9-slim
+FROM python:3.12-slim
 
 WORKDIR /app
 
-# Copy iperf3 binary from the builder stage
-COPY --from=builder /usr/bin/iperf3 /usr/bin/iperf3
-# Copy the prepared libiperf.so.0 from the builder's canonical temporary location
-# into a standard library path in the final image.
-COPY --from=builder /tmp/lib/libiperf.so.0 /usr/lib/libiperf.so.0
+# Install iperf3
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends iperf3 && \
+    rm -rf /var/lib/apt/lists/*
 
 # Copy installed Python packages from the builder stage
-COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages
+COPY --from=builder /install /usr/local
 
 # Copy the exporter application code
 COPY exporter.py .
@@ -48,5 +26,9 @@ COPY exporter.py .
 # Expose the metrics port
 EXPOSE 9876
 
+# Run as non-root user (nobody)
+USER 65534:65534
+
 # Set the entrypoint
-CMD ["python", "exporter.py"]
+CMD ["python", "exporter.py"]
+

exporter/exporter.py

@@ -4,24 +4,20 @@ Prometheus exporter for iperf3 network performance monitoring.
 This script runs iperf3 tests between the node it's running on (source) and
 other iperf3 server pods discovered in a Kubernetes cluster. It then exposes
 these metrics for Prometheus consumption.
-
-Configuration is primarily through environment variables and command-line arguments
-for log level.
 """
 import os
+import sys
 import time
+import json
+import signal
 import logging
 import argparse
-import sys
+import subprocess
 from kubernetes import client, config
 from prometheus_client import start_http_server, Gauge
-import iperf3
 
 # --- Global Configuration & Setup ---
 
-# Argument parsing for log level configuration
-# The command-line --log-level argument takes precedence over the LOG_LEVEL env var.
-# Defaults to INFO if neither is set.
 parser = argparse.ArgumentParser(description="iperf3 Prometheus exporter.")
 parser.add_argument(
     '--log-level',
@@ -29,19 +25,16 @@ parser.add_argument(
     choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
     help='Set the logging level. Overrides LOG_LEVEL environment variable. (Default: INFO)'
 )
-args = parser.parse_args()
+args, _ = parser.parse_known_args()
 log_level_str = args.log_level
 
-# Convert log level string (e.g., 'INFO') to its numeric representation (e.g., logging.INFO)
 numeric_level = getattr(logging, log_level_str.upper(), None)
 if not isinstance(numeric_level, int):
-    # This case should ideally not be reached if choices in argparse are respected.
     logging.error(f"Invalid log level: {log_level_str}. Defaulting to INFO.")
     numeric_level = logging.INFO
 logging.basicConfig(level=numeric_level, format='%(asctime)s - %(levelname)s - %(message)s')
 
 # --- Prometheus Metrics Definition ---
-# These gauges will be used to expose iperf3 test results.
 IPERF_BANDWIDTH_MBPS = Gauge(
     'iperf_network_bandwidth_mbps',
     'Network bandwidth measured by iperf3 in Megabits per second (Mbps)',
@@ -67,24 +60,61 @@ IPERF_TEST_SUCCESS = Gauge(
     'Indicates if the iperf3 test was successful (1) or failed (0)',
     ['source_node', 'destination_node', 'protocol']
 )
+IPERF_TCP_RETRANSMITS = Gauge(
+    'iperf_network_tcp_retransmits_total',
+    'Total TCP retransmits measured by iperf3 during the test',
+    ['source_node', 'destination_node', 'protocol']
+)
+IPERF_TCP_RTT_MS = Gauge(
+    'iperf_network_tcp_rtt_ms',
+    'Mean TCP round-trip time in milliseconds (ms) measured by iperf3',
+    ['source_node', 'destination_node', 'protocol']
+)
+IPERF_TEST_DURATION_SECONDS = Gauge(
+    'iperf_network_test_duration_seconds',
+    'Duration of the iperf3 test in seconds',
+    ['source_node', 'destination_node', 'protocol']
+)
+IPERF_LAST_TEST_TIMESTAMP_SECONDS = Gauge(
+    'iperf_exporter_last_success_timestamp_seconds',
+    'Unix timestamp of the last completed test cycle',
+    ['source_node']
+)
+IPERF_SERVERS_DISCOVERED = Gauge(
+    'iperf_exporter_servers_discovered',
+    'Number of target iperf3 servers discovered in the cluster',
+    ['source_node']
+)
 
-def discover_iperf_servers():
+# --- Graceful Shutdown & Exceptions ---
+shutdown_requested = False
+active_subprocess = None
+
+def signal_handler(signum, frame):
+    global shutdown_requested, active_subprocess
+    logging.info(f"Received signal {signum}. Initiating graceful shutdown...")
+    shutdown_requested = True
+    if active_subprocess and active_subprocess.poll() is None:
+        try:
+            active_subprocess.kill()
+        except Exception:
+            pass
+
+class IperfStallException(Exception):
+    """Raised when an iperf3 test experiences a silent or busy-wait stall."""
+    pass
+
+class IperfTimeoutException(Exception):
+    """Raised when an iperf3 test exceeds its maximum expected deadline."""
+    pass
+
+# --- Kubernetes Discovery ---
+def discover_iperf_servers(source_node_name):
     """
     Discovers iperf3 server pods within a Kubernetes cluster.
-
-    It uses the in-cluster Kubernetes configuration to connect to the API.
-    The target namespace and label selector for iperf3 server pods are configured
-    via environment variables:
-    - IPERF_SERVER_NAMESPACE (default: 'default')
-    - IPERF_SERVER_LABEL_SELECTOR (default: 'app=iperf3-server')
-
-    Returns:
-        list: A list of dictionaries, where each dictionary contains the 'ip'
-              and 'node_name' of a discovered iperf3 server pod. Returns an
-              empty list if discovery fails or no servers are found.
     """
     try:
-        config.load_incluster_config() # Assumes running inside a Kubernetes pod
+        config.load_incluster_config()
         v1 = client.CoreV1Api()
 
         namespace = os.getenv('IPERF_SERVER_NAMESPACE', 'default')
@@ -92,206 +122,317 @@ def discover_iperf_servers():
 
         logging.info(f"Discovering iperf3 servers with label '{label_selector}' in namespace '{namespace}'")
 
-        ret = v1.list_pod_for_all_namespaces(label_selector=label_selector, watch=False)
+        ret = v1.list_namespaced_pod(namespace=namespace, label_selector=label_selector, watch=False)
 
         servers = []
         for item in ret.items:
             if item.status.pod_ip and item.status.phase == 'Running':
                 servers.append({
                     'ip': item.status.pod_ip,
-                    'node_name': item.spec.node_name # Node where the iperf server pod is running
+                    'node_name': item.spec.node_name
                 })
-        logging.info(f"Discovered {len(servers)} iperf3 server pods.")
+        logging.info(f"Discovered {len(servers)} iperf3 server pods in namespace '{namespace}'.")
+        IPERF_SERVERS_DISCOVERED.labels(source_node=source_node_name).set(len(servers))
         return servers
     except config.ConfigException as e:
         logging.error(f"Kubernetes config error: {e}. Is the exporter running in a cluster with RBAC permissions?")
         return []
     except Exception as e:
         logging.error(f"Error discovering iperf servers: {e}")
-        return [] # Return empty list on error to avoid crashing the main loop
+        return []
 
-def run_iperf_test(server_ip, server_port, protocol, source_node_name, dest_node_name):
+# --- iperf3 Subprocess Execution with Stall Detection ---
+def execute_iperf_test(server_ip, server_port, protocol, duration, connect_timeout_ms, stall_threshold_sec):
     """
-    Runs a single iperf3 test against a specified server and publishes metrics.
-
-    Args:
-        server_ip (str): The IP address of the iperf3 server.
-        server_port (int): The port number of the iperf3 server.
-        protocol (str): The protocol to use ('tcp' or 'udp').
-        source_node_name (str): The name of the source node (where this exporter is running).
-        dest_node_name (str): The name of the destination node (where the server is running).
-
-    The test duration is controlled by the IPERF_TEST_DURATION environment variable
-    (default: 5 seconds).
+    Executes the iperf3 CLI in a subprocess with JSON output and active stall detection.
     """
-    logging.info(f"Running iperf3 {protocol.upper()} test from {source_node_name} to {dest_node_name} ({server_ip}:{server_port})")
+    global active_subprocess
 
-    iperf_client = iperf3.Client()
-    iperf_client.server_hostname = server_ip
-    iperf_client.port = server_port
-    iperf_client.protocol = protocol
-    iperf_client.duration = int(os.getenv('IPERF_TEST_DURATION', 5)) # Test duration in seconds
-    iperf_client.json_output = True # Enables easy parsing of results
+    cmd = [
+        "iperf3",
+        "-c", server_ip,
+        "-p", str(server_port),
+        "-t", str(duration),
+        "--connect-timeout", str(connect_timeout_ms),
+        "-J",
+    ]
+    if protocol == 'udp':
+        cmd.append("-u")
+
+    logging.debug(f"Executing: {' '.join(cmd)}")
+
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    active_subprocess = proc
+
+    start_time = time.monotonic()
+    # Maximum deadline: connect timeout + duration + stall threshold buffer
+    connect_timeout_sec = connect_timeout_ms / 1000.0
+    max_deadline = start_time + connect_timeout_sec + duration + stall_threshold_sec
+
+    last_io_change = start_time
+    last_wchar = 0
+    test_transfer_detected = False
 
     try:
-        result = iperf_client.run()
-        parse_and_publish_metrics(result, source_node_name, dest_node_name, protocol)
-    except Exception as e:
-        # Catch unexpected errors during client.run() or parsing
-        logging.error(f"Exception during iperf3 test or metric parsing for {dest_node_name}: {e}")
-        labels = {'source_node': source_node_name, 'destination_node': dest_node_name, 'protocol': protocol}
-        IPERF_TEST_SUCCESS.labels(**labels).set(0)
+        while proc.poll() is None:
+            if shutdown_requested:
+                proc.kill()
+                proc.wait()
+                raise KeyboardInterrupt("Shutdown requested")
+
+            now = time.monotonic()
+            if now > max_deadline:
+                proc.kill()
+                proc.wait()
+                raise IperfTimeoutException(f"iperf3 test exceeded absolute deadline of {max_deadline - start_time:.1f}s")
+
+            time.sleep(0.5)
+
+            # Check I/O progress via /proc/<pid>/io to detect busy-spin without I/O
+            try:
+                with open(f"/proc/{proc.pid}/io", "r") as f:
+                    for line in f:
+                        if line.startswith("wchar:"):
+                            wchar = int(line.split()[1])
+                            if wchar > last_wchar:
+                                last_wchar = wchar
+                                last_io_change = now
+                                test_transfer_detected = True
+                            break
+            except (FileNotFoundError, ProcessLookupError, PermissionError):
+                pass
+
+            # If traffic was active and has now completely ceased progressing for >= stall_threshold_sec
+            if test_transfer_detected and (now - last_io_change) >= stall_threshold_sec:
+                proc.kill()
+                proc.wait()
+                raise IperfStallException(f"iperf3 stalled: data transfer ceased for {now - last_io_change:.1f}s")
+
+        stdout, stderr = proc.communicate()
+        return proc.returncode, stdout, stderr
+    finally:
+        active_subprocess = None
+
+# --- Metric Reset Helper ---
+def reset_failure_metrics(labels):
+    IPERF_TEST_SUCCESS.labels(**labels).set(0)
+    for g in (
+        IPERF_BANDWIDTH_MBPS,
+        IPERF_JITTER_MS,
+        IPERF_PACKETS_TOTAL,
+        IPERF_LOST_PACKETS,
+        IPERF_TCP_RETRANSMITS,
+        IPERF_TCP_RTT_MS,
+        IPERF_TEST_DURATION_SECONDS,
+    ):
         try:
-            IPERF_BANDWIDTH_MBPS.labels(**labels).set(0)
-            IPERF_JITTER_MS.labels(**labels).set(0)
-            IPERF_PACKETS_TOTAL.labels(**labels).set(0)
-            IPERF_LOST_PACKETS.labels(**labels).set(0)
+            g.labels(**labels).set(0)
         except KeyError:
-            logging.debug(f"KeyError setting failure metrics for {labels} after client.run() exception.")
+            pass
 
-
-def parse_and_publish_metrics(result, source_node, dest_node, protocol):
+# --- Metric Parsing ---
+def parse_and_publish_metrics(data, source_node, dest_node, protocol):
     """
-    Parses the iperf3 test result and updates Prometheus gauges.
-
-    Args:
-        result (iperf3.TestResult): The result object from the iperf3 client.
-        source_node (str): Name of the source node.
-        dest_node (str): Name of the destination node.
-        protocol (str): Protocol used for the test ('tcp' or 'udp').
+    Parses iperf3 JSON result and updates Prometheus gauges.
     """
     labels = {'source_node': source_node, 'destination_node': dest_node, 'protocol': protocol}
 
-    # Handle failed tests (e.g., server unreachable) or missing result object
-    if not result or result.error:
-        error_message = result.error if result and result.error else "No result object from iperf3 client"
-        logging.warning(f"Test from {source_node} to {dest_node} ({protocol.upper()}) failed: {error_message}")
-        IPERF_TEST_SUCCESS.labels(**labels).set(0)
-        # Set all relevant metrics to 0 on failure to clear stale values from previous successes
-        try:
-            IPERF_BANDWIDTH_MBPS.labels(**labels).set(0)
-            IPERF_JITTER_MS.labels(**labels).set(0) # Applicable for UDP, zeroed for TCP later
-            IPERF_PACKETS_TOTAL.labels(**labels).set(0) # Applicable for UDP, zeroed for TCP later
-            IPERF_LOST_PACKETS.labels(**labels).set(0) # Applicable for UDP, zeroed for TCP later
-        except KeyError:
-            # This can happen if labels were never registered due to continuous failures
-            logging.debug(f"KeyError when setting failure metrics for {labels}. Gauges might not be initialized.")
+    if not data or not isinstance(data, dict):
+        logging.warning(f"Test from {source_node} to {dest_node} ({protocol.upper()}) failed: empty or invalid result")
+        reset_failure_metrics(labels)
         return
 
-    # If we reach here, the test itself was successful in execution
+    if data.get("error"):
+        error_msg = data.get("error")
+        logging.warning(f"Test from {source_node} to {dest_node} ({protocol.upper()}) failed: {error_msg}")
+        reset_failure_metrics(labels)
+        return
+
+    end = data.get("end")
+    if not end or not isinstance(end, dict):
+        logging.warning(f"Test from {source_node} to {dest_node} ({protocol.upper()}) failed: missing 'end' summary in JSON")
+        reset_failure_metrics(labels)
+        return
+
+    # Successful test execution
     IPERF_TEST_SUCCESS.labels(**labels).set(1)
 
-    # Determine bandwidth:
-    # Order of preference: received_Mbps, sent_Mbps, Mbps, then JSON fallbacks.
-    # received_Mbps is often most relevant for TCP client perspective.
-    # sent_Mbps can be relevant for UDP or as a TCP fallback.
-    bandwidth_mbps = 0
-    if hasattr(result, 'received_Mbps') and result.received_Mbps is not None:
-        bandwidth_mbps = result.received_Mbps
-    elif hasattr(result, 'sent_Mbps') and result.sent_Mbps is not None:
-        bandwidth_mbps = result.sent_Mbps
-    elif hasattr(result, 'Mbps') and result.Mbps is not None: # General attribute from iperf3 library
-        bandwidth_mbps = result.Mbps
-    # Fallback to raw JSON if direct attributes are None or missing
-    elif result.json:
-        # Prefer received sum, then sent sum from the JSON output's 'end' summary
-        if 'end' in result.json and 'sum_received' in result.json['end'] and \
-           result.json['end']['sum_received'].get('bits_per_second') is not None:
-            bandwidth_mbps = result.json['end']['sum_received']['bits_per_second'] / 1000000.0
-        elif 'end' in result.json and 'sum_sent' in result.json['end'] and \
-             result.json['end']['sum_sent'].get('bits_per_second') is not None:
-            bandwidth_mbps = result.json['end']['sum_sent']['bits_per_second'] / 1000000.0
+    sum_received = end.get("sum_received") or {}
+    sum_sent = end.get("sum_sent") or {}
+    sum_udp = end.get("sum") or {}
+
+    bandwidth_mbps = 0.0
+
+    if protocol == 'tcp':
+        if "bits_per_second" in sum_received and sum_received["bits_per_second"] is not None:
+            bandwidth_mbps = sum_received["bits_per_second"] / 1_000_000.0
+        elif "bits_per_second" in sum_sent and sum_sent["bits_per_second"] is not None:
+            bandwidth_mbps = sum_sent["bits_per_second"] / 1_000_000.0
+
+        # TCP Retransmits
+        retransmits = sum_sent.get("retransmits", 0)
+        IPERF_TCP_RETRANSMITS.labels(**labels).set(retransmits)
+
+        # TCP RTT
+        mean_rtt_us = 0.0
+        streams = end.get("streams", [])
+        if streams and isinstance(streams, list):
+            sender_info = streams[0].get("sender", {})
+            mean_rtt_us = sender_info.get("mean_rtt", sender_info.get("rtt", 0.0))
+        IPERF_TCP_RTT_MS.labels(**labels).set(mean_rtt_us / 1000.0)
+
+        # Zero out UDP-specific gauges
+        IPERF_JITTER_MS.labels(**labels).set(0)
+        IPERF_PACKETS_TOTAL.labels(**labels).set(0)
+        IPERF_LOST_PACKETS.labels(**labels).set(0)
+
+        # Test duration
+        test_seconds = sum_received.get("seconds", sum_sent.get("seconds", 0.0))
+        IPERF_TEST_DURATION_SECONDS.labels(**labels).set(test_seconds)
+    else:
+        if "bits_per_second" in sum_udp and sum_udp["bits_per_second"] is not None:
+            bandwidth_mbps = sum_udp["bits_per_second"] / 1_000_000.0
+        elif "bits_per_second" in sum_sent and sum_sent["bits_per_second"] is not None:
+            bandwidth_mbps = sum_sent["bits_per_second"] / 1_000_000.0
+
+        IPERF_JITTER_MS.labels(**labels).set(sum_udp.get("jitter_ms", 0.0) or 0.0)
+        IPERF_PACKETS_TOTAL.labels(**labels).set(sum_udp.get("packets", 0) or 0)
+        IPERF_LOST_PACKETS.labels(**labels).set(sum_udp.get("lost_packets", 0) or 0)
+        IPERF_TCP_RETRANSMITS.labels(**labels).set(0)
+        IPERF_TCP_RTT_MS.labels(**labels).set(0)
+
+        test_seconds = sum_udp.get("seconds", 0.0)
+        IPERF_TEST_DURATION_SECONDS.labels(**labels).set(test_seconds)
 
     IPERF_BANDWIDTH_MBPS.labels(**labels).set(bandwidth_mbps)
 
-    # UDP specific metrics
-    if protocol == 'udp':
-        # These attributes are specific to UDP tests in iperf3
-        IPERF_JITTER_MS.labels(**labels).set(getattr(result, 'jitter_ms', 0) if result.jitter_ms is not None else 0)
-        IPERF_PACKETS_TOTAL.labels(**labels).set(getattr(result, 'packets', 0) if result.packets is not None else 0)
-        IPERF_LOST_PACKETS.labels(**labels).set(getattr(result, 'lost_packets', 0) if result.lost_packets is not None else 0)
-    else:
-        # For TCP tests, ensure UDP-specific metrics are set to 0
-        try:
-             IPERF_JITTER_MS.labels(**labels).set(0)
-             IPERF_PACKETS_TOTAL.labels(**labels).set(0)
-             IPERF_LOST_PACKETS.labels(**labels).set(0)
-        except KeyError:
-            # Can occur if labels not yet registered (e.g. first test is TCP)
-            logging.debug(f"KeyError for {labels} when zeroing UDP metrics for TCP test.")
-            pass
+# --- Test Execution Wrapper ---
+def run_iperf_test(server_ip, server_port, protocol, source_node_name, dest_node_name, duration, connect_timeout_ms, stall_threshold_sec):
+    """
+    Runs a single iperf3 test with stall monitoring and publishes metrics.
+    """
+    logging.info(f"Running iperf3 {protocol.upper()} test from {source_node_name} to {dest_node_name} ({server_ip}:{server_port})")
+    labels = {'source_node': source_node_name, 'destination_node': dest_node_name, 'protocol': protocol}
 
+    try:
+        returncode, stdout, stderr = execute_iperf_test(
+            server_ip=server_ip,
+            server_port=server_port,
+            protocol=protocol,
+            duration=duration,
+            connect_timeout_ms=connect_timeout_ms,
+            stall_threshold_sec=stall_threshold_sec,
+        )
+
+        if not stdout.strip():
+            logging.warning(f"iperf3 produced no stdout for {dest_node_name}. Stderr: {stderr.strip()}")
+            reset_failure_metrics(labels)
+            return
+
+        try:
+            result_json = json.loads(stdout)
+        except json.JSONDecodeError as e:
+            logging.warning(f"Failed to parse iperf3 JSON output for {dest_node_name}: {e}. Output: {stdout[:200]}")
+            reset_failure_metrics(labels)
+            return
+
+        parse_and_publish_metrics(result_json, source_node_name, dest_node_name, protocol)
+    except IperfStallException as e:
+        logging.warning(f"Test from {source_node_name} to {dest_node_name} ({protocol.upper()}) aborted: {e}")
+        reset_failure_metrics(labels)
+    except IperfTimeoutException as e:
+        logging.warning(f"Test from {source_node_name} to {dest_node_name} ({protocol.upper()}) timed out: {e}")
+        reset_failure_metrics(labels)
+    except KeyboardInterrupt:
+        raise
+    except Exception as e:
+        logging.error(f"Unexpected exception during iperf3 test for {dest_node_name}: {e}")
+        reset_failure_metrics(labels)
+
+# --- Main Exporter Loop ---
 def main_loop():
     """
     Main operational loop of the iperf3 exporter.
-
-    This loop periodically:
-    1. Fetches configuration from environment variables:
-       - IPERF_TEST_INTERVAL (default: 300s): Time between test cycles.
-       - IPERF_SERVER_PORT (default: 5201): Port for iperf3 servers.
-       - IPERF_TEST_PROTOCOL (default: 'tcp'): 'tcp' or 'udp'.
-       - SOURCE_NODE_NAME (critical): Name of the node this exporter runs on.
-    2. Discovers iperf3 server pods in the Kubernetes cluster.
-    3. Runs iperf3 tests against each discovered server (unless it's on the same node).
-    4. Sleeps for the configured test interval.
-
-    If SOURCE_NODE_NAME is not set, the script will log an error and exit.
     """
-    # Fetch operational configuration from environment variables
     test_interval = int(os.getenv('IPERF_TEST_INTERVAL', 300))
     server_port = int(os.getenv('IPERF_SERVER_PORT', 5201))
-    protocol = os.getenv('IPERF_TEST_PROTOCOL', 'tcp').lower() # Ensure lowercase
+    protocol = os.getenv('IPERF_TEST_PROTOCOL', 'tcp').lower()
     source_node_name = os.getenv('SOURCE_NODE_NAME')
 
-    # SOURCE_NODE_NAME is crucial for labeling metrics correctly.
+    # Support either IPERF_TEST_DURATION or IPERF_TEST_TIMEOUT from Helm values
+    duration = int(os.getenv('IPERF_TEST_DURATION', os.getenv('IPERF_TEST_TIMEOUT', 5)))
+    connect_timeout_ms = int(os.getenv('IPERF_CONNECT_TIMEOUT_MS', 3000))
+    stall_threshold_sec = int(os.getenv('IPERF_STALL_THRESHOLD_SECONDS', 5))
+
     if not source_node_name:
         logging.error("CRITICAL: SOURCE_NODE_NAME environment variable not set. This is required. Exiting.")
         sys.exit(1)
 
     logging.info(
         f"Exporter configured. Source Node: {source_node_name}, "
-        f"Test Interval: {test_interval}s, Server Port: {server_port}, Protocol: {protocol.upper()}"
+        f"Test Interval: {test_interval}s, Duration: {duration}s, Server Port: {server_port}, Protocol: {protocol.upper()}, "
+        f"Connect Timeout: {connect_timeout_ms}ms, Stall Threshold: {stall_threshold_sec}s"
     )
 
-    while True:
+    while not shutdown_requested:
         logging.info("Starting new iperf test cycle...")
-        servers = discover_iperf_servers()
+        servers = discover_iperf_servers(source_node_name)
 
         if not servers:
             logging.warning("No iperf servers discovered in this cycle. Check K8s setup and RBAC permissions.")
         else:
             for server in servers:
-                dest_node_name = server.get('node_name', 'unknown_destination_node') # Default if key missing
+                if shutdown_requested:
+                    break
+
+                dest_node_name = server.get('node_name', 'unknown_destination_node')
                 server_ip = server.get('ip')
 
                 if not server_ip:
                     logging.warning(f"Discovered server entry missing an IP: {server}. Skipping.")
                     continue
 
-                # Avoid testing a node against itself
                 if dest_node_name == source_node_name:
                     logging.info(f"Skipping test to self: {source_node_name} to {server_ip} (on same node: {dest_node_name}).")
                     continue
 
-                run_iperf_test(server_ip, server_port, protocol, source_node_name, dest_node_name)
+                run_iperf_test(
+                    server_ip=server_ip,
+                    server_port=server_port,
+                    protocol=protocol,
+                    source_node_name=source_node_name,
+                    dest_node_name=dest_node_name,
+                    duration=duration,
+                    connect_timeout_ms=connect_timeout_ms,
+                    stall_threshold_sec=stall_threshold_sec,
+                )
 
-        logging.info(f"Test cycle completed. Sleeping for {test_interval} seconds.")
-        time.sleep(test_interval)
+        if not shutdown_requested:
+            IPERF_LAST_TEST_TIMESTAMP_SECONDS.labels(source_node=source_node_name).set(time.time())
+            logging.info(f"Test cycle completed. Sleeping for {test_interval} seconds.")
+            slept = 0
+            while slept < test_interval and not shutdown_requested:
+                time.sleep(1)
+                slept += 1
+
+    logging.info("Exporter main loop stopped gracefully.")
 
 if __name__ == '__main__':
-    # Initial logging (like log level) is configured globally at the start of the script.
+    signal.signal(signal.SIGTERM, signal_handler)
+    signal.signal(signal.SIGINT, signal_handler)
 
-    # Fetch Prometheus exporter listen port from environment variable
     listen_port = int(os.getenv('LISTEN_PORT', 9876))
 
     try:
-        # Start the Prometheus HTTP server to expose metrics.
         start_http_server(listen_port)
         logging.info(f"Prometheus exporter listening on port {listen_port}")
     except Exception as e:
         logging.error(f"Failed to start Prometheus HTTP server on port {listen_port}: {e}")
-        sys.exit(1) # Exit if the metrics server cannot start
+        sys.exit(1)
 
-    # Enter the main operational loop.
-    # main_loop() contains its own critical checks (e.g., SOURCE_NODE_NAME) and will exit if necessary.
     main_loop()

exporter/requirements.txt

@@ -1,3 +1,2 @@
-prometheus-client
-iperf3
-kubernetes
+prometheus-client>=0.20.0
+kubernetes>=29.0.0

exporter/test_exporter.py

@@ -0,0 +1,111 @@
+import os
+import sys
+import unittest
+import json
+from unittest.mock import patch, MagicMock
+
+import importlib.util
+
+spec = importlib.util.spec_from_file_location("exporter_mod", os.path.join(os.path.dirname(__file__), "exporter.py"))
+exporter = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(exporter)
+
+class TestExporter(unittest.TestCase):
+
+    def setUp(self):
+        self.source = "node-a"
+        self.dest = "node-b"
+        self.labels = {'source_node': self.source, 'destination_node': self.dest, 'protocol': 'tcp'}
+        self.udp_labels = {'source_node': self.source, 'destination_node': self.dest, 'protocol': 'udp'}
+
+    def test_parse_tcp_success(self):
+        tcp_json = {
+            "end": {
+                "streams": [
+                    {
+                        "sender": {
+                            "mean_rtt": 250,  # 250 microseconds = 0.25 ms
+                            "retransmits": 3
+                        }
+                    }
+                ],
+                "sum_sent": {
+                    "seconds": 5.0,
+                    "bytes": 50000000,
+                    "bits_per_second": 80000000.0,
+                    "retransmits": 3
+                },
+                "sum_received": {
+                    "seconds": 5.0,
+                    "bytes": 49000000,
+                    "bits_per_second": 78400000.0
+                }
+            }
+        }
+
+        exporter.parse_and_publish_metrics(tcp_json, self.source, self.dest, 'tcp')
+
+        self.assertEqual(exporter.IPERF_TEST_SUCCESS.labels(**self.labels)._value.get(), 1)
+        self.assertAlmostEqual(exporter.IPERF_BANDWIDTH_MBPS.labels(**self.labels)._value.get(), 78.4)
+        self.assertEqual(exporter.IPERF_TCP_RETRANSMITS.labels(**self.labels)._value.get(), 3)
+        self.assertAlmostEqual(exporter.IPERF_TCP_RTT_MS.labels(**self.labels)._value.get(), 0.25)
+        self.assertEqual(exporter.IPERF_TEST_DURATION_SECONDS.labels(**self.labels)._value.get(), 5.0)
+        self.assertEqual(exporter.IPERF_JITTER_MS.labels(**self.labels)._value.get(), 0)
+
+    def test_parse_udp_success(self):
+        udp_json = {
+            "end": {
+                "sum": {
+                    "seconds": 5.0,
+                    "bytes": 1000000,
+                    "bits_per_second": 1600000.0,
+                    "jitter_ms": 1.25,
+                    "packets": 1000,
+                    "lost_packets": 2
+                }
+            }
+        }
+
+        exporter.parse_and_publish_metrics(udp_json, self.source, self.dest, 'udp')
+
+        self.assertEqual(exporter.IPERF_TEST_SUCCESS.labels(**self.udp_labels)._value.get(), 1)
+        self.assertAlmostEqual(exporter.IPERF_BANDWIDTH_MBPS.labels(**self.udp_labels)._value.get(), 1.6)
+        self.assertEqual(exporter.IPERF_JITTER_MS.labels(**self.udp_labels)._value.get(), 1.25)
+        self.assertEqual(exporter.IPERF_PACKETS_TOTAL.labels(**self.udp_labels)._value.get(), 1000)
+        self.assertEqual(exporter.IPERF_LOST_PACKETS.labels(**self.udp_labels)._value.get(), 2)
+        self.assertEqual(exporter.IPERF_TCP_RETRANSMITS.labels(**self.udp_labels)._value.get(), 0)
+
+    def test_parse_error_result(self):
+        err_json = {
+            "error": "error - unable to connect to server: Connection timed out"
+        }
+
+        exporter.parse_and_publish_metrics(err_json, self.source, self.dest, 'tcp')
+
+        self.assertEqual(exporter.IPERF_TEST_SUCCESS.labels(**self.labels)._value.get(), 0)
+        self.assertEqual(exporter.IPERF_BANDWIDTH_MBPS.labels(**self.labels)._value.get(), 0)
+        self.assertEqual(exporter.IPERF_TCP_RETRANSMITS.labels(**self.labels)._value.get(), 0)
+        self.assertEqual(exporter.IPERF_TCP_RTT_MS.labels(**self.labels)._value.get(), 0)
+
+    @patch("subprocess.Popen")
+    def test_stall_exception_raised_on_stall(self, mock_popen):
+        # Simulate a process that never terminates and produces no I/O progress
+        fake_proc = MagicMock()
+        fake_proc.poll.return_value = None  # Process is running
+        fake_proc.pid = 999999  # Non-existent PID to simulate no /proc IO advancement
+        mock_popen.return_value = fake_proc
+
+        with self.assertRaises(exporter.IperfTimeoutException):
+            exporter.execute_iperf_test(
+                server_ip="127.0.0.1",
+                server_port=5201,
+                protocol="tcp",
+                duration=1,
+                connect_timeout_ms=500,
+                stall_threshold_sec=1,
+            )
+
+        fake_proc.kill.assert_called()
+
+if __name__ == '__main__':
+    unittest.main()

get_helm.sh

@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+
+# Copyright The Helm Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The install script is based off of the MIT-licensed script from glide,
+# the package manager for Go: https://github.com/Masterminds/glide.sh/blob/master/get
+
+: ${BINARY_NAME:="helm"}
+: ${USE_SUDO:="true"}
+: ${DEBUG:="false"}
+: ${VERIFY_CHECKSUM:="true"}
+: ${VERIFY_SIGNATURES:="false"}
+: ${HELM_INSTALL_DIR:="/usr/local/bin"}
+: ${GPG_PUBRING:="pubring.kbx"}
+
+HAS_CURL="$(type "curl" &> /dev/null && echo true || echo false)"
+HAS_WGET="$(type "wget" &> /dev/null && echo true || echo false)"
+HAS_OPENSSL="$(type "openssl" &> /dev/null && echo true || echo false)"
+HAS_GPG="$(type "gpg" &> /dev/null && echo true || echo false)"
+HAS_GIT="$(type "git" &> /dev/null && echo true || echo false)"
+HAS_TAR="$(type "tar" &> /dev/null && echo true || echo false)"
+
+# initArch discovers the architecture for this system.
+initArch() {
+  ARCH=$(uname -m)
+  case $ARCH in
+    armv5*) ARCH="armv5";;
+    armv6*) ARCH="armv6";;
+    armv7*) ARCH="arm";;
+    aarch64) ARCH="arm64";;
+    x86) ARCH="386";;
+    x86_64) ARCH="amd64";;
+    i686) ARCH="386";;
+    i386) ARCH="386";;
+  esac
+}
+
+# initOS discovers the operating system for this system.
+initOS() {
+  OS=$(echo `uname`|tr '[:upper:]' '[:lower:]')
+
+  case "$OS" in
+    # Minimalist GNU for Windows
+    mingw*|cygwin*) OS='windows';;
+  esac
+}
+
+# runs the given command as root (detects if we are root already)
+runAsRoot() {
+  if [ $EUID -ne 0 -a "$USE_SUDO" = "true" ]; then
+    sudo "${@}"
+  else
+    "${@}"
+  fi
+}
+
+# verifySupported checks that the os/arch combination is supported for
+# binary builds, as well whether or not necessary tools are present.
+verifySupported() {
+  local supported="darwin-amd64\ndarwin-arm64\nlinux-386\nlinux-amd64\nlinux-arm\nlinux-arm64\nlinux-ppc64le\nlinux-s390x\nlinux-riscv64\nwindows-amd64\nwindows-arm64"
+  if ! echo "${supported}" | grep -q "${OS}-${ARCH}"; then
+    echo "No prebuilt binary for ${OS}-${ARCH}."
+    echo "To build from source, go to https://github.com/helm/helm"
+    exit 1
+  fi
+
+  if [ "${HAS_CURL}" != "true" ] && [ "${HAS_WGET}" != "true" ]; then
+    echo "Either curl or wget is required"
+    exit 1
+  fi
+
+  if [ "${VERIFY_CHECKSUM}" == "true" ] && [ "${HAS_OPENSSL}" != "true" ]; then
+    echo "In order to verify checksum, openssl must first be installed."
+    echo "Please install openssl or set VERIFY_CHECKSUM=false in your environment."
+    exit 1
+  fi
+
+  if [ "${VERIFY_SIGNATURES}" == "true" ]; then
+    if [ "${HAS_GPG}" != "true" ]; then
+      echo "In order to verify signatures, gpg must first be installed."
+      echo "Please install gpg or set VERIFY_SIGNATURES=false in your environment."
+      exit 1
+    fi
+    if [ "${OS}" != "linux" ]; then
+      echo "Signature verification is currently only supported on Linux."
+      echo "Please set VERIFY_SIGNATURES=false or verify the signatures manually."
+      exit 1
+    fi
+  fi
+
+  if [ "${HAS_GIT}" != "true" ]; then
+    echo "[WARNING] Could not find git. It is required for plugin installation."
+  fi
+
+  if [ "${HAS_TAR}" != "true" ]; then
+    echo "[ERROR] Could not find tar. It is required to extract the helm binary archive."
+    exit 1
+  fi
+}
+
+# checkDesiredVersion checks if the desired version is available.
+checkDesiredVersion() {
+  if [ "x$DESIRED_VERSION" == "x" ]; then
+    # Get tag from release URL
+    local latest_release_url="https://get.helm.sh/helm-latest-version"
+    local latest_release_response=""
+    if [ "${HAS_CURL}" == "true" ]; then
+      latest_release_response=$( curl -L --silent --show-error --fail "$latest_release_url" 2>&1 || true )
+    elif [ "${HAS_WGET}" == "true" ]; then
+      latest_release_response=$( wget "$latest_release_url" -q -O - 2>&1 || true )
+    fi
+    TAG=$( echo "$latest_release_response" | grep '^v[0-9]' )
+    if [ "x$TAG" == "x" ]; then
+      printf "Could not retrieve the latest release tag information from %s: %s\n" "${latest_release_url}" "${latest_release_response}"
+      exit 1
+    fi
+  else
+    TAG=$DESIRED_VERSION
+  fi
+}
+
+# checkHelmInstalledVersion checks which version of helm is installed and
+# if it needs to be changed.
+checkHelmInstalledVersion() {
+  if [[ -f "${HELM_INSTALL_DIR}/${BINARY_NAME}" ]]; then
+    local version=$("${HELM_INSTALL_DIR}/${BINARY_NAME}" version --template="{{ .Version }}")
+    if [[ "$version" == "$TAG" ]]; then
+      echo "Helm ${version} is already ${DESIRED_VERSION:-latest}"
+      return 0
+    else
+      echo "Helm ${TAG} is available. Changing from version ${version}."
+      return 1
+    fi
+  else
+    return 1
+  fi
+}
+
+# downloadFile downloads the latest binary package and also the checksum
+# for that binary.
+downloadFile() {
+  HELM_DIST="helm-$TAG-$OS-$ARCH.tar.gz"
+  DOWNLOAD_URL="https://get.helm.sh/$HELM_DIST"
+  CHECKSUM_URL="$DOWNLOAD_URL.sha256"
+  HELM_TMP_ROOT="$(mktemp -dt helm-installer-XXXXXX)"
+  HELM_TMP_FILE="$HELM_TMP_ROOT/$HELM_DIST"
+  HELM_SUM_FILE="$HELM_TMP_ROOT/$HELM_DIST.sha256"
+  echo "Downloading $DOWNLOAD_URL"
+  if [ "${HAS_CURL}" == "true" ]; then
+    curl -SsL "$CHECKSUM_URL" -o "$HELM_SUM_FILE"
+    curl -SsL "$DOWNLOAD_URL" -o "$HELM_TMP_FILE"
+  elif [ "${HAS_WGET}" == "true" ]; then
+    wget -q -O "$HELM_SUM_FILE" "$CHECKSUM_URL"
+    wget -q -O "$HELM_TMP_FILE" "$DOWNLOAD_URL"
+  fi
+}
+
+# verifyFile verifies the SHA256 checksum of the binary package
+# and the GPG signatures for both the package and checksum file
+# (depending on settings in environment).
+verifyFile() {
+  if [ "${VERIFY_CHECKSUM}" == "true" ]; then
+    verifyChecksum
+  fi
+  if [ "${VERIFY_SIGNATURES}" == "true" ]; then
+    verifySignatures
+  fi
+}
+
+# installFile installs the Helm binary.
+installFile() {
+  HELM_TMP="$HELM_TMP_ROOT/$BINARY_NAME"
+  mkdir -p "$HELM_TMP"
+  tar xf "$HELM_TMP_FILE" -C "$HELM_TMP"
+  HELM_TMP_BIN="$HELM_TMP/$OS-$ARCH/helm"
+  echo "Preparing to install $BINARY_NAME into ${HELM_INSTALL_DIR}"
+  runAsRoot cp "$HELM_TMP_BIN" "$HELM_INSTALL_DIR/$BINARY_NAME"
+  echo "$BINARY_NAME installed into $HELM_INSTALL_DIR/$BINARY_NAME"
+}
+
+# verifyChecksum verifies the SHA256 checksum of the binary package.
+verifyChecksum() {
+  printf "Verifying checksum... "
+  local sum=$(openssl sha1 -sha256 ${HELM_TMP_FILE} | awk '{print $2}')
+  local expected_sum=$(cat ${HELM_SUM_FILE})
+  if [ "$sum" != "$expected_sum" ]; then
+    echo "SHA sum of ${HELM_TMP_FILE} does not match. Aborting."
+    exit 1
+  fi
+  echo "Done."
+}
+
+# verifySignatures obtains the latest KEYS file from GitHub main branch
+# as well as the signature .asc files from the specific GitHub release,
+# then verifies that the release artifacts were signed by a maintainer's key.
+verifySignatures() {
+  printf "Verifying signatures... "
+  local keys_filename="KEYS"
+  local github_keys_url="https://raw.githubusercontent.com/helm/helm/main/${keys_filename}"
+  if [ "${HAS_CURL}" == "true" ]; then
+    curl -SsL "${github_keys_url}" -o "${HELM_TMP_ROOT}/${keys_filename}"
+  elif [ "${HAS_WGET}" == "true" ]; then
+    wget -q -O "${HELM_TMP_ROOT}/${keys_filename}" "${github_keys_url}"
+  fi
+  local gpg_keyring="${HELM_TMP_ROOT}/keyring.gpg"
+  local gpg_homedir="${HELM_TMP_ROOT}/gnupg"
+  mkdir -p -m 0700 "${gpg_homedir}"
+  local gpg_stderr_device="/dev/null"
+  if [ "${DEBUG}" == "true" ]; then
+    gpg_stderr_device="/dev/stderr"
+  fi
+  gpg --batch --quiet --homedir="${gpg_homedir}" --import "${HELM_TMP_ROOT}/${keys_filename}" 2> "${gpg_stderr_device}"
+  gpg --batch --no-default-keyring --keyring "${gpg_homedir}/${GPG_PUBRING}" --export > "${gpg_keyring}"
+  local github_release_url="https://github.com/helm/helm/releases/download/${TAG}"
+  if [ "${HAS_CURL}" == "true" ]; then
+    curl -SsL "${github_release_url}/helm-${TAG}-${OS}-${ARCH}.tar.gz.sha256.asc" -o "${HELM_TMP_ROOT}/helm-${TAG}-${OS}-${ARCH}.tar.gz.sha256.asc"
+    curl -SsL "${github_release_url}/helm-${TAG}-${OS}-${ARCH}.tar.gz.asc" -o "${HELM_TMP_ROOT}/helm-${TAG}-${OS}-${ARCH}.tar.gz.asc"
+  elif [ "${HAS_WGET}" == "true" ]; then
+    wget -q -O "${HELM_TMP_ROOT}/helm-${TAG}-${OS}-${ARCH}.tar.gz.sha256.asc" "${github_release_url}/helm-${TAG}-${OS}-${ARCH}.tar.gz.sha256.asc"
+    wget -q -O "${HELM_TMP_ROOT}/helm-${TAG}-${OS}-${ARCH}.tar.gz.asc" "${github_release_url}/helm-${TAG}-${OS}-${ARCH}.tar.gz.asc"
+  fi
+  local error_text="If you think this might be a potential security issue,"
+  error_text="${error_text}\nplease see here: https://github.com/helm/community/blob/master/SECURITY.md"
+  local num_goodlines_sha=$(gpg --verify --keyring="${gpg_keyring}" --status-fd=1 "${HELM_TMP_ROOT}/helm-${TAG}-${OS}-${ARCH}.tar.gz.sha256.asc" 2> "${gpg_stderr_device}" | grep -c -E '^\[GNUPG:\] (GOODSIG|VALIDSIG)')
+  if [[ ${num_goodlines_sha} -lt 2 ]]; then
+    echo "Unable to verify the signature of helm-${TAG}-${OS}-${ARCH}.tar.gz.sha256!"
+    echo -e "${error_text}"
+    exit 1
+  fi
+  local num_goodlines_tar=$(gpg --verify --keyring="${gpg_keyring}" --status-fd=1 "${HELM_TMP_ROOT}/helm-${TAG}-${OS}-${ARCH}.tar.gz.asc" 2> "${gpg_stderr_device}" | grep -c -E '^\[GNUPG:\] (GOODSIG|VALIDSIG)')
+  if [[ ${num_goodlines_tar} -lt 2 ]]; then
+    echo "Unable to verify the signature of helm-${TAG}-${OS}-${ARCH}.tar.gz!"
+    echo -e "${error_text}"
+    exit 1
+  fi
+  echo "Done."
+}
+
+# fail_trap is executed if an error occurs.
+fail_trap() {
+  result=$?
+  if [ "$result" != "0" ]; then
+    if [[ -n "$INPUT_ARGUMENTS" ]]; then
+      echo "Failed to install $BINARY_NAME with the arguments provided: $INPUT_ARGUMENTS"
+      help
+    else
+      echo "Failed to install $BINARY_NAME"
+    fi
+    echo -e "\tFor support, go to https://github.com/helm/helm."
+  fi
+  cleanup
+  exit $result
+}
+
+# testVersion tests the installed client to make sure it is working.
+testVersion() {
+  set +e
+  HELM="$(command -v $BINARY_NAME)"
+  if [ "$?" = "1" ]; then
+    echo "$BINARY_NAME not found. Is $HELM_INSTALL_DIR on your "'$PATH?'
+    exit 1
+  fi
+  set -e
+}
+
+# help provides possible cli installation arguments
+help () {
+  echo "Accepted cli arguments are:"
+  echo -e "\t[--help|-h ] ->> prints this help"
+  echo -e "\t[--version|-v <desired_version>] . When not defined it fetches the latest release tag from the Helm CDN"
+  echo -e "\te.g. --version v3.0.0 or -v canary"
+  echo -e "\t[--no-sudo]  ->> install without sudo"
+}
+
+# cleanup temporary files to avoid https://github.com/helm/helm/issues/2977
+cleanup() {
+  if [[ -d "${HELM_TMP_ROOT:-}" ]]; then
+    rm -rf "$HELM_TMP_ROOT"
+  fi
+}
+
+# Execution
+
+#Stop execution on any error
+trap "fail_trap" EXIT
+set -e
+
+# Set debug if desired
+if [ "${DEBUG}" == "true" ]; then
+  set -x
+fi
+
+# Parsing input arguments (if any)
+export INPUT_ARGUMENTS="${@}"
+set -u
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    '--version'|-v)
+       shift
+       if [[ $# -ne 0 ]]; then
+           export DESIRED_VERSION="${1}"
+           if [[ "$1" != "v"* ]]; then
+               echo "Expected version arg ('${DESIRED_VERSION}') to begin with 'v', fixing..."
+               export DESIRED_VERSION="v${1}"
+           fi
+       else
+           echo -e "Please provide the desired version. e.g. --version v3.0.0 or -v canary"
+           exit 0
+       fi
+       ;;
+    '--no-sudo')
+       USE_SUDO="false"
+       ;;
+    '--help'|-h)
+       help
+       exit 0
+       ;;
+    *) exit 1
+       ;;
+  esac
+  shift
+done
+set +u
+
+initArch
+initOS
+verifySupported
+checkDesiredVersion
+if ! checkHelmInstalledVersion; then
+  downloadFile
+  verifyFile
+  installFile
+fi
+testVersion
+cleanup

mise.toml

@@ -0,0 +1,17 @@
+[tools]
+python = "3.12"
+uv = "latest"
+helm = "3.17.3"
+yq = "latest"
+
+[tasks.test]
+description = "Run exporter unit tests"
+run = "uv run --with-requirements exporter/requirements.txt python -m unittest discover -s exporter -p 'test_*.py'"
+
+[tasks."chart:build"]
+description = "Build Helm chart dependencies"
+run = "helm dependency build ./charts/iperf3-monitor"
+
+[tasks."chart:lint"]
+description = "Lint Helm chart"
+run = "helm lint ./charts/iperf3-monitor"