williamzujkowski/Helm Chart Builder

Purpose & When-To-Use

Trigger conditions:

• Deploying applications to multiple Kubernetes environments (dev, staging, prod)
• Packaging Kubernetes manifests for reusability and distribution
• Managing complex applications with dependencies (databases, message queues)
• Implementing GitOps workflows with parameterized deployments
• Version-controlling Kubernetes configurations with semantic versioning

Not for:

• Simple single-environment deployments (use kubernetes-manifest-generator)
• Serverless deployments (use cloud-serverless-designer)
• Service mesh configuration (use kubernetes-servicemesh-configurator)
• Complete orchestration across deployment types (use cloud-native-orchestrator agent)

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601): 2025-10-26T01:33:54-04:00
• Use NOW_ET for all citation access dates

Input validation:

• chart_name must be DNS-1123 compliant (lowercase, alphanumeric, hyphens)
• app_version must follow semantic versioning (e.g., 1.0.0)
• chart_version must follow semantic versioning
• resources array must contain valid K8s resource types (Deployment, Service, etc.)

Source freshness:

• Helm Documentation (accessed 2025-10-26T01:33:54-04:00): https://helm.sh/docs/
• Helm Best Practices (accessed 2025-10-26T01:33:54-04:00): https://helm.sh/docs/chart_best_practices/
• Helm Chart Template Guide (accessed 2025-10-26T01:33:54-04:00): https://helm.sh/docs/chart_template_guide/

Decision thresholds:

• T1 for basic chart structure with single environment
• T2 for multi-environment charts with dependencies and hooks

Procedure

T1: Basic Helm Chart Structure (≤2k tokens)

Step 1: Create chart directory structure

• Generate Chart.yaml with metadata (name, version, appVersion, description)
• Create values.yaml with default configuration parameters
• Build templates/ directory with basic resource templates
• Add NOTES.txt for post-install instructions

Step 2: Parameterize templates

• Convert static manifests to Helm templates with {{ .Values. }}
• Add image repository, tag, and pull policy parameters
• Parameterize replica count, resource limits, service ports
• Include conditional blocks for optional resources

Output:

• Basic Helm chart structure
• Parameterized templates for core resources
• values.yaml with sensible defaults
• helm install command

Abort conditions:

• chart_name conflicts with existing chart
• Invalid Kubernetes resource types in resources array

T2: Production-Grade Helm Chart (≤6k tokens)

All T1 steps plus:

Step 1: Multi-environment configuration

• Create values-dev.yaml, values-staging.yaml, values-prod.yaml
• Environment-specific overrides (replicas, resources, ingress)
• Secret management strategy (external-secrets, sealed-secrets)
• ConfigMap templating for environment config

Step 2: Chart dependencies

• Define dependencies in Chart.yaml (PostgreSQL, Redis, etc.)
• Configure dependency conditions (enable/disable based on values)
• Add subchart value overrides
• Generate Chart.lock with dependency versions

Step 3: Helm hooks

• Pre-install hook for database migration jobs
• Post-install hook for validation or smoke tests
• Pre-upgrade hook for backup or compatibility checks
• Add hook deletion policies (before-hook-creation, hook-succeeded)

Step 4: Advanced templating

• Named templates (_helpers.tpl) for reusable snippets
• Range loops for multiple similar resources
• Conditional resource creation with {{ if .Values.enabled }}
• Template functions (quote, toYaml, include, etc.)

Step 5: Validation and linting

• Run helm lint to check chart structure and templates
• Validate with helm template --debug
• Test installation in dry-run mode
• Generate schema for values.yaml validation

Output:

• Complete multi-environment Helm chart
• Chart dependencies with Chart.lock
• Helm hooks for lifecycle management
• Validation and installation instructions
• values.schema.json for values validation

Abort conditions:

• Dependency versions incompatible or unavailable
• Template syntax errors in complex conditionals
• Hook jobs fail validation

T3: Enterprise Helm Chart (≤12k tokens)

All T1 + T2 steps plus:

Step 1: Chart testing

• Create tests/ directory with connection tests
• Add helm test YAML for post-deployment validation
• Include integration test scripts

Step 2: Documentation

• Generate comprehensive README.md with parameter tables
• Document all values.yaml parameters with descriptions
• Add upgrade guides and migration notes
• Include troubleshooting section

Step 3: Chart repository packaging

• Package chart with helm package
• Generate index.yaml for chart repository
• Sign chart with GPG for provenance

Output:

• Enterprise-ready Helm chart with tests
• Complete documentation
• Packaged and signed chart ready for distribution
• Chart repository index

Decision Rules

Chart structure patterns:

• Simple app: Deployment, Service, ConfigMap, Secret templates only
• Stateful app: Add StatefulSet, PersistentVolumeClaim, headless Service
• Ingress required: Include Ingress template with TLS configuration
• Jobs/CronJobs: Add job templates with completion tracking

Dependency management:

