pyrox.dev
lol
nixos/garage: convert manual chapter to MD
+289
-128
+96
nixos/modules/services/web-servers/garage-doc.md
+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
+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
-
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>
22
3
<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>
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>.
25
10
</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>
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 "garage offline-repair --yes"</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>
46
151
<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.
152
+
Your upgraded cluster should be in a working state, re-enable API
153
+
and web access.
48
154
</para>
49
-
</formalpara>
50
-
</listitem>
51
-
52
-
<listitem>
53
-
<formalpara>
54
-
<title>Multiple version upgrades</title>
155
+
</section>
156
+
<section xml:id="module-services-garage-maintainer-info">
157
+
<title>Maintainer information</title>
55
158
<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><nixpkgs/pkgs/tools/filesystem/garage/default.nix></literal>):
122
-
<programlisting>
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><nixpkgs/pkgs/tools/filesystem/garage/default.nix></literal>):
186
+
</para>
187
+
<programlisting>
123
188
/* ... */
124
189
{
125
190
garage_0_7_3 = generic {
126
-
version = "0.7.3";
127
-
sha256 = "0000000000000000000000000000000000000000000000000000";
191
+
version = "0.7.3";
192
+
sha256 = "0000000000000000000000000000000000000000000000000000";
128
193
eol = true;
129
194
};
130
195
}
131
196
</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
-
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>
141
204
</chapter>
+2
nixos/modules/services/web-servers/garage.nix
+2
nixos/modules/services/web-servers/garage.nix
···
9
9
in
10
10
{
11
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`
12
14
doc = ./garage-doc.xml;
13
15
maintainers = with pkgs.lib.maintainers; [ raitobezarius ];
14
16
};