Refactoring the KoboToolbox Helm Chart: A Practical Guide to Cleaner, Maintainable Kubernetes Deployments

By Stephen Oduor

💬 Acknowledgment

Before we dive into technical recommendations, it’s important to appreciate the incredible work that the KoboToolbox core team and the wider open-source community working on the helm chart.

This article proposes incremental, maintainability-focused refinements that modern Helm practices make possible today.

Why This Refactor Matters

This article provides an in-depth analysis of the KoboToolbox Helm Chart (v5.2.2) and proposes specific areas for refactoring. The objective is to:

• Reduce code duplication
• Improve maintainability
• Increase consistency across chart components

Each suggestion includes a Deep Dive Explanation detailing rationale and impact.

1. Major Redundancy in kpi Workloads

Observation

Multiple templates define nearly identical container specs for different kpi workloads:

templates/kpi/deployment.yaml
templates/kpi/deployment-worker.yaml
templates/kpi/deployment-worker-kobocat.yaml
templates/kpi/deployment-worker-low-priority.yaml
templates/kpi/deployment-beat.yaml
templates/kpi/migration-job.yaml
templates/kpi/post-install-job.yaml

Each uses the same image and environment variables, differing only by their command definitions. Updating environment variables currently requires manual edits across all seven files.

Refactor Suggestion

Create a centralized helper in templates/_helpers.tpl defining the common container spec.

Proposed Helper: templates/_helpers.tpl

{{/*
Defines the common container spec for all kpi workloads.
*/}}
{{- define "kobo.kpi.containerSpec" -}}
securityContext:
{{- toYaml .Values.securityContext | nindent 10 }}
image: "{{ .Values.kpi.image.repository }}:{{ required "kpi.version required" .Values.kpi.version }}"
imagePullPolicy: {{ .Values.kpi.image.pullPolicy }}
env:
- name: POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
{{- if .Values.postgresql.enabled }}
- name: POSTGRES_PASSWORD
valueFrom:
secretKeyRef:
name: {{ default (include "kobo.postgresql.fullname" .) .Values.postgresql.auth.existingSecret }}
key: postgres-password
- name: DATABASE_URL
value: {{ (include "kobo.postgresql.url" .) }}
- name: KC_DATABASE_URL
value: {{ (include "kobo.postgresql.kc_url" .) }}
{{- end }}
{{- if .Values.mongodb.enabled }}
- name: MONGO_DB_URL
value: {{ (include "kobo.mongodb.url" .) }}
{{- end }}
{{- if .Values.redis.enabled }}
- name: CELERY_BROKER_URL
value: {{ (include "kobo.redis.url" .) }}/2
{{- end }}
envFrom:
- secretRef:
name: {{ include "kobo.fullname" . }}-kpi
- configMapRef:
name: {{ include "kobo.fullname" . }}-kpi
{{- with .Values.kpi.extraVolumeMounts }}
volumeMounts:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- end -}}

Example Usage (in deployment-worker.yaml)

Before:

containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.kpi.image.repository }}:{{ .Values.kpi.version }}"
# ... repeated env vars ...

After:

containers:
- name: {{ .Chart.Name }}
{{- include "kobo.kpi.containerSpec" . | nindent 10 }}
command: ["celery", "-A", "kobo", "worker", "--queues", "kpi_queue", "-l", "info"]
resources:
{{- toYaml .Values.kpi.worker.resources | nindent 12 }}

Deep Dive Explanation

• Why DRY matters: Over 30 duplicated environment variables across 7 templates.
• Risk: Configuration drift — missing or outdated variables can break migrations.
• Benefit: Centralized contract for all kpi workloads ensures consistency and ease of updates.

2. Redundancy in Horizontal Pod Autoscalers (HPA)

Observation: Five nearly identical HPA templates differ only in the target name and values path.

Refactor Suggestion: Define a generic HPA helper in _helpers.tpl and call it from all HPA templates.

Proposed Helper: templates/_helpers.tpl

{{/*
Creates a generic HPA resource.
*/}}
{{- define "kobo.common.hpa" -}}
{{- if .values.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: {{ .targetName }}
labels:
{{- include "kobo.labels" .context | nindent 4 }}
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: {{ .targetName }}
minReplicas: {{ .values.minReplicas }}
maxReplicas: {{ .values.maxReplicas }}
metrics:
{{- if .values.targetCPU }}
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: {{ .values.targetCPU }}
{{- end }}
{{- if .values.targetMemory }}
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: {{ .values.targetMemory }}
{{- end }}
{{- end }}
{{- end -}}

Example Usage:

{{- $targetName := printf "%s-%s" (include "kobo.fullname" .) "kpi-worker" -}}
{{- include "kobo.common.hpa" (dict "targetName" $targetName "values" .Values.kpi.worker.autoscaling "context" .) -}}

Explanation

• Reduces clutter: Eliminates redundant HPA files.
• Extensible: Easy to add new autoscaling targets.
• Consistent: Ensures uniform HPA configuration across components.

3. Inconsistent/Conflicting Redis Configuration

Observation

Two conflicting Redis configuration methods exist:

• Sub-chart (.Values.redis.enabled) – Preferred pattern.
• Direct values (.Values.kobotoolbox.redis) – Deprecated and confusing.

This causes duplicate and conflicting env vars (e.g., CELERY_BROKER_URL).

Refactor Suggestion

• Standardize on the sub-chart method.
• Remove Redis logic from templates/kpi/secrets.yaml and templates/enketo/secrets.yaml.
• Delete deprecated kobotoolbox.redis keys from values.yaml.

Explanation

• Problem: Duplicate Redis env vars, unclear precedence.
• Fix: One clear configuration path via redis.enabled.
• Outcome: Simplified, predictable Redis configuration.

4. Inconsistent Job Environments

Observation

migration-job.yaml and post-install-job.yaml lack the envFrom section, causing missing environment variables.

Refactor Suggestion

Adopt the centralized container spec (kobo.kpi.containerSpec) for all jobs and deployments.

Explanation

Issue: Jobs run without ENKETO_API_KEY, KOBOFORM_URL, etc.

Impact: Potential migration failures.

Solution: Centralize env setup across all workloads.

5. Deprecated Values in values.yaml

Observation

kobocat.ingress block still exists but is unused since version 4.0.0.

**Refactor Suggestion:** Remove the entire kobocat block from values.yaml.

Explanation

Why: Avoid user confusion; block is no longer referenced.

Benefit: Clean, accurate values.yaml that reflects current chart behavior.

Overall Impact: These refactors will reduce maintenance time, improve readability, and ensure future upgrades to the KoboToolbox Helm chart are safer and easier to manage.