commit 8a86d1f7592bca2a0b8d0f5c959ae7cb906cc9bd · pyrox.dev/nixpkgs

+96

nixos/modules/services/web-servers/garage-doc.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 shold 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.

+191 -128

nixos/modules/services/web-servers/garage-doc.xml

···

       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
                version="5.0"

     

       5
       -
                xml:id="module-services-garage">

     

       6
       -
        <title>Garage</title>

     

       7
       -
        <para>

     

       8
       -
         <link xlink:href="https://garagehq.deuxfleurs.fr/">Garage</link>

     

       9
       -
         is an open-source, self-hostable S3 store, simpler than MinIO, for geodistributed stores.

     

       10
       -
         The server setup can be automated using

     

       11
       -
         <link linkend="opt-services.garage.enable">services.garage</link>. A

     

       12
       -
          client configured to your local Garage instance is available in

     

       13
       -
          the global environment as <literal>garage-manage</literal>.

     

       14
       -
        </para>

     

       15
       -
        <para>

     

       16
       -
         The current default by NixOS is <literal>garage_0_8</literal> which is also the latest

     

       17
       -
         major version available.

     

       18
       -
        </para>

     

       19
       -
        <section xml:id="module-services-garage-upgrade-scenarios">

     

       20
       -
         <title>General considerations on upgrades</title>

     

       21
       -
       

     

       22
        
         <para>

     

       23
       -
           Garage provides a cookbook documentation on how to upgrade:

     

       24
       -
          <link xlink:href="https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/">https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/</link>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       25
        
         </para>

     

       26
       -
       

     

       27
       -
        <warning>

     

       28
       -
          <para>Garage has two types of upgrades: patch-level upgrades and minor/major version upgrades.</para>

     

       29
       -
       

     

       30
       -
          <para>In all cases, you should read the changelog and ideally test the upgrade on a staging cluster.</para>

     

       31
       -
       

     

       32
       -
          <para>Checking the health of your cluster can be achieved using <literal>garage-manage repair</literal>.</para>

     

       33
       -
         </warning>

     

       34
       -
       

     

       35
       -
       

     

       36
       -
        <warning>

     

       37
       -
          <para>Until 1.0 is released, patch-level upgrades are considered as minor version upgrades.

     

       38
       -
          Minor version upgrades are considered as major version upgrades.

     

       39
       -
           i.e. 0.6 to 0.7 is a major version upgrade.</para>

     

       40
       -
        </warning>

     

       41
       -
       

     

       42
       -
        <itemizedlist>

     

       43
       -
         <listitem>

     

       44
       -
          <formalpara>

     

       45
       -
           <title>Straightforward upgrades (patch-level upgrades)</title>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       46
        
           <para>

     

       47
       -
            Upgrades must be performed one by one, i.e. for each node, stop it, upgrade it : change <link linkend="opt-system.stateVersion">stateVersion</link> or <link linkend="opt-services.garage.package">services.garage.package</link>, restart it if it was not already by switching.

     

       0
        
       
     

       48
        
           </para>

     

       49
       -
          </formalpara>

     

       50
       -
         </listitem>

     

       51
       -
       

     

       52
       -
         <listitem>

     

       53
       -
          <formalpara>

     

       54
       -
           <title>Multiple version upgrades</title>

     

       55
        
           <para>

     

       56
       -
            Garage do not provide any guarantee on moving more than one major-version forward.

     

       57
       -
            E.g., if you're on <literal>0.7</literal>, you cannot upgrade to <literal>0.9</literal>.

     

       58
       -
            You need to upgrade to <literal>0.8</literal> first.

     

       59
       -
       

     

       60
       -
            As long as <link linkend="opt-system.stateVersion">stateVersion</link> is declared properly,

     

       61
       -
            this is enforced automatically. The module will issue a warning to remind the user to upgrade to latest

     

       62
       -
            Garage <emphasis>after</emphasis> that deploy.

     

       63
       -
          </para>

     

       64
       -
         </formalpara>

     

       65
       -
        </listitem>

     

       66
       -
       </itemizedlist>

     

       67
       -
       </section>

     

       68
       -
       

     

       69
       -
       <section xml:id="module-services-garage-advanced-upgrades">

     

       70
       -
        <title>Advanced upgrades (minor/major version upgrades)</title>

     

       71
       -
        <para>Here are some baseline instructions to handle advanced upgrades in Garage, when in doubt, please refer to upstream instructions.</para>

     

       72
       -
       

     

       73
       -
        <itemizedlist>

     

       74
       -
          <listitem><para>Disable API and web access to Garage.</para></listitem>

     

       75
       -
          <listitem><para>Perform <literal>garage-manage repair --all-nodes --yes tables</literal> and <literal>garage-manage repair --all-nodes --yes blocks</literal>.</para></listitem>

     

       76
       -
          <listitem><para>Verify the resulting logs and check that data is synced properly between all nodes.

     

       77
       -
           If you have time, do additional checks (<literal>scrub</literal>, <literal>block_refs</literal>, etc.).</para></listitem>

     

       78
       -
          <listitem><para>Check if queues are empty by <literal>garage-manage stats</literal> or through monitoring tools.</para></listitem>

     

       79
       -
          <listitem><para>Run <literal>systemctl stop garage</literal> to stop the actual Garage version.</para></listitem>

     

       80
       -
          <listitem><para>Backup the metadata folder of ALL your nodes, e.g. for a metadata directory (the default one) in <literal>/var/lib/garage/meta</literal>,

     

       81
       -
           you can run <literal>pushd /var/lib/garage; tar -acf meta-v0.7.tar.zst meta/; popd</literal>.</para></listitem>

     

       82
       -
          <listitem><para>Run the offline migration: <literal>nix-shell -p garage_0_8 --run "garage offline-repair --yes"</literal>, this can take some time depending on how many objects are stored in your cluster.</para></listitem>

     

       83
       -
          <listitem><para>Bump Garage version in your NixOS configuration, either by changing <link linkend="opt-system.stateVersion">stateVersion</link> or bumping <link linkend="opt-services.garage.package">services.garage.package</link>, this should restart Garage automatically.</para></listitem>

     

       84
       -
          <listitem><para>Perform <literal>garage-manage repair --all-nodes --yes tables</literal> and <literal>garage-manage repair --all-nodes --yes blocks</literal>.</para></listitem>

     

       85
       -
          <listitem><para>Wait for a full table sync to run.</para></listitem>

     

       86
       -
        </itemizedlist>

     

       87
       -
       

     

       88
       -
        <para>

     

       89
       -
          Your upgraded cluster should be in a working state, re-enable API and web access.

     

       90
       -
        </para>

     

       91
       -
       </section>

     

       92
       -
       

     

       93
       -
       <section xml:id="module-services-garage-maintainer-info">

     

       94
       -
         <title>Maintainer information</title>

     

       95
       -
       

     

       96
       -
         <para>

     

       97
       -
          As stated in the previous paragraph, we must provide a clean upgrade-path for Garage

     

       98
       -
          since it cannot move more than one major version forward on a single upgrade. This chapter

     

       99
       -
          adds some notes how Garage updates should be rolled out in the future.

     

       100
       -
       

     

       101
       -
          This is inspired from how Nextcloud does it.

     

       102
       -
         </para>

     

       103
       -
       

     

       104
       -
         <para>

     

       105
       -
          While patch-level updates are no problem and can be done directly in the

     

       106
       -
          package-expression (and should be backported to supported stable branches after that),

     

       107
       -
          major-releases should be added in a new attribute (e.g. Garage <literal>v0.8.0</literal>

     

       108
       -
          should be available in <literal>nixpkgs</literal> as <literal>pkgs.garage_0_8_0</literal>).

     

       109
       -
          To provide simple upgrade paths it's generally useful to backport those as well to stable

     

       110
       -
          branches. As long as the package-default isn't altered, this won't break existing setups.

     

       111
       -
          After that, the versioning-warning in the <literal>garage</literal>-module should be

     

       112
       -
          updated to make sure that the

     

       113
       -
          <link linkend="opt-services.garage.package">package</link>-option selects the latest version

     

       114
       -
          on fresh setups.

     

       115
       -
         </para>

     

       116
       -
       

     

       117
       -
         <para>

     

       118
       -
          If major-releases will be abandoned by upstream, we should check first if those are needed

     

       119
       -
          in NixOS for a safe upgrade-path before removing those. In that case we shold keep those

     

       120
       -
          packages, but mark them as insecure in an expression like this (in

     

       121
       -
          <literal>&lt;nixpkgs/pkgs/tools/filesystem/garage/default.nix&gt;</literal>):

     

       122
       -
       <programlisting>

     

       123
        
       /* ... */

     

       124
        
       {

     

       125
        
         garage_0_7_3 = generic {

     

       126
       -
           version = "0.7.3";

     

       127
       -
           sha256 = "0000000000000000000000000000000000000000000000000000";

     

       128
        
           eol = true;

     

       129
        
         };

     

       130
        
       }

     

       131
        
       </programlisting>

     

       132
       -
         </para>

     

       133
       -
       

     

       134
       -
         <para>

     

       135
       -
          Ideally we should make sure that it's possible to jump two NixOS versions forward:

     

       136
       -
          i.e. the warnings and the logic in the module should guard a user to upgrade from a

     

       137
       -
          Garage on e.g. 22.11 to a Garage on 23.11.

     

       138
       -
         </para>

     

       139
       -
        </section>

     

       140
       -
       

     

       141
        
       </chapter>

