Consolidate and refresh backup and restore documentation
Problem to solve
We have multiple backup and restore solutions documented across multiple pages:
It is difficult to find navigate the dispersed documentation and somewhat challenging for customers to figure out which option best suits their needs.
Also, customers on larger reference architectures with large datasets do not have adequate guidance on the best approach for their backups.
Proposal (Updated 11th May 2023)
Consolidate and streamline the backup and restore documentation.
Make it easier for customers to find and navigate the related documentation.
Simplify options
Simplify guidance down to two choices:
-
1K - 2K ref arch with <100GB of GitLab data
-
>2K (Omnibus/Hybrid) ref arch or > 100GB of GitLab data
Proposed structure and content
- We should structure the instructions similar to a run book making it easier for customers to follow.
- Provide guidance on external services (such as object storage, DB backups) that may be required to have a complete backup with link to documentation where appropriate.
- We should avoid going into specific configuration details for vendors such as AWS and GCP. Instead provide general guidance.
General principles (to be updated based from validation work)
- Customers with large dataset should always use object storage that can be backed up separately
- Where a managed DB is in use, DB backup tools provided by the vendor is strongly encourage
- Backup-utility is not recommended for large datasets because we cannot support incremental backups of repository data via this tool. Instead a separate omnibus node is required. Specs and configuration for this node should be provided.
Consolidate documentation
We have the following pages related to backup and restore:
- https://docs.gitlab.com/ee/raketasks/backup_restore.html
- https://docs.gitlab.com/ee/raketasks/backup_gitlab.html
- https://docs.gitlab.com/ee/raketasks/restore_gitlab.html
- https://docs.gitlab.com/charts/architecture/backup-restore.html
- https://docs.gitlab.com/charts/backup-restore/backup.html
- https://docs.gitlab.com/ee/administration/get_started.html#back-up-your-gitlab-data
We should consolidate and restructure this content around the guidance and runbook style instructions.
Update upgrade documentation
We recommend taking full backups when upgrading. We should review and update the guidance provided on these pages to ensure they align with the above work.
Who can address the issue
Anyone in the Geo team.