run on k8s based setups the migrations in a dedicated job

This commit is contained in:
Jonas Leder 2026-09-20 21:43:39 +02:00
commit d403eefe42
5 changed files with 186 additions and 86 deletions

View file

@ -75,6 +75,8 @@ the `ingester` service after creating one.
| `STORAGE_ENCRYPTION_KEY` | optional; enables at-rest encryption of archived mail |
| `INITIAL_ADMIN_EMAIL` / `INITIAL_ADMIN_PASSWORD` | seeded on first boot only |
| `ENABLE_SCHEDULER` | set to `false` on replicas that shouldn't run background jobs (optional — the lease makes this safe to leave on everywhere) |
| `EXECUTE_MIGRATIONS` | default `true`; set to `false` on the long-running api process when something else (e.g. the Helm chart's `db-migrate` Job) applies schema migrations instead |
| `MIGRATE_ONLY` | default `false`; set to `true` to run migrations/seeding and exit immediately instead of starting the server — used by the Helm chart's `db-migrate` Job |
### ingester
| Variable | Purpose |
@ -110,6 +112,13 @@ in-cluster hostname (`api`), matching `docker-compose.yml` — the chart
names the api `Service` accordingly, which means only one release of this
chart should run per namespace.
Schema migrations run via a dedicated `<release>-db-migrate` Job (the api
image with `MIGRATE_ONLY=true`), not on every api pod startup — the api
Deployment sets `EXECUTE_MIGRATIONS=false`. The Job is a Helm hook
(`post-install,pre-upgrade`) so it runs once per install/upgrade: after the
chart's Secrets exist on a fresh install, and before the api Deployment's
pods roll onto a new image on upgrade.
The chart deploys one ingester, authenticated via a bootstrap key
(`INGEST_BOOTSTRAP_API_KEY`) that works only while exactly one `Ingester`
exists in the database (the api auto-seeds one named "Default" on first

View file

@ -6,6 +6,7 @@ package main
import (
_ "github.com/joho/godotenv/autoload"
"jonasled.dev/jonasled/go-libs/config"
"jonasled.dev/jonasled/go-libs/log"
"jonasled.dev/jonasled/mail-achiver/api/auth"
"jonasled.dev/jonasled/mail-achiver/api/database"
@ -19,6 +20,17 @@ import (
func main() {
log.Init()
database.Init()
// Lets a Kubernetes Job run this same binary/image purely to apply
// pending schema migrations (see database.Init) before the api
// Deployment's pods roll out with EXECUTE_MIGRATIONS=false - so
// migrations run exactly once per release instead of racing across
// every api replica on every startup.
if config.GetOrDefault("MIGRATE_ONLY", "false") == "true" {
log.Log.Info("MIGRATE_ONLY is set, exiting after running database migrations")
return
}
auth.Init()
search.Init()

View file

@ -93,3 +93,99 @@ http://{{ include "mail-archiver.meilisearchFullname" . }}:{{ .Values.meilisearc
http://{{ .Values.meilisearch.external.host }}:{{ .Values.meilisearch.external.port }}
{{- end -}}
{{- end }}
{{/*
Env vars shared by the api Deployment and the db-migrate Job - both run the
same api image/binary against the same database and storage config, so this
is kept in one place rather than duplicated (and risking drift) between
deployment-api.yaml and job-migrate.yaml. Callers append their own
MIGRATE_ONLY / EXECUTE_MIGRATIONS entries after including this.
*/}}
{{- define "mail-archiver.apiEnv" -}}
- name: JWT_SECRET
valueFrom:
secretKeyRef:
name: {{ .Values.auth.existingSecret | default (printf "%s-jwt" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.auth.existingSecretJwtKey }}
- name: INITIAL_ADMIN_EMAIL
value: {{ .Values.admin.email | quote }}
- name: INITIAL_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: {{ .Values.admin.existingSecret | default (printf "%s-admin" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.admin.existingSecretPasswordKey }}
- name: INGEST_BOOTSTRAP_API_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.ingest.existingSecret | default (printf "%s-ingest" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.ingest.existingSecretApiKeyKey }}
{{- if .Values.ingest.bootstrapIngesterName }}
- name: INGEST_BOOTSTRAP_INGESTER_NAME
value: {{ .Values.ingest.bootstrapIngesterName | quote }}
{{- end }}
- name: DB_DRIVER
value: "mysql"
- name: DB_NAME
value: {{ .Values.mariadb.auth.database }}
- name: DB_USER
value: {{ .Values.mariadb.auth.username }}
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: {{ .Values.mariadb.auth.existingSecret | default (printf "%s-mariadb" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.mariadb.auth.existingSecretPasswordKey }}
- name: DB_HOST
value: {{ .Values.mariadb.external.host | quote }}
- name: DB_PORT
value: {{ .Values.mariadb.external.port | quote }}
- name: MEILISEARCH_HOST
value: {{ include "mail-archiver.meilisearchHost" . }}
{{- if .Values.meilisearch.enabled }}
{{- if eq (.Values.meilisearch.environment.MEILI_ENV | default "development") "production" }}
- name: MEILISEARCH_API_KEY
valueFrom:
secretKeyRef:
name: {{ include "mail-archiver.meilisearchFullname" . }}-master-key
key: MEILI_MASTER_KEY
{{- end }}
{{- else }}
- name: MEILISEARCH_API_KEY
value: {{ .Values.meilisearch.external.apiKey | quote }}
{{- end }}
- name: STORAGE_BACKEND
value: {{ .Values.storage.backend }}
{{- if eq .Values.storage.backend "file" }}
- name: STORAGE_FILE_PATH
value: "/data/mails"
{{- else }}
- name: STORAGE_S3_ENDPOINT
value: {{ .Values.storage.s3.endpoint | quote }}
- name: STORAGE_S3_REGION
value: {{ .Values.storage.s3.region | quote }}
- name: STORAGE_S3_BUCKET
value: {{ .Values.storage.s3.bucket | quote }}
- name: STORAGE_S3_USE_PATH_STYLE
value: {{ .Values.storage.s3.usePathStyle | quote }}
- name: STORAGE_S3_ACCESS_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.storage.s3.existingSecret | default (printf "%s-s3" (include "mail-archiver.fullname" .)) }}
key: access-key
- name: STORAGE_S3_SECRET_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.storage.s3.existingSecret | default (printf "%s-s3" (include "mail-archiver.fullname" .)) }}
key: secret-key
{{- end }}
{{- if or .Values.storage.encryptionKey .Values.storage.existingEncryptionKeySecret }}
- name: STORAGE_ENCRYPTION_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.storage.existingEncryptionKeySecret | default (printf "%s-storage-encryption" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.storage.existingEncryptionKeySecretKey }}
{{- end }}
- name: RETENTION_DEFAULT_DAYS
value: {{ .Values.retention.defaultDays | quote }}
- name: RETENTION_ENABLED
value: {{ .Values.retention.enabled | quote }}
{{- end }}

View file

@ -48,92 +48,12 @@ spec:
path: /readyz
port: http
env:
- name: JWT_SECRET
valueFrom:
secretKeyRef:
name: {{ .Values.auth.existingSecret | default (printf "%s-jwt" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.auth.existingSecretJwtKey }}
- name: INITIAL_ADMIN_EMAIL
value: {{ .Values.admin.email | quote }}
- name: INITIAL_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: {{ .Values.admin.existingSecret | default (printf "%s-admin" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.admin.existingSecretPasswordKey }}
- name: INGEST_BOOTSTRAP_API_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.ingest.existingSecret | default (printf "%s-ingest" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.ingest.existingSecretApiKeyKey }}
{{- if .Values.ingest.bootstrapIngesterName }}
- name: INGEST_BOOTSTRAP_INGESTER_NAME
value: {{ .Values.ingest.bootstrapIngesterName | quote }}
{{- end }}
- name: DB_DRIVER
value: "mysql"
- name: DB_NAME
value: {{ .Values.mariadb.auth.database }}
- name: DB_USER
value: {{ .Values.mariadb.auth.username }}
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: {{ .Values.mariadb.auth.existingSecret | default (printf "%s-mariadb" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.mariadb.auth.existingSecretPasswordKey }}
- name: DB_HOST
value: {{ .Values.mariadb.external.host | quote }}
- name: DB_PORT
value: {{ .Values.mariadb.external.port | quote }}
- name: MEILISEARCH_HOST
value: {{ include "mail-archiver.meilisearchHost" . }}
{{- if .Values.meilisearch.enabled }}
{{- if eq (.Values.meilisearch.environment.MEILI_ENV | default "development") "production" }}
- name: MEILISEARCH_API_KEY
valueFrom:
secretKeyRef:
name: {{ include "mail-archiver.meilisearchFullname" . }}-master-key
key: MEILI_MASTER_KEY
{{- end }}
{{- else }}
- name: MEILISEARCH_API_KEY
value: {{ .Values.meilisearch.external.apiKey | quote }}
{{- end }}
- name: STORAGE_BACKEND
value: {{ .Values.storage.backend }}
{{- if eq .Values.storage.backend "file" }}
- name: STORAGE_FILE_PATH
value: "/data/mails"
{{- else }}
- name: STORAGE_S3_ENDPOINT
value: {{ .Values.storage.s3.endpoint | quote }}
- name: STORAGE_S3_REGION
value: {{ .Values.storage.s3.region | quote }}
- name: STORAGE_S3_BUCKET
value: {{ .Values.storage.s3.bucket | quote }}
- name: STORAGE_S3_USE_PATH_STYLE
value: {{ .Values.storage.s3.usePathStyle | quote }}
- name: STORAGE_S3_ACCESS_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.storage.s3.existingSecret | default (printf "%s-s3" (include "mail-archiver.fullname" .)) }}
key: access-key
- name: STORAGE_S3_SECRET_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.storage.s3.existingSecret | default (printf "%s-s3" (include "mail-archiver.fullname" .)) }}
key: secret-key
{{- end }}
{{- if or .Values.storage.encryptionKey .Values.storage.existingEncryptionKeySecret }}
- name: STORAGE_ENCRYPTION_KEY
valueFrom:
secretKeyRef:
name: {{ .Values.storage.existingEncryptionKeySecret | default (printf "%s-storage-encryption" (include "mail-archiver.fullname" .)) }}
key: {{ .Values.storage.existingEncryptionKeySecretKey }}
{{- end }}
- name: RETENTION_DEFAULT_DAYS
value: {{ .Values.retention.defaultDays | quote }}
- name: RETENTION_ENABLED
value: {{ .Values.retention.enabled | quote }}
{{- include "mail-archiver.apiEnv" . | nindent 12 }}
# Schema migrations run once up front via the db-migrate Job
# (templates/job-migrate.yaml) instead of racing across every
# api replica on every startup/restart.
- name: EXECUTE_MIGRATIONS
value: "false"
{{- if eq .Values.storage.backend "file" }}
volumeMounts:
- name: mails

