ytdlp-web-player: new chart with an optional oauth2-proxy subchart (1.0.0+upv1.2.0)

Deploys matszwe02/ytdlp_web_player, a Flask app that fetches videos with
yt-dlp, transcodes them with ffmpeg and serves them as HLS. It ships no
authentication of any kind, so the chart carries a preconfigured oauth2-proxy
as an optional subchart, in the data path in front of the app.

This is the first chart in the repo with a dependency, so the rule "charts
have no dependencies" falls here. It is replaced in CLAUDE.md and README.md by
a bar: a dependency has to be optional and off by default, upstream's chart is
consumed as it comes (documented where it falls short of our conventions,
never patched), and the price is written down - above all that a subchart is
invisible to everything downstream watching Helm release versions, so a new
proxy release only reaches a cluster when this chart is republished.

CI learns the dependency in five places, not the three the plan expected:
helm lint, package, template and install all exit 1 while charts/ is unfilled,
so ci/helm-dependencies.sh runs before lint and package in validate-charts.yml,
before package in publish-helm-chart.yml, and inside run-install-test.sh,
run-trivy-config.sh and run-quantity-render-test.sh - the last of which renders
every chart on every PR and would have gone red first.

Notable chart decisions, each measured rather than assumed:

- The image has no USER and runs as root by default, but not by necessity: it
  runs under an arbitrary uid with readOnlyRootFilesystem and the full
  hardening baseline. Only the pinned uid is a deviation, and it is documented.
- Two emptyDirs, each justified separately. /data holds the video cache
  (DATA_PATH). /tmp is NOT mounted - measured across metadata extraction, HLS
  transcoding, sprite generation and audio extraction, the image never writes
  there. What it does write is $HOME/.cache, so /cache is mounted with HOME and
  XDG_CACHE_HOME pointed at it; without it yt-dlp re-downloads its JavaScript
  challenge-solver from github.com on every extraction.
- The proxy is wired through config.configFile, the only value the subchart
  passes through tpl - config.upstreams is emitted with toJson and would carry
  a literal {{ .Release.Name }} into the manifest.
- Rendering aborts when this chart's Ingress and the proxy's claim the same
  host: ingress-nginx rejects the second one and a Fleet bundle then sits in
  ErrApplied until forceSyncGeneration is bumped.

Fixes #214

ytdlp-web-player/templates/NOTES.txt

