chore(mise): pin tool versions with explicit backends

`uv` and `yq` were `latest`, and helm was declared at 3.17.3 while
ci.yaml installs v3.10.0 — so `mise run chart:lint` and the pipeline were
validating two different helm versions, and nothing said so.

Each tool is pinned on an explicit backend and checked by running it
rather than by trusting version resolution: Python 3.12.13, uv 0.13.1,
helm v3.17.3+ge4da497, yq v4.54.1.

`aqua:` for helm, yq and uv, matching the other repos in this workspace.
The `github:` backend cannot name the yq binary `yq` at all on the mise
version this repo pins, and it mis-extracts helm 3.17.x — writing the
833-byte .asc PGP signature to
installs/github-helm-helm/3.17.x/helm, with attestation and SLSA
verification both logging as passing.

helm stays on 3.17.3, matching what mise.toml already declared for the
chart. That this file and ci.yaml disagree about the version is now the
only remaining gap, and it is in the workflow, not here.

The three mise tasks parse unchanged.

.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 (`controllers.exporter`)
+# The iperf3 exporter is managed under the `controllers.exporter` section,
+# leveraging the `bjw-s/common-library` for robust workload management.
+controllers:
   exporter:
-  # -- Configuration for the exporter container image.
+    # -- Enable the exporter controller.
-  image:
+    enabled: true
-    # -- The container image repository for the exporter.
+    # -- Set the controller type for the exporter.
-    repository: ghcr.io/malarinv/iperf3-monitor
+    # Valid options are "deployment" or "daemonset".
-    # -- The container image tag for the exporter. If not set, the chart's appVersion is used.
+    # Use "daemonset" for N-to-N node monitoring where an exporter runs on each node (or selected nodes).
-    tag: ""
+    # Use "deployment" for a centralized exporter (typically with replicaCount: 1).
-    # -- The image pull policy for the exporter container.
+    # @default -- "deployment"
-    pullPolicy: IfNotPresent
+    type: deployment
-
+    # -- Number of desired exporter pods. Only used if type is "deployment".
-  # -- Number of exporter pod replicas. Typically 1 is sufficient.
+    # @default -- 1
-  replicaCount: 1
+    replicas: 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'
 
-  # -- CPU and memory resource requests and limits for the exporter pod.
+    # -- Pod-level configurations for the exporter.
-  # @default -- A small default is provided if commented out.
+    pod:
-  resources: {}
+      # -- 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
+
+    # -- 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
+  version: 91.5.3
-- name: prometheus-operator
+- name: common
-  repository: oci://tccr.io/truecharts
+  repository: https://bjw-s-labs.github.io/helm-charts/
-  version: 11.5.1
+  version: 4.1.2
-digest: sha256:3000e63445f8ba8df601cb483f4f77d14c5c4662bff2d16ffcf5cf1f7def314b
+digest: sha256:a3a063101484521564d3e8922c1c1fe7ae8040fe28c2ae246a40d0c00b860e65
-generated: "2025-06-20T17:25:44.538372209+05:30"
+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"
+    condition: "dependencies.install, serviceMonitor.enabled"
-  - name: prometheus-operator
+  - name: common
-    version: ">=8.11.1"
+    version: "4.1.2"
-    repository: "oci://tccr.io/truecharts"
+    repository: "https://bjw-s-labs.github.io/helm-charts/"
-    condition: "dependencies.install, serviceMonitor.enabled, dependencies.useTrueChartsPrometheusOperator"

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/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
+    - name: metrics # Assuming 'metrics' is the intended name, aligns with values structure
-      port: {{ .Values.service.port }}
+      port: {{ .Values.service.main.ports.metrics.port }}
-      targetPort: {{ .Values.service.targetPort }}
+      targetPort: {{ .Values.service.main.ports.metrics.targetPort }}
-      protocol: TCP
+      protocol: {{ .Values.service.main.ports.metrics.protocol | default "TCP" }}

charts/iperf3-monitor/values.yaml

@@ -8,33 +8,102 @@ nameOverride: ""
 # -- Override the fully qualified app name.
 fullnameOverride: ""
 
+controllers:
   exporter:
