# 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
```

---

## Деплой через AI-агента

В корне репозитория есть файл [AGENTS.md](../AGENTS.md) — машиночитаемая инструкция для AI-агентов.

**Если AI-агент встроен в вашу среду** (Copilot, Cursor, Claude Dev, OpenAI Codex и др.) — он найдёт `AGENTS.md` сам, запросит у вас нужные параметры (Redis, домен, токен) и проведёт весь деплой без вашего участия.

**Если AI-агента нет** — просто откройте [AGENTS.md](../AGENTS.md), скопируйте его содержимое целиком и вставьте в любой веб-чат (ChatGPT, Claude, Gemini). AI увидит пошаговый сценарий, спросит ваши параметры и поможет всё задеплоить.

---

## Установка вручную

### 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 '{"name": "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).