helm-charts/ytdlp-web-player/templates/NOTES.txt

{{- /*
NOTHING IN CI READS THIS FILE. `helm template` does not emit notes and no
workflow or script under ci/ reads it, so every claim below carries
review-only assurance - it is checked by being read, not by a stage. A
rendering ERROR here does fail `helm template`, which is all the pipeline can
see of it.
*/ -}}
{{- $replicas := include "ytdlp-web-player.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.ytdlpWebPlayer.replicas) -}}
{{- $httpRoute := .Values.httpRoute | default dict -}}
{{- /*
"Published" rather than "has an Ingress": the two modes are alternatives, so
every paragraph that asked ingress.enabled was really asking whether this
chart publishes the application (Gitea #114). Same helper the host guard uses.
*/ -}}
{{- $published := eq (include "ytdlp-web-player.published" .) "true" -}}
{{- $hostnames := $httpRoute.hostnames | default list -}}
{{- if not $hostnames -}}
{{- $hostnames = list .Values.ingress.domain -}}
{{- end -}}
{{- $ownHost := first $hostnames -}}
{{- $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.

  AN INGRESS, AND IT STAYS ONE IN BOTH OF THIS CHART'S MODES. The subchart has
  no Gateway-API support and this chart cannot give it one (upstream's chart is
  consumed as it comes), so httpRoute.enabled on THIS chart does not move the
  proxy off its Ingress. In this configuration — the recommended one — turning
  it on buys nothing.
{{- else if .Values.ingress.enabled }}

ACCESS — INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
  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 if $httpRoute.enabled }}

ACCESS — GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
{{- range $hostnames }}
  https://{{ . }}
{{- end }}

  This release renders ONE HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) and nothing
  else of the routing path — no Gateway, no class, no Certificate, no policy
  object. Three things therefore belong to the cluster:

    1. The Gateway-API CRDs. Without them this install would have failed, so
       they are present — nothing to check.
    2. The Gateway named in httpRoute.parentRefs
{{- range $httpRoute.parentRefs }}
         {{ .name }}{{ if .namespace }} in namespace {{ .namespace }}{{ end }}{{ if .sectionName }}, listener {{ .sectionName }}{{ end }}
{{- end }}
       must exist AND its listener must allow routes from this namespace
       ({{ .Release.Namespace }}) in allowedRoutes. A rejected attachment is visible only
       in the route's status:

         kubectl -n {{ .Release.Namespace }} get httproute {{ .Release.Name }}-{{ .Chart.Name }}-httproute -o yaml

       Read status.parents[].conditions — "Accepted: True" and
       "ResolvedRefs: True" is what a working attachment looks like. An empty
       status means no controller has looked at the route at all.
    3. The TLS certificate for the hostname, on the Gateway's listener.
       ingress.clusterIssuer is NOT used in this mode and is not required: the
       chart renders no Certificate here, so there is no
       tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress secret.

  ingress.annotations is inert in this mode — no annotation channel in the
  Gateway API. Note which annotation that is NOT about: the 16k
  proxy-buffer-size this chart recommends belongs on the PROXY's Ingress, and
  the subchart renders an Ingress whatever this chart does, so it is
  unaffected.
{{- else }}

ACCESS — NEITHER INGRESS NOR HTTPROUTE
  ingress.enabled and httpRoute.enabled are both false, so this release has no
  Ingress, no HTTPRoute and no certificate.
  Both ingress.domain and ingress.clusterIssuer are unnecessary here — unlike
  in some other charts in this repo, nothing but the two routing templates
  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 if $httpRoute.enabled }} and HTTPRoute stay in place, so the
  route keeps pointing at a Service with no endpoints — the Gateway answers
  with an error of its own rather than with nothing.{{ 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 $published (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: ["{{ $ownHost }}"]
    ingress:
      enabled: false          # the proxy owns the host from then on
{{- if $httpRoute.enabled }}
    httpRoute:
      enabled: false          # and so does this one: the SUBCHART HAS NO
                              # GATEWAY SUPPORT, so the proxy publishes over
                              # an Ingress either way. Leaving this on for the
                              # same host is refused by the chart; leaving it
                              # on for a different host is the bypass below.
{{- end }}

  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{{ if $httpRoute.enabled }}, and NONE of it is available in Gateway mode:
  there is no annotation channel, so an auth annotation has no counterpart.
  Authentication would have to come from the Gateway itself or from the proxy{{ end }}.
{{- end }}
{{- if and $proxy.enabled $published }}

WARNING — THE APP'S OWN {{ if $httpRoute.enabled }}ROUTE{{ else }}INGRESS{{ end }} IS A WAY PAST THE PROXY
  Both oauth2-proxy.enabled and {{ if $httpRoute.enabled }}httpRoute.enabled{{ else }}ingress.enabled{{ end }} are true. The chart only
  refuses this when both claim the SAME host; here they do not, so it renders —
  but https://{{ $ownHost }} reaches the application directly, with no
  authentication in front of it, whatever the proxy does on its own host.
  Unless that is deliberate, set {{ if $httpRoute.enabled }}httpRoute.enabled=false{{ else }}ingress.enabled=false{{ end }}.
{{- if $httpRoute.enabled }}

  AND IN THIS MODE THE SAME-HOST CASE IS THE ONE WORTH FEARING, which is why
  the chart refuses it: ingress-nginx's admission webhook compares Ingress
  objects with Ingress objects, so it never sees an HTTPRoute. Two valid
  objects would then serve one hostname — the proxy's Ingress through
  authentication, this chart's route straight to the application — and which
  one a client reaches would depend on DNS alone, with nothing reporting it.
{{- end }}
{{- 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.