helm-charts/zipline/templates/NOTES.txt

{{- $replicas := include "zipline.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.zipline.replicas) -}}
{{- $res := fromYaml (include "zipline.effectiveResources" .Values.zipline.resources) -}}
{{- $eph := index ($res.limits | default dict) "ephemeral-storage" | default "the computed ephemeral-storage limit" -}}
{{- $startup := fromYaml (include "zipline.startupProbe" .Values.zipline.startupProbe) -}}
{{- $budget := "" -}}
{{- if and (kindIs "float64" $startup.periodSeconds) (kindIs "float64" $startup.failureThreshold) -}}
{{- $budget = printf "%.0f seconds" (mulf $startup.periodSeconds $startup.failureThreshold) -}}
{{- end -}}
{{- $httpRoute := .Values.httpRoute | default dict -}}
{{- $hostnames := $httpRoute.hostnames | default list -}}
{{- if not $hostnames -}}
{{- $hostnames = list .Values.ingress.domain -}}
{{- end -}}
Zipline {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.

{{- 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 an HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) and NOTHING
  else of the routing path — no Gateway, no class, no Certificate. Three things
  therefore belong to the cluster and not to this chart, and if any is missing
  the address above does not answer:

    1. The Gateway-API CRDs. Without them this install would have failed.
    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 shows
       up 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 a working attachment. 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, so there is no
       tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress secret and nothing for cert-manager to do.

  ingress.domain is still required in this mode and is {{ .Values.ingress.domain }}: it is also
  CORE_DEFAULT_DOMAIN, the host Zipline puts into every share link it hands
  out, and the route does not replace it. If you set httpRoute.hostnames to a
  name ingress.domain does not carry, the route publishes one host while every
  link the app generates names another — set both together.

  ingress.annotations is inert in this mode: the Gateway API has no annotation
  channel. For this chart that includes the upload cap — see below.
{{- else }}

ACCESS — NEITHER INGRESS NOR HTTPROUTE
  ingress.enabled and httpRoute.enabled are both false, so this release is not
  published: no Ingress, no HTTPRoute and no certificate;
  ingress.clusterIssuer is not needed. ingress.domain still is: it is also
  CORE_DEFAULT_DOMAIN, the host Zipline puts into every share link it hands
  out. Reach the instance inside the cluster with

    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8080:80

  and open http://localhost:8080 — but every link the app generates will still
  point at https://{{ .Values.ingress.domain }}/, which nothing in this release serves.
{{- end }}
{{ if eq $replicas "0" }}
SCALED TO ZERO
  {{ if .Values.scaleDown }}scaleDown: true{{ else }}zipline.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so the endpoint
  above does not answer until you set it back and upgrade again. The uploads
  PVC, both Secrets and the Service{{ if .Values.ingress.enabled }} and Ingress stay in place, so no data is
  lost and the certificate is not re-issued.{{ else if $httpRoute.enabled }} and HTTPRoute stay in place, so no data is
  lost — the route then resolves to a Service with no endpoints and the Gateway
  answers its own error.{{ else }} stay in place, so no data is lost.{{ end }}
{{ end }}
THE FIRST VISITOR CHOOSES THE ADMINISTRATOR
  Against an empty database Zipline has no users, and it sends every visitor
  to its setup page to name the super administrator and its password; the
  endpoint behind that page refuses to run a second time once an account
  exists. Whoever reaches the URL first therefore owns this instance. Do the
  setup right after the first rollout, not the next morning. Against a
  database that already carries a Zipline schema the step is skipped and the
  normal login appears.

SECRETS — WHAT THE TWO 1PASSWORD ITEMS MUST CONTAIN
  The operator copies an item's FIELDS into the Kubernetes Secret, one key per
  field name, and this chart reads exactly one key from each. The field names
  therefore have to match to the letter:

    secrets.databaseSecretRef → {{ .Values.secrets.databaseSecretRef }}
      field "connection-url" → DATABASE_URL, a full PostgreSQL URL such as
      postgresql://zipline:password@postgres.example.com:5432/zipline
      The chart deploys no database — that server has to exist already and be
      reachable from this namespace.

    secrets.ziplineSecretRef → {{ .Values.secrets.ziplineSecretRef }}
      field "server-secret" → CORE_SECRET, which signs sessions and tokens.
      Generate one with: openssl rand -base64 32

  A field spelled differently yields a Secret without that key. The pod then
  hangs in CreateContainerConfigError while the Secret itself exists, so it
  looks as if the operator had done its job. What it actually delivered:

    kubectl -n {{ .Release.Namespace }} get secret {{ .Release.Name }}-{{ .Chart.Name }}-db-secret -o jsonpath='{.data}'

  Pointing a ref at a DIFFERENT item rolls the pod; changing the value INSIDE
  the same item does not — Helm never sees that content, so the rendered
  StatefulSet is unchanged and nothing restarts:

    kubectl -n {{ .Release.Namespace }} rollout restart statefulset/{{ .Release.Name }}-{{ .Chart.Name }}-sfs

  Note that a new CORE_SECRET logs every user out.

STARTUP RUNS THE DATABASE MIGRATIONS
  Zipline migrates its schema on start, before it serves anything. The startup
  probe covers that window{{ if $budget }} ({{ $budget }}){{ end }} and keeps liveness and readiness off
  until it is through; if a migration needs longer, the kubelet kills the
  container and the next attempt begins the migration again. A migration that
  fails looks like CrashLoopBackOff and only the log says why:

    kubectl -n {{ .Release.Namespace }} logs statefulset/{{ .Release.Name }}-{{ .Chart.Name }}-sfs

  helm rollback returns the chart to the previous app version; the database
  does not come back with it, because the schema was migrated in place. Take a
  database backup before an app-version upgrade, not after.

WHAT A READY POD PROVES — AND WHAT AN OUTAGE LOOKS LIKE
  Readiness and startup use /api/healthcheck, which also checks the database,
  so Ready here does mean "server up, database answering". Liveness
  deliberately uses "/" instead, so a database outage cannot restart the pod.
  Know the resulting picture in advance: during such an outage the container
  keeps running and stays quiet, the pod goes NotReady, its endpoint is
  dropped{{ if .Values.ingress.enabled }} and the Ingress answers 503{{ else if $httpRoute.enabled }} and the Gateway answers its own error for the route{{ end }} — and nothing in the pod's log or
  restart count points at the database. Look there first.

TWO DIFFERENT CEILINGS APPLY TO AN UPLOAD
  The app-side limit is pinned by the chart at UPLOADER_ADMIN_LIMIT=500mb and
  is not exposed as a value.
  {{- if .Values.ingress.enabled }}
  In front of it the Ingress caps the request body at config.maxUploadFileSize
  ({{ .Values.config.maxUploadFileSize }}), so that is the ceiling that actually bites: anything larger is
  rejected by ingress-nginx with 413 before Zipline sees a byte of it. Raise
  config.maxUploadFileSize to move it.
  {{- else if $httpRoute.enabled }}
  IN GATEWAY MODE config.maxUploadFileSize ({{ .Values.config.maxUploadFileSize }}) IS NOT ENFORCED. The chart
  renders it into nginx.ingress.kubernetes.io/proxy-body-size, and the Gateway
  API has NO counterpart — it knows no body size at all, that is
  implementation-specific policy — so this chart deliberately renders no policy
  object, which would bind it to one implementation. Whatever limit the Gateway
  enforces is the ceiling your uploads get, and this is an upload service: an
  oversized upload is rejected by the proxy before Zipline sees a byte, the
  user gets the Gateway's error instead of a message from the application, and
  nothing says a chart value was ignored. Set the limit at the Gateway or
  through its implementation's own policy object, next to the Gateway and not
  here.
  {{- else }}
  config.maxUploadFileSize ({{ .Values.config.maxUploadFileSize }}) is rendered nowhere in this release: it exists
  only as an ingress-nginx annotation, and neither routing mode is on.
  Whatever proxy you put in front needs its own body-size limit.
  {{- end }}

CHUNKS GO THROUGH /tmp, AND /tmp IS ACCOUNTED FOR
  The root filesystem is read-only, so /tmp is an emptyDir — and an emptyDir
  counts against the container's ephemeral-storage limit ({{ $eph }}).
  An upload that pushes it over does not fail as a request: the kubelet evicts
  the whole pod, and the reason is on the pod, not in Zipline's log. Where
  uploads approach the 500mb the app allows, raise
  zipline.resources.requests.ephemeralStorage — the limit follows it through
  zipline.resources.limitFactor.

THE UPLOADS VOLUME BELONGS TO THIS RELEASE
  uploads, public and themes share one PersistentVolumeClaim,
  {{ .Release.Name }}-{{ .Chart.Name }}-vc ({{ .Values.config.storage }} from storageClass {{ .Values.config.storageClass }}), each on its own
  subPath. It is an ordinary PVC in this release, not a StatefulSet
  volumeClaimTemplate: "helm uninstall {{ .Release.Name }}" deletes it, and with a Delete
  reclaim policy every uploaded file goes with it. Back the volume up before
  uninstalling; a resource-policy annotation added to the live PVC afterwards
  does not help, because Helm reads that annotation from the release manifest.

  Growing config.storage only takes effect if the StorageClass allows volume
  expansion. Shrinking it is refused by Kubernetes and makes the next
  helm upgrade fail on the PVC instead of touching the data.
{{- if gt (atoi $replicas) 1 }}

MORE THAN ONE REPLICA WILL NOT COME UP
  zipline.replicas is {{ $replicas }}, but every replica mounts the same
  ReadWriteOnce claim {{ .Release.Name }}-{{ .Chart.Name }}-vc — there is no volumeClaimTemplate and no
  per-pod volume. Unless the storage class hands that claim to several nodes,
  the additional pods stay stuck before start. This chart is built for one
  replica.
{{- end }}
{{- if .Values.zipline.env }}

zipline.env IS APPENDED, NOT MERGED
  The entries land after the variables the chart sets itself — DATABASE_URL,
  CORE_DEFAULT_DOMAIN, CORE_SECRET and UPLOADER_ADMIN_LIMIT — and are rendered
  through tpl, so a value may contain template expressions. Anything sensitive
  belongs in valueFrom.secretKeyRef: a plain "value" is stored in the pod spec
  and readable by everyone who can read pods in {{ .Release.Namespace }}.
{{- end }}
{{- if .Values.networkPolicy.enabled }}

NETWORKPOLICY IS ACTIVE — WHAT IT CAPS, AND WHAT IT DOES NOT
  {{ .Release.Name }}-{{ .Chart.Name }}-networkpolicy selects this workload's pods.
  Inbound: TCP 3000 only. Outbound: DNS, TCP 5432 (Postgres) and 443 (optional
  OAuth providers, and an external S3 endpoint){{ with .Values.networkPolicy.egress }}{{ with .extraPorts }}, plus TCP {{ join ", " . }}{{ end }}{{ end }}.

  5432 IS THE STANDARD PORT, NOT YOUR CONFIGURED ONE: the connection URL lives
  in a 1Password item this chart never parses. A Postgres elsewhere is blocked —
  and since all three probes hit this app's own port and not the database, that
  shows up as an application error rather than as an un-Ready pod. Add the real
  port to networkPolicy.egress.extraPorts.

  Three limits belong in the same breath, because none of them is visible in
  the object itself:

  - EGRESS IS BY PORT, NEVER BY DESTINATION. A NetworkPolicy matches CIDRs and
    selectors and cannot express a hostname, so every egress rule permits its
    port to ANY address. That is a limit of the object, not a shortcut — this
    cluster's CNI (Canal: Flannel plus Calico) has no FQDN rule either. An
    outbound port the chart does not know about is BLOCKED: add it to
    networkPolicy.egress.extraPorts, and expect to find out through an
    application-level connection error rather than through this object.
{{- if .Values.networkPolicy.probeSources }}
  - THE PROBE PATH IS RESTRICTED in this release, because
    networkPolicy.probeSources is set to
      {{ join ", " .Values.networkPolicy.probeSources }}
    Probes come from the IP of the WORKER NODE running the pod. If none of those
    CIDRs covers the node this pod lands on, the kubelet's probes are dropped
    and THE POD NEVER BECOMES READY — the rollout then times out and the symptom
    looks like a broken application. Compare

      kubectl -n {{ .Release.Namespace }} describe pod -l app={{ .Release.Name }}-{{ .Chart.Name }}-sfs

    against `kubectl get node -o wide`.
{{- else }}
  - THE PROBED PORT IS OPEN INSIDE THE CLUSTER. networkPolicy.probeSources is
    empty, so that rule carries no source selector at all and any pod the CNI
    routes to can reach it. Not from the internet — but this is NOT pod-level
    isolation. Narrowing it means listing the worker node IPs in
    networkPolicy.probeSources, because the kubelet probes from the node's own
    address and the chart cannot know it; a wrong guess there leaves the pod
    permanently un-Ready.
{{- end }}
  - IT IS ONLY A BOUNDARY WHERE THE CNI ENFORCES POLICIES. Where it does not,
    this object is accepted and filters nothing, so everything reads as
    configured while nothing is filtered. `kubectl -n {{ .Release.Namespace }} get networkpolicy`
    shows the object exists; only a connection attempt from an unrelated
    namespace shows that it bites.

  Switch it off with networkPolicy.enabled: false.
{{- end }}