diff --git a/docs/guides/cli/kubectl-plugin/index.md b/docs/guides/cli/kubectl-plugin/index.md index 587b8f58..10e4dd7d 100644 --- a/docs/guides/cli/kubectl-plugin/index.md +++ b/docs/guides/cli/kubectl-plugin/index.md @@ -42,7 +42,9 @@ Available command for `kubectl stash` cli are: | [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 | +| [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 | ## Create Command @@ -53,7 +55,7 @@ Available command for `kubectl stash` cli are: To create a `Repository`, you need to provide a `Repository` name and backend information and credential. You will provide the information and credential by using flags. The available flags are: | Flag | Description | -| ------------------- | ----------------------------------------------------------------------------- | +|---------------------|-------------------------------------------------------------------------------| | `--namespace` | Indicates the namespace where the Repository will be created | | `--secret` | Specify the name of the storage secret that will be used to create Repository | | `--bucket` | Specify the name of the cloud bucket/container. | @@ -79,13 +81,13 @@ $ kubectl stash create repository gcs-repo --namespace=demo --secret=gcs-secret To create a `BackupConfiguration`, you need to provide `BackupConfiguration` name, `Repository` name, Target, and RetentionPolicy, etc. You will provide the `Repository` name, Target, RetentionPolicy by using flags. The available flags are: | Flag | Description | -| ----------------------- | ---------------------------------------------------------------------------------------------- | +|-------------------------|------------------------------------------------------------------------------------------------| | `--namespace` | Indicates the namespace where the `BackupConfiguration` will be created | | `--target-apiversion` | Specify API-Version of the target resource. | | `--target-kind` | Specify kind of the target resource. | | `--target-name` | Specify name of the target resource. | -| `--repo-name` | Specify name of the `Repository` that will be created. | -| `--repo-namespace` | Specify namespace of the `Repository` that will be created. | +| `--repo-name` | Specify name of the `Repository` that will be created. | +| `--repo-namespace` | Specify namespace of the `Repository` that will be created. | | `--schedule` | Specify schedule of the backup. | | `--driver` | `Driver` indicates the mechanism used to backup (i.e. VolumeSnapshotter, Restic) | | `--task` | Specify name of a `Task` | @@ -121,13 +123,13 @@ $ kubectl stash create backupconfig ss-backup --namespace=demo --repo-name=gcs-r To create a `RestoreSession`, you need to provide a `Repository` name, Target or `VolumeClaimTemplate`, etc. You will provide the `Repository` name, Target or `VolumeClaimTemplate` by using flags. The available flags are: | Flag | Description | -| ---------------------- | ------------------------------------------------------------------------------ | +|------------------------|--------------------------------------------------------------------------------| | `--namespace` | Indicates the namespace where the `RestoreSession` will be created | | `--target-apiversion` | API-Version of the target resource. | | `--target-kind` | Specify kind of the target resource. | | `--target-name` | Specify name of the target resource. | -| `--repo-name` | specify name of the `Repository`. | -| `--repo-namespace` | specify namespace of the `Repository` | +| `--repo-name` | specify name of the `Repository`. | +| `--repo-namespace` | specify namespace of the `Repository` | | `--driver` | Driver indicates the mechanism used to backup (i.e. VolumeSnapshotter, Restic) | | `--task` | Name of the Task | | `--replica` | Replica specifies the number of replicas whose data should be backed up. | @@ -163,9 +165,9 @@ $ kubectl stash create restoresession ss-restore --namespace=demo --repo-name=gc To copy a Secret, you need to provide Secret name and destination namespace. You will provide the destination namespace by using flag. The available flags are: -| Flag | Description | -| ---------------- |----------------------------------------------------------------------| -| `--namespace` | Indicates the namespace of the respective `Secret`. | +| Flag | Description | +|------------------|------------------------------------------------------------------------| +| `--namespace` | Indicates the namespace of the respective `Secret`. | | `--to-namespace` | Indicates the destination namespace where the `Secret` will be copied. | **Format:** @@ -189,9 +191,9 @@ To copy a Repository, you need to provide a Repository name and destination name You will provide the destination namespace by using flag. The available flags are: -| Flag | Description | -| ---------------- |-----------------------------------------------------------------------| -| `--namespace` | Indicates the namespace of the respective `Repository`. | +| Flag | Description | +|------------------|----------------------------------------------------------------------------| +| `--namespace` | Indicates the namespace of the respective `Repository`. | | `--to-namespace` | Indicates the destination namespace where the `Repository` will be copied. | **Format:** @@ -217,7 +219,7 @@ To copy a BackupConfiguration, you need to provide BackupConfiguration name and You will provide the destination namespace by using flags. The available flags are: | Flag | Description | -| ---------------- |-------------------------------------------------------------------------------------| +|------------------|-------------------------------------------------------------------------------------| | `--namespace` | Indicates the namespace of the respective `BackupConfiguration`. | | `--to-namespace` | Indicates the destination namespace where the `BackupConfiguration` will be copied. | @@ -238,7 +240,7 @@ $ kubectl stash cp backupconfig my-backupconfig --namespace=demo --to-namespace= To copy a VolumeSnapshot, you need to provide `VolumeSnapshot` name and destination namespace. You will provide the destination namespace by using flag. The available flags are: | Flag | Description | -| ---------------- |--------------------------------------------------------------------------------| +|------------------|--------------------------------------------------------------------------------| | `--namespace` | Indicates the namespace of the respective `VolumeSnapshot`. | | `--to-namespace` | Indicates the destination namespace where the `VolumeSnapshot` will be copied. | @@ -261,7 +263,7 @@ To clone a PVC, you need to provide backend credentials for creating Repository. You will provide the backend credential by using flags. The available flags are: | Flag | Description | -| ------------------- |-------------------------------------------------------------------------------| +|---------------------|-------------------------------------------------------------------------------| | `--namespace` | Indicates namespace of the respective pvc. | | `--to-namespace` | Indicates the destination namespace where the PVC will be cloned. | | `--secret` | Specify the name of the storage secret that will be used to create Repository | @@ -530,7 +532,8 @@ $ kubectl stash key remove my-repo --namespace=demo --id cdc89a7d ## Generate Rules -`kubectl stash debug` command is used to create rules for a RestoreSession to recover the database and application backups. This command finds the nearest repository snapshots for a given timestamp and generates two rules: one for the snapshots just before the specified timestamp and another for those at or after the specified timestamp. The available flags for this command are: +`kubectl stash gen rules` command is used to create rules for a RestoreSession to recover the database and application +backups. This command finds the nearest repository snapshots for a given timestamp and generates two rules: one for the snapshots just before the specified timestamp and another for those at or after the specified timestamp. The available flags for this command are: | Flag | Description | |----------------------|-------------------------------------------------------------| @@ -549,3 +552,47 @@ kubectl stash gen rules [flags] ```bash $ kubectl stash gen rules my-repo --namespace=demo --timestamp 2023-10-05T05:16:11Z ``` + +## Check Repository + +`kubectl stash check` command is used to test the restic repository for errors and reports any errors it finds. It can also be used to read all data and therefore simulate a restore. By default, the command will always load all data directly from the repository and not use a local cache. The available flags for this command are: + +| Flag | Description | +|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--namespace` | Indicates the namespace of the respective `Repository`. | +| `--read-data` | Read all data blobs. | +| `--with-cache` | Use existing cache, only read uncached data from repository. | +| `--read-data-subset` | Read a subset of data packs, specified as 'n/t' for specific part, or either 'x%' or 'x.y%' or a size in bytes with suffixes k/K, m/M, g/G, t/T for a random subset | + +**Format** + +```bash +kubectl stash check [flags] +``` + +**Example** + +```bash +$ kubectl stash check my-repo --namespace=demo --read-data +``` + +## Rebuild Index + +`kubectl stash rebuild-index` command is used to create a new index based on the pack files in the restic repository. + +| Flag | Description | +|--------------------|---------------------------------------------------------| +| `--namespace` | Indicates the namespace of the respective `Repository`. | +| `--read-all-packs` | Read all pack files to generate new index from scratch. | + +**Format** + +```bash +kubectl stash rebuild-index [flags] +``` + +**Example** + +```bash +$ kubectl stash rebuild-index my-repo --namespace=demo --read-all-packs +``` \ No newline at end of file diff --git a/docs/guides/hooks/overview/images/job-model.svg b/docs/guides/hooks/overview/images/job-model.svg index f31032cd..d198f850 100644 --- a/docs/guides/hooks/overview/images/job-model.svg +++ b/docs/guides/hooks/overview/images/job-model.svg @@ -1,1058 +1 @@ - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + \ No newline at end of file diff --git a/docs/guides/hooks/overview/index.md b/docs/guides/hooks/overview/index.md index 146055ae..4f7ba6b5 100644 --- a/docs/guides/hooks/overview/index.md +++ b/docs/guides/hooks/overview/index.md @@ -56,13 +56,15 @@ Here, we are going to discuss how Stash executes the hooks in different scenario
Fig: Hook Execution flow in sidecar model
-- **Job Model:** In Job model, `httpGet`, `httpPost` and `tcpSocket` are executed by the backup/restore job. However, the `exec` hook is executed in the targeted application pod. In order to determine the targeted application pod, Stash uses the `Service` specified in the respective `AppBinding` crd. It first determines the endpoints of the Service. Then, it executes the hook into one of the pod pointed by those endpoints. Hence, if the `AppBinding` points to an external URL, it is not possible for Stash to execute the `exec` hook. The hook execution flow in job model is shown in the following diagram: +- **Job Model:** In the Job model, the hooks are run by the backup/restore job. For the `exec` hook, the command is executed inside the targeted application pod. In order to determine the targeted application pod, Stash uses the `Service` specified in the respective `AppBinding` CRD. It first determines the endpoints of the Service. Then, it executes the hook into one of the pod pointed by those endpoints. Hence, if the `AppBinding` points to an external URL, it is not possible for Stash to execute the hook. The hook execution flow in job model is shown in the following diagram:
  Hook Execution flow in job model
Fig: Hook Execution flow in job model
+> Note: If the postBackup hook doesn't run (e.g., because of a timeout, backup disruption, etc.), the Stash operator will handle it instead of the backup job. However, if the preBackup hook is configured but doesn’t execute or fails the postBackup hook will not be run. + - **Batch Backup:** In batch backup using `BackupBatch` object, the global hooks are executed by the Stash operator itself. When Stash operator completes executing the global pre-task hook, the individual targets start executing their local pre-task hook. Then, they complete their backup process and executes their local post-task hook. Finally, the Stash operator executes global post-task hooks. The hook execution flow in batch backup is shown in the following diagram:
@@ -91,6 +93,8 @@ If the backup or restore process fails then the respective `postBackup` or `post - `OnFailure`: The hook will be executed after the backup/restore process only if the backup/restore has failed. - `OnFinalRetryFailure`: The hook will be executed after the backup process only if the backup has failed with no more retry attempts left. +In case of backup job, if the postBackup hook container doesn't run for any reason, the postBackup hook is executed by the Stash operator instead of the backup job (if targeted application is not `AppBinding`). For `AppBinding`, hook is executed in the targeted application pod. + If the `postBackup` or `postRestore` hook fails, the respective BackupSession or RestoreSession will be marked as `Failed`. ## Templating Support in Hook