How to Write Maintainable Helm Charts for AI Services

Helm charts for AI services tend to start as a copy of an example chart, then get copied again for each new service. A year later, nobody wants to touch them. A small, consistent chart is much easier for a customer's team to maintain after you leave.

Step 1: Start with helm create, then delete

Run helm create ai-service and remove the templates you don't need. A typical AI API service needs a Deployment, a Service, a ServiceAccount, an autoscaler and perhaps an Ingress. Fewer templates means less to understand.

Step 2: Design the values file for its readers

Put the settings people actually change at the top, with comments:

image:
  repository: registry.acme.com/support-agent
  tag: "1.4.2"

model:
  name: claude-sonnet-5          # model the service calls
  promptVersion: "2026-09-10"

resources:
  requests: {cpu: 500m, memory: 1Gi}
  limits: {memory: 1Gi}

existingSecret: support-agent-keys   # created outside the chart

Don't expose every Kubernetes field as a value. When someone needs something unusual, they can add it to the chart.

Step 3: Keep secrets out of the chart

Reference secrets that already exist in the cluster instead of templating secret values. Values files end up in Git, CI logs and support tickets.

Step 4: Validate every change

helm lint ./ai-service
helm template ./ai-service -f values-prod.yaml | kubeconform -strict

kubeconform checks the rendered manifests against Kubernetes schemas and catches mistakes before they reach a cluster.

Step 5: Version the chart

Increase the chart version whenever templates change, publish charts to an OCI registry and keep a short changelog so upgrades aren't a surprise.

Step 6: One chart for similar services

If several AI services have the same shape, give them one chart with different values files. Differences stay small and easy to see.

Things to watch

• Deeply nested template logic is hard to debug. Prefer plain templates with a few if blocks.
• CPU limits often throttle Python services. Set requests, and add CPU limits only when you have a reason.
• Document every value in the chart's README. A tool like helm-docs generates it from comments.

Aim for a chart that a new engineer can read and understand in fifteen minutes.