Варианты и сценарии использования FSGW#

Варианты использования#

Сценарии использования#

Предполагается, что вы являетесь владельцем Bucket и имеете права на все файлы этого Bucket как и сам Bucket.

Доступность ReplicaSet определяется по равенству количества успешных ответов от кластеров и параметром _min-success-replication-factor_.

Все ошибки записывают в лог, а также увеличиваются соответствующие счетчики ошибок мониторинга.

Альтернативные сценарии не предусмотрены.

Загрузка файла в хранилище#

FSGW поддерживает операцию PutObject с разными опциями:

подписание объекта
получения хеш объекта
шифрование объекта

Для подписания объекта FSGW использует механизм открепленной подписи, при котором подпись будет помещена в хранилище как отдельный объект. Чтобы подписать объект, используйте заголовки:

x-amz-server-side-signature-suite: <signature-alias> # пример: key-store
x-amz-server-side-signature-object-key: <signature-object-key> # пример: key-1.txt.sign
x-amz-server-side-signature-order: <before-encryption\after-encryption> # необходим если используется шифрование объекта

Для получения хеш объекта используйте заголовки:

x-amz-server-side-hash-algorithm: <hash-algorithm> # пример: SHA2-256
x-amz-server-side-hash-order: <before-encryption\after-encryption> # необходим если используется шифрование объекта

В ответе на запрос с заголовками хеш, вы получите заголовок x-amz-server-side-hash, содержащий хэш загруженного объекта.

Способы шифрования объекта детально описываются в следующих пунктах.

Операция PutObject с FSGW версии 2.0.0 использует Multipart загрузку. Вы можете задать размер UploadPart для каждого replica-set в конфигурации приложения, параметр - upload-part-size. Если не указывать, по умолчанию: 10MB. Ориентируйтесь на минимальный размер UploadPart, который поддерживают S3 хранилища, в вашем replica-set.

Допускается возможность загрузить в хранилище объект с пустым телом запроса, но без заголовков шифрования, подписи или хеширования, в противном случае в ответе вернется соответсвующая ошибка.

Загрузка файла в хранилище с поддержкой шифрования#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName} c указанием заголовков шифрования.
2. FSGW шифрует файл.
3. FSGW выкладывает файл во все доступные кластеры ReplicaSet, в случае необходимости планирует асинхронную репликацию.
4. FSGW возвращает ответ внешней АС с заголовками шифрования.
исключительный сценарий:
- FSGW генерирует ошибку в случае указания неподдерживаемого алгоритма шифрования или расчета подписи, отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Загрузка файла в хранилище с поддержкой шифрования в режиме FSGW-TR#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName} c указанием заголовков.
```
   x-amz-server-side-encryption: fsgw-tr
   x-amz-server-side-encryption-aws-kms-key-id: <KeyID, string> (keyID example: "test")
```
2. FSGW генерирует ключ шифрования данных, шифрует данные, шифрует ключ данных ключом по оказанному keyID из TR Engine.
3. FSGW выкладывает файл и метаданные с информацией о шифровании во все доступные кластеры ReplicaSet, в случае необходимости планирует асинхронную репликацию.
4. FSGW возвращает ответ внешней АС с заголовками шифрования.
исключительный сценарий:
- FSGW генерирует ошибку в случае указания заголовков TR Engine и SSE-C , отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Загрузка файла в хранилище с поддержкой шифрования в режиме FSGW-TSE-KEY#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName} c указанием заголовков.
```
   x-amz-server-side-encryption: fsgw-tse-key
   x-amz-server-side-encryption-aws-kms-key-id: <KeyID, string> (keyID example: "test:v1")
```
2. FSGW экспортирует ключ шифрования по keyID из TR Engine.
3. FSGW применяет ключ шифрования к файлу.
4. FSGW выкладывает файл и метаданные с информацией о шифровании во все доступные кластеры ReplicaSet, в случае необходимости планирует асинхронную репликацию.
5. FSGW возвращает ответ внешней АС с заголовками шифрования.
исключительный сценарий:
- FSGW генерирует ошибку в случае указания заголовков TR Engine и SSE-C , отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Получение файла из хранилища#

FSGW поддерживает операцию GetObject с разными опциями:

проверка подписи объекта
дешифрование объекта

Для проверки подписи объекта используйте следующие заголовки:

x-amz-server-side-signature-suite: <signature-alias> # пример: key-store
x-amz-server-side-signature-object-key: <signature-object-key> # пример: key-1.txt.sign
x-amz-server-side-signature-order: <before-encryption\after-encryption> # необходим если используется шифрование объекта

