helm-charts

You are an expert in creating Helm charts following best practices and Kubernetes conventions.

Guidelines

• Use meaningful and descriptive names that clearly indicate purpose (avoid abbreviations).
• Follow Helm naming conventions consistently throughout the chart.
• Keep template logic simple and maintainable; avoid complex nested conditionals.
• Provide sensible defaults that work for common deployment scenarios.
• Document all configurable values comprehensively in the README.md.
• Follow Kubernetes best practices for resource definitions.

Naming conventions

• Chart name: lowercase (e.g., pathling, sql-on-fhir).
• Kubernetes resource names: Use {{ .Release.Name }} concatenated with descriptive suffixes.
  • Example: {{ .Release.Name }}-deployment, {{ .Release.Name }}-service, {{ .Release.Name }}-pvc.
  • Do not use helper templates for naming unless specifically requested.
• Template file names: lowercase kebab-case matching the resource type.
  • Example: deployment.yaml, service.yaml, pvc.yaml.
  • Use pvc.yaml not persistentvolumeclaim.yaml.
• Value keys: camelCase for nested properties (e.g., imagePullPolicy, resourceLimits).

Values file structure

• Use a single top-level key matching the chart name to namespace all chart values.
• Organise values into logical nested groupings that reflect their purpose.
  • Example: resources, deployment, config.
• Use tilde (~) to explicitly indicate null or unset optional values.
• Use empty arrays ([]) as defaults for lists.
• Use empty objects ({}) as defaults for maps.
• Provide meaningful defaults that work for common use cases without requiring customisation.
• Keep the structure flat where possible; avoid unnecessary nesting levels.
• Group related configuration together (e.g., all image-related settings under an image key).
• Resources: Set resources: {} by default (unset), with commented examples showing how to configure.
• Simple application charts: Do not include secretConfig or service account support unless the application specifically requires it.
• Persistence: Include PVC support for stateful applications, disabled by default with enabled: false.

Example structure for a simple application chart:

sqlOnFhir:
    image: "sql-on-fhir-server:latest"
    imagePullPolicy: "Always"
    replicas: 1

    resources: {}
        # requests:
        #   memory: "512Mi"
        #   cpu: "250m"
        # limits:
        #   memory: "1Gi"
        #   cpu: "500m"

    config: {}

    persistence:
        enabled: false
        size: "1Gi"

Template patterns

• Always quote string values to prevent type coercion issues.
  • Example: {{ .Values.pathling.image | quote }}.
• For complex types (arrays, objects), use the simple toJson pattern without conditionals.
  • Correct: volumes: {{ toJson .Values.pathling.volumes }}
  • This pattern works perfectly with empty arrays ([]), null values (~), and populated arrays.
  • Helm's toJson handles all these cases correctly without needing length checks or indent filters.
• Do NOT use conditionals with toJson for array/object fields.
  • Incorrect: {{- if gt (len .Values.pathling.volumes) 0 }} followed by {{ toJson .Values.pathling.volumes | indent 8 }}.
  • This anti-pattern is unnecessarily complex and error-prone.
  • The simple toJson pattern is cleaner, more reliable, and easier to maintain.
• Use explicit conditionals only for optional sections where you need to omit entire blocks.
  • Example: {{- if gt (len .Values.pathling.config) 0 }} when you want to completely omit the env: section if empty.
• Use range loops for iterating over maps and lists when you need to transform each item.
  • Example: {{- range $configKey, $configValue := .Values.pathling.config }}.
• Separate multiple resources in a single file with --- on its own line.
• Make resource creation conditional when appropriate.
  • Example: only create secrets if secretConfig is defined.
• Indent template logic consistently (2 spaces is standard).
• Use {{- and -}} to control whitespace appropriately.

Example of simple toJson pattern for complex types:

# These fields work perfectly with toJson and require no conditionals
volumes: { { toJson .Values.pathling.volumes } }
tolerations: { { toJson .Values.pathling.tolerations } }
affinity: { { toJson .Values.pathling.affinity } }

Example conditional block (for environment variables where you want to omit the entire section when empty):

{{- if gt (len .Values.pathling.config) 0 }}
env:
  {{- range $configKey, $configValue := .Values.pathling.config }}
  - name: {{ $configKey }}
    value: {{ $configValue | quote }}
  {{- end }}
{{- end }}

File organisation

• Create one template file per resource type as the default approach.
  • Example: deployment.yaml, service.yaml, configmap.yaml.
• Co-locate multiple instances of the same resource type in a single file when they're closely related.
  • Example: multiple services in service.yaml.
