Skip to content

Add docs for migrate cmd #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
1gtm merged 2 commits into from
Feb 7, 2025
Merged

Add docs for migrate cmd #305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
afd57b8
Add docs for migrate cmd
ishtiaqhimel Jan 15, 2025
623e848
Add docs for migration process
ishtiaqhimel Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 73 additions & 25 deletions docs/guides/cli/kubectl-plugin/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

```bash
$ kubectl stash rebuild-index my-repo --namespace=demo --read-all-packs
```
```

## 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 <repository-name> [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 <repository-name> [flags]
```

**Example**

```bash
$ kubectl stash prune my-repo --namespace=demo
```
10 changes: 10 additions & 0 deletions docs/guides/repo-upgrade/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 }}
---
29 changes: 29 additions & 0 deletions docs/guides/repo-upgrade/migration/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading