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,longhornby 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 / 10failures 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 | {} |