-  # -- Configuration for the exporter container image.
+    # -- 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
+
+    # -- 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'
+
+
+    # -- 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
+
+    # -- 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: ""
+          tag: "" # Defaults to .Chart.AppVersion via common library
           # -- The image pull policy for the exporter container.
           pullPolicy: IfNotPresent
 
-  # -- Number of exporter pod replicas. Typically 1 is sufficient.
+        # -- Environment variables for the exporter container.
-  replicaCount: 1
+        # 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
 
-  # -- Interval in seconds between complete test cycles (i.e., testing all server nodes).
+        # -- Ports for the exporter container.
-  testInterval: 300
+        # 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
 
-  # -- Log level for the iperf3 exporter (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        # -- CPU and memory resource requests and limits for the exporter container.
-  logLevel: INFO
-
-  # -- 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:
@@ -44,6 +113,16 @@ exporter:
           #   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).
+  # -- Tolerations for scheduling iperf3 server pods on tainted 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"
@@ -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.
+  # -- The name of the ServiceAccount to use/create for the exporter pod.
-  # Only used if rbac.create is false. If not set, it defaults to the chart's fullname.
+  # 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.
+  # -- If true, create a ServiceMonitor resource.
-  # Requires a running Prometheus Operator in the cluster.
   enabled: true
-
+  # -- Scrape interval for the ServiceMonitor.
-  # -- Scrape interval for the ServiceMonitor. How often Prometheus scrapes the exporter metrics.
   interval: 60s
-
+  # -- Scrape timeout for the ServiceMonitor.
-  # -- Scrape timeout for the ServiceMonitor. How long Prometheus waits for metrics response.
   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.
+  main: # A key for the service, 'main' is a common convention.
-  type: ClusterIP
+    # -- Enable the exporter service.
-  # -- Port on which the exporter service is exposed.
+    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.
+        # -- Target port on the exporter pod. Can be a number or name.
-  targetPort: 9876
+        # 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.
+# Network Policy (optional)
-# 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).
+  # -- 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 (for Prometheus Operator)
-# Dependency Configuration
-# -----------------------------------------------------------------------------
 dependencies:
-  # -- Set to true to install Prometheus operator dependency if serviceMonitor.enabled is also true.
+  # -- Set to false by default. Set to true to install a Prometheus operator dependency (used if serviceMonitor.enabled=true).
-  # -- Set to false to disable the installation of Prometheus operator dependency,
+  # -- If false (default), and serviceMonitor.enabled is true, you must have a compatible Prometheus Operator already running in your cluster.
-  # -- regardless of serviceMonitor.enabled. This is useful if you have Prometheus
+  install: false
-  # -- 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

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,34 +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
 
