nixos/modules/services/web-servers/garage.md

   1 # Garage {#module-services-garage}
   2
   3 [Garage](https://garagehq.deuxfleurs.fr/)
   4 is an open-source, self-hostable S3 store, simpler than MinIO, for geodistributed stores.
   5 The server setup can be automated using
   6 [services.garage](#opt-services.garage.enable). A
   7  client configured to your local Garage instance is available in
   8  the global environment as `garage-manage`.
   9
  10 The current default by NixOS is `garage_0_8` which is also the latest
  11 major version available.
  12
  13 ## General considerations on upgrades {#module-services-garage-upgrade-scenarios}
  14
  15 Garage provides a cookbook documentation on how to upgrade:
  16 <https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/>
  17
  18 ::: {.warning}
  19 Garage has two types of upgrades: patch-level upgrades and minor/major version upgrades.
  20
  21 In all cases, you should read the changelog and ideally test the upgrade on a staging cluster.
  22
  23 Checking the health of your cluster can be achieved using `garage-manage repair`.
  24 :::
  25
  26 ::: {.warning}
  27 Until 1.0 is released, patch-level upgrades are considered as minor version upgrades.
  28 Minor version upgrades are considered as major version upgrades.
  29 i.e. 0.6 to 0.7 is a major version upgrade.
  30 :::
  31
  32   - **Straightforward upgrades (patch-level upgrades).**
  33     Upgrades must be performed one by one, i.e. for each node, stop it, upgrade it : change [stateVersion](#opt-system.stateVersion) or [services.garage.package](#opt-services.garage.package), restart it if it was not already by switching.
  34   - **Multiple version upgrades.**
  35     Garage do not provide any guarantee on moving more than one major-version forward.
  36     E.g., if you're on `0.7`, you cannot upgrade to `0.9`.
  37     You need to upgrade to `0.8` first.
  38     As long as [stateVersion](#opt-system.stateVersion) is declared properly,
  39     this is enforced automatically. The module will issue a warning to remind the user to upgrade to latest
  40     Garage *after* that deploy.
  41
  42 ## Advanced upgrades (minor/major version upgrades) {#module-services-garage-advanced-upgrades}
  43
  44 Here are some baseline instructions to handle advanced upgrades in Garage, when in doubt, please refer to upstream instructions.
  45
  46   - Disable API and web access to Garage.
  47   - Perform `garage-manage repair --all-nodes --yes tables` and `garage-manage repair --all-nodes --yes blocks`.
  48   - Verify the resulting logs and check that data is synced properly between all nodes.
  49     If you have time, do additional checks (`scrub`, `block_refs`, etc.).
  50   - Check if queues are empty by `garage-manage stats` or through monitoring tools.
  51   - Run `systemctl stop garage` to stop the actual Garage version.
  52   - Backup the metadata folder of ALL your nodes, e.g. for a metadata directory (the default one) in `/var/lib/garage/meta`,
  53     you can run `pushd /var/lib/garage; tar -acf meta-v0.7.tar.zst meta/; popd`.
  54   - Run the offline migration: `nix-shell -p garage_0_8 --run "garage offline-repair --yes"`, this can take some time depending on how many objects are stored in your cluster.
  55   - Bump Garage version in your NixOS configuration, either by changing [stateVersion](#opt-system.stateVersion) or bumping [services.garage.package](#opt-services.garage.package), this should restart Garage automatically.
  56   - Perform `garage-manage repair --all-nodes --yes tables` and `garage-manage repair --all-nodes --yes blocks`.
  57   - Wait for a full table sync to run.
  58
  59 Your upgraded cluster should be in a working state, re-enable API and web access.
  60
  61 ## Maintainer information {#module-services-garage-maintainer-info}
  62
  63 As stated in the previous paragraph, we must provide a clean upgrade-path for Garage
  64 since it cannot move more than one major version forward on a single upgrade. This chapter
  65 adds some notes how Garage updates should be rolled out in the future.
  66 This is inspired from how Nextcloud does it.
  67
  68 While patch-level updates are no problem and can be done directly in the
  69 package-expression (and should be backported to supported stable branches after that),
  70 major-releases should be added in a new attribute (e.g. Garage `v0.8.0`
  71 should be available in `nixpkgs` as `pkgs.garage_0_8_0`).
  72 To provide simple upgrade paths it's generally useful to backport those as well to stable
  73 branches. As long as the package-default isn't altered, this won't break existing setups.
  74 After that, the versioning-warning in the `garage`-module should be
  75 updated to make sure that the
  76 [package](#opt-services.garage.package)-option selects the latest version
  77 on fresh setups.
  78
  79 If major-releases will be abandoned by upstream, we should check first if those are needed
  80 in NixOS for a safe upgrade-path before removing those. In that case we should keep those
  81 packages, but mark them as insecure in an expression like this (in
  82 `<nixpkgs/pkgs/tools/filesystem/garage/default.nix>`):
  83 ```
  84 /* ... */
  85 {
  86   garage_0_7_3 = generic {
  87     version = "0.7.3";
  88     sha256 = "0000000000000000000000000000000000000000000000000000";
  89     eol = true;
  90   };
  91 }
  92 ```
  93
  94 Ideally we should make sure that it's possible to jump two NixOS versions forward:
  95 i.e. the warnings and the logic in the module should guard a user to upgrade from a
  96 Garage on e.g. 22.11 to a Garage on 23.11.