Клиент обобщён, снята привязка к видеокартам

GPU это лишь один из тарифов, а клиент общего назначения. Примеры переписаны на обычные серверы, добавлен пример с масштабированием под нагрузку. Claude-Session: https://claude.ai/code/session_01Loz5stgQZH6ofBdMqTxiJu
2026-08-23 18:18:27 +09:00
@@ -2,27 +2,8 @@

 Клиент к API облака REG.RU (Рег.облако), точка входа `https://api.cloudvps.reg.ru`.

-Само API устроено как у DigitalOcean и особой сложности не представляет. Обёртка нужна
-из-за неочевидных мест, на которые мы уже наступили в бою, и которые тут обойдены.
-
-## Что тут учтено
-
-**Адрес машины лежит в поле `ip`.** Поле `networks`, которое по документации должно
-его содержать, всегда пустое. Метод `ip_of()` знает про это.
-
-**Снимок нельзя снять с остановленной машины.** API отвечает `SERVER_IS_STOPPED`.
-Останавливать её должен он сам, для этого есть параметр `offline`.
-
-**Сразу после снимка машина сидит в `locked` и удаляться отказывается**, отвечая
-`RESOURCE_DELETE_ERROR`. Отпускает примерно через полминуты. `destroy()` по умолчанию
-долбится, пока не поддастся, потому что забытая машина продолжает тикать по деньгам.
-
-**Тарифы с видеокартами метод `sizes()` не показывает вообще**, хотя создание с ними
-прекрасно работает. Их список лежит в [docs_slugs.md](docs_slugs.md), там же образы,
-регионы и правила составления slug'ов.
-
-**Тарификация идёт от часа.** Двадцать минут работы списываются как полный час,
-проверено на живой машине. Поднимать машину на короткие задачи невыгодно.
+Создание и удаление серверов, снимки, SSH-ключи, тарифы, образы, баланс и цены.
+Само API устроено как у DigitalOcean, сервер там называется reglet.

 ## Установка

@@ -30,9 +11,10 @@
 pip install git+https://git.stackworks.ru/viktor/regcloud-api.git
 ```

-Токен берётся в личном кабинете и кладётся в `REGRU_CLOUD_TOKEN`.
+Токен берётся в личном кабинете, в разделе настроек, и кладётся в `REGRU_CLOUD_TOKEN`.
+Либо передаётся в конструктор явно.

-## Как пользоваться
+## Быстрый старт

 ```python
 from regcloud_api import RegCloud
@@ -45,45 +27,92 @@ for s in api.list():
 print(api.balance())
 ```

-Поднять машину с видеокартой, снять с неё образ и удалить.
+Поднять сервер и дождаться готовности.

 ```python
-srv = api.create(size="c8-m32-d128-g1-a4000-gpu",
-                 image="ubuntu-24-04-amd64-gpu",
-                 name="worker",
-                 ssh_keys=["d7:3a:..."],
-                 region="openstack-spb1")
+srv = api.create(
+    size="c2-m4-d60-hp",             # 2 ядра, 4 ГБ, 60 ГБ, линейка «производительный»
+    image="ubuntu-24-04-amd64",
+    name="web-01",
+    region="openstack-msk1",
+    ssh_keys=["d7:3a:b4:..."],       # отпечаток ключа из api.ssh_keys()
+)

 info = api.wait_active(srv["id"])
-print("адрес", RegCloud.ip_of(info))
-
-api.snapshot(srv["id"], "worker-base", offline=True)   # машину остановит сам
-api.destroy(srv["id"])                                  # дождётся снятия locked
+print("адрес:", RegCloud.ip_of(info))
 ```

-Дальше машину можно поднимать уже из снимка, передав его номер вместо имени образа.
+Снять образ и поднять из него копию.

 ```python
