Skip to content

Commit 90f315f

Browse files
ishtiaqhimelishtiaqhimel
authored
Add docs for migrate cmd (#305)
Signed-off-by: Md. Ishtiaq Islam <ishtiaq@appscode.com>
1 parent 3d46dd7 commit 90f315f

File tree

3 files changed

+112
-25
lines changed

3 files changed

+112
-25
lines changed

‎docs/guides/cli/kubectl-plugin/index.md‎

Lines changed: 73 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -21,30 +21,32 @@ Stash gives you kubectl plugin support named `kubectl stash` cli. `kubectl stash
2121

2222
Available command for `kubectl stash` cli are:
2323

24-
| Main Command | Uses |
25-
|----------------------------------------------------|----------------------------------------------------------------------------|
26-
| [create repository](#create-repository) | Create a new `Repository`. |
27-
| [create backupconfig](#create-backupconfiguration) | Create a new `BackupConfiguration`. |
28-
| [create restoresession](#create-restoresession) | Create a new `RestoreSession`. |
29-
| [cp secret](#copy-secret) | Copy `Secret` from source namespace to destination namespace. |
30-
| [cp repository](#copy-repository) | Copy `Repository` from source namespace to destination namespace. |
31-
| [copy backupconfig](#copy-backupconfiguration) | Copy `BackupConfiguration` from source namespace to destination namespace. |
32-
| [copy volumesnapshot](#copy-volumesnapshot) | Copy `VolumeSnapshot` from source namespace to destination namespace. |
33-
| [clone pvc](#clone-pvc) | Clone a PVC from source namespace to destination namespace. |
34-
| [download](#download-snapshots) | Download backup snapshots from backend into your local repository. |
35-
| [trigger](#trigger-an-instant-backup) | Take an instant backup. |
36-
| [pause backup](#pause-backup) | Pause Stash backup. |
37-
| [resume backup](#resume-backup) | Resume Stash backup. |
38-
| [debug backup](#debug-backup) | Debug Stash backup issues. |
39-
| [debug restore](#debug-restore) | Debug Stash restore issues. |
40-
| [debug operator](#debug-operator) | Debug Stash operator issues. |
41-
| [key list](#key-list) | List the keys (passwords) of a restic repository. |
42-
| [key add](#key-add) | Add a new key (password) to a restic repository. |
43-
| [key update](#key-update) | Update current key (password) of a restic repository. |
44-
| [key remove](#key-remove) | Remove a key (password) of a restic repository. |
45-
| [gen rules](#generate-rules) | Generate restore rules from nearest snapshots at a specific time. |
46-
| [check](#check-repository) | Test the restic repository for errors and reports any errors it finds. |
47-
| [rebuild-index](#rebuild-index) | Create a new index based on the pack files in the restic repository |
24+
| Main Command | Uses |
25+
|----------------------------------------------------|-----------------------------------------------------------------------------|
26+
| [create repository](#create-repository) | Create a new `Repository`. |
27+
| [create backupconfig](#create-backupconfiguration) | Create a new `BackupConfiguration`. |
28+
| [create restoresession](#create-restoresession) | Create a new `RestoreSession`. |
29+
| [cp secret](#copy-secret) | Copy `Secret` from source namespace to destination namespace. |
30+
| [cp repository](#copy-repository) | Copy `Repository` from source namespace to destination namespace. |
31+
| [copy backupconfig](#copy-backupconfiguration) | Copy `BackupConfiguration` from source namespace to destination namespace. |
32+
| [copy volumesnapshot](#copy-volumesnapshot) | Copy `VolumeSnapshot` from source namespace to destination namespace. |
33+
| [clone pvc](#clone-pvc) | Clone a PVC from source namespace to destination namespace. |
34+
| [download](#download-snapshots) | Download backup snapshots from backend into your local repository. |
35+
| [trigger](#trigger-an-instant-backup) | Take an instant backup. |
36+
| [pause backup](#pause-backup) | Pause Stash backup. |
37+
| [resume backup](#resume-backup) | Resume Stash backup. |
38+
| [debug backup](#debug-backup) | Debug Stash backup issues. |
39+
| [debug restore](#debug-restore) | Debug Stash restore issues. |
40+
| [debug operator](#debug-operator) | Debug Stash operator issues. |
41+
| [key list](#key-list) | List the keys (passwords) of a restic repository. |
42+
| [key add](#key-add) | Add a new key (password) to a restic repository. |
43+
| [key update](#key-update) | Update current key (password) of a restic repository. |
44+
| [key remove](#key-remove) | Remove a key (password) of a restic repository. |
45+
| [gen rules](#generate-rules) | Generate restore rules from nearest snapshots at a specific time. |
46+
| [check](#check-repository) | Test the restic repository for errors and reports any errors it finds. |
47+
| [rebuild-index](#rebuild-index) | Create a new index based on the pack files in the restic repository |
48+
| [migrate](#migrate-repository) | Check the repository integrity and then upgrade the repository version to 2 |
49+
| [prune](#prune) | Remove unneeded data from the repository |
4850

4951
## Create Command
5052

@@ -595,4 +597,50 @@ kubectl stash rebuild-index <repository-name> [flags]
595597

596598
```bash
597599
$ kubectl stash rebuild-index my-repo --namespace=demo --read-all-packs
598-
```
600+
```
601+
602+
## Migrate Repository
603+
604+
`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.
605+
606+
| Flag | Description |
607+
|---------------|---------------------------------------------------------|
608+
| `--namespace` | Indicates the namespace of the respective `Repository`. |
609+
610+
**Format**
611+
612+
```bash
613+
kubectl stash migrate <repository-name> [flags]
614+
```
615+
616+
**Example**
617+
618+
```bash
619+
$ kubectl stash migrate my-repo --namespace=demo
620+
```
621+
622+
## Prune
623+
624+
`kubectl stash prune` command is used to remove unneeded data from the repository.
625+
626+
| Flag | Description |
627+
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
628+
| `--namespace` | Indicates the namespace of the respective `Repository`. |
629+
| `--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%`) |
630+
| `--max-repack-size` | Maximum size to repack (allowed suffixes: k/K, m/M, g/G, t/T) |
631+
| `--dry-run` | Do not modify the repository, just print what would be done |
632+
| `--repack-uncompressed` | Repack all uncompressed data |
633+
| `--repack-cacheable-only` | Only repack packs which are cacheable |
634+
| `--repack-small` | Repack pack files below `80%` of target pack size |
635+
636+
**Format**
637+
638+
```bash
639+
kubectl stash prune <repository-name> [flags]
640+
```
641+
642+
**Example**
643+
644+
```bash
645+
$ kubectl stash prune my-repo --namespace=demo
646+
```

‎docs/guides/repo-upgrade/_index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Upgrading Repository Version | Stash
3+
menu:
4+
docs_{{ .version }}:
5+
identifier: repo-upgrade
6+
name: Upgrading Repository Version
7+
parent: guides
8+
weight: 135
9+
menu_name: docs_{{ .version }}
10+
---

‎docs/guides/repo-upgrade/migration/index.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Upgrading Repository Format Version | Stash
3+
menu:
4+
docs_{{ .version }}:
5+
identifier: how-to-upgrade
6+
name: How to upgrade?
7+
parent: repo-upgrade
8+
weight: 10
9+
product_name: stash
10+
menu_name: docs_{{ .version }}
11+
section_menu_id: guides
12+
---
13+
14+
# Upgrading Repository Format Version
15+
16+
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.
17+
18+
> 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.
19+
20+
## How to upgrade
21+
22+
Upgrading to repository version 2 involves the following steps:
23+
24+
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.
25+
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.
26+
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.
27+
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.
28+
29+
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.

0 commit comments

Comments
 (0)