Сетевые диски

Управление сетевыми дисками (томами) через REST API: создание, изменение размера, копирование, пауза, FTP и SFTP-доступ. Все методы требуют токен аутентификации.

POST /v1/project/:projectId/volume

Создаёт в проекте новый том с именем, типом хранилища (hdd или ssd), размером (число в байтах или строка вида 1GiB, минимум 1GiB) и режимом доступа (rwm или rwo). Том создаётся асинхронно: в ответе возвращается объект Volume со статусом creating, после завершения подготовки том переходит в статус ready. Имя должно быть уникальным в рамках проекта и состоять из латиницы в нижнем регистре, цифр, дефиса и точки.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`projectId`	Path	UUID	Да	ID проекта

Body:

Параметр	Тип	Обязательный	Описание
`name`	string	Да	Имя тома (латиница в нижнем регистре, цифры, дефис и точка; уникальное в рамках проекта)
`type`	string	Да	Тип хранилища (`hdd` или `ssd`)
`size`	string/number	Да	Размер тома (число в байтах или строка типа `1GiB`, минимум 1GiB)
`mode`	string	Да	Режим доступа (`rwm` или `rwo`)

Пример запроса:

{
    "name": "data-volume",
    "type": "ssd",
    "size": "10GiB",
    "mode": "rwm"
}

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440030",
    "name": "data-volume",
    "type": "ssd",
    "size": 10737418240,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "creating",
    "mode": "rwm",
    "paused": false,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:30:00+00:00"
}

Ошибки:

404 Not Found — Проект не найден
409 Conflict — Том с таким именем уже существует в проекте
400 Bad Request — Неверный размер или параметры тома

PUT /v1/volume/:volumeId

Обновляет параметры тома: размер и режим доступа (rwm или rwo). Размер допускается только увеличивать — уменьшение тома невозможно. После вызова том переходит в статус processing, пока изменения применяются. Операция недоступна, если том не готов или используется запущенным контейнером, а перед изменением размера нужно отключить включённые FTP или SFTP.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Body:

Параметр	Тип	Обязательный	Описание
`size`	string/number	Нет	Новый размер (только увеличение)
`mode`	string	Нет	Режим доступа (`rwm` или `rwo`)

Пример запроса:

{
    "size": "20GiB",
    "mode": "rwo"
}

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440030",
    "name": "data-volume",
    "type": "ssd",
    "size": 21474836480,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "processing",
    "mode": "rwo",
    "paused": false,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:35:00+00:00"
}

Ошибки:

404 Not Found — Том не найден
400 Bad Request — Том не готов к обновлению
400 Bad Request — Нельзя уменьшить размер тома
400 Bad Request — Том используется запущенным контейнером
400 Bad Request — Включён SFTP или FTP, нужно отключить перед изменением размера

DELETE /v1/volume/:volumeId

Удаляет том. Удаление асинхронное: в ответе возвращается объект Volume со статусом deleting, фактическое удаление выполняется после этого. Удалить можно только том, который не смонтирован в контейнере.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440030",
    "name": "data-volume",
    "type": "ssd",
    "size": 10737418240,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "deleting",
    "mode": "rwm",
    "paused": false,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:30:00+00:00"
}

Ошибки:

404 Not Found — Том не найден
400 Bad Request — Том смонтирован в контейнере

POST /v1/volume/:volumeId/copy

Создаёт копию существующего тома: содержимое и размер исходного тома переносятся в новый том, для которого в запросе задаются имя, тип хранилища (hdd или ssd) и режим доступа (rwm или rwo). Копия создаётся асинхронно и возвращается со статусом creating. Исходный том должен быть готов, имя копии не должно совпадать с именем существующего тома.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Body:

Параметр	Тип	Обязательный	Описание
`name`	string	Да	Имя нового тома (латиница в нижнем регистре, цифры, дефис и точка)
`type`	string	Да	Тип хранилища (`hdd` или `ssd`)
`mode`	string	Да	Режим доступа (`rwm` или `rwo`)

Пример запроса:

