Helm Charts from Scratch: No Fluff, Production Guide

Helm is Kubernetes package management. This guide skips the fluff and teaches you how to write production-ready Helm charts from scratch, with real examples you can deploy today.

Key Takeaways:

• Treat Helm Charts from Scratch as a system with an explicit input and output contract.
• Benchmark a representative baseline before choosing an optimization.
• Bound retries, queues, concurrency, and total request deadlines.
• Roll out through offline replay, shadow traffic, and a measurable canary.
• Keep rollback simple and attach version identifiers to every decision.

Table of Contents:

• What is Helm and Why Use It
• Helm Chart Structure Explained
• Creating Your First Chart
• Templates and Values
• Conditionals and Loops
• Dependencies and Subcharts
• Secrets and ConfigMaps
• Testing and Validation
• Production Deployment Patterns
• Chart Repository Setup
• FAQ

What is Helm and Why Use It

Helm is a package manager for Kubernetes. It takes multiple YAML manifests (Deployments, Services, ConfigMaps, etc.) and packages them into reusable, versioned charts.

Without Helm:

• Manually apply 10+ YAML files for each environment
• Duplicate manifests for dev, staging, production with slight variations
• No versioning or rollback mechanism
• Hard-coded values scattered across files

With Helm:

• Single command to install/upgrade/rollback entire applications
• Templatize manifests with environment-specific values
• Version charts like Docker images
• Share charts via repositories (public or private)

According to the CNCF's 2026 Kubernetes survey, 73% of production clusters use Helm for application deployment. It's the de facto standard for Kubernetes package management.

Our Kubernetes platform engineering services leverage Helm to deploy and manage hundreds of production workloads.

Helm Chart Structure Explained

Every Helm chart follows a standard directory structure:

mychart/
├── Chart.yaml          # Chart metadata (name, version)
├── values.yaml         # Default configuration values
├── charts/             # Dependencies (subcharts)
├── templates/          # Kubernetes manifest templates
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── _helpers.tpl    # Template helpers (reusable snippets)
│   └── NOTES.txt       # Post-install instructions
└── .helmignore         # Files to exclude from chart

Chart.yaml defines metadata:

apiVersion: v2
name: mychart
description: A production-ready Helm chart
type: application
version: 1.0.0        # Chart version (semantic versioning)
appVersion: "2.3.1"   # Application version
maintainers:
  - name: HinterBuild Team
    email: team@hinterbuild.com

values.yaml contains default configuration:

replicaCount: 2

image:
  repository: myapp
  tag: "v1.0.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Templates in templates/ are standard Kubernetes YAML with Go template syntax for variable substitution.

Creating Your First Chart

Let's build a production-ready chart for a web application.

Step 1: Initialize the Chart

helm create webapp
cd webapp

This generates the standard structure. We'll replace the defaults with production-ready templates.

Step 2: Define Chart Metadata

Chart.yaml:

apiVersion: v2
name: webapp
description: Production web application Helm chart
type: application
version: 1.0.0
appVersion: "2.3.1"
keywords:
  - web
  - application
  - production
maintainers:
  - name: HinterBuild Team
    url: https://hinterbuild.com
sources:
  - https://github.com/yourorg/webapp

Step 3: Configure Default Values

values.yaml:

replicaCount: 2

# Container image configuration
image:
  repository: yourregistry.io/webapp
  tag: "v2.3.1"
  pullPolicy: IfNotPresent

# Service configuration
service:
  type: ClusterIP
  port: 8080
  targetPort: 8080

# Ingress configuration
ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: webapp.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: webapp-tls
      hosts:
        - webapp.example.com

# Resource limits
resources:
  requests:
    cpu: 200m
    memory: 256Mi
  limits:
    cpu: 1000m
    memory: 1Gi

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

# Health checks
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

# Environment variables
env:
  - name: LOG_LEVEL
    value: "info"
  - name: PORT
    value: "8080"

# Secrets (from existing Kubernetes secret)
envFrom:
  - secretRef:
      name: webapp-secrets

This values file is production-ready with health checks, autoscaling, resource limits, and TLS ingress.

Learn more about cloud infrastructure best practices.

Templates and Values

