Skip to content

Commit e2c23ac

Browse files
ewoutpewoutp
committed
Update docs
1 parent 32b9b71 commit e2c23ac

File tree

1 file changed

+56
-142
lines changed

1 file changed

+56
-142
lines changed

‎docs/Manual/Upgrading/Starter/README.md‎

Lines changed: 56 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
Upgrading _Starter_ Deployments
2-
===============================
1+
# Upgrading _Starter_ Deployments
32

43
Starting from versions 3.2.15 and 3.3.8, the ArangoDB [_Starter_](../../Programs/Starter/README.md)
54
supports a new, automated, procedure to perform upgrades, including rolling upgrades
@@ -9,10 +8,9 @@ The upgrade procedure of the _Starter_ described in this _Section_ can be used t
98
upgrade to a new hotfix, or to perform an upgrade to a new minor version of ArangoDB.
109

1110
**Important:** rolling upgrades of Cluster setups from 3.2 to 3.3 are only supported
12-
from versions 3.2.15 and 3.3.9.
11+
from versions 3.2.15 and 3.3.9.
1312

14-
Upgrade Procedure
15-
-----------------
13+
## Upgrade Procedure
1614

1715
The following procedure has to be executed on every ArangoDB _Starter_ instance.
1816
It is assumed that a _Starter_ deployment with mode `single`, `activefailover` or
@@ -23,21 +21,21 @@ It is assumed that a _Starter_ deployment with mode `single`, `activefailover` o
2321
Installing the new ArangoDB version binary also includes the latest ArangoDB _Starter_
2422
binary, which is necessary to perform the rolling upgrade.
2523

26-
The first step is to install the new ArangoDB package.
24+
The first step is to install the new ArangoDB package.
2725

2826
**Note:** you do not have to stop the _Starter_ processes before upgrading it.
2927

3028
For example, if you want to upgrade to `3.3.8-1` on Debian or Ubuntu, either call
3129

32-
```
33-
$ apt install arangodb=3.3.8
30+
```bash
31+
apt install arangodb=3.3.8
3432
```
3533

3634
(`apt-get` on older versions) if you have added the ArangoDB repository. Or
3735
install a specific package using
3836

39-
```
40-
$ dpkg -i arangodb3-3.3.8-1_amd64.deb
37+
```bash
38+
dpkg -i arangodb3-3.3.8-1_amd64.deb
4139
```
4240

4341
after you have downloaded the corresponding file from https://download.arangodb.com/.
@@ -49,17 +47,17 @@ stop it now, as otherwise this standalone instance that is started on your machi
4947
can create some confusion later. As you are using the _Starter_ you do not need
5048
this standalone instance, and you can hence stop it:
5149

52-
```
53-
$ service arangodb3 stop
50+
```bash
51+
service arangodb3 stop
5452
```
5553

5654
Also, you might want to remove the standalone instance from the default
5755
_runlevels_ to prevent it to start on the next reboot of your machine. How this
5856
is done depends on your distribution and _init_ system. For example, on older Debian
5957
and Ubuntu systems using a SystemV-compatible _init_, you can use:
6058

61-
```
62-
$ update-rc.d -f arangodb3 remove
59+
```bash
60+
update-rc.d -f arangodb3 remove
6361
```
6462

6563
### Stop the _Starter_ without stopping the ArangoDB Server processes
@@ -68,37 +66,36 @@ Now all the _Starter_ (_arangodb_) processes have to be stopped.
6866

6967
Please note that **no** _arangod_ processes should be stopped.
7068

71-
In order to stop the _arangodb_ processes, leaving the _arangod_ processes they
69+
In order to stop the _arangodb_ processes, leaving the _arangod_ processes they
7270
have started up and running (as we want for a rolling upgrade), we will need to
7371
use a command like `kill -9`:
7472

