diff --git a/charts/jellyfin/Chart.yaml b/charts/jellyfin/Chart.yaml index d742260..16a7eee 100644 --- a/charts/jellyfin/Chart.yaml +++ b/charts/jellyfin/Chart.yaml @@ -15,4 +15,10 @@ annotations: - kind: added description: Add startup probe to prevent pod restarts during slow initial startup with large media libraries - kind: added + description: Add persistence.cache configuration for dedicated cache volume support + - kind: added + description: Add comprehensive IPv6 and dual-stack networking documentation + - kind: changed + description: Improve health probe configuration examples for IPv6 compatibility + - kind: changed description: Add revisionHistoryLimit parameter to control rollback history retention (defaults to 3 instead of Kubernetes default 10) diff --git a/charts/jellyfin/README.md b/charts/jellyfin/README.md index 10952b6..febdd62 100644 --- a/charts/jellyfin/README.md +++ b/charts/jellyfin/README.md @@ -1,6 +1,6 @@ # jellyfin -![Version: 2.5.0](https://img.shields.io/badge/Version-2.5.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 10.11.2](https://img.shields.io/badge/AppVersion-10.11.2-informational?style=flat-square) +![Version: 2.5.1](https://img.shields.io/badge/Version-2.5.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 10.11.2](https://img.shields.io/badge/AppVersion-10.11.2-informational?style=flat-square) A Helm chart for Jellyfin Media Server @@ -69,7 +69,7 @@ helm install my-jellyfin jellyfin/jellyfin -f values.yaml | jellyfin.command | list | `[]` | Custom command to use as container entrypoint. | | jellyfin.enableDLNA | bool | `false` | Enable DLNA. Requires host network. See: https://jellyfin.org/docs/general/networking/dlna.html | | jellyfin.env | list | `[]` | Additional environment variables for the container. | -| livenessProbe | object | `{"initialDelaySeconds":10,"tcpSocket":{"port":"http"}}` | Configure liveness probe for Jellyfin. | +| livenessProbe | object | `{"httpGet":{"path":"/health","port":"http"},"initialDelaySeconds":10}` | Configure liveness probe for Jellyfin. Uses httpGet for compatibility with both IPv4 and IPv6. | | metrics | object | `{"enabled":false,"serviceMonitor":{"enabled":false,"interval":"30s","labels":{},"metricRelabelings":[],"namespace":"","path":"/metrics","port":8096,"relabelings":[],"scheme":"http","scrapeTimeout":"30s","targetLabels":[],"tlsConfig":{}}}` | Configuration for metrics collection and monitoring | | metrics.enabled | bool | `false` | Enable or disable metrics collection | | metrics.serviceMonitor | object | `{"enabled":false,"interval":"30s","labels":{},"metricRelabelings":[],"namespace":"","path":"/metrics","port":8096,"relabelings":[],"scheme":"http","scrapeTimeout":"30s","targetLabels":[],"tlsConfig":{}}` | Configuration for the Prometheus ServiceMonitor | @@ -87,6 +87,13 @@ helm install my-jellyfin jellyfin/jellyfin -f values.yaml | metrics.serviceMonitor.tlsConfig | object | `{}` | TLS configuration for scraping metrics | | nameOverride | string | `""` | Override the default name of the chart. | | nodeSelector | object | `{}` | Node selector for pod scheduling. | +| persistence.cache.accessMode | string | `"ReadWriteOnce"` | PVC specific settings, only used if type is 'pvc'. | +| persistence.cache.annotations | object | `{}` | Custom annotations to be added to the PVC | +| persistence.cache.enabled | bool | `false` | set to false to use emptyDir | +| persistence.cache.hostPath | string | `""` | Path on the host node for cache storage, only used if type is 'hostPath'. | +| persistence.cache.size | string | `"10Gi"` | | +| persistence.cache.storageClass | string | `""` | If undefined (the default) or set to null, no storageClassName spec is set, choosing the default provisioner. | +| persistence.cache.type | string | `"pvc"` | Type of volume for cache storage (pvc, hostPath, emptyDir). If 'enabled' is false, 'emptyDir' is used regardless of this setting. | | persistence.config.accessMode | string | `"ReadWriteOnce"` | | | persistence.config.annotations | object | `{}` | Custom annotations to be added to the PVC | | persistence.config.enabled | bool | `true` | set to false to use emptyDir | @@ -107,14 +114,14 @@ helm install my-jellyfin jellyfin/jellyfin -f values.yaml | podPrivileges.hostPID | bool | `false` | Enable hostPID namespace. Allows pod to see processes on the host. | | podSecurityContext | object | `{}` | Security context for the pod. | | priorityClassName | string | `""` | Define a priorityClassName for the pod. | -| readinessProbe | object | `{"initialDelaySeconds":10,"tcpSocket":{"port":"http"}}` | Configure readiness probe for Jellyfin. | +| readinessProbe | object | `{"httpGet":{"path":"/health","port":"http"},"initialDelaySeconds":10}` | Configure readiness probe for Jellyfin. Uses httpGet for compatibility with both IPv4 and IPv6. | | replicaCount | int | `1` | Number of Jellyfin replicas to start. Should be left at 1. | | resources | object | `{}` | Resource requests and limits for the Jellyfin container. | | runtimeClassName | string | `""` | Define a custom runtimeClassName for the pod. | | securityContext | object | `{}` | Security context for the container. | | service.annotations | object | `{}` | Annotations for the service. | -| service.ipFamilies | list | `[]` | Supported IP families (IPv4, IPv6). | -| service.ipFamilyPolicy | string | `""` | Configure dual-stack IP family policy. See: https://kubernetes.io/docs/concepts/services-networking/dual-stack/ | +| service.ipFamilies | list | `[]` | Supported IP families (IPv4, IPv6). Examples: IPv4 only: ["IPv4"] IPv6 only: ["IPv6"] Dual-stack (IPv4 primary): ["IPv4", "IPv6"] Dual-stack (IPv6 primary): ["IPv6", "IPv4"] Note: When using IPv6, ensure your health checks are compatible (consider using httpGet instead of tcpSocket) | +| service.ipFamilyPolicy | string | `""` | Configure dual-stack IP family policy. See: https://kubernetes.io/docs/concepts/services-networking/dual-stack/ Options: SingleStack, PreferDualStack, RequireDualStack For IPv6-only clusters, use "SingleStack" with ipFamilies: ["IPv6"] For dual-stack, use "PreferDualStack" or "RequireDualStack" with ipFamilies: ["IPv4", "IPv6"] or ["IPv6", "IPv4"] | | service.labels | object | `{}` | Labels for the service. | | service.loadBalancerClass | string | `""` | Class of the LoadBalancer. | | service.loadBalancerIP | string | `""` | Specific IP address for the LoadBalancer. | @@ -160,3 +167,32 @@ extraVolumeMounts: - name: hwa mountPath: /dev/dri ``` + +## IPv6 Configuration + +This chart supports IPv6 and dual-stack networking configurations out of the box. Health probes use httpGet by default for compatibility with both IPv4 and IPv6. + +### IPv6-only Configuration + +For IPv6-only clusters: + +```yaml +service: + ipFamilyPolicy: SingleStack + ipFamilies: + - IPv6 +``` + +### Dual-stack Configuration + +For dual-stack clusters (both IPv4 and IPv6): + +```yaml +service: + ipFamilyPolicy: PreferDualStack # or RequireDualStack + ipFamilies: + - IPv4 + - IPv6 # First family in the list is the primary +``` + +For more information about Kubernetes dual-stack networking, see: diff --git a/charts/jellyfin/README.md.gotmpl b/charts/jellyfin/README.md.gotmpl index ee08a35..90546e6 100644 --- a/charts/jellyfin/README.md.gotmpl +++ b/charts/jellyfin/README.md.gotmpl @@ -85,3 +85,32 @@ extraVolumeMounts: - name: hwa mountPath: /dev/dri ``` + +## IPv6 Configuration + +This chart supports IPv6 and dual-stack networking configurations out of the box. Health probes use httpGet by default for compatibility with both IPv4 and IPv6. + +### IPv6-only Configuration + +For IPv6-only clusters: + +```yaml +service: + ipFamilyPolicy: SingleStack + ipFamilies: + - IPv6 +``` + +### Dual-stack Configuration + +For dual-stack clusters (both IPv4 and IPv6): + +```yaml +service: + ipFamilyPolicy: PreferDualStack # or RequireDualStack + ipFamilies: + - IPv4 + - IPv6 # First family in the list is the primary +``` + +For more information about Kubernetes dual-stack networking, see: diff --git a/charts/jellyfin/templates/NOTES.txt b/charts/jellyfin/templates/NOTES.txt index e60ef26..1f2f807 100644 --- a/charts/jellyfin/templates/NOTES.txt +++ b/charts/jellyfin/templates/NOTES.txt @@ -37,6 +37,45 @@ Startup Configuration: ⚠ NOTE: Startup timeout is very long ({{ div $startupTimeout 60 }}+ minutes). Consider optimizing your media library or reducing failureThreshold. {{- end }} +Persistence Configuration: + Config: {{ if .Values.persistence.config.enabled }}{{ .Values.persistence.config.type | default "pvc" }}{{ if .Values.persistence.config.existingClaim }} (existing: {{ .Values.persistence.config.existingClaim }}){{ end }}{{ else }}emptyDir{{ end }} + Media: {{ if .Values.persistence.media.enabled }}{{ .Values.persistence.media.type | default "pvc" }}{{ if .Values.persistence.media.existingClaim }} (existing: {{ .Values.persistence.media.existingClaim }}){{ end }}{{ else }}emptyDir{{ end }} + Cache: {{ if .Values.persistence.cache.enabled }}{{ .Values.persistence.cache.type | default "pvc" }}{{ if .Values.persistence.cache.existingClaim }} (existing: {{ .Values.persistence.cache.existingClaim }}){{ end }}{{ else }}emptyDir{{ end }} + +{{- if and .Values.persistence.cache.enabled (eq .Values.persistence.cache.type "pvc") }} +Cache Volume: + Dedicated cache volume is enabled for improved performance. + Size: {{ .Values.persistence.cache.size }} + Access Mode: {{ .Values.persistence.cache.accessMode }} + {{- if .Values.persistence.cache.storageClass }} + Storage Class: {{ .Values.persistence.cache.storageClass }} + {{- end }} + + Benefits: + - Faster transcoding and metadata operations + - Separate cache lifecycle from config/media + - Can use faster storage class (SSD) for cache +{{- end }} + +{{- if and .Values.persistence.cache.enabled (eq .Values.persistence.cache.type "hostPath") }} +⚠ WARNING: Using hostPath for cache - ensure {{ .Values.persistence.cache.hostPath }} exists on the node +{{- if or .Values.service.ipFamilyPolicy .Values.service.ipFamilies }} + +Service IP Configuration: +{{- if .Values.service.ipFamilyPolicy }} + IP Family Policy: {{ .Values.service.ipFamilyPolicy }} +{{- end }} +{{- if .Values.service.ipFamilies }} + IP Families: {{ .Values.service.ipFamilies | join ", " }} + {{- if eq (index .Values.service.ipFamilies 0) "IPv6" }} + ⚠ NOTE: IPv6 primary - ensure your probes use httpGet instead of tcpSocket for compatibility + {{- end }} + {{- if has "IPv6" .Values.service.ipFamilies }} + {{- if not .Values.service.ipFamilyPolicy }} + ⚠ WARNING: ipFamilies includes IPv6 but ipFamilyPolicy is not set + {{- end }} + {{- end }} +{{- end }} {{- end }} Deployment Configuration: Revision History Limit: {{ .Values.revisionHistoryLimit }} diff --git a/charts/jellyfin/templates/deployment.yaml b/charts/jellyfin/templates/deployment.yaml index dba9529..a36d5e0 100644 --- a/charts/jellyfin/templates/deployment.yaml +++ b/charts/jellyfin/templates/deployment.yaml @@ -126,6 +126,8 @@ spec: name: config - mountPath: /media name: media + - mountPath: /cache + name: cache {{- with .Values.volumeMounts }} {{- toYaml . | nindent 12 }} {{- end }} @@ -159,6 +161,21 @@ spec: {{- else }} emptyDir: {} {{- end }} + - name: cache + {{- if .Values.persistence.cache.enabled }} + {{- if eq .Values.persistence.cache.type "pvc" }} + persistentVolumeClaim: + claimName: {{ if .Values.persistence.cache.existingClaim }}{{ .Values.persistence.cache.existingClaim }}{{- else }}{{ template "jellyfin.fullname" . }}-cache{{- end }} + {{- else if eq .Values.persistence.cache.type "hostPath" }} + hostPath: + path: {{ .Values.persistence.cache.hostPath }} + type: Directory + {{- else }} + emptyDir: {} + {{- end }} + {{- else }} + emptyDir: {} + {{- end }} {{- with .Values.volumes }} {{- toYaml . | nindent 8 }} {{- end }} diff --git a/charts/jellyfin/templates/persistentVolumeClaim.yaml b/charts/jellyfin/templates/persistentVolumeClaim.yaml index 709436d..64ad819 100644 --- a/charts/jellyfin/templates/persistentVolumeClaim.yaml +++ b/charts/jellyfin/templates/persistentVolumeClaim.yaml @@ -43,3 +43,26 @@ spec: storageClassName: {{ . | quote }} {{- end }} {{- end }} + +{{- if and .Values.persistence.cache.enabled (eq .Values.persistence.cache.type "pvc") (not .Values.persistence.cache.existingClaim) }} +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: {{ include "jellyfin.fullname" . }}-cache + labels: + {{- include "jellyfin.labels" . | nindent 4 }} + {{- with .Values.persistence.cache.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + accessModes: + - {{ .Values.persistence.cache.accessMode | quote }} + resources: + requests: + storage: {{ .Values.persistence.cache.size | quote }} + {{- with .Values.persistence.cache.storageClass }} + storageClassName: {{ . | quote }} + {{- end }} +{{- end }} diff --git a/charts/jellyfin/tests/cache_persistence_test.yaml b/charts/jellyfin/tests/cache_persistence_test.yaml new file mode 100644 index 0000000..fafcf9e --- /dev/null +++ b/charts/jellyfin/tests/cache_persistence_test.yaml @@ -0,0 +1,160 @@ +suite: test cache persistence +templates: + - deployment.yaml + - persistentVolumeClaim.yaml +tests: + # Deployment volume mount tests + - it: should mount cache as emptyDir by default + template: deployment.yaml + asserts: + - contains: + path: spec.template.spec.volumes + content: + name: cache + emptyDir: {} + + - it: should mount cache PVC when enabled + template: deployment.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + asserts: + - contains: + path: spec.template.spec.volumes + content: + name: cache + persistentVolumeClaim: + claimName: RELEASE-NAME-jellyfin-cache + + - it: should mount cache from hostPath when configured + template: deployment.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: hostPath + persistence.cache.hostPath: /mnt/jellyfin-cache + asserts: + - contains: + path: spec.template.spec.volumes + content: + name: cache + hostPath: + path: /mnt/jellyfin-cache + + - it: should mount cache at correct path + template: deployment.yaml + asserts: + - contains: + path: spec.template.spec.containers[0].volumeMounts + content: + name: cache + mountPath: /cache + + # PVC tests + - it: should not create cache PVC by default + template: persistentVolumeClaim.yaml + asserts: + - hasDocuments: + count: 2 # config and media only + + - it: should create cache PVC when enabled + template: persistentVolumeClaim.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + asserts: + - hasDocuments: + count: 3 # config, media, and cache + - contains: + path: metadata.name + content: RELEASE-NAME-jellyfin-cache + + - it: should not create cache PVC when type is hostPath + template: persistentVolumeClaim.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: hostPath + asserts: + - hasDocuments: + count: 2 # config and media only + + - it: should not create cache PVC when type is emptyDir + template: persistentVolumeClaim.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: emptyDir + asserts: + - hasDocuments: + count: 2 + + - it: should set cache PVC size correctly + template: persistentVolumeClaim.yaml + documentIndex: 2 + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + persistence.cache.size: 20Gi + asserts: + - equal: + path: spec.resources.requests.storage + value: 20Gi + + - it: should set cache PVC access mode + template: persistentVolumeClaim.yaml + documentIndex: 2 + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + persistence.cache.accessMode: ReadWriteMany + asserts: + - contains: + path: spec.accessModes + content: ReadWriteMany + + - it: should set cache PVC storage class + template: persistentVolumeClaim.yaml + documentIndex: 2 + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + persistence.cache.storageClass: fast-ssd + asserts: + - equal: + path: spec.storageClassName + value: fast-ssd + + - it: should add annotations to cache PVC + template: persistentVolumeClaim.yaml + documentIndex: 2 + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + persistence.cache.annotations: + my-annotation: my-value + asserts: + - equal: + path: metadata.annotations.my-annotation + value: my-value + + - it: should use existing claim when specified + template: deployment.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + persistence.cache.existingClaim: my-existing-cache-claim + asserts: + - contains: + path: spec.template.spec.volumes + content: + name: cache + persistentVolumeClaim: + claimName: my-existing-cache-claim + + - it: should not create PVC when existing claim used + template: persistentVolumeClaim.yaml + set: + persistence.cache.enabled: true + persistence.cache.type: pvc + persistence.cache.existingClaim: my-existing-cache-claim + asserts: + - hasDocuments: + count: 2 # config and media only, not cache diff --git a/charts/jellyfin/tests/service_ipv6_test.yaml b/charts/jellyfin/tests/service_ipv6_test.yaml new file mode 100644 index 0000000..5dee731 --- /dev/null +++ b/charts/jellyfin/tests/service_ipv6_test.yaml @@ -0,0 +1,128 @@ +suite: test service ipv6 and dual-stack +templates: + - service.yaml +tests: + - it: should not set ipFamilyPolicy by default + asserts: + - isNull: + path: spec.ipFamilyPolicy + + - it: should not set ipFamilies by default + asserts: + - isNull: + path: spec.ipFamilies + + - it: should set ipFamilyPolicy when specified + set: + service.ipFamilyPolicy: PreferDualStack + asserts: + - equal: + path: spec.ipFamilyPolicy + value: PreferDualStack + + - it: should support SingleStack policy + set: + service.ipFamilyPolicy: SingleStack + asserts: + - equal: + path: spec.ipFamilyPolicy + value: SingleStack + + - it: should support RequireDualStack policy + set: + service.ipFamilyPolicy: RequireDualStack + asserts: + - equal: + path: spec.ipFamilyPolicy + value: RequireDualStack + + - it: should set ipFamilies for IPv4 only + set: + service.ipFamilies: + - IPv4 + asserts: + - equal: + path: spec.ipFamilies[0] + value: IPv4 + + - it: should set ipFamilies for IPv6 only + set: + service.ipFamilies: + - IPv6 + asserts: + - equal: + path: spec.ipFamilies[0] + value: IPv6 + + - it: should set ipFamilies for dual-stack IPv4 primary + set: + service.ipFamilies: + - IPv4 + - IPv6 + asserts: + - equal: + path: spec.ipFamilies[0] + value: IPv4 + - equal: + path: spec.ipFamilies[1] + value: IPv6 + + - it: should set ipFamilies for dual-stack IPv6 primary + set: + service.ipFamilies: + - IPv6 + - IPv4 + asserts: + - equal: + path: spec.ipFamilies[0] + value: IPv6 + - equal: + path: spec.ipFamilies[1] + value: IPv4 + + - it: should work with PreferDualStack and both families + set: + service.ipFamilyPolicy: PreferDualStack + service.ipFamilies: + - IPv4 + - IPv6 + asserts: + - equal: + path: spec.ipFamilyPolicy + value: PreferDualStack + - equal: + path: spec.ipFamilies[0] + value: IPv4 + - equal: + path: spec.ipFamilies[1] + value: IPv6 + + - it: should work with RequireDualStack and both families + set: + service.ipFamilyPolicy: RequireDualStack + service.ipFamilies: + - IPv6 + - IPv4 + asserts: + - equal: + path: spec.ipFamilyPolicy + value: RequireDualStack + - equal: + path: spec.ipFamilies[0] + value: IPv6 + - equal: + path: spec.ipFamilies[1] + value: IPv4 + + - it: should work with SingleStack IPv6 only + set: + service.ipFamilyPolicy: SingleStack + service.ipFamilies: + - IPv6 + asserts: + - equal: + path: spec.ipFamilyPolicy + value: SingleStack + - equal: + path: spec.ipFamilies[0] + value: IPv6 diff --git a/charts/jellyfin/values.yaml b/charts/jellyfin/values.yaml index f501e47..8508198 100644 --- a/charts/jellyfin/values.yaml +++ b/charts/jellyfin/values.yaml @@ -91,8 +91,17 @@ service: # -- Service type (ClusterIP, NodePort, or LoadBalancer). type: ClusterIP # -- Configure dual-stack IP family policy. See: https://kubernetes.io/docs/concepts/services-networking/dual-stack/ + # Options: SingleStack, PreferDualStack, RequireDualStack + # For IPv6-only clusters, use "SingleStack" with ipFamilies: ["IPv6"] + # For dual-stack, use "PreferDualStack" or "RequireDualStack" with ipFamilies: ["IPv4", "IPv6"] or ["IPv6", "IPv4"] ipFamilyPolicy: "" # -- Supported IP families (IPv4, IPv6). + # Examples: + # IPv4 only: ["IPv4"] + # IPv6 only: ["IPv6"] + # Dual-stack (IPv4 primary): ["IPv4", "IPv6"] + # Dual-stack (IPv6 primary): ["IPv6", "IPv4"] + # Note: When using IPv6, ensure your health checks are compatible (consider using httpGet instead of tcpSocket) ipFamilies: [] # -- Specific IP address for the LoadBalancer. loadBalancerIP: "" @@ -153,10 +162,12 @@ startupProbe: # -- Configure liveness probe for Jellyfin. # This probe is disabled during startup (startup probe handles initial checks). +# Uses httpGet for compatibility with both IPv4 and IPv6. livenessProbe: - initialDelaySeconds: 10 - tcpSocket: + httpGet: + path: /health port: http + initialDelaySeconds: 10 # successThreshold: 1 # failureThreshold: 3 # timeoutSeconds: 1 @@ -164,10 +175,12 @@ livenessProbe: # -- Configure readiness probe for Jellyfin. # This probe is disabled during startup (startup probe handles initial checks). +# Uses httpGet for compatibility with both IPv4 and IPv6. readinessProbe: - initialDelaySeconds: 10 - tcpSocket: + httpGet: + path: /health port: http + initialDelaySeconds: 10 # successThreshold: 1 # failureThreshold: 3 # timeoutSeconds: 1 @@ -242,6 +255,22 @@ persistence: storageClass: '' ## -- Use an existing PVC for this mount # existingClaim: '' + cache: + # -- set to false to use emptyDir + enabled: false + # -- Type of volume for cache storage (pvc, hostPath, emptyDir). If 'enabled' is false, 'emptyDir' is used regardless of this setting. + type: pvc + # -- Path on the host node for cache storage, only used if type is 'hostPath'. + hostPath: "" + # -- PVC specific settings, only used if type is 'pvc'. + accessMode: ReadWriteOnce + size: 10Gi + # -- Custom annotations to be added to the PVC + annotations: {} + # -- If undefined (the default) or set to null, no storageClassName spec is set, choosing the default provisioner. + storageClass: '' + ## -- Use an existing PVC for this mount + # existingClaim: '' # -- Configuration for metrics collection and monitoring metrics: