specweave 0.3.13 → 0.4.0

package/src/skills/helm-chart-scaffolding/SKILL.md

@@ -0,0 +1,544 @@
+---
+name: helm-chart-scaffolding
+description: Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, packaging Kubernetes applications, or implementing templated deployments.
+---
+
+# Helm Chart Scaffolding
+
+Comprehensive guidance for creating, organizing, and managing Helm charts for packaging and deploying Kubernetes applications.
+
+## Purpose
+
+This skill provides step-by-step instructions for building production-ready Helm charts, including chart structure, templating patterns, values management, and validation strategies.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Create new Helm charts from scratch
+- Package Kubernetes applications for distribution
+- Manage multi-environment deployments with Helm
+- Implement templating for reusable Kubernetes manifests
+- Set up Helm chart repositories
+- Follow Helm best practices and conventions
+
+## Helm Overview
+
+**Helm** is the package manager for Kubernetes that:
+- Templates Kubernetes manifests for reusability
+- Manages application releases and rollbacks
+- Handles dependencies between charts
+- Provides version control for deployments
+- Simplifies configuration management across environments
+
+## Step-by-Step Workflow
+
+### 1. Initialize Chart Structure
+
+**Create new chart:**
+```bash
+helm create my-app
+```
+
+**Standard chart structure:**
+```
+my-app/
+├── Chart.yaml           # Chart metadata
+├── values.yaml          # Default configuration values
+├── charts/              # Chart dependencies
+├── templates/           # Kubernetes manifest templates
+│   ├── NOTES.txt       # Post-install notes
+│   ├── _helpers.tpl    # Template helpers
+│   ├── deployment.yaml
+│   ├── service.yaml
+│   ├── ingress.yaml
+│   ├── serviceaccount.yaml
+│   ├── hpa.yaml
+│   └── tests/
+│       └── test-connection.yaml
+└── .helmignore         # Files to ignore
+```
+
+### 2. Configure Chart.yaml
+
+**Chart metadata defines the package:**
+
+```yaml
+apiVersion: v2
+name: my-app
+description: A Helm chart for My Application
+type: application
+version: 1.0.0      # Chart version
+appVersion: "2.1.0" # Application version
+
+# Keywords for chart discovery
+keywords:
+  - web
+  - api
+  - backend
+
+# Maintainer information
+maintainers:
+  - name: DevOps Team
+    email: devops@example.com
+    url: https://github.com/example/my-app
+
+# Source code repository
+sources:
+  - https://github.com/example/my-app
+
+# Homepage
+home: https://example.com
+
+# Chart icon
+icon: https://example.com/icon.png
+
+# Dependencies
+dependencies:
+  - name: postgresql
+    version: "12.0.0"
+    repository: "https://charts.bitnami.com/bitnami"
+    condition: postgresql.enabled
+  - name: redis
+    version: "17.0.0"
+    repository: "https://charts.bitnami.com/bitnami"
+    condition: redis.enabled
+```
+
+**Reference:** See `assets/Chart.yaml.template` for complete example
+
+### 3. Design values.yaml Structure
+
+**Organize values hierarchically:**
+
+```yaml
+# Image configuration
+image:
+  repository: myapp
+  tag: "1.0.0"
+  pullPolicy: IfNotPresent
+
+# Number of replicas
+replicaCount: 3
+
+# Service configuration
+service:
+  type: ClusterIP
+  port: 80
+  targetPort: 8080
+
+# Ingress configuration
+ingress:
+  enabled: false
+  className: nginx
+  hosts:
+    - host: app.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+
+# Resources
+resources:
+  requests:
+    memory: "256Mi"
+    cpu: "250m"
+  limits:
+    memory: "512Mi"
+    cpu: "500m"
+
+# Autoscaling
+autoscaling:
+  enabled: false
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 80
+
+# Environment variables
+env:
+  - name: LOG_LEVEL
+    value: "info"
+
+# ConfigMap data
+configMap:
+  data:
+    APP_MODE: production
+
+# Dependencies
+postgresql:
+  enabled: true
+  auth:
+    database: myapp
+    username: myapp
+
+redis:
+  enabled: false
+```
+
+**Reference:** See `assets/values.yaml.template` for complete structure
+
+### 4. Create Template Files
+
+**Use Go templating with Helm functions:**
+
+**templates/deployment.yaml:**
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "my-app.fullname" . }}
+  labels:
+    {{- include "my-app.labels" . | nindent 4 }}
+spec:
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "my-app.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "my-app.selectorLabels" . | nindent 8 }}
+    spec:
+      containers:
+      - name: {{ .Chart.Name }}
+        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+        imagePullPolicy: {{ .Values.image.pullPolicy }}
+        ports:
+        - name: http
+          containerPort: {{ .Values.service.targetPort }}
+        resources:
+          {{- toYaml .Values.resources | nindent 12 }}
+        env:
+          {{- toYaml .Values.env | nindent 12 }}
+```
+
+### 5. Create Template Helpers
+
+**templates/_helpers.tpl:**
+```yaml
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "my-app.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "my-app.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
+*/}}
+{{- define "my-app.labels" -}}
+helm.sh/chart: {{ include "my-app.chart" . }}
+{{ include "my-app.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "my-app.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "my-app.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+```
+
+### 6. Manage Dependencies
+
+**Add dependencies in Chart.yaml:**
+```yaml
+dependencies:
+  - name: postgresql
+    version: "12.0.0"
+    repository: "https://charts.bitnami.com/bitnami"
+    condition: postgresql.enabled
+```
+
+**Update dependencies:**
+```bash
+helm dependency update
+helm dependency build
+```
+
+**Override dependency values:**
+```yaml
+# values.yaml
+postgresql:
+  enabled: true
+  auth:
+    database: myapp
+    username: myapp
+    password: changeme
+  primary:
+    persistence:
+      enabled: true
+      size: 10Gi
+```
+
+### 7. Test and Validate
+
+**Validation commands:**
+```bash
+# Lint the chart
+helm lint my-app/
+
+# Dry-run installation
+helm install my-app ./my-app --dry-run --debug
+
+# Template rendering
+helm template my-app ./my-app
+
+# Template with values
+helm template my-app ./my-app -f values-prod.yaml
+
+# Show computed values
+helm show values ./my-app
+```
+
+**Validation script:**
+```bash
+#!/bin/bash
+set -e
+
+echo "Linting chart..."
+helm lint .
+
+echo "Testing template rendering..."
+helm template test-release . --dry-run
+
+echo "Checking for required values..."
+helm template test-release . --validate
+
+echo "All validations passed!"
+```
+
+**Reference:** See `scripts/validate-chart.sh`
+
+### 8. Package and Distribute
+
+**Package the chart:**
+```bash
+helm package my-app/
+# Creates: my-app-1.0.0.tgz
+```
+
+**Create chart repository:**
+```bash
+# Create index
+helm repo index .
+
+# Upload to repository
+# AWS S3 example
+aws s3 sync . s3://my-helm-charts/ --exclude "*" --include "*.tgz" --include "index.yaml"
+```
+
+**Use the chart:**
+```bash
+helm repo add my-repo https://charts.example.com
+helm repo update
+helm install my-app my-repo/my-app
+```
+
+### 9. Multi-Environment Configuration
+
+**Environment-specific values files:**
+
+```
+my-app/
+├── values.yaml          # Defaults
+├── values-dev.yaml      # Development
+├── values-staging.yaml  # Staging
+└── values-prod.yaml     # Production
+```
+
+**values-prod.yaml:**
+```yaml
+replicaCount: 5
+
+image:
+  tag: "2.1.0"
+
+resources:
+  requests:
+    memory: "512Mi"
+    cpu: "500m"
+  limits:
+    memory: "1Gi"
+    cpu: "1000m"
+
+autoscaling:
+  enabled: true
+  minReplicas: 3
+  maxReplicas: 20
+
+ingress:
+  enabled: true
+  hosts:
+    - host: app.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+
+postgresql:
+  enabled: true
+  primary:
+    persistence:
+      size: 100Gi
+```
+
+**Install with environment:**
+```bash
+helm install my-app ./my-app -f values-prod.yaml --namespace production
+```
+
+### 10. Implement Hooks and Tests
+
+**Pre-install hook:**
+```yaml
+# templates/pre-install-job.yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ include "my-app.fullname" . }}-db-setup
+  annotations:
+    "helm.sh/hook": pre-install
+    "helm.sh/hook-weight": "-5"
+    "helm.sh/hook-delete-policy": hook-succeeded
+spec:
+  template:
+    spec:
+      containers:
+      - name: db-setup
+        image: postgres:15
+        command: ["psql", "-c", "CREATE DATABASE myapp"]
+      restartPolicy: Never
+```
+
+**Test connection:**
+```yaml
+# templates/tests/test-connection.yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: "{{ include "my-app.fullname" . }}-test-connection"
+  annotations:
+    "helm.sh/hook": test
+spec:
+  containers:
+  - name: wget
+    image: busybox
+    command: ['wget']
+    args: ['{{ include "my-app.fullname" . }}:{{ .Values.service.port }}']
+  restartPolicy: Never
+```
+
+**Run tests:**
+```bash
+helm test my-app
+```
+
+## Common Patterns
+
+### Pattern 1: Conditional Resources
+
+```yaml
+{{- if .Values.ingress.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "my-app.fullname" . }}
+spec:
+  # ...
+{{- end }}
+```
+
+### Pattern 2: Iterating Over Lists
+
+```yaml
+env:
+{{- range .Values.env }}
+- name: {{ .name }}
+  value: {{ .value | quote }}
+{{- end }}
+```
+
+### Pattern 3: Including Files
+
+```yaml
+data:
+  config.yaml: |
+    {{- .Files.Get "config/application.yaml" | nindent 4 }}
+```
+
+### Pattern 4: Global Values
+
+```yaml
+global:
+  imageRegistry: docker.io
+  imagePullSecrets:
+    - name: regcred
+
+# Use in templates:
+image: {{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}
+```
+
+## Best Practices
+
+1. **Use semantic versioning** for chart and app versions
+2. **Document all values** in values.yaml with comments
+3. **Use template helpers** for repeated logic
+4. **Validate charts** before packaging
+5. **Pin dependency versions** explicitly
+6. **Use conditions** for optional resources
+7. **Follow naming conventions** (lowercase, hyphens)
+8. **Include NOTES.txt** with usage instructions
+9. **Add labels** consistently using helpers
+10. **Test installations** in all environments
+
+## Troubleshooting
+
+**Template rendering errors:**
+```bash
+helm template my-app ./my-app --debug
+```
+
+**Dependency issues:**
+```bash
+helm dependency update
+helm dependency list
+```
+
+**Installation failures:**
+```bash
+helm install my-app ./my-app --dry-run --debug
+kubectl get events --sort-by='.lastTimestamp'
+```
+
+## Reference Files
+
+- `assets/Chart.yaml.template` - Chart metadata template
+- `assets/values.yaml.template` - Values structure template
+- `scripts/validate-chart.sh` - Validation script
+- `references/chart-structure.md` - Detailed chart organization
+
+## Related Skills
+
+- `k8s-manifest-generator` - For creating base Kubernetes manifests
+- `gitops-workflow` - For automated Helm chart deployments

package/src/skills/helm-chart-scaffolding/assets/Chart.yaml.template

@@ -0,0 +1,42 @@
+apiVersion: v2
+name: <chart-name>
+description: <Chart description>
+type: application
+version: 0.1.0
+appVersion: "1.0.0"
+
+keywords:
+  - <keyword1>
+  - <keyword2>
+
+home: https://github.com/<org>/<repo>
+
+sources:
+  - https://github.com/<org>/<repo>
+
+maintainers:
+  - name: <Maintainer Name>
+    email: <maintainer@example.com>
+    url: https://github.com/<username>
+
+icon: https://example.com/icon.png
+
+kubeVersion: ">=1.24.0"
+
+dependencies:
+  - name: postgresql
+    version: "12.0.0"
+    repository: "https://charts.bitnami.com/bitnami"
+    condition: postgresql.enabled
+    tags:
+      - database
+  - name: redis
+    version: "17.0.0"
+    repository: "https://charts.bitnami.com/bitnami"
+    condition: redis.enabled
+    tags:
+      - cache
+
+annotations:
+  category: Application
+  licenses: Apache-2.0