···

       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-garage">

     

       2
       +
         <title>Garage</title>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       3
        
         <para>

     

       4
       +
           <link xlink:href="https://garagehq.deuxfleurs.fr/">Garage</link> is

     

       5
       +
           an open-source, self-hostable S3 store, simpler than MinIO, for

     

       6
       +
           geodistributed stores. The server setup can be automated using

     

       7
       +
           <link linkend="opt-services.garage.enable">services.garage</link>. A

     

       8
       +
           client configured to your local Garage instance is available in the

     

       9
       +
           global environment as <literal>garage-manage</literal>.

     

       10
        
         </para>

     

       11
       +
         <para>

     

       12
       +
           The current default by NixOS is <literal>garage_0_8</literal> which

     

       13
       +
           is also the latest major version available.

     

       14
       +
         </para>

     

       15
       +
         <section xml:id="module-services-garage-upgrade-scenarios">

     

       16
       +
           <title>General considerations on upgrades</title>

     

       17
       +
           <para>

     

       18
       +
             Garage provides a cookbook documentation on how to upgrade:

     

       19
       +
             <link xlink:href="https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/" role="uri">https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/</link>

     

       20
       +
           </para>

     

       21
       +
           <warning>

     

       22
       +
             <para>

     

       23
       +
               Garage has two types of upgrades: patch-level upgrades and

     

       24
       +
               minor/major version upgrades.

     

       25
       +
             </para>

     

       26
       +
             <para>

     

       27
       +
               In all cases, you should read the changelog and ideally test the

     

       28
       +
               upgrade on a staging cluster.

     

       29
       +
             </para>

     

       30
       +
             <para>

     

       31
       +
               Checking the health of your cluster can be achieved using

     

       32
       +
               <literal>garage-manage repair</literal>.

     

       33
       +
             </para>

     

       34
       +
           </warning>

     

       35
       +
           <warning>

     

       36
       +
             <para>

     

       37
       +
               Until 1.0 is released, patch-level upgrades are considered as

     

       38
       +
               minor version upgrades. Minor version upgrades are considered as

     

       39
       +
               major version upgrades. i.e. 0.6 to 0.7 is a major version

     

       40
       +
               upgrade.

     

       41
       +
             </para>

     

       42
       +
           </warning>

     

       43
       +
           <itemizedlist spacing="compact">

     

       44
       +
             <listitem>

     

       45
       +
               <para>

     

       46
       +
                 <emphasis role="strong">Straightforward upgrades (patch-level

     

       47
       +
                 upgrades).</emphasis> Upgrades must be performed one by one,

     

       48
       +
                 i.e. for each node, stop it, upgrade it : change

     

       49
       +
                 <link linkend="opt-system.stateVersion">stateVersion</link> or

     

       50
       +
                 <link linkend="opt-services.garage.package">services.garage.package</link>,

     

       51
       +
                 restart it if it was not already by switching.

     

       52
       +
               </para>

     

       53
       +
             </listitem>

     

       54
       +
             <listitem>

     

       55
       +
               <para>

     

       56
       +
                 <emphasis role="strong">Multiple version upgrades.</emphasis>

     

       57
       +
                 Garage do not provide any guarantee on moving more than one

     

       58
       +
                 major-version forward. E.g., if you're on

     

       59
       +
                 <literal>0.7</literal>, you cannot upgrade to

     

       60
       +
                 <literal>0.9</literal>. You need to upgrade to

     

       61
       +
                 <literal>0.8</literal> first. As long as

     

       62
       +
                 <link linkend="opt-system.stateVersion">stateVersion</link> is

     

       63
       +
                 declared properly, this is enforced automatically. The module

     

       64
       +
                 will issue a warning to remind the user to upgrade to latest

     

       65
       +
                 Garage <emphasis>after</emphasis> that deploy.

     

       66
       +
               </para>

     

       67
       +
             </listitem>

     

       68
       +
           </itemizedlist>

     

       69
       +
         </section>

     

       70
       +
         <section xml:id="module-services-garage-advanced-upgrades">

     

       71
       +
           <title>Advanced upgrades (minor/major version upgrades)</title>

     

       72
       +
           <para>

     

       73
       +
             Here are some baseline instructions to handle advanced upgrades in

     

       74
       +
             Garage, when in doubt, please refer to upstream instructions.

     

       75
       +
           </para>

     

       76
       +
           <itemizedlist spacing="compact">

     

       77
       +
             <listitem>

     

       78
       +
               <para>

     

       79
       +
                 Disable API and web access to Garage.

     

       80
       +
               </para>

     

       81
       +
             </listitem>

     

       82
       +
             <listitem>

     

       83
       +
               <para>

     

       84
       +
                 Perform

     

       85
       +
                 <literal>garage-manage repair --all-nodes --yes tables</literal>

     

       86
       +
                 and

     

       87
       +
                 <literal>garage-manage repair --all-nodes --yes blocks</literal>.

     

       88
       +
               </para>

     

       89
       +
             </listitem>

     

       90
       +
             <listitem>

     

       91
       +
               <para>

     

       92
       +
                 Verify the resulting logs and check that data is synced

     

       93
       +
                 properly between all nodes. If you have time, do additional

     

       94
       +
                 checks (<literal>scrub</literal>,

     

       95
       +
                 <literal>block_refs</literal>, etc.).

     

       96
       +
               </para>

     

       97
       +
             </listitem>

     

       98
       +
             <listitem>

     

       99
       +
               <para>

     

       100
       +
                 Check if queues are empty by

     

       101
       +
                 <literal>garage-manage stats</literal> or through monitoring

     

       102
       +
                 tools.

     

       103
       +
               </para>

     

       104
       +
             </listitem>

     

       105
       +
             <listitem>

     

       106
       +
               <para>

     

       107
       +
                 Run <literal>systemctl stop garage</literal> to stop the

     

       108
       +
                 actual Garage version.

     

       109
       +
               </para>

     

       110
       +
             </listitem>

     

       111
       +
             <listitem>

     

       112
       +
               <para>

     

       113
       +
                 Backup the metadata folder of ALL your nodes, e.g. for a

     

       114
       +
                 metadata directory (the default one) in

     

       115
       +
                 <literal>/var/lib/garage/meta</literal>, you can run

     

       116
       +
                 <literal>pushd /var/lib/garage; tar -acf meta-v0.7.tar.zst meta/; popd</literal>.

     

       117
       +
               </para>

     

       118
       +
             </listitem>

     

       119
       +
             <listitem>

     

       120
       +
               <para>

     

       121
       +
                 Run the offline migration:

     

       122
       +
                 <literal>nix-shell -p garage_0_8 --run &quot;garage offline-repair --yes&quot;</literal>,

     

       123
       +
                 this can take some time depending on how many objects are

     

       124
       +
                 stored in your cluster.

     

       125
       +
               </para>

     

       126
       +
             </listitem>

     

       127
       +
             <listitem>

     

       128
       +
               <para>

     

       129
       +
                 Bump Garage version in your NixOS configuration, either by

     

       130
       +
                 changing

     

       131
       +
                 <link linkend="opt-system.stateVersion">stateVersion</link> or

     

       132
       +
                 bumping

     

       133
       +
                 <link linkend="opt-services.garage.package">services.garage.package</link>,

     

       134
       +
                 this should restart Garage automatically.

     

       135
       +
               </para>

     

       136
       +
             </listitem>

     

       137
       +
             <listitem>

     

       138
       +
               <para>

     

       139
       +
                 Perform

     

       140
       +
                 <literal>garage-manage repair --all-nodes --yes tables</literal>

     

       141
       +
                 and

     

       142
       +
                 <literal>garage-manage repair --all-nodes --yes blocks</literal>.

     

       143
       +
               </para>

     

       144
       +
             </listitem>

     

       145
       +
             <listitem>

     

       146
       +
               <para>

     

       147
       +
                 Wait for a full table sync to run.

     

       148
       +
               </para>

     

       149
       +
             </listitem>

     

       150
       +
           </itemizedlist>

     

       151
        
           <para>

     

       152
       +
             Your upgraded cluster should be in a working state, re-enable API

     

       153
       +
             and web access.

     

       154
        
           </para>

     

       155
       +
         </section>

     

       156
       +
         <section xml:id="module-services-garage-maintainer-info">

     

       157
       +
           <title>Maintainer information</title>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       158
        
           <para>

     

       159
       +
             As stated in the previous paragraph, we must provide a clean

     

       160
       +
             upgrade-path for Garage since it cannot move more than one major

     

       161
       +
             version forward on a single upgrade. This chapter adds some notes

     

       162
       +
             how Garage updates should be rolled out in the future. This is

     

       163
       +
             inspired from how Nextcloud does it.

     

       164
       +
           </para>

     

       165
       +
           <para>

     

       166
       +
             While patch-level updates are no problem and can be done directly

     

       167
       +
             in the package-expression (and should be backported to supported

     

       168
       +
             stable branches after that), major-releases should be added in a

     

       169
       +
             new attribute (e.g. Garage <literal>v0.8.0</literal> should be

     

       170
       +
             available in <literal>nixpkgs</literal> as

     

       171
       +
             <literal>pkgs.garage_0_8_0</literal>). To provide simple upgrade

     

       172
       +
             paths it's generally useful to backport those as well to stable

     

       173
       +
             branches. As long as the package-default isn't altered, this won't

     

       174
       +
             break existing setups. After that, the versioning-warning in the

     

       175
       +
             <literal>garage</literal>-module should be updated to make sure

     

       176
       +
             that the

     

       177
       +
             <link linkend="opt-services.garage.package">package</link>-option

     

       178
       +
             selects the latest version on fresh setups.

     

       179
       +
           </para>

     

       180
       +
           <para>

     

       181
       +
             If major-releases will be abandoned by upstream, we should check

     

       182
       +
             first if those are needed in NixOS for a safe upgrade-path before

     

       183
       +
             removing those. In that case we shold keep those packages, but

     

       184
       +
             mark them as insecure in an expression like this (in

     

       185
       +
             <literal>&lt;nixpkgs/pkgs/tools/filesystem/garage/default.nix&gt;</literal>):

     

       186
       +
           </para>

     

       187
       +
           <programlisting>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       188
        
       /* ... */

     

       189
        
       {

     

       190
        
         garage_0_7_3 = generic {

     

       191
       +
           version = &quot;0.7.3&quot;;

     

       192
       +
           sha256 = &quot;0000000000000000000000000000000000000000000000000000&quot;;

     

       193
        
           eol = true;

     

       194
        
         };

     

       195
        
       }

     

       196
        
       </programlisting>

     

       197
       +
           <para>

     

       198
       +
             Ideally we should make sure that it's possible to jump two NixOS

     

       199
       +
             versions forward: i.e. the warnings and the logic in the module

     

       200
       +
             should guard a user to upgrade from a Garage on e.g. 22.11 to a

     

       201
       +
             Garage on 23.11.

     

       202
       +
           </para>

     

       203
       +
         </section>

     

       0
        
       
     

       0
        
       
     

       204
        
       </chapter>

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

···

       9
        
       in

     

       10
        
       {

     

       11
        
         meta = {

     

       0
        
       
     

       0
        
       
     

       12
        
           doc = ./garage-doc.xml;

     

       13
        
           maintainers = with pkgs.lib.maintainers; [ raitobezarius ];

     

       14
        
         };

···

       9
        
       in

     

       10
        
       {

     

       11
        
         meta = {

     

       12
       +
           # Don't edit the docbook xml directly, edit the md and generate it:

     

       13
       +
           # `pandoc garage-doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > garage-doc.xml`

     

       14
        
           doc = ./garage-doc.xml;

     

       15
        
           maintainers = with pkgs.lib.maintainers; [ raitobezarius ];

     

       16
        
         };