docs: add deploy/README.md with full self-hosted installation guide

2026-04-13 07:09:50 +03:00
parent d9950ad4d4
commit cc5b78f8ee
2 changed files with 155 additions and 0 deletions
@@ -0,0 +1,151 @@
+# shared-sqs — Self-hosted Helm Chart
+
+Этот Helm-чарт разворачивает [shared-sqs](https://gitea.services.ngcloud.ru/Nail/shared-SQS) — AWS SQS-совместимый сервис очередей — в вашем Kubernetes-кластере.
+
+После деплоя клиенты подключаются через стандартный AWS SDK / CLI, меняя только `endpoint_url` на ваш домен.
+
+---
+
+## Что потребуется заранее
+
+| Компонент | Зачем | Примечание |
+|-----------|-------|------------|
+| Kubernetes кластер | Платформа | Любой вариант: k3s, EKS, GKE, bare-metal |
+| **Redis ≥ 6** | Хранит все очереди и сообщения | Внешний или задеплоенный в кластер |
+| **Ingress NGINX** | Принимает внешние HTTP/HTTPS запросы | `helm install ingress-nginx ingress-nginx/ingress-nginx` |
+| **cert-manager** | Автоматически выпускает TLS-сертификат | `helm install cert-manager jetstack/cert-manager --set installCRDs=true` |
+| **DNS-запись** | Связывает ваш домен с кластером | A-запись домена → External IP вашего ingress-контроллера |
+| PostgreSQL *(опционально)* | Биллинг — учёт операций | Если не нужен — `billing.enabled: false` |
+
+Узнать External IP ingress-контроллера:
+```bash
+kubectl get svc -n ingress-nginx ingress-nginx-controller
+# Смотрите колонку EXTERNAL-IP
+```
+
+---
+
+## Установка
+
+### 1. Клонируйте репозиторий
+
+```bash
+git clone https://gitea.services.ngcloud.ru/Nail/shared-SQS.git
+cd shared-SQS
+```
+
+### 2. Отредактируйте `deploy/values.yaml`
+
+Обязательно заполните:
+
+```yaml
+redis:
+  addr: "ваш-redis-хост:6379"
+  password: "ваш-redis-пароль"
+
+admin:
+  token: "придумайте-любой-токен"   # например: openssl rand -hex 20
+
+ingress:
+  host: "sqs.ваш-домен.com"
+```
+
+Если PostgreSQL не нужен — оставьте `billing.enabled: false`.
+
+### 3. Задеплойте
+
+```bash
+helm install shared-sqs ./deploy -n shared-sqs --create-namespace
+```
+
+### 4. Проверьте что всё поднялось
+
+```bash
+# Под должен быть Running и Ready
+kubectl get pods -n shared-sqs
+
+# Сервис должен ответить OK
+curl https://sqs.ваш-домен.com/health
+```
+
+---
+
+## Параметры values.yaml
+
+| Параметр | Описание | Пример |
+|----------|----------|--------|
+| `namespace` | Kubernetes namespace | `shared-sqs` |
+| `image.tag` | Версия образа | `v0.1.24` |
+| `redis.addr` | Адрес Redis в формате `host:port` | `redis.default.svc:6379` |
+| `redis.user` | Redis-пользователь (обычно `default`) | `default` |
+| `redis.password` | Пароль Redis | — |
+| `admin.token` | Токен для Admin API (`/admin/*`) | любая строка |
+| `seedDemo` | Создать demo-тенанта при старте | `true` / `false` |
+| `resources` | CPU и Memory лимиты пода | см. defaults |
+| `ingress.enabled` | Включить Ingress | `true` |
+| `ingress.className` | Ingress класс | `nginx` |
+| `ingress.host` | Домен сервиса | `sqs.example.com` |
+| `ingress.annotations` | Аннотации (cert-manager, timeouts) | см. defaults |
+| `ingress.tls.enabled` | Включить TLS через cert-manager | `true` |
+| `ingress.tls.secretName` | Имя Secret для TLS-сертификата | `shared-sqs-tls` |
+| `billing.enabled` | Включить запись статистики в PostgreSQL | `false` |
+| `billing.postgres.*` | Параметры подключения к PostgreSQL | — |
+
+---
+
+## Admin API — создание тенантов
+
+После деплоя сервис готов принимать SQS-запросы, но для этого нужен тенант с credentials.
+
+### Создать тенанта
+
+```bash
+curl -s -X POST https://sqs.ваш-домен.com/admin/tenants \
+  -H "Authorization: Bearer ВАШ_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "my-tenant"}'
+```
+
+Ответ:
+```json
+{
+  "id": "my-tenant",
+  "access_key": "SSAK-...",
+  "secret_key": "..."
+}
+```
+
+> **Сохраните `secret_key`** — он показывается только один раз.
+
+### Использовать credentials в AWS CLI
+
+```bash
+export AWS_ACCESS_KEY_ID="SSAK-..."
+export AWS_SECRET_ACCESS_KEY="..."
+export AWS_DEFAULT_REGION="us-east-1"
+ENDPOINT="--endpoint-url https://sqs.ваш-домен.com"
+
+aws sqs create-queue --queue-name my-queue $ENDPOINT
+aws sqs send-message --queue-url "..." --message-body "Hello" $ENDPOINT
+```
+
+---
+
+## Обновление
+
+```bash
+helm upgrade shared-sqs ./deploy -n shared-sqs
+```
+
+## Удаление
+
+```bash
+helm uninstall shared-sqs -n shared-sqs
+kubectl delete namespace shared-sqs
+```
+
+---
+
+## Полная документация
+
+Использование сервиса (AWS CLI, boto3, Node.js) — в [основном README](../README.md).