Chart Directory Layout

Every MATIH service chart follows a consistent directory structure with standardized template files, values patterns, and naming conventions.

Standard Chart Layout

service-name/
  Chart.yaml              # Chart metadata and dependencies
  values.yaml             # Production defaults
  values-dev.yaml         # Development overrides (optional)
  templates/
    _helpers.tpl          # Reusable template functions
    deployment.yaml       # Deployment specification
    service.yaml          # ClusterIP Service
    configmap.yaml        # Non-sensitive configuration
    secret.yaml           # Secret references
    ingress.yaml          # Ingress resource (optional)
    hpa.yaml              # Horizontal Pod Autoscaler
    pdb.yaml              # Pod Disruption Budget
    servicemonitor.yaml   # Prometheus ServiceMonitor
    networkpolicy.yaml    # Network isolation rules
    NOTES.txt             # Post-install instructions

Chart.yaml

Every chart declares its metadata and dependencies on the base library:

apiVersion: v2
name: ai-service
description: MATIH AI Service - NLP-to-SQL and conversational analytics
type: application
version: 0.1.0
appVersion: "1.0.0"
maintainers:
  - name: MATIH Engineering
    email: engineering@matih.ai
dependencies:
  - name: matih-base
    version: "1.x.x"
    repository: "file://../base"
  - name: redis
    version: "18.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled

values.yaml Structure

Values files follow a consistent top-level structure:

# 1. Billing configuration (required)
billing:
  costCenter: "CC-ML"
  application: "data-plane"
  team: "ml-engineering"
  workloadType: "api"
  service: "ai-service"
 
# 2. Image configuration
image:
  registry: matihlabsacr.azurecr.io
  repository: matih/ai-service
  tag: ""
  pullPolicy: Always
 
# 3. Service configuration
service:
  type: ClusterIP
  port: 8000
  targetPort: 8000
 
# 4. Resource limits
resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 2000m
    memory: 4Gi
 
# 5. Autoscaling
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
 
# 6. Health probes
startupProbe: { ... }
livenessProbe: { ... }
readinessProbe: { ... }
 
# 7. Application config
config:
  environment: "production"
  ...
 
# 8. Security contexts
podSecurityContext: { ... }
securityContext: { ... }
 
# 9. Scheduling
nodeSelector: { ... }
tolerations: [ ... ]
affinity: { ... }
 
# 10. Network policy
networkPolicy:
  enabled: true
  ...

Template Patterns

Deployment Template

Deployments use checksum annotations for automatic rollout on config changes:

template:
  metadata:
    annotations:
      checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
      checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}

Conditional Replicas

When HPA is enabled, the deployment omits the replicas field:

spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}

Secret References

All credentials use secretKeyRef -- never hardcoded values:

- name: DATABASE_PASSWORD
  valueFrom:
    secretKeyRef:
      name: {{ .Values.config.database.existingSecret }}
      key: {{ .Values.config.database.passwordKey }}

Overview Base Library Chart