documentation/pages/databox.md

# Компонент DataBox и работа с файлами

## DataBox

Компонент DataBox позволяет хранить данные, необходимые для работы модуля, в файловом хранилище S3.

Рекомендуемая структура расположения данных:

1. Образ Docker:
   1. Код проекта
   2. Системные библиотеки и прочие программные зависимости
   3. Постоянные файлы настроек
2. DataBox для данных:
   1. Веса предобученных моделей машинного обучения.
   2. Большие и постоянные наборы внешних данных (например, исторические погодные данные для модуля прогноза погоды).
3. DataBox для пользователей:
   1. Изначально бокс пуст.
   2. В боксе хранятся загруженные пользователями входные данные и рассчитанные модулем выходные данные работы ML-компонентов и пайплайнов.

Пример манифеста компонента DataBox

```yaml
apiVersion: "unified-platform.cs.hse.ru/v1"
kind: DataBox
metadata:
  name: userdata
  namespace: my-app
spec:
  s3DefaultStorage:
    capacity: 1G
```

В данном примере `userdata` - это имя компонента DataBox, по которому к нему в дальнейшем смогут обращаться другие компоненты и пользователи. Например, в [ML-компонентах](./mlcmp.md) это имя используется в разделе `connectedBoxes`.

Поле `spec.s3DefaultStorage.capacity` определяет размер выделенного под DataBox дискового пространства. Можно не указывать `capacity`, тогда поле будет выглядеть так:

```yaml
spec:
  s3DefaultStorage: {}
```

Если `capacity` не указано, по умолчанию выделяется 1ГБ пространства.

## Пути

### Файловое хранилище

В файловом хранилище имена файлов имеют следующую структуру:

```
/my-app/userdata/users/test_user/file_groups/my_file_group/file.txt
```

Здесь:

- `my-app` - имя приложения. Файлы разных приложений хранятся изолированно отдельно друг от друга.
- `userdata` - имя компонента DataBox.
- `users` - системная часть пути, означающая "далее идут файлы, загруженные пользователями".
- `test_user` - имя пользователя, который загрузил данные
- `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
```

Здесь подключается компонент DataBox с именем `model-box`:

- Путь `users/developer/file_groups/models_pretrained` в DataBox (в хранилище S3)
- Путь `/home/myproject/data/weights/` в локальной файловой системе контейнера
- Название компонента DataBox контролируется полем `s3BoxName`
- Название смонтированного компонента для упоминания внутри манифеста контролируется полем `name`. В этом примере эти два названия совпадают.

### Файловый API

Доступ к файлам через API производится по ссылкам со следующей структурой

```
https://platform.stratpro.hse.ru/my-app/model-box/my_file_group/file.txt
```

Здесь:

- `my-app` - имя приложения
- `model-box` - имя DataBox, в который загружаются данные или из которого скачиваются данные
- `my_file_group/file.txt` путь к файлу, соответствующий пути после `file_groups` в хранилище
- Имя пользователя в участке пути `users/USERNAME/file_groups` определяется, исходя из того, реквизиты какого пользователя используются при выполнении запроса.