kube-cluster/.claude/commands/helm-adapt.md

Adapt a Helm chart's values.yaml for this cluster. The user will provide the service name or path.

Cluster facts (always apply these)

• Node: single Raspberry Pi, hostname master, arch aarch64
• Ingress controller: Traefik — use ingressClassName: traefik
• TLS: cert-manager with cluster issuer letsencrypt-prod (HTTP-01 only — no wildcard certs)
• Domain pattern: <service>.immich-ad.ovh
• StorageClass: local-storage (no-provisioner, WaitForFirstConsumer)
• Storage root: /storage/<service>/
• PV/PVC pattern: pre-create PVs manually; StatefulSets use volumeClaimTemplates (add claimRef); Deployments use standalone PVCs referenced via existingClaim
• Images: prefer arm64 or multi-arch images; replace any amd64-specific image tags

Ingress block template

ingress:
  main:  # or the chart's ingress key name
    enabled: true
    ingressClassName: traefik
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
    hosts:
      - host: <service>.immich-ad.ovh
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: <service>-tls
        hosts:
          - <service>.immich-ad.ovh

PV template (for Deployments with existingClaim)

# pv-<service>.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-<service>
spec:
  capacity:
    storage: <size>
  volumeMode: Filesystem
  accessModes:
  - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-storage
  local:
    path: /storage/<service>
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
          - master

PV template (for StatefulSets — claimRef binds to auto-created PVC)

# pv-<service>.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-<service>-data
spec:
  capacity:
    storage: <size>
  volumeMode: Filesystem
  accessModes:
  - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-storage
  local:
    path: /storage/<service>/data
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
          - master
  claimRef:
    name: data-<release>-0    # matches StatefulSet volumeClaimTemplate
    namespace: <namespace>

PVC template (for Deployments)

# pvc-<service>.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-<service>
  namespace: <namespace>
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: <size>
  storageClassName: local-storage

Steps to follow

1. Read the chart's values.yaml (and README.md if present) to understand available keys.
2. Read an existing service's values file (e.g. ../vaultwarden/values.yaml) if the chart type is similar.
3. Apply all cluster facts above:
   • Set ingress to traefik + letsencrypt-prod + correct host
   • Set storageClass to local-storage
   • Set replicaCount to 1
   • Fix any amd64 image to arm64 equivalent
4. Create pv-<service>.yaml in the service folder with correct path and sizes.
5. Create pvc-<service>.yaml only if the workload is a Deployment (not StatefulSet).
6. Create NOTE.md with helm install/upgrade/delete commands, PV apply commands, and useful kubectl check/log commands — following the style of ../immich/notes.md.