helm-charts/garage/templates/_helpers.tpl

{{/*
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).

NOTE: this helper is duplicated into every chart's templates/_helpers.tpl with
the chart's name as define prefix, because sharing it would mean a library
chart, and a dependency is admissible but expensive (README, guideline 14) -
this chart takes none. The reference implementation is
template-chart/templates/_helpers.tpl.
*/}}
{{- define "garage.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 "garage.resourceKey" $key) $value -}}
{{- end -}}
{{- end -}}
{{- $limits := dict -}}
{{- range $key, $value := ($resources.limits | default dict) -}}
{{- if not (kindIs "invalid" $value) -}}
{{- $_ := set $limits (include "garage.resourceKey" $key) $value -}}
{{- end -}}
{{- end -}}
{{- range $key, $request := $requests -}}
{{- if and (ne $key "cpu") (not (hasKey $limits $key)) -}}
{{- $_ := set $limits $key (include "garage.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 "garage.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>.
*/}}
{{- define "garage.multiplyQuantity" -}}
{{- $quantity := include "garage.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 "garage.formatNumber" $product) $suffix -}}
{{- end -}}
{{- end -}}

{{/*
Render a number as a plain decimal string, never in exponential notation
(issue #157): the null-safe fallback helpers pass values through fromYaml,
which parses every number as float64, and Go's "%v" switches float64 to
exponential notation from about 1e6 upwards - "1.048576e+06" is not a valid
Kubernetes quantity. Strings ("512Mi") are passed through untouched.
*/}}
{{- define "garage.formatNumber" -}}
{{- if kindIs "float64" . -}}
{{- regexReplaceAll "\\.?0+$" (printf "%.10f" .) "" -}}
{{- else -}}
{{- printf "%v" . -}}
{{- end -}}
{{- end -}}

{{/*
Render the replica count for the StatefulSet.

Input: dict "scaleDown" <flag|nil> "replicas" <value|nil>.

  - 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 kindIs "invalid"
    nil check.
  - a missing replicas value defaults to 1.

A NOTE SPECIFIC TO THIS CHART: more than one replica is not a cluster. Garage
nodes find each other through RPC and a cluster LAYOUT, and this chart renders
neither peer bootstrapping nor the kubernetes_discovery CRD (see values.yaml).
A second replica would come up as a lone node with its own empty metadata db on
its own volume, and with --single-node it refuses to start at all once it sees
the other node. The value exists because guideline 11 requires it and because
0 is the documented way to stop the release; the schema caps it at 1.
*/}}
{{- define "garage.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
(issues #61, #99). Input: dict "defaults" <dict> "given" <dict|nil> "path"
<string>. Output: YAML of the merged dict (consume it with fromYaml).

An override key written without children is YAML null, and Helm treats that
null as a deletion of the chart's default. This helper defines the opposite
semantics - an empty block means "chart defaults apply" - while an explicitly
set value still wins, including false and 0.
*/}}
{{- define "garage.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 "garage.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>.
*/}}
{{- define "garage.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 GARAGE SETTINGS - everything the ConfigMap and the StatefulSet
read out of .Values.garage, merged onto this chart's defaults.

Why the whole settings block goes through the null-safe helper and not only the
three usual suspects (guideline 12.2: "the rule is about the shape, not about
those three block kinds"): every value below is dereferenced by a template, and
an erased one would not abort the render - it would render a garage.toml with
an empty right-hand side, or a containerPort with no number. The first produces
a pod that crash-loops on a config parse error, the second a manifest the API
server rejects at apply time. Both are failures that arrive after the render
looked fine, which is exactly the class #99 is about. Satisfactory shipped the
same shape with half its blocks null-safe and half not (Gitea #16), and the
half that was not took the Service's port with it.

The defaults here MUST stay in sync with values.yaml, which remains the
documented, user-facing place for them; this copy is only the fallback.

Usage: {{ $settings := fromYaml (include "garage.settings" .) }}
*/}}
{{- define "garage.settings" -}}
{{- $given := (fromYaml (include "garage.subBlock" (dict "block" .Values "key" "garage" "path" ".Values"))).value -}}
{{- $defaults := dict
      "singleNode" true
      "defaultAccessKey" true
      "defaultBucket" true
      "replicationFactor" 1
      "dbEngine" "lmdb"
      "metadataFsync" true
      "dataFsync" false
      "metadataAutoSnapshotInterval" "6h"
      "compressionLevel" 1
      "blockSize" "1M"
      "bindAddress" "[::]"
      "adminBindAddress" "0.0.0.0"
      "ports" (dict "s3" 3900 "rpc" 3901 "web" 3902 "admin" 3903)
      "s3" (dict "region" "garage" "rootDomain" nil)
      "web" (dict "enabled" false "rootDomain" nil) -}}
{{- include "garage.defaultedDict" (dict "defaults" $defaults "given" $given "path" "garage") -}}
{{- end -}}

{{/*
The three directories, defined once because TWO templates have to agree on
them: garage.toml names them and the StatefulSet mounts the volumes underneath
them. They are deliberately NOT values - a path that disagrees with its mount
is a pod that writes its metadata into the container's ephemeral layer, which
looks like it works until the pod is replaced.

The split is the point of this chart's storage layout (see values.yaml):
metadata and data are two SUBDIRECTORIES OF ONE VOLUME, the metadata snapshots
sit on a SECOND one. Garage creates all three itself on start
(src/model/garage.rs, create_dir_all for metadata_dir and data_dir;
src/model/snapshot.rs for the snapshots dir), which matters here because the
image is FROM scratch and carries no mkdir - nothing else in this pod could
create them.
*/}}
{{- define "garage.dataVolumePath" -}}/mnt/garage{{- end -}}
{{- define "garage.metadataDir" -}}{{ include "garage.dataVolumePath" . }}/meta{{- end -}}
{{- define "garage.dataDir" -}}{{ include "garage.dataVolumePath" . }}/data{{- end -}}
{{- define "garage.snapshotsDir" -}}/mnt/garage-snapshots{{- end -}}

{{/*
The effective security contexts, probes and resources (issue #99).

The defaults below MUST stay in sync with values.yaml. They reproduce THIS
chart's defaults, not the repo standard - see the fsGroupChangePolicy note.
*/}}
{{- define "garage.podSecurityContext" -}}
{{- $given := (fromYaml (include "garage.subBlock" (dict "block" . "key" "pod" "path" "garage.securityContext"))).value -}}
{{- $defaults := dict
      "runAsNonRoot" true
      "runAsUser" 20000
      "runAsGroup" 1000
      "fsGroup" 1000
      "fsGroupChangePolicy" "OnRootMismatch"
      "seccompProfile" (dict "type" "RuntimeDefault") -}}
{{- include "garage.defaultedDict" (dict "defaults" $defaults "given" $given "path" "garage.securityContext.pod") -}}
{{- end -}}

{{- define "garage.containerSecurityContext" -}}
{{- $given := (fromYaml (include "garage.subBlock" (dict "block" . "key" "container" "path" "garage.securityContext"))).value -}}
{{- $defaults := dict
      "allowPrivilegeEscalation" false
      "readOnlyRootFilesystem" true
      "runAsNonRoot" true
      "capabilities" (dict "drop" (list "ALL") "add" (list)) -}}
{{- include "garage.defaultedDict" (dict "defaults" $defaults "given" $given "path" "garage.securityContext.container") -}}
{{- end -}}

{{/*
LIVENESS: a TCP connect to the admin port, and NOT the /health endpoint the
readiness probe uses. The reason is the one zipline wrote down (README,
guideline 12.3) in its sharpest form: /health answers 503 until the cluster
LAYOUT exists (src/rpc/system.rs, "Layout not yet configured, special case" ->
ClusterHealthStatus::Unavailable -> 503 in src/api/admin/special.rs). A node
waiting for its layout - every install with garage.singleNode: false, and any
install whose layout was lost - would therefore be killed and restarted
forever, and a restart is precisely what cannot fix it.

What the TCP probe does prove is what a liveness probe is for: the process is
alive and its listener is open. A wedged process that stops accepting is
restarted; a healthy process that has nothing to serve yet is not.
*/}}
{{- define "garage.livenessProbe" -}}
{{- $defaults := dict
      "tcpSocket" (dict "port" "admin")
      "periodSeconds" 10
      "timeoutSeconds" 5
      "failureThreshold" 3 -}}
{{- include "garage.defaultedDict" (dict "defaults" $defaults "given" . "path" "garage.livenessProbe") -}}
{{- end -}}

{{/*
READINESS: GET /health on the admin port - the one endpoint that answers the
question a readiness probe asks, namely "can this node serve requests".

Measured against the source at tag v2.4.1 rather than chosen:

  - the S3 API server is spawned independently of the layout state
    (src/garage/server.rs, the S3/web/admin servers are all spawned after
    initial_config), so the S3 socket binds and ANSWERS - with errors - before
    any layout exists. A tcpSocket probe on port 3900 would therefore report a
    service ready that accepts nothing, which is the lie this chart is not
    allowed to tell.
  - /health needs no token (@special in src/api/admin/router_v2.rs) and maps
    ClusterHealthStatus straight onto the status code: Healthy and Degraded ->
    200, Unavailable -> 503 with "Quorum is not available for some/all
    partitions, reads and writes will fail". An unconfigured layout is a
    special case in src/rpc/system.rs and yields Unavailable.

So with garage.singleNode: true the pod becomes Ready a moment after start
(initial_config applies the layout BEFORE the servers are spawned), and with
singleNode: false it stays not-Ready until an operator applies a layout by hand
- which is the truth, not a defect: until then the S3 endpoint accepts nothing
and no Service should route to it.
*/}}
{{- define "garage.readinessProbe" -}}
{{- $defaults := dict
      "httpGet" (dict "path" "/health" "port" "admin")
      "periodSeconds" 10
      "timeoutSeconds" 5
      "failureThreshold" 3 -}}
{{- include "garage.defaultedDict" (dict "defaults" $defaults "given" . "path" "garage.readinessProbe") -}}
{{- end -}}

{{/*
STARTUP: TCP again, for the same reason as liveness - a startup probe that
fails forever kills the container, so it must not depend on a layout that only
an operator can create.

Budget = periodSeconds * failureThreshold = 5 * 24 = 120s. It covers the slow
part of a real start, which is not Garage: attaching and mounting two network
volumes, plus opening (and on an unclean shutdown recovering) the LMDB
metadata database. Garage's own startup work after that is sub-second.
*/}}
{{- define "garage.startupProbe" -}}
{{- $defaults := dict
      "tcpSocket" (dict "port" "admin")
      "periodSeconds" 5
      "timeoutSeconds" 5
      "failureThreshold" 24 -}}
{{- include "garage.defaultedDict" (dict "defaults" $defaults "given" . "path" "garage.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.
*/}}
{{- define "garage.effectiveResources" -}}
{{- $defaults := dict
      "limitFactor" 3
      "requests" (dict "cpu" "100m" "memory" "512Mi" "ephemeral-storage" "32Mi") -}}
{{- $merged := fromYaml (include "garage.defaultedDict" (dict "defaults" $defaults "given" . "path" "garage.resources")) -}}
{{- include "garage.resources" $merged -}}
{{- end -}}

{{/*
The additive env block, rendered through tpl with the value, secretKeyRef and
configMapKeyRef forms (guideline 10).

ADDITIVE MEANS ADDITIVE: an entry repeating a name this chart already sets does
not replace it. At install time both reach the pod and the later one wins; on
an EXISTING release the pair collapses to the chart's own value, because
Kubernetes merges env by name - and helm upgrade still reports success. So do
not use this block to override GARAGE_RPC_SECRET or the three
GARAGE_DEFAULT_* variables; change the values that produce them.
*/}}
{{- define "garage.env" -}}
{{- $root := .root -}}
{{- range $value := .env }}
{{- if $value.value }}
- name: {{ $value.name | quote }}
  # quote is required, not cosmetic: a value like "3900" 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 $root | quote }}
{{- else if $value.valueFrom }}
{{- if $value.valueFrom.secretKeyRef }}
- name: {{ $value.name }}
  valueFrom:
    secretKeyRef:
      name: {{ tpl $value.valueFrom.secretKeyRef.name $root | quote }}
      key: {{ tpl $value.valueFrom.secretKeyRef.key $root | quote }}
{{- else if $value.valueFrom.configMapKeyRef }}
- name: {{ $value.name }}
  valueFrom:
    configMapKeyRef:
      name: {{ tpl $value.valueFrom.configMapKeyRef.name $root | quote }}
      key: {{ tpl $value.valueFrom.configMapKeyRef.key $root | quote }}
{{- end }}
{{- end }}
{{- end }}
{{- end -}}