• Include subchart: Common dependencies (PostgreSQL, Redis) as subcharts
• External dependency: Reference external charts in Chart.yaml dependencies
• Conditional dependency: Use condition or tags for optional dependencies

Hook usage:

• Pre-install: Database schema initialization, secret generation
• Post-install: Smoke tests, notification webhooks
• Pre-upgrade: Backup jobs, compatibility validation
• Post-upgrade: Migration cleanup, cache invalidation

Values organization:

• Global values: Shared across all environments (image repository, labels)
• Environment values: Replicas, resources, domains (in values-{env}.yaml)
• Secret values: Not in values files, use external-secrets or Vault

Ambiguity handling:

• If environments not specified → create values.yaml only (single environment)
• If dependencies unclear → request application architecture diagram
• If resource types unknown → infer from application type (web app → Deployment + Service)

Output Contract

Required fields (all tiers):

yaml
chart_structure:
  Chart.yaml: "chart metadata"
  values.yaml: "default configuration values"
  templates/:
    - deployment.yaml
    - service.yaml
    - _helpers.tpl
  NOTES.txt: "post-install instructions"

validation_results:
  helm_lint: "output of helm lint"
  template_render: "output of helm template"
  errors: ["array of validation errors if any"]

Additional T2 fields:

yaml
multi_environment:
  values_dev.yaml: "development overrides"
  values_staging.yaml: "staging overrides"
  values_prod.yaml: "production overrides"

dependencies:
  Chart.yaml_dependencies: ["array of chart dependencies"]
  Chart.lock: "locked dependency versions"

hooks:
  pre_install: ["array of pre-install hook jobs"]
  post_install: ["array of post-install hook jobs"]
  pre_upgrade: ["array of pre-upgrade hook jobs"]

helpers:
  _helpers.tpl: "named template definitions"

values_schema:
  values.schema.json: "JSON schema for values validation"

Additional T3 fields:

yaml
testing:
  tests/: ["array of test YAML files"]
  test_commands: ["helm test chart-name"]

documentation:
  README.md: "comprehensive chart documentation"
  UPGRADING.md: "upgrade and migration guide"

packaging:
  chart_package: "chart-name-version.tgz"
  chart_signature: "chart-name-version.tgz.prov"
  index.yaml: "chart repository index"

Examples

yaml
# T1 Example: Chart.yaml
apiVersion: v2
name: myapp
description: A Helm chart for my application
type: application
version: 0.1.0
appVersion: "1.0.0"
maintainers:
- name: Developer
  email: dev@example.com

yaml
# T1 Example: values.yaml
replicaCount: 3

image:
  repository: myregistry/myapp
  pullPolicy: IfNotPresent
  tag: "1.0.0"

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10

yaml
# T1 Example: templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    {{- include "myapp.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "myapp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "myapp.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: 8080
        resources:
          {{- toYaml .Values.resources | nindent 12 }}

Quality Gates

Token budgets (enforced):

• T1: ≤2,000 tokens - basic chart structure with parameterization
• T2: ≤6,000 tokens - multi-environment, dependencies, hooks, validation
• T3: ≤12,000 tokens - testing, documentation, packaging, signing

Safety checks:

• No hardcoded secrets in values.yaml or templates
• Image tags are parameterized (not hardcoded :latest)
• Resource limits defined in values.yaml
• NOTES.txt provides clear installation instructions

Auditability:

• Chart.yaml includes maintainer information
• Semantic versioning for chart and app versions
• All template functions cite Helm documentation
• Dependency versions locked in Chart.lock

Determinism:

• helm template renders identical output for same values
• Chart dependencies are version-locked
• Named templates produce consistent output

Validation requirements:

• Chart must pass helm lint without errors
• Templates must render without errors using helm template
• T2+ charts must include values.schema.json validation
• T3 charts must pass helm test successfully

Resources

Official Documentation (accessed 2025-10-26T01:33:54-04:00):

• Helm Documentation: https://helm.sh/docs/
• Helm Chart Best Practices: https://helm.sh/docs/chart_best_practices/
• Chart Template Guide: https://helm.sh/docs/chart_template_guide/
• Helm Hooks: https://helm.sh/docs/topics/charts_hooks/
• Chart Dependencies: https://helm.sh/docs/helm/helm_dependency/
• Values Files: https://helm.sh/docs/chart_template_guide/values_files/

Template Functions:

• Sprig Functions: http://masterminds.github.io/sprig/
• Template Function List: https://helm.sh/docs/chart_template_guide/function_list/

Validation and Testing:

• Helm Lint: https://helm.sh/docs/helm/helm_lint/
• Helm Test: https://helm.sh/docs/helm/helm_test/
• Chart Testing (ct): https://github.com/helm/chart-testing

Chart Repositories:

• Artifact Hub: https://artifacthub.io/
• Helm Chart Repository Guide: https://helm.sh/docs/topics/chart_repository/