{
    "name": "data-volume-copy",
    "type": "ssd",
    "mode": "rwm"
}

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440031",
    "name": "data-volume-copy",
    "type": "ssd",
    "size": 10737418240,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "creating",
    "mode": "rwm",
    "paused": false,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:30:00+00:00"
}

Ошибки:

404 Not Found — Исходный том не найден
400 Bad Request — Исходный том не готов
409 Conflict — Том с таким именем уже существует

GET /v1/volume/:volumeId

Возвращает том по его UUID. Ответ содержит полный объект Volume: текущий статус, размер и использованный размер, метрики производительности (задержки, IOPS, пропускная способность чтения и записи), флаги и пути монтирования в контейнерах. Метод не изменяет состояние тома.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440030",
    "name": "data-volume",
    "type": "ssd",
    "size": 10737418240,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "ready",
    "mode": "rwm",
    "paused": false,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:30:00+00:00"
}

Ошибки:

404 Not Found — Том не найден

GET /v1/project/:projectId/volumes

Возвращает все тома проекта в виде массива объектов Volume. Для каждого тома доступны статус, размер, режим доступа (rwm или rwo), флаги и пути монтирования. Метод не изменяет состояние томов.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`projectId`	Path	UUID	Да	ID проекта

Ответ:

[
    {
        "id": "660e8400-e29b-41d4-a716-446655440030",
        "name": "data-volume",
        "type": "ssd",
        "size": 10737418240,
        "usedSize": 0,
        "readLatency": 0.0,
        "writeLatency": 0.0,
        "readIops": 0.0,
        "writeIops": 0.0,
        "readThroughput": 0.0,
        "writeThroughput": 0.0,
        "status": "ready",
        "mode": "rwm",
        "paused": false,
        "flags": ["sftp", "mount", "used"],
        "mountPaths": [
            {
                "containerId": "880e8400-e29b-41d4-a716-446655440003",
                "containerName": "app-container",
                "mountPath": "/data",
                "subPath": null
            }
        ],
        "createdAt": "2025-01-15T10:30:00+00:00",
        "updatedAt": "2025-01-15T10:30:00+00:00"
    }
]

Ошибки:

404 Not Found — Проект не найден

POST /v1/volume/:volumeId/ftp/enable

Включает FTP-доступ к тому. В запросе можно задать использование SSL (ssl, по умолчанию false) и идентификаторы uid/gid (по умолчанию 0); учётные данные для подключения возвращаются методом GET /v1/volume/:volumeId/ftp. Доступно только для томов с mode rwm. Том должен быть готов, а для развёртывания — активная нода.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Body:

Параметр	Тип	Обязательный	Описание
`ssl`	boolean	Нет	Использовать SSL (по умолчанию `false`)
`uid`	number	Нет	UID пользователя (по умолчанию `0`)
`gid`	number	Нет	GID группы (по умолчанию `0`)

Пример запроса:

{
    "ssl": true,
    "uid": 0,
    "gid": 0
}

Ответ:

true

Ошибки:

404 Not Found — Том не найден
400 Bad Request — Том не готов
400 Bad Request — Том должен быть в режиме rwm
400 Bad Request — Нет активной ноды для развёртывания
500 Internal Server Error — Ошибка включения FTP

POST /v1/volume/:volumeId/ftp/disable

Отключает FTP-доступ к тому. Перед изменением размера тома FTP-доступ обязательно отключается. В ответе возвращается true.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

true

Ошибки:

404 Not Found — Том не найден

GET /v1/volume/:volumeId/ftp

Возвращает FTP-конфигурацию тома: хост, порт, имя пользователя, пароль, пассивные порты, признак SSL, uid/gid и статус. Полученные данные используются для подключения FTP-клиента к тому. Том должен быть готов.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

{
    "id": "990e8400-e29b-41d4-a716-446655440032",
    "host": "abc-def-ghi.cluster.example.com",
    "port": 21,
    "user": "ftpuser",
    "password": "securepassword123",
    "passivPorts": [30000, 30001, 30002, 30003, 30004],
    "useSsl": true,
    "uid": 0,
    "gid": 0,
    "status": "ready",
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:35:00+00:00"
}

Ошибки:

404 Not Found — Том не найден
400 Bad Request — Том не готов

