Extract backup ID into concept

Rewrites backup docs to introduce a backup ID. This generalises
timestamp.

doc/administration/backup_restore/backup_gitlab.md

@@ -283,22 +283,11 @@ Dumping database tables:
 - Dumping table wikis... [DONE]
 Dumping repositories:
 - Dumping repository abcd... [DONE]
-Creating backup archive: $TIMESTAMP_gitlab_backup.tar [DONE]
+Creating backup archive: <backup-id>_gitlab_backup.tar [DONE]
 Deleting tmp directories...[DONE]
 Deleting old backups... [SKIPPING]
 ```
 
-### Backup timestamp
-
-The backup archive is saved in `backup_path`, which is specified in the
-`config/gitlab.yml` file. The default path is `/var/opt/gitlab/backups`. The file name is `[TIMESTAMP]_gitlab_backup.tar`,
-where `TIMESTAMP` identifies the time at which each backup was created, plus
-the GitLab version. The timestamp is needed if you need to restore GitLab and
-multiple backups are available.
-
-For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`,
-the timestamp is `1493107454_2018_04_25_10.6.4-ce`.
-
 ### Backup options
 
 The command-line tool GitLab provides to back up your instance can accept more
@@ -333,9 +322,8 @@ WARNING:
 If you use a custom backup file name, you can't
 [limit the lifetime of the backups](#limit-backup-lifetime-for-local-files-prune-old-backups).
 
-By default, a backup file is created according to the specification in the
-previous [Backup timestamp](#backup-timestamp) section. You can, however,
-override the `[TIMESTAMP]` portion of the file name by setting the `BACKUP`
+Backup files are created with file names according to [specific defaults](index.md#backup-id). However, you can
+override the `<backup-id>` portion of the file name by setting the `BACKUP`
 environment variable. For example:
 
 ```shell
@@ -613,9 +601,9 @@ Incremental repository backups can be faster than full repository backups becaus
 The incremental backup archives are not linked to each other: each archive is a self-contained backup of the instance. There must be an existing backup
 to create an incremental backup from:
 
-- In GitLab 14.9 and 14.10, use the `BACKUP=<timestamp_of_backup>` option to choose the backup to use. The chosen previous backup is overwritten.
-- In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<timestamp_of_backup>` option to choose the backup to use. By default, a backup file is created
-  as documented in the [Backup timestamp](#backup-timestamp) section. You can override the `[TIMESTAMP]` portion of the file name by setting the
+- In GitLab 14.9 and 14.10, use the `BACKUP=<backup-id>` option to choose the backup to use. The chosen previous backup is overwritten.
+- In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<backup-id>` option to choose the backup to use. By default, a backup file is created
+  as documented in the [Backup ID](index.md#backup-id) section. You can override the `<backup-id>` portion of the file name by setting the
   [`BACKUP` environment variable](#backup-file-name).
 
 To create an incremental backup, run:
@@ -623,13 +611,13 @@ To create an incremental backup, run:
 - In GitLab 15.0 or later:
 
   ```shell
-  sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<timestamp_of_backup>
+  sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<backup-id>
   ```
 
 - In GitLab 14.9 and 14.10:
 
   ```shell
-  sudo gitlab-backup create INCREMENTAL=yes BACKUP=<timestamp_of_backup>
+  sudo gitlab-backup create INCREMENTAL=yes BACKUP=<backup-id>
   ```
 
 To create an [untarred](#skipping-tar-creation) incremental backup from a tarred backup, use `SKIP=tar`:

doc/administration/backup_restore/backup_large_reference_architectures.md

@@ -96,12 +96,12 @@ To back up the Git repositories:
    sudo gitlab-backup create SKIP=db
    ```
 
-   The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the file name will end in `_gitlab_backup.tar`](backup_gitlab.md#backup-timestamp).
+   The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the file name will end in `_gitlab_backup.tar`](index.md#backup-id).
 
    Since we configured uploading backups to remote cloud storage, the tar file will be uploaded to the remote region and deleted from disk.
 
-1. Note the [timestamp](backup_gitlab.md#backup-timestamp) of the backup file for the next step. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the timestamp is `1493107454_2018_04_25_10.6.4-ce`.
-1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the timestamp of the source backup file. Using the example timestamp from the previous step, the command is:
+1. Note the [backup ID](index.md#backup-id) of the backup file for the next step. For example, if the backup archive name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the backup ID is `1493107454_2018_04_25_10.6.4-ce`.
+1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the backup ID of the source backup file. Using the example ID from the previous step, the command is:
 
    ```shell
    sudo gitlab-backup create SKIP=db INCREMENTAL=yes PREVIOUS_BACKUP=1493107454_2018_04_25_10.6.4-ce
@@ -277,7 +277,7 @@ To restore Git repositories:
    sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar
    ```
 
-1. Restore the backup, specifying the timestamp of the backup you wish to restore:
+1. Restore the backup, specifying the ID of the backup you wish to restore:
 
    WARNING:
    The restore command requires

doc/administration/backup_restore/index.md

@@ -58,6 +58,19 @@ When working with GitLab backups, you might need to know how GitLab creates back
 1. Optional. Uploads the new backup archive to object-storage.
 1. Cleans up backup staging directory files that are now archived.
 
+## Backup ID
+
+Backup IDs identify individual backup archives. You need the backup ID of a backup archive if you need to restore GitLab and multiple backup archives are available.
+
+Backup archives are saved in a directory set in `backup_path`, which is specified in the `config/gitlab.yml` file.
+
+- By default, backup archives are stored in `/var/opt/gitlab/backups`.
+- By default, backup archive file names are `<backup-id>_gitlab_backup.tar` where `<backup-id>` identifies the time when the
+  backup archive was created, the GitLab version, and the GitLab edition.
+
+For example, if the archive file name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`,
+the backup ID is `1493107454_2018_04_25_10.6.4-ce`.
+
 ## Backup staging directory
 
 The backup staging directory is a place to temporarily:
@@ -151,7 +164,7 @@ up once no matter the replication factor.
 You can configure repository backups as server-side repository backups. When specified, `gitaly-backup` makes a single RPC call for each repository to create the backup. This RPC
 does not transmit any repository data. Instead, the RPC triggers the Gitaly node that stores that physical repository to upload the backup data directly to object-storage. Because
 the data is no longer transmitted through RPCs from Gitaly, server-side backups require much less network transfer and require no disk storage on the machine that is running the
-backup Rake task. The backups stored on object-storage are linked to the created backup archive by [the backup name](backup_gitlab.md#backup-timestamp).
+backup Rake task. The backups stored on object-storage are linked to the created backup archive by [the backup ID](#backup-id).
 
 ```mermaid
 sequenceDiagram

doc/administration/backup_restore/restore_gitlab.md

@@ -100,7 +100,7 @@ sudo gitlab-ctl status
 Next, ensure you have completed the [restore prerequisites](#restore-prerequisites) steps and have run `gitlab-ctl reconfigure`
 after copying over the GitLab secrets file from the original installation.
 
-Next, restore the backup, specifying the timestamp of the backup you wish to
+Next, restore the backup, specifying the ID of the backup you wish to
 restore:
 
 ```shell
@@ -301,8 +301,8 @@ options.
 
 ### Specify backup to restore when there are more than one
 
-By default, backup files use a naming scheme [starting with a timestamp](backup_gitlab.md#backup-timestamp). When more than one backup exists, you must specify which
-`*_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=timestamp_of_backup`.
+Backup files use a naming scheme [starting with a backup ID](index.md#backup-id). When more than one backup exists, you must specify which
+`<backup-id>_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=<backup-id>`.
 
 ### Disable prompts during restore
 
@@ -350,13 +350,13 @@ To exclude specific tasks:
 - Linux package installations:
 
   ```shell
-  sudo gitlab-backup restore BACKUP=timestamp_of_backup SKIP=db,uploads
+  sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads
   ```
 
 - Self-compiled installations:
 
   ```shell
-  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup SKIP=db,uploads RAILS_ENV=production
+  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production
   ```
 
 ### Restore specific repository storages
@@ -373,13 +373,13 @@ For example:
 - Linux package installations:
 
   ```shell
-  sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2
+  sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
   ```
 
 - Self-compiled installations:
 
   ```shell
-  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2
+  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
   ```
 
 ### Restore specific repositories
@@ -397,19 +397,19 @@ and skip the **Project D** in **Group A** (`group-a/project-d`):
 - Linux package installations:
 
   ```shell
-  sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
+  sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
   ```
 
 - Self-compiled installations:
 
   ```shell
-  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
+  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
   ```
 
 ### Restore untarred backups
 
 If an [untarred backup](backup_gitlab.md#skipping-tar-creation) (made with `SKIP=tar`) is found,
-and no backup is chosen with `BACKUP=<timestamp>`, the untarred backup is used.
+and no backup is chosen with `BACKUP=<backup-id>`, the untarred backup is used.
 
 For example:
 
@@ -471,7 +471,7 @@ While restoring from backup, you can encounter an error when the following are t
 The error looks like:
 
 ```plaintext
-{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupTimestamp>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}
+{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}
 ```
 
 To resolve this, you can update the Git [server hooks](../server_hooks.md) for GitLab version 15.11 and later, and create a new backup.