-api.create(size="c8-m32-d128-g1-a4000-gpu", image=7887485, region="openstack-spb1")
+api.snapshot(srv["id"], "web-01-base", offline=True)   # сервер остановит сам
+copy = api.create(size="c2-m4-d60-hp", image=7887485, region="openstack-msk1")
 ```

-## Что умеет
+Удалить.
+
+```python
+api.destroy(srv["id"])
+```
+
+## Методы

 | Метод | Что делает |
 |---|---|
-| `list()`, `get(id)` | машины на аккаунте |
-| `create(...)` | поднять машину, из образа или из снимка |
-| `destroy(id)` | удалить, настойчиво |
-| `stop(id)`, `start(id)` | выключить и включить |
-| `action(id, type, **kw)` | любое действие из списка API |
-| `snapshot(id, name)` | снять образ |
-| `wait_active(id)`, `wait_action(id)` | дождаться готовности |
+| `list()`, `get(id)` | серверы на аккаунте |
+| `create(size, image, name, ssh_keys, region)` | создать сервер, из образа или из снимка |
+| `destroy(id)` | удалить |
+| `stop(id)`, `start(id)` | выключить, включить |
+| `action(id, type, **kw)` | любое действие: reboot, rebuild, resize, clone, restore и прочие |
+| `snapshot(id, name, offline)` | снять образ |
+| `wait_active(id)`, `wait_action(id)` | дождаться готовности сервера или завершения действия |
 | `sizes()`, `gpu_sizes()` | тарифы |
 | `images()`, `snapshots()` | образы и снимки |
 | `ssh_keys()` | ключи доступа |
 | `balance()`, `prices()` | деньги |
+| `RegCloud.ip_of(server)` | вытащить адрес из карточки сервера |

-## Полезное рядом
+## Особенности API, которые тут уже обойдены

- [docs_slugs.md](docs_slugs.md) — тарифы с картами, образы, регионы, правила slug'ов
- [openapi_v1.json](openapi_v1.json) — спецификация API, снятая с их сервера
+Это не претензии к платформе, просто места, где поведение отличается от ожидаемого.
+Собрано на живых серверах, чтобы вы на них не наступали.
+
+**Адрес сервера лежит в поле `ip`.** Поле `networks`, которое по документации должно
+его содержать, на практике всегда пустое. `ip_of()` смотрит в оба места.
+
+**Снимок снимается только с работающего сервера.** У остановленного API отвечает
+`SERVER_IS_STOPPED`. Останавливать его для снимка должна сама платформа,
+для этого есть параметр `offline`.
+
+**Сразу после снимка сервер сидит в `locked`** и на удаление отвечает
+`RESOURCE_DELETE_ERROR`. Отпускает примерно через полминуты. Поэтому `destroy()`
+по умолчанию повторяет попытки, пока не получится, и считает `NO_SUCH_REGLET`
+успехом. Забытый сервер продолжает тарифицироваться, так что молча сдаваться тут нельзя.
+
+**`sizes()` показывает не все тарифы.** Часть линеек метод не возвращает, хотя создание
+с ними работает нормально. Полный список смотрите в панели управления, в разделе
+настроек, пункт со slug'ами для API и Terraform. Наша выборка лежит в [docs_slugs.md](docs_slugs.md).
+
+**Тарификация идёт от часа.** Двадцать минут работы списываются как полный час.
+Короткие запуски невыгодны, задачи лучше копить и выполнять пачкой.
+
+## Составление slug тарифа
+
+`c<ядра>-m<память>-d<диск>-<линейка>`, например `c4-m8-d120-hp`.
+
+Линейки: `std` стандартный, `stdp` стандартный плюс, `hp` производительный,
+`hps` производительный ФЗ-152, `ddc` выделенный CPU, `high` высокочастотный.
+Допустимые сочетания ядер, памяти и диска смотрите в [docs_slugs.md](docs_slugs.md).
+
+## Регионы
+
+`openstack-msk1`, `openstack-msk2`, `openstack-msk3`, `openstack-spb1`,
+`openstack-sam1`, `openstack-fz1` и архивный `msk1`.
+
+Не все образы и тарифы доступны в каждом регионе.
+
+## Рядом
+
+- [docs_slugs.md](docs_slugs.md) — тарифы, образы, регионы, правила составления slug'ов
+- [openapi_v1.json](openapi_v1.json) — спецификация API, снятая с сервера платформы
+- [examples/](examples/) — примеры