helm-charts

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

- Creating a new Helm chart for a Kubernetes application.
- Writing or reviewing Helm templates (`templates/`, `_helpers.tpl`).
- Managing chart dependencies and multi-chart deployments.
- Configuring hooks for lifecycle events (migrations, backups, cleanup).
- Debugging template rendering issues or failed releases.

## Critical Patterns

- **Named Templates in `_helpers.tpl`:** ALWAYS extract reusable label sets, selectors, and name
  logic into named templates. Duplicating labels across resources is a maintenance trap.
- **Values Schema Validation:** Provide a `values.schema.json` to catch misconfiguration early,
  before templates render invalid YAML.
- **Immutable Selectors:** NEVER change `matchLabels` selectors after initial deployment —
  Kubernetes rejects updates to immutable fields and the release breaks.
- **Quote All Strings in Templates:** Use `{{ .Values.foo | quote }}` for string values to prevent
  YAML type coercion (`"true"` becomes boolean `true` without quotes).
- **Resource Naming Conventions:** Include release name in resource names via
  `{{ include "mychart.fullname" . }}` to support multiple installations in the same namespace.
- **Hook Weight and Delete Policy:** Always set `helm.sh/hook-weight` for ordering and
  `helm.sh/hook-delete-policy` to clean up completed hook resources.

## Code Examples

### Chart Structure

```
mychart/
├── Chart.yaml              # Chart metadata and dependencies
├── Chart.lock              # Locked dependency versions (committed)
├── values.yaml             # Default configuration values
├── values.schema.json      # Optional: JSON Schema for values validation
├── templates/
│   ├── _helpers.tpl        # Named template definitions
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── secret.yaml
│   ├── hpa.yaml
│   ├── serviceaccount.yaml
│   └── tests/
│       └── test-connection.yaml
└── charts/                 # Dependency charts (populated by helm dep update)
```

### Chart.yaml

```yaml
apiVersion: v2
name: api-server
description: A Helm chart for the API server application
type: application
version: 0.3.0        # Chart version — bump on template changes
appVersion: "1.2.0"   # Application version — matches container image tag
maintainers:
  - name: platform-team
    email: platform@example.com
dependencies:
  - name: postgresql
    version: "~13.2.0"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
  - name: redis
    version: "~18.6.0"
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled
```

### _helpers.tpl — Named Templates

```yaml
{ { /*
  Chart name, truncated to 63 chars (K8s label limit).
  */ } }
  { { - define "mychart.name" - } }
  { { - default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" } }
  { { - end } }

  { { /*
    Fully qualified app name: release-chartname, truncated.
    */ } }
  { { - define "mychart.fullname" - } }
  { { - if .Values.fullnameOverride } }
  { { - .Values.fullnameOverride | trunc 63 | trimSuffix "-" } }
  { { - else } }
  { { - $name := default .Chart.Name .Values.nameOverride } }
  { { - if contains $name .Release.Name } }
  { { - .Release.Name | trunc 63 | trimSuffix "-" } }
  { { - else } }
  { { - printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" } }
  { { - end } }
  { { - end } }
  { { - end } }

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

  { { /*
    Selector labels — used in both Deployment and Service.
    NEVER change these after first install.
    */ } }
  { { - define "mychart.selectorLabels" - } }
app.kubernetes.io/name: { { include "mychart.name" . } }
app.kubernetes.io/instance: { { .Release.Name } }
  { { - end } }

  { { /*
    Chart label: name-version.
      */ } }
  { { - define "mychart.chart" - } }

From dallay/agents-skills, MIT.

More from dallay/agents-skills