Helm architecture

Why one Helm chart is enough

Reuse one chart and separate values files instead of copying Deployment, Service, and HTTPRoute templates into every service repo.

Chart fidelity

Examples below match Universal Helm Chart application 0.4.3 keys from values.yaml and docs/configuration.md. Replace ghcr.io/example-org/* images and hostnames with your own.

Chart 0.4.3 — `args` / multi-port / `service.enabled`

From application 0.4.3: main container args (default []); Deployment revisionHistoryLimit (default 10); multi-port via containerPorts and service.ports; optional chart-managed Service via service.enabled (default true). When service.ports is set, Ingress / simple HTTPRoute / NOTES use the first entry (templates/_helpers.tpl application.servicePort). Legacy single-port service.name / service.port / service.protocol / service.appProtocol remain supported. Set service.enabled: false when the workload does not need a chart-managed Service. Do not invent other port keys.

Chart 0.4.3 — `service.appProtocol`

Optional service.appProtocol (default "") sets Service.spec.ports[].appProtocol on the chart-managed Service (templates/7_service.yaml). For Services created by ingressPlain paths with createService: true, set paths[].service.appProtocol (since 0.4.0). Leave empty when you do not need a protocol hint (for example grpc). Do not invent other service.* protocol keys.

The duplication tax

A typical microservice chart repeats the same objects: Deployment, Service, probes, resources, ServiceAccount, optional Ingress or HTTPRoute, ConfigMap mounts, and secret env wiring. When each team forks a chart, upgrades (securityContext defaults, probe ports, label conventions) land as N pull requests instead of one chart bump.

Universal Helm Chart keeps those templates in helm-charts/application/templates/ and exposes application intent through values.yaml.

Map intent to values, not forks

Per service you usually change:

image / imageTag / imagePullPolicy (defaults: nginx, latest, Always)
replicaCount (default 1)
service.port (default 80; Service port name default http; optional service.appProtocol since 0.4.1)
env, envFrom, envSecrets, configMaps
resources, livenessProbe, readinessProbe
route.* for Gateway API or ingress.* for classic Ingress

The chart still models Kubernetes directly—you are not learning a proprietary DSL. You stop maintaining N copies of deployment.yaml.

# service-a/values.yaml
replicaCount: 2
image: ghcr.io/example-org/service-a
imageTag: "1.4.2"
imagePullPolicy: IfNotPresent
service:
  port: 8080
readinessProbe:
  httpGet:
    path: /ready
    port: http
route:
  enabled: true
  gateway: external
  gatewayNamespace: gateway-system
  sectionName: https
  hostname: service-a.example.com

Same chart, different values file for service-b. GitOps (Argo CD Application pointing at universal/application + path to values) upgrades the chart version once across the fleet.

What one chart standardizes

Labels/selectors via chart helpers (application.fullname, application.labels)
Optional serviceMonitor (enabled: false by default) for Prometheus Operator
Gateway API HTTPRoute via route (disabled by default; route.gateway required when enabled)
Init/sidecar patterns via initContainers / extraContainers
Escape hatches: extraManifests, extraDeployments, job / cronjob

When a dedicated chart is still better

Keep (or write) a dedicated chart when:

The workload needs specialized CRDs or multi-component operators the values model does not cover cleanly
Teams must own template logic (custom controllers, unusual networking) rather than values
The deployment shape diverges enough that extraManifests becomes an unreadable second chart

That boundary is documented upstream in docs/why-this-chart.md.

Verify reuse locally

Install the chart once

helm repo add universal https://chaser100.github.io/u-helm-chart
helm repo update
helm search repo universal/application --versions

Package: Artifact Hub · universal-helm-chart/application.

helm template service-a universal/application --version 0.4.3 -f service-a/values.yaml | head
helm upgrade --install service-a universal/application --version 0.4.3 \
  --namespace apps --create-namespace -f service-a/values.yaml

Next: Gateway API HTTPRoute examples → · Browse language examples → · Getting started →