From f28a9b1d2038f30e49ec096dd2e0233f4618a0b8 Mon Sep 17 00:00:00 2001
From: Georgii Zhulikov <gzhulikov@hse.ru>
Date: Wed, 12 Mar 2025 12:44:41 +0300
Subject: [PATCH] Expand on files

---
 pages/databox.md | 89 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 80 insertions(+), 9 deletions(-)

diff --git a/pages/databox.md b/pages/databox.md
index 6bfdc7e..bd44ea2 100644
--- a/pages/databox.md
+++ b/pages/databox.md
@@ -1,14 +1,15 @@
-# Компонент DataBox
+# Компонент DataBox и работа с файлами
 
-Компонент DataBox позволяет хранить данные, необходимые для работы модуля.
+## DataBox
+
+Компонент DataBox позволяет хранить данные, необходимые для работы модуля, в файловом хранилище S3.
 
 Рекомендуемая структура расположения данных:
 
 1. Образ Docker:
    1. Код проекта
-   2. Среда с зависимостями
-   3. Системные библиотеки и прочие "программные" зависимости
-   4. Постоянные файлы настроек
+   2. Системные библиотеки и прочие программные зависимости
+   3. Постоянные файлы настроек
 2. DataBox для данных:
    1. Предобученные веса моделей машинного обучения.
    2. Большие и постоянные наборы внешних данных (например, исторические погодные данные для модуля прогноза погоды).
@@ -22,14 +23,84 @@
 apiVersion: "unified-platform.cs.hse.ru/v1"
 kind: DataBox
 metadata:
-  name: users
-  namespace: pu-username-pa-bm99
+  name: userdata
+  namespace: my-app
 spec:
   s3DefaultStorage:
     capacity: 1G
 ```
 
-В данном примере `users` - это имя компонента DataBox, по которому в дальнейшем смогут обращаться другие компоненты и пользователи.
+В данном примере `userdata` - это имя компонента DataBox, по которому в дальнейшем смогут обращаться другие компоненты и пользователи. Например, в [ML-компонентах](./mlcmp.md) это имя используется в разделе `connectedBoxes`.
+
+Поле `spec.s3DefaultStorage.capacity` определяет размер выделенного под DataBox дискового пространства. Можно не указывать `capacity`, тогда поле будет выглядеть так:
+
+```yaml
+spec:
+  s3DefaultStorage: {}
+```
+
+Если `capacity` не указано, по умолчанию выделяется 1ГБ пространства.
+
+## Пути
+
+### Файловое хранилище
+
+В файловом хранилище файлы хранятся со следующей структурой:
+
+```
+/my-app/userdata/users/gzhulikov/file_groups/my_file_group/file.txt
+```
+
+Здесь:
+
+- `my-app` - имя приложения. Файлы разных приложений хранятся отдельно друг от друга, между ними нет пересечения
+- `userdata` - имя компонента DataBox.
+- `users` - системная часть пути, означающая "далее идут файлы, загруженные пользователями".
+- `gzhulikov` - имя пользователя, который загрузил данные
+- `file_groups` - системная часть пути
+- `my_file_group` - созданная пользователем файловая группа (можно считать это "папкой" в хранилище S3)
+- `file.txt` - файл в хранилище S3
+
+### Компоненты модуля
+
+Компоненты `MLComponent` и `ExperimentPipeline` взаимодействуют с данными из хранилища S3. Это взаимодействие контролируется разделом `connectedBoxes`, а также параметром `mountFrom` в переменных пайплайнов.
+
+Структура пути в манифестах `MLComponent` и `ExperimentPipeline`:
+
+```
+users/developer/file_groups/my_file_group_file.txt
+```
+
+Здесь:
+
+- Имя приложения заранее известно, так как во всех компонентах уже указано, какому приложению они принадлежат
+- Имя компонента `DataBox` указывается отдельно от пути в соответствующем поле манифеста
+- Остальные компоненты пути повторяют структуру файлового хранилища, начиная с системной части пути - `users`
+
+Пример:
+
+
+```yaml
+  connectedBoxes:
+    - name: model-box
+      path: /home/myproject/data/weights/
+      mountS3Box:
+        subPath: users/developer/file_groups/models_pretrained
+        s3BoxName: model-box
+    - name: user-box
+      copyS3Box:
+        s3BoxName: userdata
+```
+
+Здесь подключаются два компонента DataBox:
+
+1. Монтируется DataBox `model-box`
+   - Путь `users/developer/file_groups/models_pretrained` в DataBox (в хранилище S3)
+   - Путь `/home/myproject/data/weights/` в локальной файловой системе контейнера
+   - Название компонента DataBox контролируется полем `s3BoxName`
+   - Название смонтированного компонента для упоминания внутри манифеста контролируется полем `name`. В этом примере эти два названия совпадают
+2. DataBox `userdata` подключается в режиме копирования
+   - Название компонента DataBox контролируется полем `s3BoxName`
+   - Название смонтированного компонента для упоминания внутри манифеста контролируется полем `name`. Если в этом манифесте нужно будет упомянуть этот DataBox, нужно будет использовать имя `user-box`, не `userdata`.
 
-Например, в [ML-компонентах](./mlcmp.md) это имя используется в разделе `connectedBoxes`.