75-
```
73+
```bash
7674
kill -9 <pid-of-starter>
7775
```
7876

7977
The _pid_ associated to your _Starter_ can be checked using a command like _ps_:
8078

81-
82-
```
79+
```bash
8380
ps -C arangodb -fww
8481
```
8582

86-
The output of the command above does not only show the PID's of all _arangodb_
83+
The output of the command above does not only show the PID's of all _arangodb_
8784
processes but also the used commands, which can be useful for the following
8885
restart of all _arangodb_ processes.
8986

9087
The output belove is from a test machine where three instances of a _Starter_ are
9188
running locally. In a more production-like scenario, you will find only one instance
9289
of _arangodb_ running:
9390

94-
```
91+
```bash
9592
ps -C arangodb -fww
9693
UID PID PPID C STIME TTY TIME CMD
9794
max 29419 3684 0 11:46 pts/1 00:00:00 arangodb --starter.data-dir=./db1
9895
max 29504 3695 0 11:46 pts/2 00:00:00 arangodb --starter.data-dir=./db2 --starter.join 127.0.0.1
9996
max 29513 3898 0 11:46 pts/4 00:00:00 arangodb --starter.data-dir=./db3 --starter.join 127.0.0.1
10097
```
101-
98+
10299
### Restart the _Starter_
103100

104101
When using a supervisor like _SystemD_, this will happens automatically. In case
@@ -112,150 +109,67 @@ situation:
112109
- The ArangoDB Server processes are up and running, and they are still on the
113110
old version
114111

115-
### Send an HTTP `POST` request to all _Starters_
116-
117-
A `POST` request with an empty body hast to be sent to `/database-auto-upgrade`
118-
on all _Starters_ one by one.
119-
120-
Once the upgrade on the first _Starter_ has finished, the same request can be sent
121-
to the next one.
122-
123-
The default port of the first _Starter_ is 8528. In a local test (all _Starters_
124-
running on the same machine), the ports of the additional _Starters_ are increased
125-
by 5 (before 3.2.15 and 3.3.8) or 10 (since 3.2.15 and 3.3.8).
126-
127-
Please note that the _Starter_ port is also shown in the _Starter_ output e.g.
128-
`Listening on 0.0.0.0:8528 (:8528)`.
129-
130-
As the port of the _Starter_ is a configurable variable, please identify and use
131-
the one of your specific setup.
112+
### Start the upgrade process of all _arangod_ & _arangosync_ servers
132113

133-
You might use _curl_ to send the `POST` request. For example:
114+
Run the following command:
134115

116+
```bash
117+
arangodb upgrade --starter.endpoint=<endpoint-of-a-starter>
135118
```
136-
curl -X POST --dump - http://localhost:8538/database-auto-upgrade
137119

138-
HTTP/1.1 200 OK
139-
Date: Wed, 09 May 2018 10:35:35 GMT
140-
Content-Length: 2
141-
Content-Type: text/plain; charset=utf-8
142-
```
143-
144-
Response `200 OK` means that the request was accepted and the upgrade process
145-
for this _Starter_ has begun.
146-
147-
### _Starter_ response
148-
149-
The _Starter_ will respond to the HTTP `POST` request depending on the deployment
150-
mode.
120+
The `--starter.endpoint` option can be set to the endpoint of any
121+
of the starters. E.g. `http://localhost:8528`.
151122

152123
#### Deployment mode `single`
153124

154-
The _Starter_ will:
125+
For deployment mode `single`, the `arangodb upgrade` command will:
155126

156127
- Restart the single server with an additional `--database.auto-upgrade=true` argument.
157128
The server will perform the auto-upgrade and then stop.
158129
After that the _Starter_ will automatically restart it with its normal arguments.
159130

160-
#### Deployment mode `activefailover`
131+
The `arangodb upgrade` command will complete right away.
132+
Inspect the log of the _Starter_ to know when the upgrade has finished.
161133

162-
The _Starter_ will:
134+
#### Deployment mode `activefailover` or `cluster`
163135

