You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Public documentation update for backup service as it is GA in 3.20 (#59106)
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>
Copy file name to clipboardExpand all lines: content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/about-the-backup-service-for-github-enterprise-server.md
+8-5Lines changed: 8 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,9 @@ topics:
12
12
- Infrastructure
13
13
---
14
14
15
+
{% ifversion ghes < 3.20 %}
15
16
>[!NOTE] {% data variables.product.prodname_enterprise_backup_service %} is currently in {% data variables.release-phases.public_preview %} and subject to change. The service is available at no additional cost and will remain free.
17
+
{% endif %}
16
18
17
19
## About the {% data variables.product.prodname_enterprise_backup_service %}
18
20
@@ -29,7 +31,9 @@ Compared to the legacy backup utilities, the {% data variables.product.prodname_
29
31
* Doesn’t require a separate host for backup software.
30
32
* Stores backups on a dedicated storage volume directly accessible by your instance.
31
33
34
+
{% ifversion ghes < 3.20 %}
32
35
>[!NOTE] {% data variables.product.prodname_enterprise_backup_service %} is currently only supported on standalone instances and high availability primary nodes. Cluster configurations and replica nodes are not yet supported.
36
+
{% endif %}
33
37
34
38
## How does the backup service differ from a High Availability replica?
35
39
@@ -47,8 +51,7 @@ The backup service is a disaster recovery solution. It captures full, timestampe
intro: 'Enable backup from a high availability replica node.'
5
+
versions:
6
+
ghes: '> 3.19'
7
+
type: how_to
8
+
topics:
9
+
- Backups
10
+
---
11
+
12
+
## Configuring backups from a replica node
13
+
14
+
For high availability, you can designate a replica node as your backup server. To minimize latency, {% data variables.product.github %} recommends picking a replica node in the same region or datacenter as your primary node.
15
+
16
+
> [!IMPORTANT]
17
+
> Backups from cache replica nodes or active geo replica nodes are not supported.
18
+
19
+
To configure your backup server, run the following commands, replacing `HOSTNAME` with the hostname of the node:
20
+
21
+
```shell
22
+
ghe-config cluster.HOSTNAME.backup-server true
23
+
24
+
ghe-config-apply
25
+
```
26
+
27
+
You can now run `ghe-backup` directly on your replica node.
28
+
29
+
> [!WARNING]
30
+
> Due to the latency between primary and replica nodes, you may lose data when backing up from a replica node.
For clustering, you can designate a node as your backup server. To minimize latency, {% data variables.product.github %} recommends picking a data node (for example, a `mysql-server` node or a `git-server` node) instead of a frontend node.
15
+
16
+
> [!IMPORTANT]
17
+
> Only one node can be specified as a `backup-server` node.
18
+
19
+
1. To configure your backup server, set up a backup disk on one of the cluster nodes of your choice. See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/configuring-the-backup-service).
20
+
21
+
1. After `ghe-storage-init-backup` is executed, the `backup-server` role will be set on this cluster node. You can now run `ghe-backup` directly on this node, or use the management console to schedule backups.
intro: 'Enable a remote archive for backups through SSH.'
5
+
versions:
6
+
ghes: '> 3.19'
7
+
type: how_to
8
+
topics:
9
+
- Backups
10
+
---
11
+
12
+
If you are running {% data variables.product.prodname_ghe_server %} on a cloud platform or virtualization platform that supports disk snapshots, we recommend that you use snapshots to archive your backup disk, and recreate a new backup disk for testing, restoring, or disaster recovery purposes. However, if your infrastructure does not support disk snapshots or similar solutions, you can setup a {% data variables.product.prodname_ghe_server %} backup archive on a remote {% data variables.product.prodname_ghe_server %} appliance for data replication and restoration purposes.
13
+
14
+
## Set up a remote archive destination
15
+
16
+
Remote archives are required to be saved on a backup disk of a {% data variables.product.prodname_ghe_server %} appliance, which is used as a staging or testing {% data variables.product.prodname_ghe_server %} appliance. Follow these steps to configure remote backup archives.
17
+
18
+
1. Set up a backup disk on a remote {% data variables.product.prodname_ghe_server %} appliance. See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/configuring-the-backup-service).
19
+
1. From the production appliance, run the following command to initiate configuration and display the SSH public key that needs to be added to the remote {% data variables.product.prodname_ghe_server %} appliance:
This command will print a public SSH key that you need to add to the remote {% data variables.product.prodname_ghe_server %} environment through the management console.
26
+
1. After the SSH key has been added to the remote {% data variables.product.prodname_ghe_server %} appliance, run the same command again to complete the configuration:
It will display "Done: Configured remote backup archive destination host to <hostname-or-ip-of-remote-appliance>." A {% data variables.product.prodname_ghe_server %} configuration `ghe-config backup.remote-archive-destination-host` will be set.
33
+
1. After that, any successful invocation of `ghe-backup` will sync the latest backup to this remote archive destination in the background, displaying a message like "Uploading backup data to remote host <hostname-or-ip-of-remote-appliance> in background...".
34
+
35
+
### Manually sync a snapshot
36
+
37
+
To push the current snapshot immediately without taking a new backup, you can manually run: `/usr/local/share/github-backup/ghe-backup-remote-archive`.
38
+
39
+
### Limitations
40
+
41
+
{% data variables.product.prodname_ghe_server %} remote backup archives are archived via SSH and are limited by your network and I/O. We recommend using disk snapshots whenever your infrastructure allows, instead of remote archives.
Copy file name to clipboardExpand all lines: content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/configuring-the-backup-service.md
+48-25Lines changed: 48 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -87,6 +87,35 @@ If you're using a dedicated block device as your backup target, you need to init
87
87
From {% data variables.product.prodname_ghe_server %} 3.17.4 onward, the script is installed in PATH so you can run it directly using: `ghe-storage-init-backup /dev/YOUR_DEVICE_NAME`.
88
88
{% endif %}
89
89
90
+
91
+
#### Detach a backup disk
92
+
93
+
> [!WARNING]
94
+
> Before detaching a backup disk, ensure that no backups or restores are currently in progress. Detaching a disk while it is in use can result in data loss or service interruption.
95
+
96
+
In case you need to detach backup disk from {% data variables.product.prodname_ghe_server %}, please use following steps
97
+
98
+
1. List block devices and unmount `/data/backup`.
99
+
100
+
```bash
101
+
sudo lsblk
102
+
sudo umount /data/backup
103
+
```
104
+
105
+
1. List logical volumes and deactivate logical volume.
106
+
107
+
```bash
108
+
sudo lvs
109
+
sudo lvchange -an <backup_VG>/<backup_LV>
110
+
```
111
+
112
+
1. Detach disk using console or CLI provided by cloud provider or hypervisor.
113
+
1. Remove mount point.
114
+
115
+
```bash
116
+
sudo rmdir /data/backup
117
+
```
118
+
90
119
#### Reusing a previously initialized disk
91
120
92
121
If the device was already initialized using `ghe-storage-init-backup`, you can reuse it without reformatting:
@@ -110,7 +139,7 @@ If the device was already initialized using `ghe-storage-init-backup`, you can r
110
139
111
140
### Configuring backup settings
112
141
113
-
After the backup target is mounted, the Backup Service page will become available in the {% data variables.enterprise.management_console %}. {% ifversion ghes > 3.19 %} If your instance is part of a clustered environment, the system will automatically detect the node that was initialized with `ghe-storage-init-backup` and treat it as the backup server. {% endif %}
142
+
After the backup target is mounted, the Backup Service page will become available in the {% data variables.enterprise.management_console %} in the "Backup" section. {% ifversion ghes > 3.19 %} If your instance is part of a clustered environment, the system will automatically detect the node that was initialized with `ghe-storage-init-backup` and treat it as the backup server. {% endif %}
114
143
115
144
>[!NOTE] The settings page won’t appear until the backup storage is mounted at `/data/backup` by completing the initialization or mount steps above.
116
145
@@ -125,36 +154,30 @@ If you're migrating from {% data variables.product.prodname_enterprise_backup_ut
125
154
126
155
Use the `--dry-run` flag to preview changes without applying them.
127
156
128
-
#### Scheduling automated backups
129
-
130
-
Once the service is configured, you can define a backup schedule.
131
-
132
-
1. In the {% data variables.enterprise.management_console %}, open the "Backups" tab from the top menu.
133
-
1. In the "Backup Schedule" section, choose a predefined schedule (e.g., Daily) or enter a custom cron expression.
134
-
1. Click **Save** to apply the changes.
135
-
136
-
The first run will be a full backup. Future runs will be incremental. If a new backup attempt starts while a previous one is still running, it may be skipped or fail. In that case, adjust the schedule to avoid overlap.
137
-
138
157
{% ifversion ghes > 3.19 %}
158
+
#### Take a backup
139
159
140
-
### Configuring backups from a replica node
160
+
Once the service is configured, you can take a backup manually using the following steps:
141
161
142
-
For high availability, you can designate a replica node as your backup server. To minimize latency, {% data variables.product.github %} recommends picking a replica node in the same region or datacenter as your primary node.
143
-
144
-
> [!IMPORTANT]
145
-
> Backups from cache replica nodes or active geo replica nodes are not supported.
146
-
147
-
To configure your backup server, run the following commands, replacing `HOSTNAME` with the hostname of the node:
162
+
1. In the {% data variables.enterprise.management_console %}, open the "Backups" tab from the top menu.
163
+
1. Click **Backup Now**.
148
164
149
-
```shell
150
-
ghe-config cluster.HOSTNAME.backup-server true
165
+
A {% data variables.product.prodname_ghe_server %} backup will be taken, and displayed in a list.
151
166
152
-
ghe-config-apply
153
-
```
167
+
{% endif %}
154
168
155
-
You can now run `ghe-backup` directly on your replica node.
169
+
#### Scheduling automated backups
156
170
157
-
> [!WARNING]
158
-
> Due to the latency between primary and replica nodes, you may lose data when backing up from a replica node.
171
+
Once the service is configured, you can define a backup schedule.
159
172
173
+
{% ifversion ghes > 3.19 %}
174
+
1. In the {% data variables.enterprise.management_console %}, open the "Settings" tab from the top menu.
175
+
1. In the "Backup" section, choose a predefined schedule (e.g., Daily) or enter a custom cron expression.
176
+
1. Click **Save settings** to apply the changes.
177
+
{% else %}
178
+
1. In the {% data variables.enterprise.management_console %}, open the "Backups" tab from the top menu.
179
+
1. In the "Backup Schedule" section, choose a predefined schedule (e.g., Daily) or enter a custom cron expression.
180
+
1. Click **Save** to apply the changes.
160
181
{% endif %}
182
+
183
+
The first run will be a full backup. Future runs will be incremental. If a new backup attempt starts while a previous one is still running, it may be skipped or fail. In that case, adjust the schedule to avoid overlap.
0 commit comments