fix version and command in upgrade with api and cli (#62024) · github/docs@b65c01d · GitHub
Skip to content

Commit b65c01d

Browse files
zheng022subatoiam-stead
authored
fix version and command in upgrade with api and cli (#62024)
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
1 parent b300460 commit b65c01d

4 files changed

Lines changed: 348 additions & 4 deletions

File tree

‎content/admin/upgrading-your-instance/index.md‎

Lines changed: 0 additions & 3 deletions

‎content/admin/upgrading-your-instance/performing-an-upgrade/automating-an-upgrade.md‎

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
---
2+
title: Automating an upgrade
3+
intro: You can automate upgrade operations using the REST API or a {% data variables.product.prodname_cli %} extension.
4+
versions:
5+
ghes: '>=3.22'
6+
shortTitle: Automate an upgrade
7+
contentType: how-tos
8+
---
9+
10+
You can upgrade your {% data variables.product.prodname_ghe_server %} instance using the Manage {% data variables.product.prodname_ghe_server %} API or the `gh es` extension for {% data variables.product.prodname_cli %}. These tools automate the process of downloading the upgrade package, running pre-upgrade checks, and applying the new version.
11+
12+
## Prerequisites
13+
14+
* Back up your data with [{% data variables.product.prodname_enterprise_backup_utilities %}](https://github.com/github/backup-utils#readme).
15+
* Schedule a maintenance window for end users.
16+
* Ensure you can authenticate to the Manage {% data variables.product.prodname_ghe_server %} API. For more information, see [AUTOTITLE](/rest/enterprise-admin#authentication).
17+
18+
## Automating an upgrade using the REST API
19+
20+
1. Download the upgrade package.
21+
22+
```shell
23+
curl -L \
24+
-X POST \
25+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
26+
-H "Content-Type: application/json" \
27+
https://HOSTNAME:8443/manage/v1/upgrade/download \
28+
-d '{"version":"VERSION"}'
29+
```
30+
31+
1. Confirm the download has completed before proceeding.
32+
33+
```shell
34+
curl -L \
35+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
36+
-H "Content-Type: application/json" \
37+
https://HOSTNAME:8443/manage/v1/upgrade/download/status
38+
```
39+
40+
Wait until `status` shows `COMPLETED`.
41+
42+
1. Apply the upgrade's pre-upgrade phase.
43+
44+
```shell
45+
curl -L \
46+
-X POST \
47+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
48+
-H "Content-Type: application/json" \
49+
https://HOSTNAME:8443/manage/v1/upgrade/apply \
50+
-d '{"version":"VERSION", "phase":"pre-upgrade"}'
51+
```
52+
53+
1. Monitor the pre-upgrade phase until it completes.
54+
55+
```shell
56+
curl -L \
57+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
58+
-H "Content-Type: application/json" \
59+
"https://HOSTNAME:8443/manage/v1/upgrade/status?is_verbose=true"
60+
```
61+
62+
Wait until `status` shows `completed` and `is_running` shows `false`.
63+
64+
1. Enable maintenance mode.
65+
66+
```shell
67+
curl -L \
68+
-X POST \
69+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
70+
-H "Content-Type: application/json" \
71+
https://HOSTNAME:8443/manage/v1/maintenance \
72+
-d '{"enabled":true}'
73+
```
74+
75+
1. Apply the upgrade's upgrade phase.
76+
77+
```shell
78+
curl -L \
79+
-X POST \
80+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
81+
-H "Content-Type: application/json" \
82+
https://HOSTNAME:8443/manage/v1/upgrade/apply \
83+
-d '{"version":"VERSION", "phase":"upgrade"}'
84+
```
85+
86+
1. Confirm the release version has been updated.
87+
88+
```shell
89+
curl -L \
90+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
91+
-H "Content-Type: application/json" \
92+
https://HOSTNAME:8443/manage/v1/version
93+
```
94+
95+
1. Disable maintenance mode.
96+
97+
```shell
98+
curl -L \
99+
-X POST \
100+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
101+
-H "Content-Type: application/json" \
102+
https://HOSTNAME:8443/manage/v1/maintenance \
103+
-d '{"enabled":false}'
104+
```
105+
106+
## Automating an upgrade using the {% data variables.product.prodname_cli %} extension
107+
108+
1. Download the upgrade package. To download a specific version, specify the `--version` flag; otherwise, the latest available version is downloaded.
109+
110+
```shell
111+
# Download a specific version
112+
gh es upgrade download --version VERSION
113+
114+
# Or download the latest available version
115+
gh es upgrade download
116+
```
117+
118+
1. Confirm the download has completed before proceeding.
119+
120+
```shell
121+
gh es upgrade download status
122+
```
123+
124+
Wait until `status` shows `COMPLETED`.
125+
126+
1. Apply the upgrade's pre-upgrade phase.
127+
128+
```shell
129+
gh es upgrade apply --version VERSION --phase pre-upgrade
130+
```
131+
132+
1. Monitor the pre-upgrade phase until it completes.
133+
134+
```shell
135+
gh es upgrade status --verbose
136+
```
137+
138+
Wait until `status` shows `completed` and `is_running` shows `false`.
139+
140+
1. Enable maintenance mode.
141+
142+
```shell
143+
gh es maintenance set --enabled true
144+
```
145+
146+
1. Apply the upgrade's upgrade phase.
147+
148+
```shell
149+
gh es upgrade apply --version VERSION --phase upgrade
150+
```
151+
152+
1. Confirm the release version has been updated.
153+
154+
```shell
155+
gh es release version
156+
```
157+
158+
1. Disable maintenance mode.
159+
160+
```shell
161+
gh es maintenance set --enabled false
162+
```
163+
164+
## Upgrading a high availability deployment
165+
166+
For instances with a high availability (HA) replica, the download and pre-upgrade phases are non-disruptive and can run across all nodes at once. UUID targeting is only needed for the upgrade phase itself, which triggers the reboot. This lets you control the order nodes reboot in: upgrade the replica first, then the primary.
167+
168+
To retrieve node UUIDs, run `gh es config get-metadata` or query `GET /manage/v1/config/nodes`.
169+
170+
### Upgrading a high availability deployment using the {% data variables.product.prodname_cli %}
171+
172+
1. Download the package to all nodes.
173+
174+
```shell
175+
gh es upgrade download --version VERSION
176+
```
177+
178+
1. Wait for the download to complete on all nodes.
179+
180+
```shell
181+
gh es upgrade download status
182+
```
183+
184+
1. Run the pre-upgrade phase on all nodes at once. This phase is non-disruptive.
185+
186+
```shell
187+
gh es upgrade apply --version VERSION --phase pre-upgrade
188+
```
189+
190+
1. Wait for the pre-upgrade phase to complete.
191+
192+
```shell
193+
gh es upgrade status --verbose
194+
```
195+
196+
1. Enable maintenance mode.
197+
198+
```shell
199+
gh es maintenance set --enabled true
200+
```
201+
202+
1. Stop replication on the replica.
203+
204+
```shell
205+
ghe-repl-stop
206+
```
207+
208+
1. Upgrade the primary first, which triggers the reboot, then monitor its progress.
209+
210+
```shell
211+
gh es upgrade apply --version VERSION --phase upgrade --uuid PRIMARY-UUID
212+
gh es upgrade status --uuid PRIMARY-UUID --verbose
213+
```
214+
215+
1. After the primary finishes, upgrade the replica, then monitor its progress.
216+
217+
```shell
218+
gh es upgrade apply --version VERSION --phase upgrade --uuid REPLICA-UUID
219+
gh es upgrade status --uuid REPLICA-UUID --verbose
220+
```
221+
222+
1. Start replication again on the replica.
223+
224+
```shell
225+
ghe-repl-start
226+
```
227+
228+
1. Verify replication health and the version, then disable maintenance mode.
229+
230+
```shell
231+
gh es replication status
232+
gh es release version
233+
gh es maintenance set --enabled false
234+
```
235+
236+
### Upgrading a high availability deployment using the REST API
237+
238+
1. Download the package to all nodes.
239+
240+
```shell
241+
curl -L -X POST \
242+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
243+
-H "Content-Type: application/json" \
244+
https://HOSTNAME:8443/manage/v1/upgrade/download \
245+
-d '{"version":"VERSION"}'
246+
```
247+
248+
1. Wait for the download to complete on all nodes.
249+
250+
```shell
251+
curl -L \
252+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
253+
-H "Content-Type: application/json" \
254+
https://HOSTNAME:8443/manage/v1/upgrade/download/status
255+
```
256+
257+
1. Run the pre-upgrade phase on all nodes at once. This phase is non-disruptive.
258+
259+
```shell
260+
curl -L -X POST \
261+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
262+
-H "Content-Type: application/json" \
263+
https://HOSTNAME:8443/manage/v1/upgrade/apply \
264+
-d '{"version":"VERSION","phase":"pre-upgrade"}'
265+
```
266+
267+
1. Wait for the pre-upgrade phase to complete.
268+
269+
```shell
270+
curl -L \
271+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
272+
-H "Content-Type: application/json" \
273+
"https://HOSTNAME:8443/manage/v1/upgrade/status?is_verbose=true"
274+
```
275+
276+
1. Enable maintenance mode.
277+
278+
```shell
279+
curl -L -X POST \
280+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
281+
-H "Content-Type: application/json" \
282+
https://HOSTNAME:8443/manage/v1/maintenance \
283+
-d '{"enabled":true}'
284+
```
285+
286+
1. Stop replication on the replica.
287+
288+
```shell
289+
ghe-repl-stop
290+
```
291+
292+
1. Upgrade the primary first, which triggers the reboot, then monitor its progress.
293+
294+
```shell
295+
curl -L -X POST \
296+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
297+
-H "Content-Type: application/json" \
298+
https://HOSTNAME:8443/manage/v1/upgrade/apply \
299+
-d '{"version":"VERSION","phase":"upgrade","uuid":"PRIMARY-UUID"}'
300+
301+
curl -L \
302+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
303+
-H "Content-Type: application/json" \
304+
"https://HOSTNAME:8443/manage/v1/upgrade/status?uuid=PRIMARY-UUID&is_verbose=true"
305+
```
306+
307+
1. After the primary finishes, upgrade the replica, then monitor its progress.
308+
309+
```shell
310+
curl -L -X POST \
311+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
312+
-H "Content-Type: application/json" \
313+
https://HOSTNAME:8443/manage/v1/upgrade/apply \
314+
-d '{"version":"VERSION","phase":"upgrade","uuid":"REPLICA-UUID"}'
315+
316+
curl -L \
317+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
318+
-H "Content-Type: application/json" \
319+
"https://HOSTNAME:8443/manage/v1/upgrade/status?uuid=REPLICA-UUID&is_verbose=true"
320+
```
321+
322+
1. Start replication again on the replica.
323+
324+
```shell
325+
ghe-repl-start
326+
```
327+
328+
1. Verify replication health and the version, then disable maintenance mode.
329+
330+
```shell
331+
curl -L \
332+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
333+
-H "Content-Type: application/json" \
334+
https://HOSTNAME:8443/manage/v1/replication/status
335+
336+
curl -L \
337+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
338+
-H "Content-Type: application/json" \
339+
https://HOSTNAME:8443/manage/v1/version
340+
341+
curl -L -X POST \
342+
-u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
343+
-H "Content-Type: application/json" \
344+
https://HOSTNAME:8443/manage/v1/maintenance \
345+
-d '{"enabled":false}'
346+
```

‎content/admin/upgrading-your-instance/performing-an-upgrade/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ versions:
66
children:
77
- /upgrading-with-a-hotpatch
88
- /upgrading-with-an-upgrade-package
9+
- /automating-an-upgrade
910
- /migrating-from-github-enterprise-1110x-to-2123
1011
shortTitle: Perform an upgrade
1112
redirect_from:

‎content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package.md‎

Lines changed: 1 addition & 1 deletion

0 commit comments

Comments
 (0)