fukuops/k8s/charts/_template/README.md

chart

A Helm chart template with standardized structure for self-hosted services.

TL;DR

helm install chart oci://git.roboces.dev/catalin/fukuops/chart --version 1.0.1 -n apps-roboces

Prerequisites

• Kubernetes 1.19+
• Helm 3+
• A NFS storage class (default: truenas-nfs-csi) - only if persistence is enabled
• An existing Secret with credentials if required (see secret.existingSecretName)

Configuration

All values are nested under the chart: key. Example:

chart:
  replicaCount: 1
  service:
    type: LoadBalancer
    port: 80
  ingress:
    enabled: true
    className: "traefik"
    hosts:
      - host: chart.example.com
        paths:
          - path: /
            pathType: Prefix
  config:
    # Key-value pairs that will be mapped to env vars (uppercased)
    # Example: `FOO: "bar"` becomes env var FOO=bar
  persistence:
    enabled: true
    storageClass: "truenas-nfs-csi"
    accessMode: ReadWriteMany
    size: 10Gi
  secret:
    existingSecretName: chart-secrets

Values Reference

Key	Type	Default	Description
chart.replicaCount	int	1	Number of replicas
chart.image.repository	string	nginx	Image repository
chart.image.pullPolicy	string	IfNotPresent	Image pull policy
chart.image.tag	string	.Chart.AppVersion	Image tag
chart.service.type	string	LoadBalancer	Service type
chart.service.port	int	80	Service port
chart.service.targetPort	int	80	Container port
chart.ingress.enabled	bool	false	Enable ingress
chart.ingress.className	string	traefik	Ingress class
chart.config	object	{}	Config key-value pairs mapped to env vars
chart.persistence.enabled	bool	false	Enable persistence
chart.persistence.storageClass	string	truenas-nfs-csi	Storage class
chart.persistence.accessMode	string	ReadWriteMany	Access mode
chart.persistence.size	string	1Gi	PVC size
chart.persistence.name	string	chart-data	PVC name
chart.secret.existingSecretName	string	""	Existing secret name
chart.debug.enabled	bool	false	Enable debug mode (adds init container for troubleshooting)
chart.resources	object	{}	Container resources
chart.livenessProbe	object	(see values.yaml)	Liveness probe
chart.readinessProbe	object	(see values.yaml)	Readiness probe
chart.nodeSelector	object	{}	Node selector
chart.tolerations	array	[]	Tolerations
chart.affinity	object	{}	Affinity rules

ConfigMap

The config: section creates a ConfigMap that maps keys to environment variables. Keys are uppercased.

chart:
  config:
    FOO: "bar"
    BAZ: "qux"

This creates env vars FOO=bar and BAZ=qux.

Persistence

When persistence is enabled, a PVC named chart-data is created. The PVC uses the truenas-nfs-csi storage class by default with ReadWriteMany access mode.

Secret Management

The chart looks for an existing Secret with the name specified in chart.secret.existingSecretName. If not provided, no secret is mounted.

Troubleshooting

Debug Mode

Enable debug mode to troubleshoot issues by adding an init container with a shell:

chart:
  debug:
    enabled: true

This adds an alpine:3.19 init container with sleep infinity that mounts all volumes and inherits env vars. You can exec into it to inspect the environment:

kubectl exec -it <pod-name> -c debug -- sh

When debug mode is enabled, liveness and readiness probes are disabled to prevent restarts.

Pod not starting

kubectl get pvc -n apps-roboces -l app.kubernetes.io/name=chart

Check logs

kubectl logs chart-0 -n apps-roboces

Verify configmap

kubectl get configmap chart-config -n apps-roboces -o yaml