164-
- Turning off _supervision_ in the _Agency_ and wait for it to be confirmed.
165-
- Restarting one _Agent_ at a time with an additional `--database.auto-upgrade=true` argument.
166-
The _Agent_ will perform the auto-upgrade and then stop.
167-
After that the _Starter_ will automatically restart it with its normal arguments.
168-
- Restarting one single server at a time with an additional `--database.auto-upgrade=true` argument.
169-
This server will perform the auto-upgrade and then stop.
170-
After that the _Starter_ will automatically restart it with its normal arguments.
171-
- Turning on _supervision_ in the _Agency_ and wait for it to be confirmed.
136+
The _Starters_ will now perform an initial check that upgrading is possible
137+
and when that all succeeds, create an upgrade plan.
138+
This plan is then executed by every _Starter_.
172139

173-
#### Deployment mode `cluster`
140+
The `arangodb upgrade` command will show the progress of the upgrade
141+
and stop when the upgrade has either finished successfully or finished
142+
with an error.
174143

175-
The _Starter_ will:
144+
### Retrying a failed upgrade
176145

177-
- Turning off _supervision_ in the _Agency_ and wait for it to be confirmed.
178-
- Restarting one _Agent_ at a time with an additional `--database.auto-upgrade=true` argument.
179-
The _Agent_ will perform the auto-upgrade and then stop.
180-
After that the _Starter_ will automatically restart it with its normal arguments.
181-
- Restarting one _DBSserver_ at a time with an additional `--database.auto-upgrade=true` argument.
182-
This _DBSserver_ will perform the auto-upgrade and then stop.
183-
After that the _Starter_ will automatically restart it with its normal arguments.
184-
- Restarting one _Coordinator_ at a time with an additional `--database.auto-upgrade=true` argument.
185-
This _Coordinator_ will perform the auto-upgrade and then stop.
186-
After that the _Starter_ will automatically restart it with its normal arguments.
187-
- Turning on _supervision_ in the _Agency_ and wait for it to be confirmed.
146+
When an upgrade plan (in deployment mode `activefailover` or `cluster`)
147+
has failed, it can be retried.
188148

149+
To retry, run:
189150

190-
Example: Rolling Upgrade in a Cluster
191-
-------------------------------------
151+
```bash
152+
arangodb retry upgrade --starter.endpoint=<endpoint-of-a-starter>
153+
```
192154

193-
In this example we will perform a rolling upgrade of an ArangoDB Cluster setup
194-
from version 3.3.7 to version 3.3.8.
155+
The `--starter.endpoint` option can be set to the endpoint of any
156+
of the starters. E.g. `http://localhost:8528`.
195157

196-
Once a `POST` request to the first _Starter_ is sent, the following output is shown
197-
when the upgrade has finished:
158+
### Aborting an upgrade
198159

