Skip to content

Upgrades & migrations

The schema is versioned with embedded migrations. By default (database.autoMigrate: true) every server applies pending migrations at startup, under a Postgres advisory lock, so several replicas can start at once and only one migrates.

To control migrations yourself — for example from a pre-upgrade Job, or with a database user that has DDL rights the server doesn’t — turn automatic migration off and run:

Terminal window
entrepot migrate -config config.yaml # applies pending migrations and exits

Values stored before encryption at rest was enabled are re-sealed with the current key at startup; no manual step is needed.

  1. Back up Postgres (and note the blob stores’ snapshot state). See Backups.

  2. Read the release notes for configuration or values changes, and diff the rendered manifests:

    Terminal window
    helm template entrepot oci://ghcr.io/entrepotproj/charts/entrepot --version <new> -f my-values.yaml > new.yaml
  3. Upgrade:

    Terminal window
    helm upgrade entrepot oci://ghcr.io/entrepotproj/charts/entrepot --version <new> -n entrepot -f my-values.yaml

    With S3 or ReadWriteMany stores the Deployment rolls pods one at a time. With a ReadWriteOnce (EBS) store it uses Recreate, so expect a short outage while the volume moves to the new pod.

  4. Check /readyz, the logs and GET /api/v1/system/info (which reports the running version).

  • Secrets key — see Secrets at rest: deploy the new key with the old one in secrets.previousKeys, then drop the old one.
  • Session secret — changing it signs everyone out and invalidates outstanding registry tokens. If secrets.key is not set, add the old session secret to secrets.previousKeys first.
  • OIDC client secret, GitLab API tokens, bootstrap token — update the Kubernetes Secret and restart the pods.
  • Repository signing keys — rotate through the API.

A repository’s blob store is fixed at creation. To move a repository:

  1. Create a new store and a new repository on it.
  2. For proxies, just switch clients over — the new proxy fills itself on demand. Delete the old repository when traffic has moved.
  3. For hosted repositories, re-publish the content with the native client (npm publish, twine upload, crane copy, curl -T) or a script over GET /api/v1/repositories/{name}/assets and POST …/upload, then point a group at the new repository.

Unreferenced blobs in the old store are garbage-collected after the old repository is deleted.