From afd57b80d9335692bc7e8f9f18ed85e9aa1e1dbf Mon Sep 17 00:00:00 2001 From: "Md. Ishtiaq Islam" Date: Wed, 15 Jan 2025 11:24:40 +0600 Subject: [PATCH 1/2] Add docs for migrate cmd Signed-off-by: Md. Ishtiaq Islam --- docs/guides/cli/kubectl-plugin/index.md | 98 ++++++++++++++++++------- 1 file changed, 73 insertions(+), 25 deletions(-) diff --git a/docs/guides/cli/kubectl-plugin/index.md b/docs/guides/cli/kubectl-plugin/index.md index 10e4dd7d..0810e8bd 100644 --- a/docs/guides/cli/kubectl-plugin/index.md +++ b/docs/guides/cli/kubectl-plugin/index.md @@ -21,30 +21,32 @@ Stash gives you kubectl plugin support named `kubectl stash` cli. `kubectl stash Available command for `kubectl stash` cli are: -| Main Command | Uses | -|----------------------------------------------------|----------------------------------------------------------------------------| -| [create repository](#create-repository) | Create a new `Repository`. | -| [create backupconfig](#create-backupconfiguration) | Create a new `BackupConfiguration`. | -| [create restoresession](#create-restoresession) | Create a new `RestoreSession`. | -| [cp secret](#copy-secret) | Copy `Secret` from source namespace to destination namespace. | -| [cp repository](#copy-repository) | Copy `Repository` from source namespace to destination namespace. | -| [copy backupconfig](#copy-backupconfiguration) | Copy `BackupConfiguration` from source namespace to destination namespace. | -| [copy volumesnapshot](#copy-volumesnapshot) | Copy `VolumeSnapshot` from source namespace to destination namespace. | -| [clone pvc](#clone-pvc) | Clone a PVC from source namespace to destination namespace. | -| [download](#download-snapshots) | Download backup snapshots from backend into your local repository. | -| [trigger](#trigger-an-instant-backup) | Take an instant backup. | -| [pause backup](#pause-backup) | Pause Stash backup. | -| [resume backup](#resume-backup) | Resume Stash backup. | -| [debug backup](#debug-backup) | Debug Stash backup issues. | -| [debug restore](#debug-restore) | Debug Stash restore issues. | -| [debug operator](#debug-operator) | Debug Stash operator issues. | -| [key list](#key-list) | List the keys (passwords) of a restic repository. | -| [key add](#key-add) | Add a new key (password) to a restic repository. | -| [key update](#key-update) | Update current key (password) of a restic repository. | -| [key remove](#key-remove) | Remove a key (password) of a restic repository. | -| [gen rules](#generate-rules) | Generate restore rules from nearest snapshots at a specific time. | -| [check](#check-repository) | Test the restic repository for errors and reports any errors it finds. | -| [rebuild-index](#rebuild-index) | Create a new index based on the pack files in the restic repository | +| Main Command | Uses | +|----------------------------------------------------|-----------------------------------------------------------------------------| +| [create repository](#create-repository) | Create a new `Repository`. | +| [create backupconfig](#create-backupconfiguration) | Create a new `BackupConfiguration`. | +| [create restoresession](#create-restoresession) | Create a new `RestoreSession`. | +| [cp secret](#copy-secret) | Copy `Secret` from source namespace to destination namespace. | +| [cp repository](#copy-repository) | Copy `Repository` from source namespace to destination namespace. | +| [copy backupconfig](#copy-backupconfiguration) | Copy `BackupConfiguration` from source namespace to destination namespace. | +| [copy volumesnapshot](#copy-volumesnapshot) | Copy `VolumeSnapshot` from source namespace to destination namespace. | +| [clone pvc](#clone-pvc) | Clone a PVC from source namespace to destination namespace. | +| [download](#download-snapshots) | Download backup snapshots from backend into your local repository. | +| [trigger](#trigger-an-instant-backup) | Take an instant backup. | +| [pause backup](#pause-backup) | Pause Stash backup. | +| [resume backup](#resume-backup) | Resume Stash backup. | +| [debug backup](#debug-backup) | Debug Stash backup issues. | +| [debug restore](#debug-restore) | Debug Stash restore issues. | +| [debug operator](#debug-operator) | Debug Stash operator issues. | +| [key list](#key-list) | List the keys (passwords) of a restic repository. | +| [key add](#key-add) | Add a new key (password) to a restic repository. | +| [key update](#key-update) | Update current key (password) of a restic repository. | +| [key remove](#key-remove) | Remove a key (password) of a restic repository. | +| [gen rules](#generate-rules) | Generate restore rules from nearest snapshots at a specific time. | +| [check](#check-repository) | Test the restic repository for errors and reports any errors it finds. | +| [rebuild-index](#rebuild-index) | Create a new index based on the pack files in the restic repository | +| [migrate](#migrate-repository) | Check the repository integrity and then upgrade the repository version to 2 | +| [prune](#prune) | Remove unneeded data from the repository | ## Create Command @@ -595,4 +597,50 @@ kubectl stash rebuild-index [flags] ```bash $ kubectl stash rebuild-index my-repo --namespace=demo --read-all-packs -``` \ No newline at end of file +``` + +## Migrate Repository + +`kubectl stash migrate` command is used to check the repository integrity and then upgrade the repository version to 2. After the migration is complete, run `kubectl stash prune` to compress the repository metadata. + +| Flag | Description | +|---------------|---------------------------------------------------------| +| `--namespace` | Indicates the namespace of the respective `Repository`. | + +**Format** + +```bash +kubectl stash migrate [flags] +``` + +**Example** + +```bash +$ kubectl stash migrate my-repo --namespace=demo +``` + +## Prune + +`kubectl stash prune` command is used to remove unneeded data from the repository. + +| Flag | Description | +|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `--namespace` | Indicates the namespace of the respective `Repository`. | +| `--max-unused-limit` | Tolerate given limit of unused data (absolute value in bytes with suffixes k/K, m/M, g/G, t/T, a value in % or the word 'unlimited') (default `5%`) | +| `--max-repack-size` | Maximum size to repack (allowed suffixes: k/K, m/M, g/G, t/T) | +| `--dry-run` | Do not modify the repository, just print what would be done | +| `--repack-uncompressed` | Repack all uncompressed data | +| `--repack-cacheable-only` | Only repack packs which are cacheable | +| `--repack-small` | Repack pack files below `80%` of target pack size | + +**Format** + +```bash +kubectl stash prune [flags] +``` + +**Example** + +```bash +$ kubectl stash prune my-repo --namespace=demo +``` From 623e848891119517956d1ab6d8a1c42994c0eb48 Mon Sep 17 00:00:00 2001 From: "Md. Ishtiaq Islam" Date: Wed, 15 Jan 2025 17:43:45 +0600 Subject: [PATCH 2/2] Add docs for migration process Signed-off-by: Md. Ishtiaq Islam --- docs/guides/repo-upgrade/_index.md | 10 +++++++ docs/guides/repo-upgrade/migration/index.md | 29 +++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 docs/guides/repo-upgrade/_index.md create mode 100644 docs/guides/repo-upgrade/migration/index.md diff --git a/docs/guides/repo-upgrade/_index.md b/docs/guides/repo-upgrade/_index.md new file mode 100644 index 00000000..529d3177 --- /dev/null +++ b/docs/guides/repo-upgrade/_index.md @@ -0,0 +1,10 @@ +--- +title: Upgrading Repository Version | Stash +menu: + docs_{{ .version }}: + identifier: repo-upgrade + name: Upgrading Repository Version + parent: guides + weight: 135 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/repo-upgrade/migration/index.md b/docs/guides/repo-upgrade/migration/index.md new file mode 100644 index 00000000..bef374d4 --- /dev/null +++ b/docs/guides/repo-upgrade/migration/index.md @@ -0,0 +1,29 @@ +--- +title: Upgrading Repository Format Version | Stash +menu: + docs_{{ .version }}: + identifier: how-to-upgrade + name: How to upgrade? + parent: repo-upgrade + weight: 10 +product_name: stash +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +# Upgrading Repository Format Version + +Repositories created with older versions of `Stash` use an older repository format version, which needs to be upgraded to unlock new features. This upgrade process is optional but required if you want to take advantage of the latest enhancements. Keep in mind that upgrading the repository format will increase the up-to-date Stash version needed to access it. For example, repositories upgraded to format version 2 can only be read by `Stash v2025.1.9` or later. + +> Upgrading repository format version will take some time depending on the repository size. Repository issues must be corrected before upgrading. It is recommended to contact with Stash team before upgrading repository. + +## How to upgrade + +Upgrading to repository version 2 involves the following steps: + +1. **Pause the Corresponding Backup:** Before upgrading, pause the backup associated with the repository. You can do this using the [pause backup](/docs/guides/cli/kubectl-plugin/index.md#pause-backup) command provided by the Stash kubectl plugin. +2. **Run the Migration Command:** Next, execute the [migrate](/docs/guides/cli/kubectl-plugin/index.md#migrate-repository) command provided by the Stash kubectl plugin. This command will first check the repository’s integrity and then upgrade its format to version 2. Note that if any issues are found during the integrity check, they must be resolved before the migration can proceed. +3. **Run the Prune Command:** After a successful migration, use the [prune](/docs/guides/cli/kubectl-plugin/index.md#prune) command provided by Stash kubectl plugin to compress the repository metadata. If you want to limit the amount of data rewritten in a single operation, use the `--max-repack-size` flag with the `prune` command. +4. **Resume the Corresponding Backup:** Now resume the backup associated with the repository. You can do this using the [resume backup](/docs/guides/cli/kubectl-plugin/index.md#resume-backup) command provided by the Stash kubectl plugin. + +Keep in mind that the contents of files already stored in the repository will not be rewritten during the upgrade. Only data from new backups will be compressed. Over time, more and more of the repository will be automatically compressed as new backups are added.