199-
```
200-
2018/05/09 12:33:02 Upgrading agent
201-
2018/05/09 12:33:05 restarting agent
202-
2018/05/09 12:33:05 Looking for a running instance of agent on port 8531
203-
2018/05/09 12:33:05 Starting agent on port 8531
204-
2018/05/09 12:33:05 Agency is not yet healthy: Agent http://localhost:8531 is not responding
205-
2018/05/09 12:33:06 restarting agent
206-
2018/05/09 12:33:06 Looking for a running instance of agent on port 8531
207-
2018/05/09 12:33:06 Starting agent on port 8531
208-
2018/05/09 12:33:07 agent up and running (version 3.3.8).
209-
2018/05/09 12:33:10 Upgrading dbserver
210-
2018/05/09 12:33:15 restarting dbserver
211-
2018/05/09 12:33:15 Looking for a running instance of dbserver on port 8530
212-
2018/05/09 12:33:15 Starting dbserver on port 8530
213-
2018/05/09 12:33:15 DBServers are not yet all responding: Get http://localhost:8530/_admin/server/id: dial tcp 127.0.0.1:8530: connect: connection refused
214-
2018/05/09 12:33:15 restarting dbserver
215-
2018/05/09 12:33:15 Looking for a running instance of dbserver on port 8530
216-
2018/05/09 12:33:15 Starting dbserver on port 8530
217-
2018/05/09 12:33:16 dbserver up and running (version 3.3.8).
218-
2018/05/09 12:33:20 Upgrading coordinator
219-
2018/05/09 12:33:23 restarting coordinator
220-
2018/05/09 12:33:23 Looking for a running instance of coordinator on port 8529
221-
2018/05/09 12:33:23 Starting coordinator on port 8529
222-
2018/05/09 12:33:23 Coordinator are not yet all responding: Get http://localhost:8529/_admin/server/id: dial tcp 127.0.0.1:8529: connect: connection refused
223-
2018/05/09 12:33:23 restarting coordinator
224-
2018/05/09 12:33:23 Looking for a running instance of coordinator on port 8529
225-
2018/05/09 12:33:23 Starting coordinator on port 8529
226-
2018/05/09 12:33:24 coordinator up and running (version 3.3.8).
227-
2018/05/09 12:33:24 Your cluster can now be accessed with a browser at `http://localhost:8529` or
228-
2018/05/09 12:33:24 using `arangosh --server.endpoint tcp://localhost:8529`.
229-
2018/05/09 12:33:28 Server versions:
230-
2018/05/09 12:33:28 agent 1 3.3.8
231-
2018/05/09 12:33:28 agent 2 3.3.7
232-
2018/05/09 12:33:28 agent 3 3.3.7
233-
2018/05/09 12:33:28 dbserver 1 3.3.8
234-
2018/05/09 12:33:28 dbserver 2 3.3.7
235-
2018/05/09 12:33:28 dbserver 3 3.3.7
236-
2018/05/09 12:33:28 coordinator 1 3.3.8
237-
2018/05/09 12:33:28 coordinator 2 3.3.7
238-
2018/05/09 12:33:28 coordinator 3 3.3.7
239-
2018/05/09 12:33:28 Upgrading of all servers controlled by this starter done, you can continue with the next starter now.
240-
```
160+
When an upgrade plan (in deployment mode `activefailover` or `cluster`)
161+
is in progress or has failed, it can be aborted.
241162

242-
_Agent_ 1, _DBSserver_ 1 and _Coordinator_ 1 are successively updated and the last
243-
messages indicate that the `POST` request can be sent so the next _Starter_. After this
244-
procedure has been repeated for every _Starter_ the last _Starter_ will show:
163+
To abort, run:
245164

165+
```bash
166+
arangodb abort upgrade --starter.endpoint=<endpoint-of-a-starter>
246167
```
247-
2018/05/09 12:35:59 Server versions:
248-
2018/05/09 12:35:59 agent 1 3.3.8
249-
2018/05/09 12:35:59 agent 2 3.3.8
250-
2018/05/09 12:35:59 agent 3 3.3.8
251-
2018/05/09 12:35:59 dbserver 1 3.3.8
252-
2018/05/09 12:35:59 dbserver 2 3.3.8
253-
2018/05/09 12:35:59 dbserver 3 3.3.8
254-
2018/05/09 12:35:59 coordinator 1 3.3.8
255-
2018/05/09 12:35:59 coordinator 2 3.3.8
256-
2018/05/09 12:35:59 coordinator 3 3.3.8
257-
2018/05/09 12:35:59 Upgrading done.
258-
```
259168

260-
All _Agents_, _DBServers_ and _Coordinators_ are upgraded and the rolling upgrade
261-
has successfully finished.
169+
The `--starter.endpoint` option can be set to the endpoint of any
170+
of the starters. E.g. `http://localhost:8528`.
171+
172+
Note that an abort does not stop all upgrade processes immediately.
173+
If an _arangod_ or _arangosync_ server is being upgraded when the abort
174+
was issued, this upgrade will be finished.
175+
Remaining servers will not be upgraded.

0 commit comments

Comments
 (0)