@@ -0,0 +1,243 @@
+{{- $replicas := include "ytdlp-web-player.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.ytdlpWebPlayer.replicas) -}}
+{{- $res := fromYaml (include "ytdlp-web-player.effectiveResources" .Values.ytdlpWebPlayer.resources) -}}
+{{- $eph := index ($res.limits | default dict) "ephemeral-storage" | default "the computed ephemeral-storage limit" -}}
+{{- $startup := fromYaml (include "ytdlp-web-player.startupProbe" .Values.ytdlpWebPlayer.startupProbe) -}}
+{{- $proxy := (index .Values "oauth2-proxy") | default dict -}}
+{{- $proxyIngress := $proxy.ingress | default dict -}}
+{{- $proxyHost := first ($proxyIngress.hosts | default list) -}}
+{{- $env := dict -}}
+{{- range $entry := .Values.ytdlpWebPlayer.env }}
+{{- if not (kindIs "invalid" $entry.value) }}{{- $_ := set $env $entry.name $entry.value }}{{- end }}
+{{- end }}
+ytdlp_web_player {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
+{{- if $proxy.enabled }} With the oauth2-proxy subchart enabled.{{ end }}
+
+{{- if and $proxy.enabled $proxyIngress.enabled }}
+
+ACCESS — THROUGH THE PROXY
+  https://{{ $proxyHost | default "<oauth2-proxy.ingress.hosts is empty>" }}
+
+  The Ingress belongs to the proxy, the proxy forwards to
+  {{ include "ytdlp-web-player.appServiceAddress" . }}, and that Service is the only
+  way into the application. Certificate and TLS secret are the subchart's too —
+  this chart's ingress.clusterIssuer does not reach it; set the cert-manager
+  annotation under oauth2-proxy.ingress.annotations.
+{{- else if .Values.ingress.enabled }}
+
+ACCESS
+  https://{{ .Values.ingress.domain }}
+
+  The certificate is requested by cert-manager through the "{{ .Values.ingress.clusterIssuer }}"
+  cluster issuer. Until it has been issued the browser shows a warning; follow it with
+
+    kubectl -n {{ .Release.Namespace }} get certificate tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+{{- else }}
+
+ACCESS — NO INGRESS
+  ingress.enabled is false, so this release has no Ingress and no certificate.
+  Both ingress.domain and ingress.clusterIssuer are unnecessary here — unlike
+  in some other charts in this repo, nothing outside the Ingress template reads
+  the domain: this application builds no absolute URLs and has no base-URL
+  setting. Reach it inside the cluster:
+
+    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8080:80
+
+  Then open http://localhost:8080.
+{{- end }}
+{{ if eq $replicas "0" }}
+SCALED TO ZERO
+  {{ if .Values.scaleDown }}scaleDown: true{{ else }}ytdlpWebPlayer.replicas: 0{{ end }} — the Deployment runs with replicas: 0, so nothing answers
+  until you set it back and upgrade again. Service{{ if .Values.ingress.enabled }} and Ingress stay in place,
+  so the certificate is not re-issued.{{ else }} stays in place.{{ end }} Nothing is lost that was not
+  going to be lost anyway: the video cache is an emptyDir (see below).
+  {{- if $proxy.enabled }}
+  Note that scaleDown does NOT reach the subchart — the proxy keeps running and
+  will answer with a gateway error. Set oauth2-proxy.replicaCount: 0 as well.
+  {{- end }}
+{{ end }}
+{{- if and .Values.ingress.enabled (not $proxy.enabled) }}
+THIS RELEASE IS OPEN TO EVERYONE WHO KNOWS THE URL
+  The application has NO authentication of any kind, and this chart adds none
+  while oauth2-proxy.enabled is false. What an anonymous visitor can do here is
+  not "read a page": they can make this pod fetch and transcode arbitrary
+  videos from the internet — your egress, your CPU, your IP address in the
+  logs of whatever site is being pulled from, and your ephemeral storage.
+
+  Assume it is found. Hosts get scanned, and certificate transparency logs
+  publish every name cert-manager requests, so "nobody knows the URL" has a
+  half-life of hours.
+
+  The intended fix is in this chart:
+
+    oauth2-proxy:
+      enabled: true
+      ingress:
+        enabled: true
+        hosts: ["{{ .Values.ingress.domain }}"]
+    ingress:
+      enabled: false          # the proxy owns the host from then on
+
+  Anything else in front of it — an ingress-nginx auth annotation, a network
+  policy, a VPN-only ingress class — has to come from ingress.annotations or
+  from outside this chart.
+{{- end }}
+{{- if and $proxy.enabled .Values.ingress.enabled }}
+
+WARNING — THE APP'S OWN INGRESS IS A WAY PAST THE PROXY
+  Both oauth2-proxy.enabled and ingress.enabled are true. The chart only
+  refuses this when both claim the SAME host; here they do not, so it renders —
+  but https://{{ .Values.ingress.domain }} reaches the application directly, with no
+  authentication in front of it, whatever the proxy does on its own host.
+  Unless that is deliberate, set ingress.enabled=false.
+{{- end }}
+{{- if $proxy.enabled }}
+
+THE PROXY IS A SUBCHART, AND THAT HAS TWO CONSEQUENCES
+  1. Its version comes from THIS chart's Chart.yaml (oauth2-proxy {{ (first .Chart.Dependencies).Version | default "" }}) and is
+     baked into the packaged chart. Nothing that watches Helm release versions
+     can see it, so a new proxy release — a security fix included — arrives
+     only when a new ytdlp-web-player version is released. There is no second
+     place that would notice; do not wait for one.
+  2. Its templates are upstream's. It does not follow this repo's hardening,
+     probe and resource conventions, and we deliberately do not patch it. Give
+     it values (oauth2-proxy.resources, .securityContext, …) if you want that
+     shape.
+
+SECRETS — WHAT THE 1PASSWORD ITEM MUST CARRY
+  {{ if .Values.secrets.oauth2ProxySecretRef }}{{ .Values.secrets.oauth2ProxySecretRef }}{{ else }}(secrets.oauth2ProxySecretRef is not set){{ end }}
+    → Secret {{ .Release.Name }}-{{ .Chart.Name }}-oauth2-proxy-secret
+      client-id       the OIDC client id
+      client-secret   its secret
+      cookie-secret   16, 24 or 32 bytes, URL-SAFE base64
+
+  The operator copies the item's FIELD NAMES into the Secret's keys, so those
+  three spellings are exact. A field named differently does not fail this
+  install — the Secret is written without that key and the proxy pod sits in
+  CreateContainerConfigError, which looks like a broken chart.
+
+  Generate the cookie secret as
+
+    openssl rand -base64 32 | tr '+/' '-_'
+
+  The tr is not cosmetic: oauth2-proxy decodes the value as URL-safe base64
+  first, so a standard-base64 value containing + or / fails to decode and the
+  pod exits with "cookie_secret must be 16, 24, or 32 bytes".
+
+  Repointing secrets.oauth2ProxySecretRef at a different item does NOT restart
+  the proxy — the subchart's pod template is unchanged by it, and Helm never
+  sees a Secret's content anyway:
+
+    kubectl -n {{ .Release.Namespace }} rollout restart deployment/{{ .Release.Name }}-oauth2-proxy
+
+THE PROVIDER IS THE ONLY GATE, AND IT IS WIDER THAN IT LOOKS
+  The proxy is configured with email_domains = ["*"], so it admits every
+  identity the provider hands it. Which people that is, is decided ENTIRELY by
+  the group or policy binding on the provider application — and this app has no
+  second login behind the proxy, unlike the other instances in the cluster. A
+  forgotten or too-wide binding therefore does not mean "one more user", it
+  means every account the provider knows. Check that binding when you set this
+  up, not later.
+
+  Two settings in the default configFile are load-bearing; do not remove them
+  while trimming:
+    reverse_proxy = true             else every redirect is built on http://
+                                     behind the TLS ingress — a loop
+    session_cookie_minimal = true    else id_token and access_token go into the
+                                     session cookie, a longer group list pushes
+                                     it past 4kB, and the browser drops it: the
+                                     symptom is HTTP 502 AFTER a successful
+                                     login, with [AuthSuccess] in the log
+  Its companion belongs on the proxy's Ingress:
+    nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"
+
+  And leave alphaConfig.enabled false. With it on, the subchart generates a
+  config WITHOUT upstreams and ignores config.configFile silently — the login
+  succeeds and the app answers 404.
+
+NOT MEASURED: HLS PLAYBACK THROUGH THE PROXY
+  Rendering and wiring are verified; a long HLS stream through proxy and
+  ingress is not. Three places to look first if playback stalls where a direct
+  ingress works: proxy-buffering in ingress-nginx, its 60-second
+  proxy-read/send timeouts, and the proxy's own upstream timeout. Browser
+  extension and PWA are unverified too — an expired session answers with a
+  redirect to the provider, not a 401, and a fetch() sees only an opaque
+  redirect.
+{{- end }}
+
+A READY POD DOES NOT MEAN A VIDEO WILL PLAY
+  All three probes request "/", which renders the player page and touches
+  neither the network nor ffmpeg. That is on purpose — it is the only cheap
+  path the app has, and it keeps a slow upstream site from restarting the pod.
+  The price is that egress problems are invisible to Kubernetes: with DNS
+  broken or outbound traffic blocked, "/" still answers 200, the rollout goes
+  green, and every playback fails. Check it from the outside instead:
+
+    kubectl -n {{ .Release.Namespace }} logs deployment/{{ .Release.Name }}-{{ .Chart.Name }}-deployment
+
+  A failing fetch shows up there as a yt-dlp error line, never as a probe
+  failure. The startup budget is {{ $startup.periodSeconds }}s x {{ $startup.failureThreshold }} = {{ mul $startup.periodSeconds $startup.failureThreshold }}s, which only has to
+  cover the first process start.
+
+THE VIDEO CACHE IS AN emptyDir — AND IT IS AN EVICTION RISK, NOT A DISK
+  DATA_PATH is /data, backed by an emptyDir. Two things follow:
+
+  Nothing survives. A restart, a node drain, an eviction or a helm upgrade
+  empties it, and every cached video is fetched again on demand. That is the
+  intended shape — the app expires files by itself after MAX_VIDEO_AGE — but do
+  not treat it as storage.
+
+  An emptyDir counts against the container's ephemeral-storage limit
+  ({{ $eph }}){{ if (.Values.storage).dataSizeLimit }}, and storage.dataSizeLimit ({{ (.Values.storage).dataSizeLimit }}) caps it a second time{{ end }}. Going over it is not an
+  application error: the kubelet evicts the whole pod, the reason sits on the
+  pod rather than in any log, and everything in flight goes with it. Raising
+  the limit is the wrong first move — the knobs that decide how much lands
+  there are in ytdlpWebPlayer.env:
+
+    MAX_VIDEO_DURATION   upstream default 36000 (ten hours, one enormous file)
+    MAX_VIDEO_AGE        upstream default 3600 (seconds after last access)
+    MAX_PROCESSES        upstream default 5 (concurrent ffmpeg/yt-dlp)
+
+  Currently set here: {{ if $env }}{{ range $k, $v := $env }}{{ $k }}={{ $v }} {{ end }}{{ else }}none — all upstream defaults apply{{ end }}
+
+yt-dlp DOES NOT UPDATE ITSELF IN THIS CHART
+  On start and periodically the app runs "pip install --upgrade yt-dlp" into
+  its own site-packages. With readOnlyRootFilesystem: true that write cannot
+  happen; the app catches the failure and carries on with the version baked
+  into the image (verified — the container starts, serves and transcodes
+  normally, the update attempt just does nothing).
+
+  This is the right trade in a cluster — a pod that pulls unpinned code off the
+  network on every restart is not something to want — but know the
+  consequence: when a video site changes its extraction and playback breaks,
+  waiting does not fix it. The fix arrives as a new app image, i.e. a new
+  appVersion of this chart. There is no in-place update path.
+
+  The tools' CACHE is a separate matter and is writable on purpose: /cache is
+  an emptyDir, with HOME and XDG_CACHE_HOME pointed at it, holding deno's
+  module cache and yt-dlp's JavaScript challenge-solver library. Without it
+  the pod still works, but re-fetches that library from github.com on every
+  extraction — so if egress is restricted, github.com belongs on the allow
+  list either way, and doubly so if this volume is ever removed.
+
+ytdlpWebPlayer.env IS APPENDED, NOT MERGED
+  The entries land after DATA_PATH and PORT, which the chart sets itself. Do
+  not set those two here: Kubernetes applies the LAST entry of the list, so a
+  duplicate silently wins and points the app away from its writable volume or
+  off the port that the Service and all three probes use. Everything else the
+  upstream understands is fair game; src/example.env in the upstream repository
+  is the authoritative list.
+{{- if gt (atoi $replicas) 1 }}
+
+MORE THAN ONE REPLICA SHARES NOTHING
+  ytdlpWebPlayer.replicas is {{ $replicas }}. Each pod has its own /data emptyDir, so a
+  video fetched by one is invisible to the other, and without session affinity
+  the segment requests of a single playback are spread across both — which
+  looks like a stuttering or failing stream rather than an error. Pin clients
+  to a pod at the ingress, or stay at one replica.
+{{- end }}
+
+WHAT THIS CHART DELIBERATELY DOES NOT DO
+  No cookies.txt: videos that require a login on the source site do not work,
+  and there is no value to make them work. No PersistentVolume. No mirror of
+  the upstream's twenty environment switches as chart values — they live in
+  ytdlpWebPlayer.env, so an upstream release cannot make this chart lie.

ytdlp-web-player/templates/_helpers.tpl

@@ -0,0 +1,372 @@
+{{/*
+Render the body of a container "resources:" block from a values dict of the form
+
+  resources:
+    limitFactor: 3          # optional, default 3
+    requests: { cpu, memory, ephemeral-storage / ephemeralStorage, ... }
+    limits:   { ... }       # optional, every entry optional
+
+Rules (variant B, see issue #19):
+  - requests are rendered as given (camelCase "ephemeralStorage" is normalized
+    to the Kubernetes key "ephemeral-storage").
+  - an explicitly set limit always wins.
+  - a missing memory / ephemeral-storage limit is computed as
+    limitFactor x the corresponding request.
+  - a missing cpu limit is NOT set at all (the kubelet then treats CPU as
+    unlimited; CPU is compressible, so this cannot kill the workload).
+
+Usage (the values path to the resources dict varies per chart):
+  resources:
+    {{- include "ytdlp-web-player.resources" .Values.<app>.resources | nindent 12 }}
+
+NOTE: this helper is duplicated into every chart's templates/_helpers.tpl with
+the chart's name as define prefix; template-chart/templates/_helpers.tpl is the
+reference implementation, and ci/run-quantity-render-test.sh renders every
+chart on every PR precisely because a copy can carry an old bug into a diff
+nobody reads. The copy is not a leftover of the old "charts have no
+dependencies" rule: a library chart would be a second thing to publish,
+version and pull for a helper that changes about once a year.
+*/}}
+{{- define "ytdlp-web-player.resources" -}}
+{{- $resources := . | default dict -}}
+{{- $factor := 3.0 -}}
+{{- if not (kindIs "invalid" $resources.limitFactor) -}}
+{{- $factor = float64 $resources.limitFactor -}}
+{{- end -}}
+{{- $requests := dict -}}
+{{- range $key, $value := ($resources.requests | default dict) -}}
+{{- if not (kindIs "invalid" $value) -}}
+{{- $_ := set $requests (include "ytdlp-web-player.resourceKey" $key) $value -}}
+{{- end -}}
+{{- end -}}
+{{- $limits := dict -}}
+{{- range $key, $value := ($resources.limits | default dict) -}}
+{{- if not (kindIs "invalid" $value) -}}
+{{- $_ := set $limits (include "ytdlp-web-player.resourceKey" $key) $value -}}
+{{- end -}}
+{{- end -}}
+{{- range $key, $request := $requests -}}
+{{- if and (ne $key "cpu") (not (hasKey $limits $key)) -}}
+{{- $_ := set $limits $key (include "ytdlp-web-player.multiplyQuantity" (dict "quantity" $request "factor" $factor)) -}}
+{{- end -}}
+{{- end -}}
+{{- $out := dict -}}
+{{- with $requests }}{{- $_ := set $out "requests" . }}{{- end -}}
+{{- with $limits }}{{- $_ := set $out "limits" . }}{{- end -}}
+{{- toYaml $out -}}
+{{- end -}}
+
+{{/*
+Normalize a resource name from values to its Kubernetes key.
+*/}}
+{{- define "ytdlp-web-player.resourceKey" -}}
+{{- if eq . "ephemeralStorage" -}}ephemeral-storage{{- else -}}{{ . }}{{- end -}}
+{{- end -}}
+
+{{/*
+Multiply a Kubernetes quantity by a factor, keeping its suffix.
+Input: dict "quantity" <string|number> "factor" <float64>.
+Handles plain numbers ("2", "0.5", 1073741824), decimal ("1.5Gi"), binary
+("512Mi", "1Gi", "10Ki") and milli/SI suffixes ("100m", "500M"). Integer
+results are printed without a decimal point.
+*/}}
+{{- define "ytdlp-web-player.multiplyQuantity" -}}
+{{- $quantity := include "ytdlp-web-player.formatNumber" .quantity -}}
+{{- $number := regexFind "^[0-9]+(\\.[0-9]+)?" $quantity -}}
+{{- if not $number -}}
+{{- fail (printf "cannot parse resource quantity %q" $quantity) -}}
+{{- end -}}
+{{- $suffix := trimPrefix $number $quantity -}}
+{{- if not (regexMatch "^(m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei)?$" $suffix) -}}
+{{- fail (printf "unsupported resource quantity suffix %q in %q" $suffix $quantity) -}}
+{{- end -}}
+{{- $product := mulf (float64 $number) .factor -}}
+{{- if eq $product (floor $product) -}}
+{{- printf "%d%s" (int64 $product) $suffix -}}
+{{- else -}}
+{{- printf "%s%s" (include "ytdlp-web-player.formatNumber" $product) $suffix -}}
+{{- end -}}
+{{- end -}}
+
+{{/*
+Render a number as a plain decimal string, never in exponential notation.
+
+Why this exists (issue #157): the null-safe fallback helpers pass values
+through fromYaml, which parses every number as float64. Go's "%v" switches
+float64 to exponential notation from about 1e6 upwards, so a bare byte count
+like 1048576 became "1.048576e+06" - not a valid Kubernetes quantity, and the
+render aborted. Strings ("512Mi") are passed through untouched.
+*/}}
+{{- define "ytdlp-web-player.formatNumber" -}}
+{{- if kindIs "float64" . -}}
+{{- regexReplaceAll "\\.?0+$" (printf "%.10f" .) "" -}}
+{{- else -}}
+{{- printf "%v" . -}}
+{{- end -}}
+{{- end -}}
+
+{{/*
+Render the replica count for a Deployment/StatefulSet.
+
+Input: dict
+  "scaleDown"  the chart-global .Values.scaleDown flag (may be nil)
+  "replicas"   the workload's replicas value (may be nil)
+
+Rules (issue #25):
+  - scaleDown: true takes precedence and always yields 0.
+  - otherwise an explicitly set replicas value is used as given, including an
+    explicit 0 — Helm's "default" would swallow 0, hence the explicit
+    kindIs "invalid" nil check.
+  - a missing replicas value defaults to 1.
+
+Usage (the values path to the workload's replicas varies per chart):
+  replicas: {{ include "ytdlp-web-player.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.<app>.replicas) }}
+
+NOTE: like the resources helper above, this is a copy carrying this chart's
+name as define prefix; template-chart holds the reference implementation.
+*/}}
+{{- define "ytdlp-web-player.replicas" -}}
+{{- if .scaleDown -}}
+0
+{{- else if not (kindIs "invalid" .replicas) -}}
+{{- .replicas -}}
+{{- else -}}
+1
+{{- end -}}
+{{- end -}}
+
+{{/*
+Merge a user-supplied values sub-tree onto a dict of chart defaults so that a
+null / empty override falls back to the defaults instead of erasing them.
+
+Input: dict "defaults" <dict> "given" <dict|nil> "path" <string, optional
+values path used in error messages>. Output: YAML of the merged dict (consume
+it with fromYaml).
+
+Why this exists (issues #61 and #99): Helm merges values maps recursively, but
+an override key written without children — e.g. a leftover
+
+  securityContext:
+
+after deleting its last remaining sub-key — is YAML null. Where the chart
+defines a default, Helm treats that null as a deletion of the default; the
+template then renders "securityContext: null": no readOnlyRootFilesystem, no
+dropped capabilities, no allowPrivilegeEscalation: false. The workload starts
+and reports healthy while being unhardened, so nothing points at the mistake.
+The same shape erases a probe (it disappears) or the resources block (no
+requests, no computed limits). This helper defines the opposite semantics: an
+empty block means "chart defaults apply".
+
+Rules:
+  - a nil "given" is treated as an empty dict (all defaults apply).
+  - a key whose override value is null keeps the default (nulls never delete).
+  - a key present in both as a map is merged recursively, so a partially
+    filled block only overrides the keys it actually sets.
+  - a scalar override for a key the defaults define as a map is rejected with
+    a message naming the values path, instead of failing later with a template
+    field error.
+  - any other set value wins as given, including an explicit false or 0 —
+    Helm's "default" and sprig's "mergeOverwrite" would both swallow those
+    zero values, hence the explicit kindIs "invalid" nil check.
+  - keys only present in the override are passed through unchanged.
+
+NOTE: like the helpers above, this is a copy carrying this chart's name as
+define prefix; template-chart holds the reference implementation.
+*/}}
+{{- define "ytdlp-web-player.defaultedDict" -}}
+{{- $defaults := .defaults | default dict -}}
+{{- $given := .given -}}
+{{- $path := .path | default "value" -}}
+{{- if kindIs "invalid" $given -}}
+{{- $given = dict -}}
+{{- end -}}
+{{- if not (kindIs "map" $given) -}}
+{{- fail (printf "%s must be a mapping or null, got %s (%v)" $path (kindOf $given) $given) -}}
+{{- end -}}
+{{- $out := deepCopy $defaults -}}
+{{- range $key, $value := $given -}}
+{{- if not (kindIs "invalid" $value) -}}
+{{- $default := index $defaults $key -}}
+{{- if and (kindIs "map" $value) (kindIs "map" $default) -}}
+{{- $_ := set $out $key (fromYaml (include "ytdlp-web-player.defaultedDict" (dict "defaults" $default "given" $value "path" (printf "%s.%s" $path $key)))) -}}
+{{- else if kindIs "map" $default -}}
+{{- fail (printf "%s.%s must be a mapping or null, got %s (%v)" $path $key (kindOf $value) $value) -}}
+{{- else -}}
+{{- $_ := set $out $key $value -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+{{- toYaml $out -}}
+{{- end -}}
+
+{{/*
+Pick one sub-block out of a values block that may itself be null.
+
+Input: dict "block" <dict|nil> "key" <string> "path" <string>.
+Returns YAML of dict "value" <the sub-block, may be nil>, after rejecting a
+non-mapping block with a message that names the values path. Needed because
+".Values.<app>.securityContext" can itself be erased, and indexing into nil
+inside a template is not an error but silently yields nothing.
+*/}}
+{{- define "ytdlp-web-player.subBlock" -}}
+{{- $block := .block -}}
+{{- if kindIs "invalid" $block -}}
+{{- $block = dict -}}
+{{- end -}}
+{{- if not (kindIs "map" $block) -}}
+{{- fail (printf "%s must be a mapping or null, got %s (%v)" .path (kindOf $block) $block) -}}
+{{- end -}}
+{{- toYaml (dict "value" (index $block .key)) -}}
+{{- end -}}
+
+{{/*
+The effective security contexts, probes and resources (issue #99).
+
+The defaults below MUST stay in sync with the corresponding blocks in
+values.yaml, which stays the documented, user-facing place for them; this copy
+is only the fallback for the case where an override has erased the block.
+
+Two rules that these fallbacks exist to demonstrate (README, "Chart style
+guidelines"):
+
+  - Reproduce THIS chart's defaults, not the repo standard. Where a chart
+    deviates on purpose (a root-starting image, a non-default limitFactor, a
+    pinned uid), the fallback must reproduce the deviation. Restoring the
+    "clean" standard here is not tidying, it is an outage - in one chart it
+    would move the runtime uid from 1000 to 911 and make existing volume data
+    inaccessible.
+  - Carry the probe's CONTEXT, not just its timings. A probe default without
+    its port name, Host header or exec command is worse than useless: in one
+    chart the probe vanished entirely, in another it answered 403 and the pod
+    never became Ready.
+*/}}
+{{- define "ytdlp-web-player.podSecurityContext" -}}
+{{- $given := (fromYaml (include "ytdlp-web-player.subBlock" (dict "block" . "key" "pod" "path" "ytdlpWebPlayer.securityContext"))).value -}}
+{{- $defaults := dict
+      "runAsNonRoot" true
+      "runAsUser" 20000
+      "runAsGroup" 1000
+      "fsGroup" 1000
+      "fsGroupChangePolicy" "Always"
+      "seccompProfile" (dict "type" "RuntimeDefault") -}}
+{{- include "ytdlp-web-player.defaultedDict" (dict "defaults" $defaults "given" $given "path" "ytdlpWebPlayer.securityContext.pod") -}}
+{{- end -}}
+
+{{- define "ytdlp-web-player.containerSecurityContext" -}}
+{{- $given := (fromYaml (include "ytdlp-web-player.subBlock" (dict "block" . "key" "container" "path" "ytdlpWebPlayer.securityContext"))).value -}}
+{{- $defaults := dict
+      "allowPrivilegeEscalation" false
+      "readOnlyRootFilesystem" true
+      "runAsNonRoot" true
+      "capabilities" (dict "drop" (list "ALL") "add" (list)) -}}
+{{- include "ytdlp-web-player.defaultedDict" (dict "defaults" $defaults "given" $given "path" "ytdlpWebPlayer.securityContext.container") -}}
+{{- end -}}
+
+{{- define "ytdlp-web-player.livenessProbe" -}}
+{{- $defaults := dict
+      "httpGet" (dict "path" "/" "port" "http")
+      "periodSeconds" 10
+      "timeoutSeconds" 5
+      "failureThreshold" 3 -}}
+{{- include "ytdlp-web-player.defaultedDict" (dict "defaults" $defaults "given" . "path" "ytdlpWebPlayer.livenessProbe") -}}
+{{- end -}}
+
+{{- define "ytdlp-web-player.readinessProbe" -}}
+{{- $defaults := dict
+      "httpGet" (dict "path" "/" "port" "http")
+      "periodSeconds" 10
+      "timeoutSeconds" 5
+      "failureThreshold" 3 -}}
+{{- include "ytdlp-web-player.defaultedDict" (dict "defaults" $defaults "given" . "path" "ytdlpWebPlayer.readinessProbe") -}}
+{{- end -}}
+
+{{- define "ytdlp-web-player.startupProbe" -}}
+{{- $defaults := dict
+      "httpGet" (dict "path" "/" "port" "http")
+      "periodSeconds" 5
+      "timeoutSeconds" 5
+      "failureThreshold" 30 -}}
+{{- include "ytdlp-web-player.defaultedDict" (dict "defaults" $defaults "given" . "path" "ytdlpWebPlayer.startupProbe") -}}
+{{- end -}}
+
+{{/*
+The effective resources block, fed into the resources helper above so that an
+erased "resources:" still yields the chart's requests and computed limits
+instead of a container without any resource accounting.
+*/}}
+{{- define "ytdlp-web-player.effectiveResources" -}}
+{{- $defaults := dict
+      "limitFactor" 3
+      "requests" (dict "cpu" 0.5 "memory" "512Mi" "ephemeral-storage" "2Gi") -}}
+{{- $merged := fromYaml (include "ytdlp-web-player.defaultedDict" (dict "defaults" $defaults "given" . "path" "ytdlpWebPlayer.resources")) -}}
+{{- include "ytdlp-web-player.resources" $merged -}}
+{{- end -}}
+
+{{/*
+The application's listening port, taken from the container port named "http".
+
+Deliberately NOT null-safe, unlike the probe and resources helpers above.
+Issue #99 covers the silent class of erased values - a probe that vanishes, a
+container that renders unhardened. This one is loud: a missing port yields a
+Service pointing nowhere and an application told to listen on "", which fails
+at once and in the open. An error that shows itself needs no fallback, and
+every extra branch has to be read by someone.
+
+Because of this helper the number lives in exactly one place: it becomes the
+PORT environment variable, while the Service and all three probes address the
+same entry by NAME.
+*/}}
+{{- define "ytdlp-web-player.port" -}}
+{{- $port := "" -}}
+{{- range (.Values.ytdlpWebPlayer.ports | default list) -}}
+{{- if eq (.name | default "") "http" -}}
+{{- $port = .containerPort -}}
+{{- end -}}
+{{- end -}}
+{{- if or (kindIs "invalid" $port) (eq (printf "%v" $port) "") -}}
+{{- fail "ytdlpWebPlayer.ports must contain an entry named \"http\" carrying a containerPort - it is the port the application is told to listen on (PORT), the port the Service targets, and the port all three probes address" -}}
+{{- end -}}
+{{- printf "%v" $port -}}
+{{- end -}}
+
+{{/*
+The in-cluster address of this release's application Service - the address the
+oauth2-proxy subchart has to carry in its upstreams line.
+
+A helper so that NOTES.txt and the default in values.yaml cannot drift apart.
+Note what it may NOT be built from on the subchart side: inside the subchart
+.Chart.Name is "oauth2-proxy", so the parent chart's name has to be written out
+literally there. Only .Release.Name is shared by both.
+*/}}
+{{- define "ytdlp-web-player.appServiceAddress" -}}
+http://{{ .Release.Name }}-{{ .Chart.Name }}-service:80
+{{- end -}}
+
+{{/*
+Refuse to render two Ingresses for the same host (issue #214).
+
+With the proxy enabled, this chart's Ingress and the subchart's Ingress can
+both be switched on, and both then claim the same host. That is not a merge and
+not a warning: ingress-nginx's admission webhook rejects whichever arrives
+second with "host ... and path ... is already defined in ingress ...". Under
+Fleet the bundle goes to ErrApplied and Fleet does not retry a rejected apply
+by itself - getting out costs a forceSyncGeneration bump on the GitRepo.
+Failing here costs a re-render.
+
+Host-based rather than "both switched on", because a proxy on a host of its own
+collides with nothing. That case is not silently blessed either: NOTES.txt says
+plainly that the app's own Ingress is then a way past the proxy.
+
+Called from the Deployment - the one template that always renders - so the
+guard cannot be skipped by scaling to zero or by rendering a single file with
+"helm template -s".
+*/}}
+{{- define "ytdlp-web-player.validate" -}}
+{{- $proxy := (index .Values "oauth2-proxy") | default dict -}}
+{{- $proxyIngress := $proxy.ingress | default dict -}}
+{{- if and .Values.ingress.enabled $proxy.enabled $proxyIngress.enabled -}}
+{{- if has .Values.ingress.domain ($proxyIngress.hosts | default list) -}}
+{{- fail (printf "ingress.enabled and oauth2-proxy.ingress.enabled both claim the host %q. ingress-nginx allows only one Ingress per host and path; its admission webhook rejects the second one, which leaves a Fleet bundle in ErrApplied until forceSyncGeneration is bumped. Decide who owns the host: with the proxy in the data path set ingress.enabled=false (the app is then reached through the proxy and its Service), or drop the proxy's Ingress with oauth2-proxy.ingress.enabled=false." .Values.ingress.domain) -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}

ytdlp-web-player/templates/ytdlp-web-player.deployment.yaml

@@ -0,0 +1,135 @@
+{{- include "ytdlp-web-player.validate" . }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+  labels:
+    app: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+spec:
+  replicas: {{ include "ytdlp-web-player.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.ytdlpWebPlayer.replicas) }}
+  selector:
+    matchLabels:
+      app: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+  template:
+    metadata:
+      name: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+      labels:
+        app: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+      # NO checksum/config ANNOTATION HERE, AND NOTHING IS MISSING (#82).
+      #
+      # The rule is "every pod template consuming a ConfigMap carries a hash of
+      # it". This workload consumes none: the application is configured purely
+      # through environment variables, which are part of the pod template
+      # already, so a changed value rolls the pods by itself. The chart renders
+      # no ConfigMap and no Secret for the app - it has no credentials of its
+      # own - so there is nothing to hash and no silent-stale-config gap to
+      # close. Written down because an absent annotation otherwise looks like
+      # an oversight on the next review round.
+      #
+      # The one Secret this chart can render, the oauth2-proxy OnePasswordItem,
+      # is consumed by the SUBCHART's pod template, which this chart cannot
+      # annotate. See values.yaml for the manual rollout restart that replaces
+      # it.
+    spec:
+      automountServiceAccountToken: false
+      securityContext:
+        {{- include "ytdlp-web-player.podSecurityContext" .Values.ytdlpWebPlayer.securityContext | nindent 8 }}
+      containers:
+        - name: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+          # Fully qualified on purpose: an unqualified "matszwe02/ytdlp_web_player"
+          # resolves to Docker Hub implicitly, which is how the repo accumulated
+          # its unqualified images.
+          image: "docker.io/matszwe02/ytdlp_web_player:{{ .Chart.AppVersion }}"
+          imagePullPolicy: IfNotPresent
+          env:
+            # The four variables the chart owns.
+            #
+            # DATA_PATH is absolute, which the application explicitly allows (it
+            # runs the value through os.path.abspath), so nothing has to be
+            # writable below /app and the root filesystem stays read-only.
+            #
+            # PORT follows the container port named "http", so the Service, the
+            # probes and the application cannot drift apart.
+            #
+            # HOME and XDG_CACHE_HOME point the cache of the two bundled tools
+            # at the writable volume below. They are set rather than relying on
+            # a mount at /.cache so that the path does not depend on which uid
+            # the pod ends up running as - see values.yaml under storage.
+            - name: DATA_PATH
+              value: "/data"
+            - name: PORT
+              value: {{ include "ytdlp-web-player.port" . | quote }}
+            - name: HOME
+              value: "/cache"
+            - name: XDG_CACHE_HOME
+              value: "/cache"
+            {{- range $value := .Values.ytdlpWebPlayer.env }}
+            {{- if $value.value }}
+            - name: {{ $value.name | quote }}
+              # quote is required, not cosmetic: a value like "5000" or "true"
+              # renders unquoted as a YAML number/bool, and the API server then
+              # rejects the whole manifest with "cannot unmarshal number into
+              # Go struct field EnvVar.value of type string".
+              value: {{ tpl $value.value $ | quote }}
+            {{- else if $value.valueFrom }}
+            {{- if $value.valueFrom.secretKeyRef }}
+            - name: {{ $value.name }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ tpl $value.valueFrom.secretKeyRef.name $ | quote }}
+                  key: {{ tpl $value.valueFrom.secretKeyRef.key $ | quote }}
+            {{- else if $value.valueFrom.configMapKeyRef }}
+            - name: {{ $value.name }}
+              valueFrom:
+                configMapKeyRef:
+                  name: {{ tpl $value.valueFrom.configMapKeyRef.name $ | quote }}
+                  key: {{ tpl $value.valueFrom.configMapKeyRef.key $ | quote }}
+            {{- end }}
+            {{- end }}
+            {{- end }}
+          ports:
+            {{- toYaml .Values.ytdlpWebPlayer.ports | nindent 12 }}
+          volumeMounts:
+            # Exactly two, and each was measured on its own rather than added
+            # as a precaution - see values.yaml under storage. Note in
+            # particular that /tmp is NOT here: the usual reflex for a
+            # read-only root filesystem, and this image does not need it.
+            - name: data
+              mountPath: /data
+            - name: cache
+              mountPath: /cache
+          # Probes, resources and both security contexts go through the
+          # null-safe helpers (#99): an erased block means "chart defaults
+          # apply" instead of a vanished probe or an unhardened container.
+          # Never wrap these in an "if" - a guard hides the erased case
+          # completely instead of rendering a visible null.
+          livenessProbe:
+            {{- include "ytdlp-web-player.livenessProbe" .Values.ytdlpWebPlayer.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- include "ytdlp-web-player.readinessProbe" .Values.ytdlpWebPlayer.readinessProbe | nindent 12 }}
+          startupProbe:
+            {{- include "ytdlp-web-player.startupProbe" .Values.ytdlpWebPlayer.startupProbe | nindent 12 }}
+          resources:
+            {{- include "ytdlp-web-player.effectiveResources" .Values.ytdlpWebPlayer.resources | nindent 12 }}
+          securityContext:
+            {{- include "ytdlp-web-player.containerSecurityContext" .Values.ytdlpWebPlayer.securityContext | nindent 12 }}
+      volumes:
+        # The "emptyDir: {}" branches are written out rather than folded into
+        # one block with an optional key: an emptyDir whose body renders empty
+        # is YAML null, and a volume without a source is rejected by the API
+        # server with "must specify a volume type" - after a green render.
+        - name: data
+          {{- if (.Values.storage).dataSizeLimit }}
+          emptyDir:
+            sizeLimit: {{ (.Values.storage).dataSizeLimit }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+        - name: cache
+          {{- if (.Values.storage).cacheSizeLimit }}
+          emptyDir:
+            sizeLimit: {{ (.Values.storage).cacheSizeLimit }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+      restartPolicy: Always

ytdlp-web-player/templates/ytdlp-web-player.ingress.yaml

@@ -0,0 +1,29 @@
+{{- if .Values.ingress.enabled }}
+{{- include "ytdlp-web-player.validate" . }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-ingress
+  annotations:
+    cert-manager.io/cluster-issuer: {{ required "A Cluster-Issuer must be provided" .Values.ingress.clusterIssuer }}
+    {{- with .Values.ingress.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  ingressClassName: {{ .Values.ingress.className }}
+  rules:
+    - host: {{ required "A Domain/Host must be provided" .Values.ingress.domain }}
+      http:
+        paths:
+          - backend:
+              service:
+                name: {{ .Release.Name }}-{{ .Chart.Name }}-service
+                port:
+                  name: http
+            path: /
+            pathType: Prefix
+  tls:
+    - hosts:
+        - {{ required "A Domain/Host must be provided" .Values.ingress.domain }}
+      secretName: tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+{{- end }}

ytdlp-web-player/templates/ytdlp-web-player.oauth2-proxy-secret.yaml

@@ -0,0 +1,26 @@
+{{- $proxy := (index .Values "oauth2-proxy") | default dict -}}
+{{- $config := $proxy.config | default dict -}}
+{{- $ownSecret := printf "%s-%s-oauth2-proxy-secret" .Release.Name .Chart.Name -}}
+{{- if and $proxy.enabled (eq (tpl ($config.existingSecret | default "") .) $ownSecret) }}
+# The three credentials the proxy needs, as a 1Password item (README, guideline
+# 8). This chart renders the CR itself rather than only expecting a Secret name,
+# for the same reason every other chart here does: the operator is the repo's
+# secret mechanism, and a chart that only names a Secret leaves the operator
+# half of the wiring to a second, undocumented place.
+#
+# It is rendered only while the subchart still points at THIS name. Set
+# oauth2-proxy.config.existingSecret to a Secret of your own and the chart
+# creates nothing here - your Secret then has to carry the same three keys.
+#
+# Note what the operator does and does not do: it copies the item's FIELD NAMES
+# into the Secret's keys. A field spelled differently produces a Secret without
+# that key, the install stays green, and the proxy pod sits in
+# CreateContainerConfigError. See values.yaml for the three names and for the
+# URL-safe base64 trap on cookie-secret.
+apiVersion: onepassword.com/v1
+kind: OnePasswordItem
+metadata:
+  name: {{ $ownSecret }}
+spec:
+  itemPath: {{ required "The oauth2-proxy needs its credentials: set secrets.oauth2ProxySecretRef to the op:// path of an item carrying client-id, client-secret and cookie-secret - or point oauth2-proxy.config.existingSecret at a Secret you manage yourself." .Values.secrets.oauth2ProxySecretRef }}
+{{- end }}

ytdlp-web-player/templates/ytdlp-web-player.service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-service
+spec:
+  selector:
+    app: {{ .Release.Name }}-{{ .Chart.Name }}-deployment
+  ports:
+    - protocol: TCP
+      port: 80
+      # By name, so the container port is configured in exactly one place
+      # (ytdlpWebPlayer.ports).
+      targetPort: http
+      name: http
+  type: ClusterIP