View file

@ -0,0 +1,63 @@
apiVersion: batch/v1
kind: Job
metadata:
name: {{ include "mail-archiver.fullname" . }}-db-migrate
labels:
{{- include "mail-archiver.labels" . | nindent 4 }}
annotations:
# Runs the api image with MIGRATE_ONLY=true so schema migrations apply
# exactly once per release instead of racing across every api replica
# on every startup (see EXECUTE_MIGRATIONS=false on the api Deployment).
#
# post-install rather than pre-install: this Job's env references
# Secrets from templates/secrets.yaml, which - like the rest of the
# chart's non-hook resources - are only created during Helm's main
# install phase, which runs *after* pre-install hooks but *before*
# post-install ones. A pre-install hook would fail on every fresh
# install with "secret not found". On upgrades those Secrets already
# exist from the prior release, so pre-upgrade (which runs before the
# api Deployment's pods are updated, gating new code on the new schema)
# is safe to use there.
helm.sh/hook: post-install,pre-upgrade
helm.sh/hook-weight: "0"
helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded
spec:
backoffLimit: 3
template:
metadata:
labels:
mail-archiver/service: db-migrate
{{- include "mail-archiver.selectorLabels" . | nindent 8 }}
spec:
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
serviceAccountName: {{ include "mail-archiver.serviceAccountName" . }}
securityContext:
{{- toYaml .Values.podSecurityContext | nindent 8 }}
restartPolicy: Never
containers:
- name: db-migrate
securityContext:
{{- toYaml .Values.securityContext | nindent 12 }}
image: "{{ .Values.image.repositoryApi }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
env:
{{- include "mail-archiver.apiEnv" . | nindent 12 }}
- name: MIGRATE_ONLY
value: "true"
resources:
{{- toYaml .Values.resources | nindent 12 }}
{{- with .Values.nodeSelector }}
nodeSelector:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.affinity }}
affinity:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.tolerations }}
tolerations:
{{- toYaml . | nindent 8 }}
{{- end }}