Нельзя одновременно использовать заголовки проверки подписи и заголовок Range.

Способы дешифрования объекта детально описываются в следующих пунктах.

Получение файла из хранилища с поддержкой шифрования#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения GET /s3/{bucket}/{fileName} c указанием заголовков шифрования.
2. FSGW получает шифрованный файл из первого кластера ReplicaSet, который успешно ответит.
3. FSGW расшифровывает файл.
4. FSGW возвращает ответ внешней АС с телом исходного файла.
исключительный сценарий:
- При использовании алгоритмов шифрования реализующих контроль целостности - GCM и т.д. при попытке извлечь объект с некорректным ключом, для маленького размера объекта клиент не получит ответа, а соединение будет разорвано по таймауту, для большого размера объекта клиент получит статус и заголовки ответа, после чего соединение будет ожидать тело ответа, пока не будет разорвано по таймауту. В теле ответа придет некорректно расшифрованное содержимое файла.
- FSGW генерирует ошибку в случае указания неверного пароля, отсутствия Bucket или отсутствия зашифрованного файла, а также в случае отсутствия в конфигурации ReplicaSet.

Получение файла из хранилища с поддержкой шифрования в режиме FSGW-TR#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName} c указанием заголовков
```
   x-amz-server-side-encryption: fsgw-tr
   x-amz-server-side-encryption-aws-kms-key-id: <KeyID, string> (keyID example: "test")
```
2. FSGW получает шифрованный файл из первого кластера ReplicaSet, который успешно ответит.
3. FSGW дешифрует метаинформацию о шифровании с использованием KeyID из TR Engine, извлекает ключ шифрования данных дешифрует данные
4. FSGW возвращает ответ внешней АС с телом исходного файла.
исключительный сценарий:
- FSGW генерирует ошибку в случае указания заголовков TR Engine и SSE-C, отсутствия Bucket или отсутствия зашифрованного файла, а также в случае отсутствия в конфигурации ReplicaSet.

Получение файла из хранилища с поддержкой шифрования в режиме FSGW-TSE-KEY#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName} c указанием заголовков
```
   x-amz-server-side-encryption: fsgw-tse-key
   x-amz-server-side-encryption-aws-kms-key-id: <KeyID, string> (keyID example: "test:v1")
```
2. FSGW экспортирует ключ из TR по keyID
3. FSGW запрашивает данные из первого ответившего кластера replica-set
4. FSGW дешифрует данные экспортированным ключом из TR.
5. FSGW возвращает ответ внешней АС с телом исходного файла.
исключительный сценарий:
- FSGW генерирует ошибку в случае указания заголовков TR Engine и SSE-C, отсутствия Bucket или отсутствия зашифрованного файла, а также в случае отсутствия в конфигурации ReplicaSet.

Получение метаданных объекта без содержимого из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения HEAD /s3/{bucket}/{fileName}.
2. FSGW получает метаданные из первого кластера ReplicaSet, который успешно ответит.
3. FSGW возвращает ответ внешней АС с метаданными, без содержимого файла.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия Bucket, файла, а также в случае отсутствия в конфигурации ReplicaSet.

Удаление объекта, содержимого и метаданных из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения DELETE /s3/{bucket}/{fileName}.
2. FSGW удаляет файл из всех доступных кластеров ReplicaSet, в случае необходимости планирует асинхронную репликацию.
3. FSGW возвращает ответ об успешном удалении файла.

В случае если использовалась подпись файла, файл подписи необходимо удалить отдельным запросом с указанием в качестве fileName имя файла подписи.

исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Удаление списка объектов, содержимого и метаданных из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения POST /s3/{bucket}/?delete с телом:
```
<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Object>
        <Key>1</Key>
    </Object>
    ...
    <Object>
        <Key>n</Key>
    </Object>
</Delete>
```
1. FSGW удаляет файлы из всех доступных кластеров ReplicaSet, в случае необходимости планирует асинхронную репликацию.
2. FSGW возвращает ответ об успешном удалении файлов.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Копирование объекта из ReplicaSet с заменой или копированием метаданных#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName} c указание заголовков копирования.
2. FSGW копирует файл во все доступные кластеры ReplicaSet, в случае необходимости планирует асинхронную репликацию.
3. FSGW возвращает ответ об успешном копировании файла.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия исходного Bucket или целевого Bucket, исходного файла, а также в случае отсутствия в конфигурации ReplicaSet.

