add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,79 @@
+# S3 Bucket Notifications: изменения в бакете и вызов функции
+
+## Короткий ответ
+
+Да, для S3-совместимого хранилища можно вызывать обработчик при изменениях в бакете через стандартный механизм уведомлений:
+
+- событие в бакете (`ObjectCreated`, `ObjectRemoved`),
+- правило уведомления на бакете,
+- destination (webhook/queue/topic),
+- consumer/функция, которая принимает событие.
+
+## Что проверено в нашем контуре
+
+Проверка выполнялась удалённо (через SSH), не локально.
+
+- API `deck-api-test.ngcloud.ru`:
+  - есть общий endpoint `/notifications`,
+  - явных endpoint'ов вида `bucketNotifications`, `events`, `webhooks` в этом API не обнаружено.
+- Документация `docs.s3.msk-1.ngcloud.ru`:
+  - в публичных страницах не найден явный раздел про bucket notifications.
+- Прямая проверка S3-слоя:
+  - `mc event ls <alias>/<bucket>` отработал успешно (код возврата `0`),
+  - это подтверждает доступность стандартной S3 операции чтения notification-конфигурации;
+  - пустой вывод означает, что правила ещё не заданы.
+
+## Нужно ли задавать это при создании бакета
+
+Рекомендуется задавать сразу в том же Terraform apply, но это отдельная конфигурация относительно самого факта создания бакета.
+
+Практически правильно так:
+
+1. Создать (или использовать) `S3 Storage service`.
+2. Создать бакет.
+3. Создать destination для событий (webhook/queue/topic).
+4. Назначить notification rule на бакет.
+5. Поднять consumer/функцию, которая обрабатывает событие.
+
+## Как это выглядит архитектурно
+
+```text
+Bucket (ObjectCreated/ObjectRemoved)
+  -> Bucket Notification Rule
+    -> Destination (Webhook / Queue / Topic)
+      -> Function/Worker (business logic)
+```
+
+## Что это значит для Terraform
+
+Лучший путь: один модуль/стек, где декларативно описано сразу всё:
+
+- bucket,
+- destination,
+- notification rule,
+- function/consumer.
+
+Это даёт предсказуемый результат: после `apply` события бакета уже маршрутизируются в обработчик.
+
+## Если notifications недоступны в конкретном backend
+
+Fallback — polling:
+
+- периодический опрос бакета,
+- сравнение состояния (`key + etag/version_id + mtime`),
+- вызов функции только на diff.
+
+## Проверка и настройка через CLI
+
+Пример скрипта в репозитории:
+
+- `scripts/s3_notification_example.sh`
+
+Скрипт:
+
+- читает `.s3cfg`,
+- показывает текущие правила,
+- добавляет правило,
+- показывает итоговую конфигурацию.
+
+> Важно: для `event add` нужен существующий destination (`TARGET_ARN`) в S3/MinIO-конфигурации.