Bahriya Tersane

Documentation / khadim

Khadim

A lean Helm chart for deploying worker and daemon containers on Kubernetes. Khadim (Arabic for “servant”) is designed for non-HTTP workloads: queue workers, background processors, cron consumers, and long-running daemons.

Unlike Safeena (which includes ingress, Kong plugins, and TLS certificates), Khadim has no networking by default — no Ingress, no Kong, no cert-manager. It deploys a Deployment with optional Service, HPA, and health probes.

Prerequisites

  • Kubernetes 1.23+
  • Helm 3.x
  • A StorageClass for persistentVolumes, if used: persistentVolumesStorageClass, longhorn by default

Architecture

┌─────────────────────────────────┐
│         Deployment              │
│  ┌───────────┐ ┌───────────┐   │
│  │  worker-0  │ │  worker-1  │  │    (replicas controlled by replicaCount or HPA)
│  └───────────┘ └───────────┘   │
└─────────────────────────────────┘
         │ (optional)
    ┌────▼────┐
    │ Service │   (only when service.enabled = true, e.g., for health check endpoints)
    └─────────┘
  • Each pod runs your worker image as PID 1.
  • No ingress or external access by default.
  • Pods are spread across nodes via topologySpreadConstraints (built-in, maxSkew: 1, ScheduleAnyway).
  • Optional Service for exposing a health check port (e.g., for liveness probes or internal monitoring).

Installation

# Basic worker
helm install my-worker charts/khadim \
  --set image.repository=my-registry/my-worker \
  --set image.tag=v1.2.3

# With a fixed resource name, independent of the release name
helm install my-worker charts/khadim \
  --set fullnameOverride=my-worker \
  --set image.repository=my-registry/my-worker \
  --set image.tag=v1.2.3

# With multiple replicas and autoscaling
helm install my-worker charts/khadim \
  --set image.repository=my-registry/my-worker \
  --set image.tag=v1.2.3 \
  --set autoscaling.enabled=true \
  --set autoscaling.minReplicas=2 \
  --set autoscaling.maxReplicas=10 \
  --set autoscaling.targetCPUUtilizationPercentage=70

Configuration

Environment variables

Inject environment variables directly or from Kubernetes Secrets/ConfigMaps:

env:
  - name: APP_ENV
    value: production
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: my-db-credentials
        key: password

envFrom:
  - secretRef:
      name: my-app-secrets
  - configMapRef:
      name: my-app-config

Volumes and volume mounts

Mount ConfigMaps, Secrets, PVCs, or emptyDirs into the worker container:

volumes:
  - name: config
    configMap:
      name: my-worker-config
  - name: tmp
    emptyDir: {}

volumeMounts:
  - name: config
    mountPath: /etc/my-worker
    readOnly: true
  - name: tmp
    mountPath: /tmp

Health probes

Probes are disabled by default since many workers don’t expose HTTP endpoints. Enable them when your worker has a health check:

service:
  enabled: true
  port: 8080

probes:
  enabled: true
  path: /healthz
  port: http
  bootstraptime: 30    # seconds to wait before failing startup probe

When probes are enabled:

  • A startup probe polls the health endpoint every 10 seconds, allowing up to bootstraptime / 10 failures before killing the pod.
  • A liveness probe continues checking after startup succeeds.
  • The Service must also be enabled to expose the health check port.

Autoscaling

Horizontal Pod Autoscaler based on CPU and/or memory utilisation:

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80    # optional

When autoscaling is enabled, the replicaCount value is ignored — the HPA manages replica count.

Pod topology spread

Khadim includes a built-in topologySpreadConstraints rule that spreads pods across nodes (maxSkew: 1, ScheduleAnyway). This is not configurable — it’s always applied to avoid hotspotting worker pods on a single node.

Connecting to MySQL with TLS

When a MySQL instance deployed with the mysql chart has TLS enabled, the MySQL chart publishes the CA certificate as a ConfigMap named <mysql-release>-tls-ca. Workers deployed via Khadim can mount this ConfigMap to verify the MySQL server’s identity and establish encrypted connections.

volumes:
  - name: mysql-ca
    configMap:
      name: my-db-tls-ca          # <mysql-release>-tls-ca

volumeMounts:
  - name: mysql-ca
    mountPath: /etc/mysql-tls
    readOnly: true

env:
  - name: MYSQL_SSL_CA
    value: /etc/mysql-tls/ca.crt

The worker then reads the MYSQL_SSL_CA environment variable and passes it to its MySQL driver. See the MySQL chart README for driver-specific examples (PHP/Kipchak, Node.js, Python, Go).

Pod Security

