cloudru-dbaas

CLI для Managed ClickHouse, Redis и Kafka в cloud.ru поверх Public API, плюс скиллы для агентов, которые учат им пользоваться.

• cloudru-dbaas — все три продукта: cloudru-dbaas clickhouse|redis|kafka …, плюс то, что нужно кластеру вокруг: zones list, network subnets|vpcs (подсети и VPC) и iam service-accounts|access-keys|roles (сервисные аккаунты, ключи доступа, роли в проекте).

cloudru-dbaas redis clusters list
cloudru-dbaas kafka clusters get <CLUSTER_ID> --json
cloudru-dbaas clickhouse users create <CLUSTER_ID> app --password-stdin --role cloud_admin < app.pass

Установка

Одной строкой, без root (в ~/.local/bin, сверка sha256 по checksums.txt):

curl -fsSL https://raw.githubusercontent.com/cloud-ru/evo-dbaas-cli-sdk/main/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/cloud-ru/evo-dbaas-cli-sdk/main/install.sh | sh -s -- --version v0.1.0

Или бинарник со страницы релизов: cloudru-dbaas_<os>_<arch> (linux, darwin, windows; amd64, arm64), сверка — checksums.txt.

Или из исходников (Go — версия из go.mod):

go install github.com/cloud-ru/evo-dbaas-cli-sdk/cmd/cloudru-dbaas@latest

Доступ

Нужен ключ доступа сервисного аккаунта (или персональный) с ролью на нужный продукт в проекте, например dbaas.clickhouse.admin.

export CLOUDRU_KEY_ID=…
export CLOUDRU_KEY_SECRET=…
export CLOUDRU_PROJECT_ID=…      # или флаг --project
cloudru-dbaas clickhouse auth check

CLI сам обменивает ключ на токен IAM и кеширует токен в пользовательском каталоге кеша (cloudru-dbaas/, права 0600). Пароли пользователей кластеров передаются только через stdin (--password-stdin) или переменную окружения (--password-env) — флага с самим паролем нет.

