# regcloud-api

Клиент к 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'ов.

**Тарификация идёт от часа.** Двадцать минут работы списываются как полный час,
проверено на живой машине. Поднимать машину на короткие задачи невыгодно.

## Установка

```bash
pip install git+https://git.stackworks.ru/viktor/regcloud-api.git
```

Токен берётся в личном кабинете и кладётся в `REGRU_CLOUD_TOKEN`.

## Как пользоваться

```python
from regcloud_api import RegCloud

api = RegCloud()

for s in api.list():
    print(s["id"], s["name"], s["status"], RegCloud.ip_of(s))

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")

info = api.wait_active(srv["id"])
print("адрес", RegCloud.ip_of(info))

api.snapshot(srv["id"], "worker-base", offline=True)   # машину остановит сам
api.destroy(srv["id"])                                  # дождётся снятия locked
```

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

```python
api.create(size="c8-m32-d128-g1-a4000-gpu", image=7887485, region="openstack-spb1")
```

## Что умеет

| Метод | Что делает |
|---|---|
| `list()`, `get(id)` | машины на аккаунте |
| `create(...)` | поднять машину, из образа или из снимка |
| `destroy(id)` | удалить, настойчиво |
| `stop(id)`, `start(id)` | выключить и включить |
| `action(id, type, **kw)` | любое действие из списка API |
| `snapshot(id, name)` | снять образ |
| `wait_active(id)`, `wait_action(id)` | дождаться готовности |
| `sizes()`, `gpu_sizes()` | тарифы |
| `images()`, `snapshots()` | образы и снимки |
| `ssh_keys()` | ключи доступа |
| `balance()`, `prices()` | деньги |

## Полезное рядом

- [docs_slugs.md](docs_slugs.md) — тарифы с картами, образы, регионы, правила slug'ов
- [openapi_v1.json](openapi_v1.json) — спецификация API, снятая с их сервера