-# Minimal dependencies for builder stage if any Python packages had C extensions.
-# Assuming requirements.txt does not need gcc or other build tools for now.
-# If pip install fails later, add necessary build tools (e.g., gcc, python3-dev) here.
-RUN apt-get update &&
-    # apt-get install -y --no-install-recommends gcc python3-dev # Example if needed
-    rm -rf /var/lib/apt/lists/*
-
 # 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
 
-# Install iperf3 and its runtime dependency libsctp1 directly in the final stage.
+# Install iperf3
-# This simplifies the Dockerfile by removing the need to copy iperf3 components from the builder.
+RUN apt-get update && \
-RUN apt-get update &&
+    apt-get install -y --no-install-recommends iperf3 && \
-    apt-get install -y --no-install-recommends iperf3 libsctp1 &&
     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 .
@@ -36,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"]
+

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.
+    Executes the iperf3 CLI in a subprocess with JSON output and active stall detection.
-
-    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).
     """
-    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()
+    cmd = [
-    iperf_client.server_hostname = server_ip
+        "iperf3",
-    iperf_client.port = server_port
+        "-c", server_ip,
-    iperf_client.protocol = protocol
+        "-p", str(server_port),
-    iperf_client.duration = int(os.getenv('IPERF_TEST_DURATION', 5)) # Test duration in seconds
+        "-t", str(duration),
-    iperf_client.json_output = True # Enables easy parsing of results
+        "--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()
+        while proc.poll() is None:
-        parse_and_publish_metrics(result, source_node_name, dest_node_name, protocol)
+            if shutdown_requested:
-    except Exception as e:
+                proc.kill()
-        # Catch unexpected errors during client.run() or parsing
+                proc.wait()
-        logging.error(f"Exception during iperf3 test or metric parsing for {dest_node_name}: {e}")
+                raise KeyboardInterrupt("Shutdown requested")
-        labels = {'source_node': source_node_name, 'destination_node': dest_node_name, 'protocol': protocol}
+
+            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)
+            g.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)
         except KeyError:
-            logging.debug(f"KeyError setting failure metrics for {labels} after client.run() exception.")
+            pass
 
-
+# --- Metric Parsing ---
-def parse_and_publish_metrics(result, source_node, dest_node, protocol):
+def parse_and_publish_metrics(data, source_node, dest_node, protocol):
     """
-    Parses the iperf3 test result and updates Prometheus gauges.
+    Parses iperf3 JSON 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').
     """
     labels = {'source_node': source_node, 'destination_node': dest_node, 'protocol': protocol}
 
-    # Handle failed tests (e.g., server unreachable) or missing result object
+    if not data or not isinstance(data, dict):
-    if not result or result.error:
+        logging.warning(f"Test from {source_node} to {dest_node} ({protocol.upper()}) failed: empty or invalid result")
-        error_message = result.error if result and result.error else "No result object from iperf3 client"
+        reset_failure_metrics(labels)
-        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.")
         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:
+    sum_received = end.get("sum_received") or {}
-    # Order of preference: received_Mbps, sent_Mbps, Mbps, then JSON fallbacks.
+    sum_sent = end.get("sum_sent") or {}
-    # received_Mbps is often most relevant for TCP client perspective.
+    sum_udp = end.get("sum") or {}
-    # 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
 
-    IPERF_BANDWIDTH_MBPS.labels(**labels).set(bandwidth_mbps)
+    bandwidth_mbps = 0.0
 
-    # UDP specific metrics
+    if protocol == 'tcp':
-    if protocol == 'udp':
+        if "bits_per_second" in sum_received and sum_received["bits_per_second"] is not None:
-        # These attributes are specific to UDP tests in iperf3
+            bandwidth_mbps = sum_received["bits_per_second"] / 1_000_000.0
-        IPERF_JITTER_MS.labels(**labels).set(getattr(result, 'jitter_ms', 0) if result.jitter_ms is not None else 0)
+        elif "bits_per_second" in sum_sent and sum_sent["bits_per_second"] is not None:
-        IPERF_PACKETS_TOTAL.labels(**labels).set(getattr(result, 'packets', 0) if result.packets is not None else 0)
+            bandwidth_mbps = sum_sent["bits_per_second"] / 1_000_000.0
-        IPERF_LOST_PACKETS.labels(**labels).set(getattr(result, 'lost_packets', 0) if result.lost_packets is not None else 0)
+
-    else:
+        # TCP Retransmits
-        # For TCP tests, ensure UDP-specific metrics are set to 0
+        retransmits = sum_sent.get("retransmits", 0)
-        try:
+        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)
-        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 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)
+
+# --- 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,
+                )
 
+        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.")
-        time.sleep(test_interval)
+            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
+prometheus-client>=0.20.0
-iperf3
+kubernetes>=29.0.0
-kubernetes

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,25 @@
+# Backends named and versions exact: `uv` and `yq` were `latest`, and `helm`
+# was a floating major-less spec that CI did not share — ci.yaml installs
+# v3.10.0 while this file declared 3.17.3, so local `mise run chart:lint` and
+# the pipeline that runs it were validating two different helm versions.
+#
+# `aqua:` for helm and yq, matching the other repos in this workspace. The
+# `github:` backend cannot name the yq binary `yq` at all on the mise version
+# this repo pins, and it mis-extracts helm 3.17.x.
+[tools]
+"core:python" = "3.12"
+"aqua:astral-sh/uv" = "0.13.1"
+"aqua:helm/helm" = "3.17.3"
+"aqua:mikefarah/yq" = "4.54.1"
+
+[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"