The chart runs the image you supply, so it sets no security context by default. With the defaults, the Pod meets the Kubernetes baseline Pod Security Standard, provided the image itself needs no extra privileges.

To meet restricted, the image must run as a user other than root, and the following values must be set. Use the user and group IDs the image expects:

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 10001
  runAsGroup: 10001
  fsGroup: 10001
  seccompProfile:
    type: RuntimeDefault

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL

An image that starts as root and changes user itself does not start under these values; use an unprivileged variant of it. fsGroup gives the user write access to the volumes in persistentVolumes. When these values are added to a release that already has data on its volumes, the files keep their previous owner and are made writable through the group on the next start.

Examples

Queue worker

fullnameOverride: "billing-worker"
image:
  repository: registry.example.com/acme/queue-workers
  tag: "v1.5.0"
replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 256Mi
env:
  - name: WORKER_QUEUE
    value: billing
envFrom:
  - secretRef:
      name: billing-worker-env

Worker with health check and autoscaling

fullnameOverride: "email-sender"
image:
  repository: my-registry/email-sender
  tag: "v1.4.0"
service:
  enabled: true
  port: 8080
probes:
  enabled: true
  path: /healthz
  port: http
  bootstraptime: 60
autoscaling:
  enabled: true
  minReplicas: 1
  maxReplicas: 5
  targetCPUUtilizationPercentage: 80
resources:
  limits:
    cpu: "1"
    memory: 1Gi
  requests:
    cpu: 250m
    memory: 512Mi

Worker with MySQL TLS and Secrets

fullnameOverride: "data-processor"
image:
  repository: my-registry/data-processor
  tag: "v2.0.0"
replicaCount: 3
env:
  - name: DB_HOST
    value: my-db
  - name: MYSQL_SSL_CA
    value: /etc/mysql-tls/ca.crt
envFrom:
  - secretRef:
      name: data-processor-env
volumes:
  - name: mysql-ca
    configMap:
      name: my-db-tls-ca
volumeMounts:
  - name: mysql-ca
    mountPath: /etc/mysql-tls
    readOnly: true
resources:
  limits:
    cpu: "2"
    memory: 2Gi
  requests:
    cpu: 500m
    memory: 1Gi

Parameters

Image

Parameter Description Default
image.repository Container image repository. Required ""
image.tag Container image tag. Required Set in each release
image.pullPolicy Image pull policy IfNotPresent
imagePullSecrets Image pull secrets [{name: 1x-ax}]

Deployment

Parameter Description Default
replicaCount Number of replicas (ignored when autoscaling is enabled) 1
nameOverride Override the chart name ""
fullnameOverride Override the full release name ""
podAnnotations Additional pod annotations {}
podLabels Additional pod labels {}
podSecurityContext Pod-level security context {}
securityContext Container-level security context {}

Service

Parameter Description Default
service.enabled Create a ClusterIP Service false
service.type Service type ClusterIP
service.port Service port 8080

Probes

Parameter Description Default
probes.enabled Enable startup and liveness probes false
probes.path HTTP path for health checks /healthz
probes.port Port name for health checks http
probes.bootstraptime Seconds to wait for startup before failing 30

Resources

Parameter Description Default
resources.limits.cpu CPU limit 100m
resources.limits.memory Memory limit 256Mi
resources.requests.cpu CPU request 20m
resources.requests.memory Memory request 64Mi

Autoscaling

Parameter Description Default
autoscaling.enabled Enable HPA false
autoscaling.minReplicas Minimum replicas 1
autoscaling.maxReplicas Maximum replicas 3
autoscaling.targetCPUUtilizationPercentage CPU target for scaling 100
autoscaling.targetMemoryUtilizationPercentage Memory target for scaling (optional) —

Environment

Parameter Description Default
env Environment variables for the container []
envFrom Environment variable sources (Secrets, ConfigMaps) []
persistentVolumes Volumes {name, mountPath, sizeGb}, optionally with storageClass; when set, the chart renders a StatefulSet with one claim per volume []
persistentVolumesStorageClass StorageClass of the volumes in persistentVolumes; empty uses the cluster’s default. Set it before the first install with volumes, because a StatefulSet’s claims cannot change longhorn
volumes Additional volumes []
volumeMounts Additional volume mounts []

Service account

Parameter Description Default
serviceAccount.create Create a ServiceAccount false
serviceAccount.automount Auto-mount API credentials true
serviceAccount.annotations ServiceAccount annotations {}
serviceAccount.name ServiceAccount name (auto-generated if empty) ""

Scheduling

Parameter Description Default
nodeSelector Node selector labels {}
tolerations Pod tolerations []
affinity Pod affinity rules {}