helm-charts/urlaubsverwaltung/templates/NOTES.txt

{{- $replicas := include "urlaubsverwaltung.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.urlaubsverwaltung.replicas) -}}
{{- $res := fromYaml (include "urlaubsverwaltung.effectiveResources" .Values.urlaubsverwaltung.resources) -}}
{{/*
Both figures go through formatNumber for the reason issue #157 documents: they
come back from fromYaml as float64, and a bare byte count would print as
"1e+06" here just as it did in the rendered manifest.
*/}}
{{- $memLimitRaw := index ($res.limits | default dict) "memory" -}}
{{- $memLimit := "the computed memory limit" -}}
{{- if not (kindIs "invalid" $memLimitRaw) -}}
{{- $memLimit = include "urlaubsverwaltung.formatNumber" $memLimitRaw -}}
{{- end -}}
{{- $memRequestRaw := index ($res.requests | default dict) "memory" -}}
{{- $memRequest := "the memory request" -}}
{{- if not (kindIs "invalid" $memRequestRaw) -}}
{{- $memRequest = include "urlaubsverwaltung.formatNumber" $memRequestRaw -}}
{{- end -}}
{{/*
The effective limitFactor. It cannot be read back out of $res: that dict is the
RENDERED resources block (requests / limits only), so $res.limitFactor is always
empty and would silently print the default even where another factor is in
force. Mirror the defaulting of the resources helper on the raw value instead.
*/}}
{{- $resIn := .Values.urlaubsverwaltung.resources -}}
{{- if kindIs "invalid" $resIn -}}
{{- $resIn = dict -}}
{{- end -}}
{{- $factor := 3 -}}
{{- if not (kindIs "invalid" (index $resIn "limitFactor")) -}}
{{- $factor = index $resIn "limitFactor" -}}
{{- end -}}
{{/* An explicitly set memory limit wins over the computed one - say which. */}}
{{- $limitsIn := index $resIn "limits" -}}
{{- if kindIs "invalid" $limitsIn -}}
{{- $limitsIn = dict -}}
{{- end -}}
{{- $memLimitExplicit := not (kindIs "invalid" (index $limitsIn "memory")) -}}
{{- $startup := fromYaml (include "urlaubsverwaltung.startupProbe" .Values.urlaubsverwaltung.startupProbe) -}}
{{- $budget := "" -}}
{{- if and (kindIs "float64" $startup.periodSeconds) (kindIs "float64" $startup.failureThreshold) -}}
{{- $budget = printf "%.0f seconds" (mulf $startup.periodSeconds $startup.failureThreshold) -}}
{{- end -}}
{{- $envNames := list -}}
{{- range $entry := .Values.urlaubsverwaltung.env }}
{{- $envNames = append $envNames $entry.name }}
{{- end }}
{{- $httpRoute := .Values.httpRoute | default dict -}}
{{- $hostnames := $httpRoute.hostnames | default list -}}
{{- if not $hostnames -}}
{{- $hostnames = list .Values.ingress.domain -}}
{{- end -}}
Urlaubsverwaltung {{ .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

  The Ingress publishes the application at "/" with no path restriction, so
  everything the app serves is served under this host — including
  /swagger-ui.html and /v3/api-docs, which this app version enables by default
  and this chart does not turn off. Both are behind the login (they answer 302
  to the identity provider like every other path), so this is exposure of an
  API description, not of data. Turning them off is a
  springdoc.api-docs.enabled / springdoc.swagger-ui.enabled property; the chart
  sets neither, so it can be added through urlaubsverwaltung.env.
{{- else if $httpRoute.enabled }}

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

  The route publishes the application at "/" with no path restriction, exactly
  as the Ingress does — including /swagger-ui.html and /v3/api-docs, which this
  app version enables by default and this chart does not turn off. Both are
  behind the login, so this is exposure of an API description, not of data;
  springdoc.api-docs.enabled / springdoc.swagger-ui.enabled through
  urlaubsverwaltung.env is how to turn them off.

  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:

    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.

  THE HOSTNAME AND THE APPLICATION'S IDEA OF ITSELF STILL DO NOT AGREE BY
  THEMSELVES. No environment variable of the container derives from
  ingress.domain or from httpRoute.hostnames; the address the application
  considers its own is the OIDC redirect URI, out of the 1Password item below.
  The two can drift apart without any complaint — the route answers, the login
  bounces.

  ingress.annotations is inert in this mode: the Gateway API has no annotation
  channel. Nothing this chart needs lives there.
{{- 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;
  ingress.clusterIssuer is not needed, and neither is ingress.domain. Unlike
  other charts in this repo, ingress.domain is read by NOTHING here except the
  two routing templates — no environment variable of the container derives from
  it. The address the application considers its own is the OIDC redirect URI,
  and that comes out of the 1Password item below, not out of this value. The
  two can drift apart without any complaint.

  Reach the release inside the cluster with

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

  and open http://localhost:8080. The login redirects to your identity
  provider, which will refuse to come back to a localhost callback unless that
  exact URL is registered there as well.
{{- end }}
{{ if eq $replicas "0" }}
SCALED TO ZERO
  {{ if .Values.scaleDown }}scaleDown: true{{ else }}urlaubsverwaltung.replicas: 0{{ end }} — the Deployment runs with replicas: 0, so the endpoint
  above does not answer until you set it back and upgrade again. Both
  OnePasswordItem CRs and the 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 }} stay in place.{{ end }} This chart owns no volume: all
  state lives in the external database, so scaling to zero loses nothing.
{{ end }}
SECRETS — THE FIELDS EACH 1PASSWORD ITEM MUST CARRY
  The operator copies an item's FIELDS into the Kubernetes Secret, one key per
  field name, and this chart reads each key by name into an environment
  variable. The field names are decided here and appear nowhere in 1Password,
  so they are exactly what you would otherwise have to read out of the
  deployment template. They must match to the letter.

    secrets.databaseSecretRef → {{ .Values.secrets.databaseSecretRef }}
      → Secret {{ .Release.Name }}-{{ .Chart.Name }}-db-secret
        jdbc-url   a full JDBC URL, e.g.
                   jdbc:postgresql://postgres.example.com:5432/urlaubsverwaltung
        username
        password

    secrets.oidcSecretRef → {{ .Values.secrets.oidcSecretRef }}
      → Secret {{ .Release.Name }}-{{ .Chart.Name }}-oidc-secret
        client-id
        client-secret
        issuer-name      the provider's display name on the login button
        issuer-uri       the OIDC issuer, WITHOUT /.well-known/openid-configuration
        jwt-issuer-uri   the same issuer for the resource-server side
        redirect-uri     the full callback URL. This chart registers the client
                         under the id "default", so the path is
                         /login/oauth2/code/default — for example
                         https://{{ if or .Values.ingress.enabled $httpRoute.enabled }}{{ first $hostnames }}{{ else }}example.com{{ end }}/login/oauth2/code/default
                         and the same URL has to be registered at the provider.

  This chart deploys NO database and NO identity provider. Both have to exist
  already and be reachable from this namespace.

  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 a value INSIDE the
  same item does not. Helm never sees that content, so the rendered Deployment
  is unchanged and this chart stamps no checksum over the secrets — nothing
  restarts, and the pod keeps running with the old values:

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

THE IDENTITY PROVIDER IS REQUIRED AT BOOT, NOT AT LOGIN
  On start the application resolves the provider's configuration itself, with a
  GET on

    <issuer-uri>/.well-known/openid-configuration

  and it does this while building its security beans — before the HTTP port
  opens. An issuer-uri that does not resolve, is unreachable from this
  namespace, or answers something other than a discovery document therefore
  does not produce a broken login page: the process exits with

    Application run failed ... Unable to resolve Configuration with the
    provided Issuer of "<issuer-uri>"

  and the pod goes into CrashLoopBackOff having never served a request. So a
  provider that is down at rollout time keeps this release from starting at
  all. The reason is only in the log:

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

  Note the order: the database migration runs BEFORE this step. A rollout that
  dies on the identity provider has already migrated the schema.

STARTUP MIGRATES THE DATABASE, AND ROLLBACK DOES NOT UNMIGRATE
  Liquibase brings the schema up to date on every start, before anything is
  served; against an empty database it creates it from scratch and the app then
  seeds its initial settings, vacation types and sick-note types. The startup
  probe covers that whole window{{ if $budget }} ({{ $budget }}){{ end }} and holds liveness and readiness off
  until it is through. A measured cold start against an empty database — JVM,
  full migration, seeding — took about 30 seconds; an upgrade that carries a
  long migration takes longer, and if it outruns the budget the kubelet kills
  the container mid-migration and the next attempt starts over.

  helm rollback puts the previous app version back; the schema does not come
  back with it, because it was migrated in place. Take a database backup BEFORE
  an app-version upgrade. There is no volume in this release to back up — the
  database is the whole of the state.

  A failed rollout does not take the release down: the previous pod keeps
  serving until the new one becomes Ready. "helm upgrade" without --wait
  therefore reports success while the new pod crashloops behind it. Check:

    kubectl -n {{ .Release.Namespace }} rollout status deployment/{{ .Release.Name }}-{{ .Chart.Name }}-deployment

THE MEMORY LIMIT SIZES THE JAVA HEAP — IT IS NOT JUST A CEILING
  The image is built with Cloud Native Buildpacks, and its memory calculator
  reads the container's memory LIMIT at every start and derives -Xmx and the
  metaspace from it. In this release that limit is {{ $memLimit }}.
{{- if $memLimitExplicit }}
  It is set explicitly under urlaubsverwaltung.resources.limits.memory, which
  wins over the factor the chart would otherwise apply.
{{- else }}
  The chart does not set it directly: it is computed as
  urlaubsverwaltung.resources.limitFactor ({{ include "urlaubsverwaltung.formatNumber" $factor }})
  x the memory request ({{ $memRequest }}).
{{- end }}

  So the memory limit is not an operational safety margin here, it is a JVM
  tuning knob. Lowering it shrinks the heap; raising it raises the heap.
  A limit chosen too tightly does not merely risk an OOMKill under load —
  the calculator refuses to start at all when what is left after metaspace,
  code cache and the thread stacks is negative, and that failure appears before
  any application log line. The sizing it chose is the first line of the log:

    kubectl -n {{ .Release.Namespace }} logs deployment/{{ .Release.Name }}-{{ .Chart.Name }}-deployment | head -1

THE THREE HEALTH PATHS AND WHAT EACH ONE ANSWERS FOR
  This chart sets two health settings in the deployment template, and they are
  what makes the three paths mean different things:

    MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE=readinessState,db
    MANAGEMENT_HEALTH_MAIL_ENABLED=false

  /actuator/health            everything the release actually runs: db,
                              diskSpace, ping, ssl and the two lifecycle
                              states. 200 UP on a healthy release. The mail
                              indicator is NOT in it — see the mail section.
    → point external monitoring here. This is the only path that also fails on
      diskSpace or ssl.

  /actuator/health/readiness  readinessState AND db. Goes DOWN (503) on a
                              database outage, which takes the pod out of Ready
                              and stops traffic reaching it.
    → the readinessProbe.

  /actuator/health/liveness   livenessState alone, deliberately WITHOUT db.
                              Stays 200 through a database outage.
    → the livenessProbe and the startupProbe.

  The split is the point: a database outage has to keep traffic away, but
  restarting the pod does not bring the database back. Adding db to the
  liveness group would turn every outage into a crash loop on top of the
  outage. Measured on this chart, with the database scaled to zero underneath a
  running pod: readiness 503, liveness 200, pod 0/1 Ready, restart count 0 —
  the pod left Ready about 20 seconds after the database went away.

  The other half of that measurement matters just as much: when the database
  came back, the pod returned to Ready by itself within about five seconds,
  still with restart count 0. Nothing had to be rolled, deleted or scaled by
  hand. That is what leaving the liveness group alone buys — the outage is
  ridden out and then simply over.

  How readiness actually fails is worth knowing before you tune it. The db
  indicator does not answer 503 quickly — it waits out the JDBC connection
  timeout first, measured at 30 seconds against a database whose Service has no
  endpoints at all. readinessProbe.timeoutSeconds is 5, so the kubelet gives up
  long before the answer arrives and logs

    Readiness probe failed: ... context deadline exceeded

  rather than a 503. The pod leaves Ready either way, and faster; the 503 is
  what a client with patience sees. Raising timeoutSeconds past the JDBC
  timeout would swap the timeout for the 503 and delay the reaction — there is
  no reason to.

WHAT A READY POD DOES AND DOES NOT PROVE
  Ready now means the pod can reach the database — that is checked on every
  readiness period, not once at boot. It still does not mean the identity
  provider is reachable: OIDC is resolved once at startup (see below) and no
  health indicator watches it afterwards, so a provider that goes down after
  the rollout leaves a Ready pod on which nobody can log in.

  Ready also proves reachability, not correctness: the db indicator validates a
  connection, it never looks at the schema. Measured here — a database that came
  back EMPTY put the pod straight back to Ready with /actuator/health at 200,
  while not one table existed in it. A restored-but-wrong database reads as
  healthy, so a probe going green after a database incident is not on its own
  evidence that the data came back with it.

  A database outage now shows up in the pod's status: READY drops to 0/1 while
  STATUS stays Running and RESTARTS stays put. That combination — running, not
  restarting, not Ready — is the signature of a dependency outage rather than
  of a broken release. The reason is in the endpoint, not in the log:

    kubectl -n {{ .Release.Namespace }} get pod -l app={{ .Release.Name }}-{{ .Chart.Name }}-deployment
    kubectl -n {{ .Release.Namespace }} port-forward svc/{{ .Release.Name }}-{{ .Chart.Name }}-service 8080:80
    curl -s localhost:8080/actuator/health

  The body names components only when show-details is on; the chart does not
  set it, so the aggregate answers {"status":"DOWN","groups":[...]} and the
  status code carries the message. To see WHICH component is down, add

    urlaubsverwaltung.env:
      - name: MANAGEMENT_ENDPOINT_HEALTH_SHOW_DETAILS
        value: always

  and know what that publishes to anyone who can reach the endpoint: the
  database product, the container's filesystem path and free bytes, the
  certificate chains, and the stack-trace class of whatever failed.

  Note also that there is no shell in this image: "kubectl exec" cannot open
  one, and neither can a debug sidecar sharing the process namespace run the
  app's own tooling. Everything you can learn from a running pod, you learn
  from its log and its HTTP endpoints.

MAIL AND THE APPLICATION URL ARE PLACEHOLDERS UNTIL YOU SET THEM
  The chart hardcodes the mail wiring to values that work nowhere:

    SPRING_MAIL_HOST=localhost, SPRING_MAIL_PORT=1025
    UV_MAIL_FROM / UV_MAIL_REPLYTO = urlaubsverwaltung@example.org
    UV_CALENDAR_ORGANIZER = organizer@example.org
    UV_MAIL_APPLICATIONURL = http://localhost:8080

  Nothing in this pod listens on localhost:1025, so no notification mail leaves
  the release. UV_MAIL_APPLICATIONURL is what the app puts into the links
  inside those mails — it is NOT derived from ingress.domain. Left as it is,
  every link points at the reader's own machine.

  BECAUSE that wiring is a placeholder, the chart sets

    MANAGEMENT_HEALTH_MAIL_ENABLED=false

  and the mail indicator is gone from /actuator/health. Otherwise the aggregate
  would answer 503 DOWN on a perfectly healthy release for its whole lifetime,
  and any monitor pointed at it would page forever about a mail server nobody
  configured.

  THE PART THAT BITES LATER: the day you configure real mail delivery, switch
  the indicator back on in the SAME change —

    urlaubsverwaltung.env:
      - name: MANAGEMENT_HEALTH_MAIL_ENABLED
        value: "true"

  Left at false it does not report a false alarm, it reports nothing: the
  endpoint answers 200 while the mail server is unreachable and notifications
  are silently not delivered. The setting is only honest while there is no mail
  server to be honest about.

  Note that this variable repeats a name the chart already sets, so per the rule
  below it only takes effect when it goes in at INSTALL time. Put into an
  already installed release it does nothing at all, and says so nowhere: helm
  reports a successful upgrade while the container keeps "false".

urlaubsverwaltung.env IS ADDITIVE ONLY, AND A COLLISION IS LOST ON UPGRADE
  The entries are appended AFTER the chart's own list{{ if $envNames }} (this release appends:
  {{ join ", " $envNames }}){{ end }}. An entry that repeats a name the
  chart already sets does not replace it — it renders the variable twice, and
  what happens to that pair depends on WHEN it first appears:

  AT INSTALL both entries reach the pod and the later one — yours — wins in the
  container. The API server accepts it with a warning:

    Warning: spec.template.spec.containers[0].env[N]: hides previous definition
    of "NAME", which may be dropped when using apply

  AT UPGRADE that warning comes true. Kubernetes merges env by name, so the pair
  collapses back to ONE entry and the surviving value is the CHART's, not yours.
  Nothing fails: helm prints "Release has been upgraded", the revision counts up,
  and the override is simply gone. Measured on this chart (helm 3.19.0,
  Kubernetes 1.35): "helm get manifest" shows the variable twice while the live
  Deployment shows it once, with the chart's value.

  So the trap is silence, not an error. Treat the variables above as fixed for
  the life of a release: to really change one, reinstall. And never read a green
  upgrade as proof that an override took effect — read it off the object:

    kubectl -n {{ .Release.Namespace }} get deployment {{ .Release.Name }}-{{ .Chart.Name }}-deployment \
      -o jsonpath='{.spec.template.spec.containers[0].env}'

  Anything sensitive belongs in valueFrom.secretKeyRef rather than a plain
  value: a value is stored in the pod spec and readable by anyone who can read
  pods in {{ .Release.Namespace }}.
{{- if not $envNames }}

  urlaubsverwaltung.env is empty in this release, so the placeholders above are
  live exactly as printed.
{{- end }}