Переменная	Зачем
CLOUDRU_KEY_ID, CLOUDRU_KEY_SECRET	ключ доступа
CLOUDRU_PROJECT_ID	проект по умолчанию
CLOUDRU_CLICKHOUSE_API_URL	другой адрес Public API ClickHouse (по умолчанию https://clickhouse.api.cloud.ru)
CLOUDRU_IAM_AUTH_URL	другой адрес выдачи токена IAM
CLOUDRU_IAM_API_URL, CLOUDRU_VPC_API_URL, CLOUDRU_COMPUTE_API_URL	другие адреса API IAM, VPC и виртуальных машин

Адрес http:// не на localhost CLI отвергает: ключ и токен ушли бы без TLS. Стенд без TLS — CLOUDRU_ALLOW_HTTP=1, тогда только предупреждение.

Файл конфига и профили

То же можно держать в файле ~/.config/cloudru-dbaas/config.yaml (или $XDG_CONFIG_HOME/cloudru-dbaas/config.yaml; другой путь — --config или CLOUDRU_CONFIG). Ключи: key_id, key_secret, project_id, clickhouse_url, redis_url, kafka_url, compute_url, vpc_url, iam_url, iam_auth_url, allow_http.

profile: stand            # профиль по умолчанию; без строки — default
profiles:
  default:
    key_id: …
    project_id: …
  stand:
    key_id: …
    key_secret: …
    clickhouse_url: http://10.0.0.5:8080
    allow_http: true

Профиль выбирают --profile > CLOUDRU_PROFILE > profile: в файле > default. Значение берётся по порядку: флаг > переменная окружения > профиль > встроенное. Незаданное в профиле — встроенное, не из default; пустое значение ("" или ключ без значения) — как незаданное. Неизвестный ключ или неверный тип — ошибка с путём файла: опечатка не уведёт молча на адрес по умолчанию. Файл с key_secret держите с правами 0600, иначе CLI предупредит. help и дополнение по Tab файл не читают.

Что возьмёт команда и откуда — config list: каждый ключ со значением и источником (flag, env CLOUDRU_…, file <профиль>, default; нигде не задан — none), key_secret маской. Одно значение — config get <ключ>. Обе работают без ключа доступа и понимают --profile, --config, --project, --json. Флаг продукта --api-url config list не видит: адрес из него команда возьмёт, а список покажет env, файл или умолчание.

cloudru-dbaas config list --profile stand
cloudru-dbaas config get clickhouse_url

Править файл можно и из CLI. config set <ключ> <значение> пишет в профиль из --profile (иначе в текущий) и создаёт профиль, файл и каталог, если их нет: каталог с правами 0700, файл 0600. Запись идёт через временный файл; комментарии остаются, отступы и пустые строки выравниваются. Файл с якорями YAML или несколькими документами CLI не правит. Значение - читается из stdin, так key_secret не попадёт в историю команд. Если ключ задан переменной окружения, она по-прежнему сильнее файла, и CLI об этом предупредит. config use-profile <имя> меняет строку profile:. Кривой файл CLI не перезаписывает, а показывает ошибку.

cloudru-dbaas config set clickhouse_url http://10.0.0.5:8080 --profile stand
printf '%s\n' "$SECRET" | cloudru-dbaas config set key_secret - --profile stand
cloudru-dbaas config use-profile stand

Отдельный ключ для агента можно выпустить из CLI ключом с правом управлять сервисными аккаунтами проекта:

cloudru-dbaas iam service-accounts create --name agent-clickhouse
cloudru-dbaas iam roles grant --subject <SA_ID> --role dbaas.clickhouse.admin
cloudru-dbaas iam access-keys create <SA_ID> --env-file agent.env   # секрет — только в файл 0600

Для агентов

• --json у любой команды — ответ API как есть, одной строкой.
• Долгие операции (создание, resize, удаление) возвращают операцию; --wait ждёт её завершения, предел — --timeout.
• Коды выхода: 0 успех, 1 ошибка (и операция в облаке упала), 2 отмена (Ctrl-C), 4 ключ или доступ, 8 --wait не дождался — операция могла продолжиться, ресурс не пересоздавать.
• --body '<JSON>' у create и resize кластеров — поле API, для которого ещё нет флага.
• Скиллы в формате agentskills.io — в skills/: cloudru-managed-clickhouse, cloudru-managed-redis, cloudru-managed-kafka и cloudru-access-setup (сервисный аккаунт, роли и свой ключ агента с нуля, без консоли). Скопируйте каталог целиком, вместе с references/, туда, где ваш агент ищет скиллы (например, .claude/skills/). В SKILL.md — основной сценарий, в references/ — установка, ключ и роли, коды выхода и долгие операции: агент читает их, когда дошёл до шага.

Разработка

go test ./...                 # в том числе сверка CLI со спецификацией OpenAPI
scripts/generate.sh --fetch   # свежие спецификации с cloud.ru/docs и перегенерация клиентов

• Клиенты API сгенерированы oapi-codegen из api/openapi-*.yaml (опубликованы в документации cloud.ru); команды написаны руками в internal/cmd/.
• TestAPICoverage проверяет, что каждая операция, поле и значение enum из спецификации доступны из CLI; TestSkillCommandsParse — что каждая команда из скиллов существует. Подробнее — docs/api-coverage.md.
• tests/e2e/ — сетка e2e на Ginkgo: настоящий бинарник против фейкового облака, каждая команда; ожидаемое — в tests/e2e/testdata/golden/. Гоняется в go test ./....
• Живой уровень той же сетки — tests/e2e/live_test.go за тегом e2e: создаёт, смотрит и удаляет платный кластер каждого продукта в настоящем cloud.ru. Переменные и команда запуска — в начале файла; перед релизом. Прогон — до двух часов.
• scripts/stand-check.sh ходит в живой API, слой 2 создаёт платные кластеры и проверяет пользователей, топики и resize, которых нет в живом уровне. Описание — в начале скрипта.
• Как вносить изменения — CONTRIBUTING.md, стиль — CODESTYLE.md, планка качества — CONSTRAINTS.md.
• Релиз — тег vX.Y.Z, бинарники собирает GoReleaser (.github/workflows/release.yml).

---

Лицензия

MIT, см. LICENSE.

English

cloudru-dbaas is a command-line client for cloud.ru Managed ClickHouse, Redis and Kafka, built on the public API, plus agent skills (agentskills.io format) in skills/. Help texts and skills are in Russian.

Install a binary from Releases or go install github.com/cloud-ru/evo-dbaas-cli-sdk/cmd/cloudru-dbaas@latest. Set CLOUDRU_KEY_ID, CLOUDRU_KEY_SECRET and CLOUDRU_PROJECT_ID, then run cloudru-dbaas clickhouse auth check. The same keys can live in ~/.config/cloudru-dbaas/config.yaml under named profiles (--profile, CLOUDRU_PROFILE); flags win over env, env over the file; config list shows each value with its source (except the per-product --api-url flag). config set <key> <value> and config use-profile <name> edit the file (0600, comments kept; value - reads stdin). Add --json to any command for machine-readable output. Run go test ./... before sending changes.

Licensed under MIT, see LICENSE.