• Group dependent resources together when it improves clarity.
  • Example: secrets with the deployment that consumes them.
• Use the templates/ directory for all Kubernetes resource templates.
• Place helper functions in templates/_helpers.tpl.
• Keep the root directory clean with only essential files: Chart.yaml, values.yaml, README.md.

Documentation standards

• Include a comprehensive README.md in every chart with the following sections:
  • Introduction: Brief description of what the chart deploys.
  • Features: Bullet-point list of key capabilities.
  • Prerequisites: Required Kubernetes version, other dependencies.
  • Installation: Step-by-step installation instructions with code examples.
  • Configuration: Complete table of all configurable values.
  • Examples: Multiple example configurations for different deployment scenarios.
  • Upgrading: Notes on upgrade considerations if applicable.
  • Uninstalling: Instructions for clean removal.
• Format the configuration table with these columns:
  • Parameter: Full path using dot notation (e.g., pathling.resources.limits.memory).
  • Description: Clear explanation of what the parameter controls.
  • Default: The default value (use backticks for code, show actual default from values.yaml).
• Provide working code examples in the README that users can copy and paste.
• Use proper language identifiers in all code blocks (yaml, bash, etc.).
• Keep inline comments in values.yaml minimal; let the README provide detailed documentation.
• Make value names self-documenting; choose clarity over brevity.

Example configuration table format:

Configuration approach

• Separate public configuration from sensitive configuration clearly.
  • Use config for non-sensitive environment variables.
  • Use secretConfig for sensitive values that should be stored in Kubernetes secrets.
• Prefer environment variable-based configuration for application settings.
• Don't tightly couple the chart to specific aspects of the application configuration, prefer the flexibility of letting the user set any configuration they need.
• Support both standard values and secret values for the same configuration pattern.
• Use consistent field naming across related configuration types.
  • Example: if you have config, name the secret variant secretConfig, not secrets or secretEnv.
• Provide examples of both configuration types in the README.
• Document which configuration method is preferred for different use cases.

Example configuration pattern:

pathling:
    # Non-sensitive configuration
    config:
        PATHLING_TERMINOLOGY_SERVER_URL: "https://tx.fhir.org/r4"
        PATHLING_SPARK_MASTER: "local[*]"

    # Sensitive configuration
    secretConfig:
        PATHLING_AUTH_TOKEN: "secret-token-value"

Kubernetes best practices

• Always include health probes for application containers.
  • Define startupProbe for slow-starting applications.
  • Define livenessProbe to detect and restart unhealthy containers.
  • Define readinessProbe to control when containers receive traffic.
• Define resource requests and limits for all containers to enable proper scheduling.
• Support service accounts and RBAC when the application requires Kubernetes API access.
• Make image pull policies configurable (default to Always).
• Support pod-level configurations:
  • tolerations for node taints.
  • affinity rules for pod placement.
  • nodeSelector for basic node selection.
• Use appropriate service types based on access requirements:
  • ClusterIP for internal services (default).
  • NodePort for external access in development.
  • LoadBalancer for production external access.
• Follow the principle of least privilege for service accounts and RBAC roles.
• Use Recreate deployment strategy for stateful applications; use RollingUpdate for stateless applications.
• Set appropriate terminationGracePeriodSeconds for graceful shutdown.
• Do not include ingress resources in charts, they are generally deployment-specific and not always necessary.
• Do not include other charts as dependencies unless absolutely necessary.
• Never depend upon any chart from Bitnami.

Example health probe configuration:

startupProbe:
    httpGet:
        path: /healthcheck
        port: http
    initialDelaySeconds: 30
    periodSeconds: 10
    failureThreshold: 30

livenessProbe:
    httpGet:
        path: /healthcheck
        port: http
    periodSeconds: 30
    failureThreshold: 3

readinessProbe:
    httpGet:
        path: /healthcheck
        port: http
    periodSeconds: 10
    failureThreshold: 3

Testing and validation

• Use helm template to inspect rendered templates during development.
• Use helm lint to validate chart structure and templates before committing.
• Test installation with default values in a clean namespace in the docker-desktop cluster.
• Test with custom values that exercise different configuration paths.

Version management

• Follow semantic versioning for the chart version (major.minor.patch).
• Increment major version for breaking changes to the values schema.
• Increment minor version for new features or significant enhancements.
• Increment patch version for bug fixes and minor improvements.
• Update appVersion in Chart.yaml to match the application version being deployed.
• Document version compatibility in the README (chart version, app version, Kubernetes version).