helm-workload

A general-purpose Kubernetes workload Helm chart with batteries included. Deploy any container image as a Deployment or StatefulSet with optional addon sidecars for VPN, PostgreSQL, and Cloudflare Tunnel.

Prerequisites

• Kubernetes 1.26+
• Helm 3.x

Installation

From OCI Registry

helm install my-release oci://ghcr.io/temikus/helm-charts/workload --version 1.8.0

From Source

git clone https://github.com/Temikus/helm-workload.git
cd helm-workload
helm install my-release .

With Helmfile (recommended)

releases:
  - name: my-app
    namespace: my-namespace
    chart: oci://ghcr.io/temikus/helm-charts/workload
    version: 1.8.0
    values:
      - image:
          repository: nginx
          tag: stable
        ports:
          - name: http
            port: 80
            service:
              enabled: true
              port: 80

Examples

Simple container

image:
  repository: quay.io/curl/curl
  tag: latest
command: ["sleep", "infinity"]

Web application with Ingress and persistence

image:
  repository: homebridge/homebridge
  tag: "2024-01-08"

ports:
  - name: http
    port: 8581
    service:
      enabled: true
      port: 8581

persistence:
  enabled: true
  type: statefulset
  storageClassName: longhorn-retained
  mountPath: /homebridge
  accessModes:
    - ReadWriteOnce
  size: 5Gi

ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: traefik
    cert-manager.io/cluster-issuer: letsencrypt-production
  hosts:
    - host: homebridge.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: homebridge-tls
      hosts:
        - homebridge.example.com

Configuration

All configuration is done through values.yaml. See the file for full documentation of each field, or use helm show values oci://ghcr.io/temikus/helm-charts/workload.

Key Configuration Areas

Parameter	Description	Default
image.repository	Container image repository	nginx
image.tag	Container image tag	latest
replicaCount	Number of replicas	1
ports	List of container/service port definitions	[]
persistence.enabled	Enable persistent storage	false
ingress.enabled	Enable Ingress resource	false
autoscaling.enabled	Enable HorizontalPodAutoscaler (autoscaling/v2)	false
hostNetwork.enabled	Enable host networking	false
strategy	Rollout strategy (RollingUpdate/Recreate for Deployment; RollingUpdate/OnDelete for StatefulSet)	{}
networkPolicy.enabled	Create a NetworkPolicy restricting ingress traffic	false
extraServices	Additional multi-port Service resources alongside port-derived services	[]

Addons

Addon sidecars are injected into the pod alongside your main container. All addons are disabled by default.

Init Container (addons.init)

Run an init container before the main application starts.

addons:
  init:
    enabled: true
    image:
      repository: busybox
      tag: latest
    command: ["sh", "-c", "echo initializing"]

VPN (addons.vpn)

Adds a Gluetun VPN sidecar. Supports OpenVPN and WireGuard with multiple providers.

addons:
  vpn:
    enabled: true
    provider:
      name: mullvad
      type: wireguard
    wireguard:
      privateKey: ""        # or use existingSecret
    config:
      timezone: UTC
      serverSelection:
        countries: Sweden

PostgreSQL (addons.postgres)

Adds a PostgreSQL sidecar with persistent storage. Useful for applications that need a dedicated database.

addons:
  postgres:
    enabled: true
    auth:
      username: myapp
      password: secret      # or use existingSecret
      database: myapp_db
    persistence:
      enabled: true
      size: 8Gi

Cloudflare Tunnel (addons.cloudflareTunnel)

Exposes your service through a Cloudflare Tunnel using the cloudflare-operator. Requires the operator to be installed in your cluster.

addons:
  cloudflareTunnel:
    enabled: true
    fqdn: myapp.example.com
    protocol: http
    targetPort: 8080
    tunnelRef:
      kind: ClusterTunnel
      name: my-cluster-tunnel

Supports optional path filtering (nginx sidecar proxy) and NetworkPolicy for defense-in-depth.

Rollout Strategy (strategy)

Configure the rollout strategy for Deployments or StatefulSets. The same strategy value is used for both — it maps to spec.strategy on Deployments and spec.updateStrategy on StatefulSets.

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 0
    maxSurge: 1

NetworkPolicy (networkPolicy)

Create a Kubernetes NetworkPolicy to restrict ingress traffic to the pod.

networkPolicy:
  enabled: true
  # Allow ingress on all ports from .Values.ports (default). Set false for deny-all.
  allowPortsIngress: true
  # Or specify explicit ingress rules:
  ingress:
    - ports:
        - port: 80
          protocol: TCP
      from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: monitoring

Extra Services (extraServices)

Create additional Service resources with custom port mappings (e.g. for UDP discovery protocols or mixed-type services).

extraServices:
  - name: device-mgmt
    type: LoadBalancer
    ports:
      - name: discovery
        port: 29810
        targetPort: discovery
        protocol: UDP
      - name: manager
        port: 29811
        targetPort: manager

Known Limitations

• appVersion is not dynamically set from the image tag; it mirrors the chart version.

Development

Prerequisites

• Helm 3.x
• helm-unittest plugin
• just (optional, for task automation)

Commands

just lint          # Lint the chart
just test          # Run unit tests
just test -u       # Update test snapshots
just build         # Package the chart

Or without just:

helm lint .
helm unittest .

License

Apache License 2.0 - see LICENSE for details.