# regcloud-api

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

Создание и удаление серверов, снимки, SSH-ключи, тарифы, образы, баланс и цены.
Само API устроено как у DigitalOcean, сервер там называется reglet.

## Установка

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

Снять образ и поднять из него копию.

```python
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(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, которые тут уже обойдены

Это не претензии к платформе, просто места, где поведение отличается от ожидаемого.
Собрано на живых серверах, чтобы вы на них не наступали.

**Адрес сервера лежит в поле `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/) — примеры