Создание multiPartUpload в ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения POST /s3/{bucket}/{fileName}?uploads с указанием заголовков шифрования и\или подписи
2. FSGW создает на кластере служебную информацию о начале multipartUpload загрузке в ReplicaSet
3. FSGW возвращает успешный ответ.
исключительный сценарий:
1. FSGW генерирует ошибку в случае отсутствия целевого Bucket, а также в случае отсутствия в конфигурации ReplicaSet

Загрузка части multiPartUpload в ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/{fileName}?uploadId=<value>&partNumber=<value> с указанием заголовков шифрования и\или подписи (обязательно должны соответствовать созданию multiPartUpload)
2. FSGW размешает указанный парт в ReplicaSet.
3. FSGW возвращает успешный ответ.
исключительный сценарий:
1. FSGW генерирует ошибку в случае отсутствия целевого Bucket, отсутствия информации о multipart загрузке, а также в случае отсутствия в конфигурации ReplicaSet

Завершение multiPartUpload в ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения POST /s3/{bucket}/{fileName} с указанием заголовков шифрования и\или подписи (обязательно должны соответствовать созданию multiPartUpload) c телом:
```
<CompleteMultipartUpload xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Part>
       <PartNumber>1</PartNumber>
       <ETag>dfa63ea517f64c3450269a013493d88</ETag>
   </Part>
               ....
   <Part>
       <PartNumber>n</PartNumber>
       <ETag>dfa63ea517f64c3450269adfa63ea517</ETag>
   </Part>
</CompleteMultipartUpload>
```
2. FSGW завершает multipart загрузку.
3. FSGW возвращает успешный ответ.
исключительный сценарий:
1. FSGW генерирует ошибку в случае отсутствия целевого Bucket, отсутствия информации о multipart загрузке, а также в случае отсутствия в конфигурации ReplicaSet.
2. Если была передана не вся информация о частях загрузки, либо найдены не все части на момент завершения загрузки, FSGW удаляет информацию о загрузке и генерирует ошибку с указанием причины ошибки.

Отмена multiPartUpload в ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения DELETE /s3/{bucket}/{fileName}?uploadId=<value> с указанием заголовков шифрования и\или подписи (обязательно должны соответствовать созданию multiPartUpload).
2. FSGW удаляет информацию о multipart загрузке из ReplicaSet.
3. FSGW возвращает успешный ответ.
исключительный сценарий:
1. FSGW генерирует ошибку в случае отсутствия целевого Bucket, отсутствия информации о multipart загрузке, а также в случае отсутствия в конфигурации ReplicaSet.

Создание Bucket в ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения PUT /s3/{bucket}/.
2. FSGW создаст Bucket во всех кластерах ReplicaSet, в случае необходимости планирует асинхронную репликацию.
3. FSGW возвращает ответ об успешном копировании файла.
исключительный сценарий:
- FSGW генерирует ошибку, если Bucket с таким именем уже существует, а также в случае отсутствия в конфигурации ReplicaSet.

Удаление Bucket из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на эндпоинт DELETE /s3/{bucket}/.
2. FSGW удаляет Bucket из доступных кластеров в рамках ReplicaSet, в случае необходимости планирует асинхронную репликацию.
3. FSGW возвращает успешный ответ об удалении Bucket.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия в конфигурации ReplicaSet.

Заголовок x-amz-expected-bucket-owner поддерживается только при условии, что в ReplicaSet задано не более одного кластера. В противном случае клиент получит ответ с кодом 501 и соответствующей ошибкой.

Получение списка объектов, содержащихся в рамках Bucket, из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения GET /s3/{bucket}/.
2. FSGW получает первый успешный ответ от кластера в рамках ReplicaSet.
3. FSGW возвращает успешный ответ со списком объектов в рамках Bucket.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Получение информации о bucket из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения HEAD /s3/{bucket}/.
2. FSGW получает первый успешный ответ от кластера в рамках ReplicaSet.
3. FSGW возвращает успешный ответ с информацией о bucket.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия Bucket, а также в случае отсутствия в конфигурации ReplicaSet.

Получение списка bucket из ReplicaSet#

главный сценарий:
1. Внешняя АС обращается к FSGW на точку подключения GET /s3/.
2. FSGW получает первый успешный ответ от кластеров в рамках ReplicaSet.
3. FSGW возвращает успешный ответ со списком Buckets.
исключительный сценарий:
- FSGW генерирует ошибку в случае отсутствия в конфигурации ReplicaSet