Chart Development

This page covers the workflow for creating new Helm charts, testing them, and ensuring they conform to MATIH standards.

Creating a New Chart

Step 1: Scaffold from Base

# Create chart directory
mkdir infrastructure/helm/my-service
cd infrastructure/helm/my-service
 
# Create Chart.yaml with base dependency
cat > Chart.yaml << 'CHART'
apiVersion: v2
name: my-service
description: My new MATIH service
type: application
version: 0.1.0
appVersion: "1.0.0"
dependencies:
  - name: matih-base
    version: "1.x.x"
    repository: "file://../base"
CHART

Step 2: Create values.yaml

Follow the standard structure: billing, image, service, resources, autoscaling, probes, config, security, scheduling.

Step 3: Create Templates

At minimum, create these template files:

File	Use Base Template
`_helpers.tpl`	Extend `matih.name`, `matih.fullname`, etc.
`deployment.yaml`	Use `matih.deployment.spring` / `matih.deployment.python`
`service.yaml`	Use `matih.service` or inline
`hpa.yaml`	Use `matih.hpa`
`pdb.yaml`	Use `matih.pdb`
`servicemonitor.yaml`	Standard ServiceMonitor
`networkpolicy.yaml`	Service-specific rules

Mandatory Checks

Before declaring a chart complete:

1. Billing Labels

Every chart must set billing configuration:

billing:
  costCenter: "CC-DATA-PLANE"   # Required
  application: "data-plane"      # Required
  team: "data-engineering"       # Required
  workloadType: "api"            # Recommended
  service: "my-service"          # Recommended

2. Security Context

All pods must run non-root with minimal capabilities:

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000
 
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop: [ALL]

3. Health Probes

All containers must have startup, liveness, and readiness probes.

4. No Hardcoded Secrets

All credentials must use secretKeyRef or existingSecret references.

Testing

Lint

helm lint infrastructure/helm/my-service \
  -f infrastructure/helm/my-service/values.yaml

Template Rendering

helm template my-service infrastructure/helm/my-service \
  -f infrastructure/helm/my-service/values.yaml \
  --namespace matih-data-plane

Verify Rendered Output

Check the rendered YAML for:

Correct image and tag
Security contexts with no leaked values
All env vars use secretKeyRef (no hardcoded credentials)
Correct service ports
Proper label selectors
Health probe endpoints match the application

Adding to Umbrella Chart

To include the new chart in an umbrella:

Add dependency to the umbrella Chart.yaml:

dependencies:
  - name: my-service
    version: ">=0.1.0"
    repository: "file://../my-service"
    condition: my-service.enabled

Add default values in the umbrella values.yaml:

my-service:
  enabled: true
  replicaCount: 2
  image:
    tag: ""
  resources:
    requests:
      cpu: "250m"
      memory: "512Mi"

Update dependencies:

helm dependency update infrastructure/helm/matih-data-plane

Common Pitfalls

Pitfall	Solution
Image does not exist in registry	Verify with `docker manifest inspect` before referencing
Security context mismatch	Run `docker run --rm image:tag id` to verify UID
Stale subchart archives	Delete `charts/*.tgz` and `Chart.lock` when removing dependencies
Base values leak through override	Ensure base `values.yaml` has correct defaults for ALL keys
Missing health probe endpoint	Verify endpoint exists in the image with `curl`

Values Management Overview