Templates use Go's text/template syntax to inject values from values.yaml.

Basic Templating

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "webapp.fullname" . }}
  labels:
    {{- include "webapp.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "webapp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "webapp.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - containerPort: {{ .Values.service.targetPort }}
        resources:
          {{- toYaml .Values.resources | nindent 10 }}
        env:
          {{- toYaml .Values.env | nindent 10 }}
        {{- if .Values.envFrom }}
        envFrom:
          {{- toYaml .Values.envFrom | nindent 10 }}
        {{- end }}
        livenessProbe:
          {{- toYaml .Values.livenessProbe | nindent 10 }}
        readinessProbe:
          {{- toYaml .Values.readinessProbe | nindent 10 }}

Key syntax:

• {{ .Values.replicaCount }} - Access values from values.yaml
• {{ .Chart.Name }} - Access Chart.yaml metadata
• {{- toYaml .Values.resources | nindent 10 }} - Convert YAML and indent
• {{- include "webapp.labels" . | nindent 4 }} - Call template helper

Template Helpers

Define reusable snippets in templates/_helpers.tpl:

{{/*
Expand the name of the chart.
*/}}
{{- define "webapp.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a fully qualified app name.
*/}}
{{- define "webapp.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "webapp.labels" -}}
helm.sh/chart: {{ include "webapp.chart" . }}
{{ include "webapp.selectorLabels" . }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "webapp.selectorLabels" -}}
app.kubernetes.io/name: {{ include "webapp.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/*
Chart name and version
*/}}
{{- define "webapp.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }}
{{- end }}

Helpers reduce duplication across templates. Use them for labels, names, and reusable logic.

Service Template

templates/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "webapp.fullname" . }}
  labels:
    {{- include "webapp.labels" . | nindent 4 }}
spec:
  type: {{ .Values.service.type }}
  ports:
  - port: {{ .Values.service.port }}
    targetPort: {{ .Values.service.targetPort }}
    protocol: TCP
    name: http
  selector:
    {{- include "webapp.selectorLabels" . | nindent 4 }}

Ingress Template

templates/ingress.yaml:

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "webapp.fullname" . }}
  labels:
    {{- include "webapp.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  {{- if .Values.ingress.className }}
  ingressClassName: {{ .Values.ingress.className }}
  {{- end }}
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            pathType: {{ .pathType }}
            backend:
              service:
                name: {{ include "webapp.fullname" $ }}
                port:
                  number: {{ $.Values.service.port }}
          {{- end }}
    {{- end }}
{{- end }}

This template conditionally renders based on ingress.enabled and loops over multiple hosts/paths.

Conditionals and Loops

Helm supports if/else conditionals and range loops for dynamic manifests.

Conditionals

Syntax:

{{- if .Values.feature.enabled }}
# Rendered if feature.enabled is true
{{- else }}
# Rendered if feature.enabled is false
{{- end }}

Example: Optional HPA:

{{- if .Values.autoscaling.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: {{ include "webapp.fullname" . }}
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {{ include "webapp.fullname" . }}
  minReplicas: {{ .Values.autoscaling.minReplicas }}
  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
  metrics:
  {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
  {{- end }}
  {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
  {{- end }}
{{- end }}

If autoscaling.enabled: false, the HPA manifest isn't rendered at all.

Loops

Syntax:

{{- range .Values.items }}
- name: {{ .name }}
  value: {{ .value }}
{{- end }}

Example: Multiple environment variables:

values.yaml:

env:
  - name: LOG_LEVEL
    value: "info"
  - name: DATABASE_HOST
    value: "postgres.internal"
  - name: CACHE_ENABLED
    value: "true"

Template:

env:
  {{- range .Values.env }}
  - name: {{ .name }}
    value: {{ .value | quote }}
  {{- end }}

Rendered output:

env:
  - name: LOG_LEVEL
    value: "info"
  - name: DATABASE_HOST
    value: "postgres.internal"
  - name: CACHE_ENABLED
    value: "true"

With Blocks

Scope a template block to a specific value path:

{{- with .Values.resources }}
resources:
  requests:
    cpu: {{ .requests.cpu }}
    memory: {{ .requests.memory }}
  limits:
    cpu: {{ .limits.cpu }}
    memory: {{ .limits.memory }}
{{- end }}

This simplifies nested value access.

Dependencies and Subcharts

Helm charts can depend on other charts (subcharts). This is useful for bundling databases, caches, or message queues with your application.

Declaring Dependencies

Chart.yaml:

apiVersion: v2
name: webapp
version: 1.0.0
dependencies:
  - name: postgresql
    version: "12.1.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
  - name: redis
    version: "17.3.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled

Download Dependencies

helm dependency update webapp/

This downloads subcharts to webapp/charts/.

Configuring Subcharts

Override subchart values in your main values.yaml:

# Parent chart values
replicaCount: 2
image:
  repository: webapp
  tag: "v1.0.0"

# PostgreSQL subchart values
postgresql:
  enabled: true
  auth:
    username: webapp
    password: changeme
    database: webapp_db
  primary:
    persistence:
      enabled: true
      size: 10Gi

# Redis subchart values
redis:
  enabled: true
  auth:
    enabled: false
  master:
    persistence:
      enabled: false

When you install the chart, Helm deploys your webapp + PostgreSQL + Redis.

helm install myapp webapp/

For complex systems with many dependencies, check our Kubernetes platform engineering services.

Secrets and ConfigMaps

Never hardcode secrets in values.yaml. Use Kubernetes Secrets and external secret managers.

Using Kubernetes Secrets

Create a secret:

kubectl create secret generic webapp-secrets \
  --from-literal=database-password=supersecret \
  --from-literal=api-key=abcdef123456

Reference in deployment:

envFrom:
  - secretRef:
      name: webapp-secrets

ConfigMaps for Non-Sensitive Config

templates/configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "webapp.fullname" . }}
  labels:
    {{- include "webapp.labels" . | nindent 4 }}
data:
  app.conf: |
    server {
      port = {{ .Values.service.port }}
      log_level = "{{ .Values.logLevel }}"
    }

Mount in deployment:

volumeMounts:
  - name: config
    mountPath: /etc/config
volumes:
  - name: config
    configMap:
      name: {{ include "webapp.fullname" . }}

External Secrets Operator

For production, use External Secrets Operator to sync secrets from AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault.

Example ExternalSecret:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: {{ include "webapp.fullname" . }}
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secretsmanager
    kind: SecretStore
  target:
    name: webapp-secrets
  data:
    - secretKey: database-password
      remoteRef:
        key: prod/webapp/database
        property: password
    - secretKey: api-key
      remoteRef:
        key: prod/webapp/api
        property: key

See our guide on securing production Kubernetes deployments.

Testing and Validation

Always test charts before deploying to production.

Lint Chart

helm lint webapp/

This checks for syntax errors and common mistakes.

Render Templates Locally

helm template myapp webapp/ --values webapp/values-prod.yaml

This outputs all rendered manifests without deploying. Review the YAML to ensure values are interpolated correctly.

Dry Run Install

helm install myapp webapp/ --dry-run --debug

This simulates the install and shows what would be deployed.

Unit Testing with helm-unittest

Install the plugin:

helm plugin install https://github.com/helm-unittest/helm-unittest

tests/deployment_test.yaml:

suite: test deployment
templates:
  - deployment.yaml
tests:
  - it: should create deployment with correct replicas
    set:
      replicaCount: 3
    asserts:
      - equal:
          path: spec.replicas
          value: 3

  - it: should use correct image
    set:
      image:
        repository: myapp
        tag: v2.0.0
    asserts:
      - equal:
          path: spec.template.spec.containers[0].image
          value: myapp:v2.0.0

  - it: should have resource limits
    asserts:
      - isNotEmpty:
          path: spec.template.spec.containers[0].resources.limits

Run tests:

helm unittest webapp/

Integration Testing in Staging

Deploy to a staging cluster before production:

helm install webapp-staging webapp/ --namespace staging --values webapp/values-staging.yaml

Validate:

• Pods are running: kubectl get pods -n staging
• Health checks pass: kubectl logs -n staging <pod>
• Ingress works: curl https://staging.example.com/health

Production Deployment Patterns

Multi-Environment Values Files

Create separate values files for each environment:

webapp/
├── values.yaml            # Defaults
├── values-dev.yaml        # Development overrides
├── values-staging.yaml    # Staging overrides
└── values-prod.yaml       # Production overrides

values-prod.yaml:

replicaCount: 5

image:
  repository: prodregistry.io/webapp
  tag: "v2.3.1"

autoscaling:
  enabled: true
  minReplicas: 5
  maxReplicas: 50

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 2000m
    memory: 2Gi

ingress:
  enabled: true
  hosts:
    - host: webapp.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: webapp-prod-tls
      hosts:
        - webapp.example.com

Install with production values:

helm install webapp webapp/ --namespace production --values webapp/values-prod.yaml

Blue-Green Deployments

Deploy a new version alongside the old, then switch traffic:

# Deploy blue (current version)
helm install webapp-blue webapp/ --set service.selector.version=blue

# Deploy green (new version)
helm install webapp-green webapp/ --set service.selector.version=green

# Test green deployment
curl https://green.example.com/health

# Switch production traffic to green
kubectl patch service webapp -p '{"spec":{"selector":{"version":"green"}}}'

# Remove blue after validation
helm uninstall webapp-blue

Canary Deployments with Flagger

Use Flagger for automated canary deployments:

apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
  name: webapp
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: webapp
  service:
    port: 8080
  analysis:
    interval: 1m
    threshold: 5
    maxWeight: 50
    stepWeight: 10
    metrics:
      - name: request-success-rate
        thresholdRange:
          min: 99
      - name: request-duration
        thresholdRange:
          max: 500

Flagger gradually shifts traffic from old to new version based on metrics.

Rollback Strategy

Helm tracks release history. Rollback if a deployment fails:

# List releases
helm list --namespace production

# View release history
helm history webapp --namespace production

# Rollback to previous version
helm rollback webapp --namespace production

# Rollback to specific revision
helm rollback webapp 3 --namespace production

Our cloud infrastructure services implement these patterns for zero-downtime deployments.

Chart Repository Setup

Share charts via a Helm repository. Repositories are just HTTP servers hosting index.yaml and chart tarballs.

Package Chart

helm package webapp/
# Creates: webapp-1.0.0.tgz

Create Repository Index

helm repo index . --url https://charts.example.com
# Creates: index.yaml

index.yaml:

apiVersion: v1
entries:
  webapp:
    - name: webapp
      version: 1.0.0
      description: Production web application
      created: "2026-09-11T14:00:00Z"
      digest: abc123def456...
      urls:
        - https://charts.example.com/webapp-1.0.0.tgz

Host on S3 or GitHub Pages

S3 example:

# Upload chart and index
aws s3 cp webapp-1.0.0.tgz s3://charts.example.com/
aws s3 cp index.yaml s3://charts.example.com/

# Configure bucket policy for public read
aws s3api put-bucket-policy --bucket charts.example.com --policy file://policy.json

policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::charts.example.com/*"
    }
  ]
}

Add Repository

helm repo add myrepo https://charts.example.com
helm repo update
helm install webapp myrepo/webapp

Private Repository with ChartMuseum

For private charts, use ChartMuseum:

# Run ChartMuseum
docker run -d \
  -p 8080:8080 \
  -e STORAGE=local \
  -e STORAGE_LOCAL_ROOTDIR=/charts \
  -v $(pwd)/charts:/charts \
  ghcr.io/helm/chartmuseum:latest

# Push chart
curl --data-binary "@webapp-1.0.0.tgz" http://localhost:8080/api/charts

# Add repo with auth
helm repo add myrepo http://localhost:8080 --username admin --password secret

For production chart registries, explore our DevOps services.

Related implementation guides:

• Build Fine Tuning Dataset From Scratch
• Llm Eval Suite From Scratch
• Advanced Rag Techniques Beyond Naive Chunking

Primary references: official documentation, official documentation, official documentation, official documentation.

Helm Charts from Scratch Decision Table

Operating Helm Charts from Scratch as a System

The implementation is only one part of Helm Charts from Scratch. A production design also needs an explicit contract for inputs, outputs, ownership, and failure behavior. Write that contract before selecting a library. It should identify which component validates input, where state lives, what may be retried, and which result is authoritative when two components disagree. This prevents a convenient prototype boundary from silently becoming the long-term architecture.

Start with a representative baseline. Capture request shape, traffic distribution, dependency latency, error classes, and the quality signal users actually care about. Averages hide the cases that cause incidents, so keep percentiles and segment measurements by workload type. Record the configuration and dataset version beside every result. Without that context, a faster or more accurate run cannot be reproduced and should not be used to approve a rollout.

Define the failure model

List failures by where they originate: invalid input, capacity exhaustion, dependency timeout, partial state change, malformed output, and semantically wrong output. Each class needs a different response. Validation errors should fail immediately. Transient dependency failures may be retried with a budget and jitter. An operation that may have committed must use an idempotency key or reconciliation step before retrying. A syntactically valid but incorrect result belongs in evaluation and review, not a blind retry loop.

Set a deadline for the complete operation and derive smaller budgets for each dependency. Local timeouts that add up to more than the caller's deadline merely create abandoned work. Propagate cancellation where the protocol supports it. Bound every queue, retry loop, context buffer, and concurrency pool; an unbounded safety mechanism becomes a second outage during overload.

Design a degraded mode before it is needed. Depending on the workload, that can mean returning a cached answer, selecting a simpler path, placing work in a durable queue, or asking for human review. The degraded response must be visible in telemetry and, where it changes meaning, visible to the caller. Silent fallback makes quality regressions almost impossible to diagnose.

Measure the decision, not just the component

Use three layers of signals. System metrics cover latency, throughput, saturation, and errors. Correctness metrics measure whether the result satisfies its contract. Business or user metrics show whether the system solved the intended problem. Improving only one layer can move the others backward, so release criteria should name acceptable movement for all three.

Attach a reason code to every route, rejection, fallback, and retry. Include version identifiers for configuration, code, model, schema, and data when relevant. Logs should let an engineer reconstruct a decision without storing secrets or raw personal data. Traces should cross process boundaries, while metrics should remain low-cardinality enough to operate reliably.

Alert on symptoms that require action, not every internal anomaly. A useful alert names the affected service objective, links to a runbook, and distinguishes a customer-visible incident from exhausted headroom. Dashboards serve a different purpose: they support diagnosis and capacity planning. Treating a dashboard as an alerting strategy leaves failures undiscovered until someone happens to look.

Roll out with reversible steps

Ship Helm Charts from Scratch behind a versioned interface and a kill switch. Begin with offline replay using production-shaped, privacy-safe samples. Then use shadow execution when duplicate work has acceptable cost and side effects can be suppressed. A small canary should exercise the real dependency graph before traffic expands. Compare the canary with the baseline by cohort rather than mixing both populations into one aggregate.

Promotion gates should be written before the rollout. Include a minimum sample size or observation window, maximum regression in tail latency and error rate, and a correctness threshold. Roll back automatically when a hard safety boundary is crossed; use manual review for ambiguous quality movement. Preserve enough evidence from both paths to explain why the gate passed or failed.

Configuration deserves the same discipline as code. Review changes, validate them before activation, keep an immutable history, and make rollback a single operation. If a deployment changes code and configuration together, record both versions. Otherwise an incident responder may roll back the binary while leaving the triggering configuration active.

Capacity and cost controls

Model capacity in units the bottleneck understands: concurrent connections, tokens, queue jobs, database transactions, GPU memory, or bytes in flight. Convert the expected traffic distribution into those units and include burst behavior. Then load-test the first constrained dependency, not merely the public endpoint. A system that accepts more work than it can finish within its deadline is overloaded even if CPU utilization looks comfortable.

Cost is also a reliability limit. Add per-request attribution, tenant or workflow budgets, and a global circuit breaker for unexpectedly expensive paths. Review unit economics at the same granularity as performance; a cheap median can conceal a small class of requests responsible for most spend. Optimize only after measuring, because reducing context, replicas, validation, or redundancy can trade visible cost for less visible risk.

Production readiness review

Before launch, ask an engineer who did not build the feature to follow the runbook through one simulated failure. Verify backups or checkpoints by restoring them, not by checking that a job reported success. Exercise credential rotation, dependency unavailability, bad configuration, and rollback. Assign an owner for each alarm and a date for reviewing thresholds after real traffic arrives.

The final architecture document should be short enough to remain current. Keep the decision, rejected alternatives, invariants, dependency contracts, dashboards, and rollback procedure. Link detailed experiments rather than pasting them into the document. Teams that need help turning this review into an operable service can use our Helm Charts from Scratch engineering support.

Frequently Asked Questions

What is a Helm chart?

A Helm chart is a package of Kubernetes manifests (YAML files) organized into a standardized directory structure with templates for variable substitution. It's like a Docker image for Kubernetes applications—versioned, shareable, and reusable.

When should I use Helm vs raw YAML?

Use Helm when:

• Deploying the same application to multiple environments (dev, staging, prod)
• You need version control and rollback capabilities
• Your application has complex multi-resource deployments
• You want to share deployment configurations with others

Use raw YAML for simple, static deployments that never change.

What's the difference between Chart.yaml version and appVersion?

version is the Helm chart version (semantic versioning: 1.0.0, 1.1.0, etc.). Increment this when you change templates or values structure.

appVersion is the application version being deployed (your Docker image tag). This changes with every app release but the chart version might stay the same.

How do I upgrade a deployed chart?

helm upgrade webapp webapp/ --namespace production --values values-prod.yaml

Helm applies the diff between current state and new templates. Kubernetes rolls out changes gradually (default deployment strategy).

Can I use Helm with GitOps tools like ArgoCD?

Yes. ArgoCD and Flux support Helm natively. Store charts in Git, and GitOps tools automatically sync changes to Kubernetes. This is the recommended production pattern.

ArgoCD Application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: webapp
spec:
  source:
    repoURL: https://github.com/yourorg/charts
    path: webapp
    targetRevision: main
    helm:
      valueFiles:
        - values-prod.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: production

How do I manage secrets securely?

Never commit secrets to Git. Use one of these approaches:

• Kubernetes Secrets: Create manually, reference in chart
• External Secrets Operator: Sync from AWS/GCP/Vault
• Sealed Secrets: Encrypt secrets before committing to Git
• Helm Secrets Plugin: Encrypt values.yaml with SOPS

We recommend External Secrets Operator for production.

What's the difference between install and upgrade?

• helm install: Creates a new release (fails if release already exists)
• helm upgrade: Updates an existing release (fails if release doesn't exist)
• helm upgrade --install: Upgrades if exists, installs if not (idempotent)

Use helm upgrade --install in CI/CD pipelines for idempotency.

How do I debug a failed installation?

# View rendered templates
helm template myapp webapp/ --values values.yaml

# Dry run with debug output
helm install myapp webapp/ --dry-run --debug

# Check Kubernetes events
kubectl get events --sort-by='.lastTimestamp'

# View pod logs
kubectl logs -l app.kubernetes.io/name=webapp

# Describe deployment
kubectl describe deployment webapp

Can I use Helm 2 charts with Helm 3?

Helm 3 removed Tiller (server-side component) and changed release storage. Most Helm 2 charts work with Helm 3 after minor updates. Update apiVersion: v2 in Chart.yaml and test.

What's the performance impact of Helm?

Helm is a client-side tool. It renders templates locally and sends YAML to Kubernetes API. Performance is equivalent to kubectl apply. The only overhead is template rendering (~100ms for large charts).

Conclusion

Helm charts transform Kubernetes deployments from manual YAML management into versioned, reproducible packages. The patterns in this guide—environment-specific values, subcharts, testing, and proper secret handling—are production-tested across hundreds of deployments.

Key takeaways:

• Helm packages multiple Kubernetes manifests into reusable charts
• Templates use Go syntax for variable substitution from values.yaml
• Subcharts enable bundling dependencies (databases, caches)
• Separate values files for dev/staging/prod environments
• Test with lint, dry-run, and helm-unittest before production
• Use chart repositories (S3, ChartMuseum) to share charts

Modern Kubernetes platforms run on Helm. Our Kubernetes platform engineering services design and deploy production Helm charts for complex distributed systems.

Related resources:

• Kubernetes Platform Engineering Services
• Cloud Infrastructure & DevOps
• Observability & Monitoring