POST /v1/volume/:volumeId/sftp/enable

Включает SFTP-доступ к тому. В запросе можно задать идентификаторы uid/gid (по умолчанию 0); учётные данные для подключения возвращаются методом GET /v1/volume/:volumeId/sftp. Доступно только для томов с mode rwm. Том должен быть готов, а для развёртывания — активная нода.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Body:

Параметр	Тип	Обязательный	Описание
`uid`	number	Нет	UID пользователя (по умолчанию `0`)
`gid`	number	Нет	GID группы (по умолчанию `0`)

Пример запроса:

{
    "uid": 0,
    "gid": 0
}

Ответ:

true

Ошибки:

404 Not Found — Том не найден
400 Bad Request — Том не готов
400 Bad Request — Том должен быть в режиме rwm
400 Bad Request — Нет активной ноды для развёртывания
500 Internal Server Error — Ошибка включения SFTP

POST /v1/volume/:volumeId/sftp/disable

Отключает SFTP-доступ к тому. Перед изменением размера тома SFTP-доступ обязательно отключается. В ответе возвращается true.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

true

Ошибки:

404 Not Found — Том не найден

GET /v1/volume/:volumeId/sftp

Возвращает SFTP-конфигурацию тома: хост, порт, имя пользователя, пароль, uid/gid и статус. Полученные данные используются для подключения SFTP-клиента к тому. Том должен быть готов.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

{
    "id": "aa0e8400-e29b-41d4-a716-446655440033",
    "host": "xyz-abc-def.cluster.example.com",
    "port": 22,
    "user": "sftpuser",
    "password": "securepassword456",
    "status": "ready",
    "uid": 0,
    "gid": 0,
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:35:00+00:00"
}

Ошибки:

404 Not Found — Том не найден
400 Bad Request — Том не готов

POST /v1/volume/:volumeId/pause/enable

Приостанавливает том: в ответе возвращается объект Volume со статусом paused и флагом paused: true. Приостановленный том требуется для отката к снимку — откат возможен только для приостановленного тома.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440030",
    "name": "data-volume",
    "type": "ssd",
    "size": 10737418240,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "paused",
    "mode": "rwm",
    "paused": true,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:30:00+00:00"
}

Ошибки:

404 Not Found — Том не найден

POST /v1/volume/:volumeId/pause/disable

Возобновляет приостановленный том: в ответе возвращается объект Volume со статусом ready и флагом paused: false. После возобновления том возвращается в обычный режим работы.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`volumeId`	Path	UUID	Да	ID тома

Ответ:

{
    "id": "660e8400-e29b-41d4-a716-446655440030",
    "name": "data-volume",
    "type": "ssd",
    "size": 10737418240,
    "usedSize": 0,
    "readLatency": 0.0,
    "writeLatency": 0.0,
    "readIops": 0.0,
    "writeIops": 0.0,
    "readThroughput": 0.0,
    "writeThroughput": 0.0,
    "status": "ready",
    "mode": "rwm",
    "paused": false,
    "flags": ["sftp", "mount", "used"],
    "mountPaths": [
        {
            "containerId": "880e8400-e29b-41d4-a716-446655440003",
            "containerName": "app-container",
            "mountPath": "/data",
            "subPath": null
        }
    ],
    "createdAt": "2025-01-15T10:30:00+00:00",
    "updatedAt": "2025-01-15T10:30:00+00:00"
}

Ошибки:

404 Not Found — Том не найден

Сетевые диски

POST /v1/project/:projectId/volume

PUT /v1/volume/:volumeId

DELETE /v1/volume/:volumeId

POST /v1/volume/:volumeId/copy

GET /v1/volume/:volumeId

GET /v1/project/:projectId/volumes

POST /v1/volume/:volumeId/ftp/enable

POST /v1/volume/:volumeId/ftp/disable

GET /v1/volume/:volumeId/ftp

POST /v1/volume/:volumeId/sftp/enable

POST /v1/volume/:volumeId/sftp/disable

GET /v1/volume/:volumeId/sftp

POST /v1/volume/:volumeId/pause/enable

POST /v1/volume/:volumeId/pause/disable

Мы используем файлы cookies