From 685324740826cfb2bf5ace5f2caaa7cca87ede5c Mon Sep 17 00:00:00 2001
From: Martin Schroschk <martin.schroschk@tu-dresden.de>
Date: Wed, 30 Oct 2024 09:26:13 +0100
Subject: [PATCH] Improve subsections on expiration and restoring workspaces
- Improve structure of the subsection on restoring workspaces
- Sketch general process
- Add detailed example
- Mention expirer procesess in subsection of manual deleting of workspaces
- Minor wording improvements
---
.../docs/data_lifecycle/workspaces.md | 96 ++++++++++++-------
1 file changed, 64 insertions(+), 32 deletions(-)
diff --git a/doc.zih.tu-dresden.de/docs/data_lifecycle/workspaces.md b/doc.zih.tu-dresden.de/docs/data_lifecycle/workspaces.md
index ceb4ebaac..556f8d26f 100644
--- a/doc.zih.tu-dresden.de/docs/data_lifecycle/workspaces.md
+++ b/doc.zih.tu-dresden.de/docs/data_lifecycle/workspaces.md
@@ -324,7 +324,12 @@ ws_send_ical --filesystem horse --mail <your.email>@tu-dresden.de --workspace te
### Deletion of a Workspace
-To delete a workspace use the `ws_release` command. It is mandatory to specify the name of the
+There is an [Expire process](#expire-process) for every workspace filesystem running on a daily
+basis. This processes check the lifetime of all workspaces and move expired workspaces into the
+grace period.
+
+In addition to this automatic process, you also have the option of **explicitly releasing
+workspaces** using the `ws_release` command. It is mandatory to specify the name of the
workspace and the filesystem in which it is allocated:
```console
@@ -344,17 +349,24 @@ marie-numbercrunch-1701873907
```
In this example, the user `marie` has two inactive, i.e., expired, workspaces namely
-`test-workspace` in `horse`, as well as numbercrunch in the `walrus` filesystem. The command
+`test-workspace` in `horse`, as well as `numbercrunch` in the `walrus` filesystem. The command
`ws_restore --list` lists the name of the workspace and its expiration date. As you can see, the
-expiration date is added to the workspace name as Unix timestamp.
+expiration date in Unix timestamp format is added to the workspace name.
-!!! hint "Deleting data in in an expired workspace"
+!!! hint "Deleting data in an expired workspace"
If you are short on quota, you might want to delete data in expired workspaces since it counts
to your quota. Expired workspaces are moved to a hidden directory named `.removed`. The access
rights remain unchanged. I.e., you can delete the data inside the workspace directory but you
must not delete the workspace directory itself!
+!!! warning
+
+ When you release a workspace **by hand**, it will not receive a grace period and be
+ **permanently deleted** the **next day**. The advantage of this design is that you can create
+ and release workspaces inside jobs and not flood the filesystem with data no one needs anymore
+ in the hidden directories (when workspaces are in the grace period).
+
#### Expire Process
The clean up process of expired workspaces is automatically handled by a so-called expirer process.
@@ -370,42 +382,62 @@ It performs the following steps once per day and filesystem:
### Restoring Expired Workspaces
At expiration time your workspace will be moved to a special, hidden directory. For a month,
-you can still restore your data **into an existing workspace**.
+you can still restore your data **into an existing workspace** using the command `ws_restore`.
-!!! warning
+The expired workspace has to be specified by its full name as listed by `ws_restore --list`,
+including username prefix and timestamp suffix. Otherwise, it cannot be uniquely identified. The
+target workspace, on the other hand, must be given with just its short name, as listed by `ws_list`,
+without the username prefix.
- When you release a workspace **by hand**, it will not receive a grace period and be
- **permanently deleted** the **next day**. The advantage of this design is that you can create
- and release workspaces inside jobs and not flood the filesystem with data no one needs anymore
- in the hidden directories (when workspaces are in the grace period).
+Both workspaces must be on the **very same filesystem**. The data from the old workspace will be
+moved into a directory in the new workspace with the name of the old one. This means a newly
+allocated workspace works as well as a workspace that already contains data.
-Use
+!!! note "Steps for restoring a workspace"
-```console
-marie@login$ ws_restore --list
-horse:
-marie-test-workspace-1701873807
- unavailable since Wed Dec 6 15:43:27 2023
-walrus:
-marie-numbercrunch-1701873907
- unavailable since Wed Dec 6 15:45:07 2023
-```
+ 1. Use `ws_restore --list` to list all your expired workspaces and get the correct identifier
+ string for the expired workspace. The identifier string of an expired and an active workspace
+ are different!
+ 1. (Optional) Allocate a new workspace on the very same filesystem using `ws_allocate`.
+ 1. Then, you can invoke `ws_restore <workspace_name> <target_name>` to restore the expired
+ workspace into the active workspace.
-to get a list of your expired workspaces, and then restore them like that into an existing, active
-workspace 'new_ws':
+??? example "Restore workspace `number_crunch` into new workspace `long_computations`"
-```console
-marie@login$ ws_restore --filesystem horse marie-test-workspace-1701873807 new_ws
-```
+ This example depictes the necessary steps to restore the expired workspace `number_crunch` into
+ a newly allocated workspace named `long_computations.`
-The expired workspace has to be specified by its full name as listed by `ws_restore --list`,
-including username prefix and timestamp suffix (otherwise, it cannot be uniquely identified). The
-target workspace, on the other hand, must be given with just its short name, as listed by `ws_list`,
-without the username prefix.
+ **First step**: List expired workspaces and retrieve correct identifier for the expired workspace.
+ In this example, `marie` has two expired workspaces, namely `test-workspace` and `number_crunch`
+ both in the `horse` filesystem. The identifier for the restore command is
+ `marie-number_crunch-1701873907`.
-Both workspaces must be on the same filesystem. The data from the old workspace will be moved into
-a directory in the new workspace with the name of the old one. This means a fresh workspace works as
-well as a workspace that already contains data.
+ ```console
+ marie@login$ ws_restore --list
+ horse:
+ marie-test-workspace-1701873807
+ unavailable since Wed Dec 6 15:43:27 2023
+ marie-number_crunch-1701873907
+ unavailable since Wed Dec 6 15:45:07 2023
+ walrus:
+ ```
+
+ **Second step:** Allocate new workspace `long_compuations` on the very same filesystem. Please
+ refer to the documentation of the [`ws_allocate` command](#allocate-a-workspace) for
+ additional useful options.
+
+ ```console
+ marie@login$ ws_allocate --filesystem horse --name long_computations --duration 60
+ ```
+
+ **Third step:** Invoke the command `ws_restore`.
+
+ ```console
+ marie@login$ ws_restore --filesystem horse marie-number_crunch-1701873907 long_computations
+ to verify that you are human, please type 'menunesarowo': menunesarowo
+ you are human
+ Info: restore successful, database entry removed.
+ ```
## Linking Workspaces in HOME
--
GitLab