doc: add multitenant architecture summary (2026-05-15)
Единый сводный документ, описывающий полную архитектуру мультитенантного Fission. Заменяет необходимость читать 50+ пошаговых thinking-файлов. Содержит: - Причина и концепция решения - Архитектурная карта изменений (ASCII diagram) - Таблица ключевых файлов с ролями - Инженерные решения: Snapshot API, NamespaceManager event bus, EnsureNamespaceSA, buildermgr dedup bug, router nil guard - RBAC: что и почему (включая нетривиальные events:create и LSAR) - Backward compatibility guarantees - Описание test scenario (Layer 1, PASS=5) - Порядок деплоя нового форка - Направления дальнейшей работы
This commit is contained in:
“Naeel”
@@ -0,0 +1,231 @@
|
||||
# Мультитенантный Fission: сводная архитектура и инженерная логика
|
||||
|
||||
> Дата: 2026-05-15
|
||||
> Контекст: форк Fission v1.22.0, ветка `feature/multitenant`
|
||||
> Статус: реализовано, тесты зелёные
|
||||
|
||||
---
|
||||
|
||||
## Зачем это было нужно
|
||||
|
||||
Стандартный Fission требует, чтобы все namespace-ы, в которых живут функции,
|
||||
были перечислены в переменной окружения `FISSION_RESOURCE_NAMESPACES` **до старта**
|
||||
процессов. Добавление нового namespace = rolling restart всех компонентов (executor,
|
||||
router, buildermgr). На сотнях тенантов — постоянный restart loop, каскадные сбои.
|
||||
|
||||
Наша задача: добавить новый tenant (namespace) без какого-либо рестарта.
|
||||
|
||||
---
|
||||
|
||||
## Концепция решения
|
||||
|
||||
Единственный public contract для внешних систем — label на Namespace:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: tenant-abc123
|
||||
labels:
|
||||
fission.io/managed: "true"
|
||||
```
|
||||
|
||||
Никакого другого coupling с Fission internals не требуется.
|
||||
|
||||
После появления namespace с этим label Fission автоматически:
|
||||
1. Регистрирует namespace во всех компонентах (executor, router, buildermgr)
|
||||
2. Создаёт SA `fission-fetcher` и необходимый RBAC в namespace
|
||||
3. Подключает informer factory для CRD (Functions, Environments, HTTPTriggers и т.д.)
|
||||
4. Тенант может деплоить функции без задержки
|
||||
|
||||
---
|
||||
|
||||
## Архитектурная карта изменений
|
||||
|
||||
```
|
||||
Kubernetes Namespace API
|
||||
│
|
||||
│ watch: label fission.io/managed=true
|
||||
▼
|
||||
utils.RunManagedNamespaceWatcher(...)
|
||||
│
|
||||
│ (shared utility, один и тот же вызов из трёх компонентов)
|
||||
▼
|
||||
utils.NamespaceManager (interface)
|
||||
│
|
||||
├─ Bootstrap(envNamespaces) ← уже существующие NS при старте
|
||||
├─ DispatchAdd(ns) ← новый NS от watcher
|
||||
└─ DispatchRemove(ns) ← NS удалён (track-only)
|
||||
│
|
||||
▼
|
||||
NamespaceSubscriber.OnNamespaceAdd(...)
|
||||
│
|
||||
┌───────────┼───────────┐
|
||||
▼ ▼ ▼
|
||||
executor router buildermgr
|
||||
│ │ │
|
||||
registerNS AddNS(ts) envw+pkgw
|
||||
│ .AddNamespace
|
||||
├─ DefaultNSResolver().AddNamespace(ns) ← thread-safe, dedup
|
||||
├─ EnsureNamespaceSA(ctx, client, log, ns) ← SA + RBAC provisioning
|
||||
└─ et.AddNamespace(ns, mgr) ← для каждого executor type
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ключевые файлы
|
||||
|
||||
| Файл | Роль |
|
||||
|------|------|
|
||||
| `pkg/utils/namespace.go` | `NamespaceResolver` — хранит список NS, thread-safe Snapshot/AddNamespace |
|
||||
| `pkg/utils/namespace_manager.go` | `NamespaceManager` — lifecycle, subscribers, event dispatch |
|
||||
| `pkg/utils/namespace_manager_model.go` | Типы: Record, Phase, Event, Source, Summary |
|
||||
| `pkg/utils/serviceaccount.go` | `EnsureNamespaceSA` — создаёт fission-fetcher SA/Role/RoleBinding |
|
||||
| `pkg/executor/multitenant/ns_watcher.go` | Executor NSWatcher + `registerNamespace` |
|
||||
| `pkg/executor/multitenant/namespace_subscriber.go` | Executor subscriber adapter |
|
||||
| `pkg/router/ns_watcher.go` | Router NSWatcher (1 строка, через shared utility) |
|
||||
| `pkg/router/namespace_subscriber.go` | Router subscriber adapter |
|
||||
| `pkg/buildermgr/ns_watcher.go` | BuilderMgr NSWatcher (1 строка, через shared utility) |
|
||||
| `pkg/buildermgr/namespace_subscriber.go` | BuilderMgr subscriber adapter |
|
||||
| `deploy/multitenant/rbac.yaml` | ClusterRole/ClusterRoleBinding для всех трёх компонентов |
|
||||
|
||||
---
|
||||
|
||||
## Инженерные решения и почему именно так
|
||||
|
||||
### 1. Snapshot API вместо прямого чтения map
|
||||
|
||||
**Проблема:** `NamespaceResolver.FissionResourceNS` — mutable map, защищённая mutex
|
||||
только на запись. Читатели в разных горутинах обращались к ней напрямую — data race.
|
||||
|
||||
**Решение:** `Snapshot() []string` — под read lock копирует map в sorted slice.
|
||||
Потребители итерируют по стабильной копии, безопасно даже при конкурентных `AddNamespace`.
|
||||
|
||||
**Почему slice а не map:** потребителям нужен обход, а не lookup. Sorted slice даёт
|
||||
детерминированный порядок — важно для тестов и для startup factory generation.
|
||||
|
||||
### 2. NamespaceManager как event bus
|
||||
|
||||
**Проблема:** каждый компонент реализовывал свой namespace watcher с нуля —
|
||||
дублирование кода watcher setup, event handlers, deduplication, logging.
|
||||
|
||||
**Решение:** единый `utils.NamespaceManager` + `NamespaceSubscriber` interface.
|
||||
Компонент реализует только `OnNamespaceAdd/Remove/Resync`, всё остальное — shared utility.
|
||||
|
||||
Это сократило `router/ns_watcher.go` до **5 строк**, `buildermgr/ns_watcher.go` до **5 строк**.
|
||||
|
||||
### 3. EnsureNamespaceSA — одно место, один вызов
|
||||
|
||||
**Проблема:** при динамической регистрации нового NS executor пытался создать pool pod,
|
||||
но SA `fission-fetcher` ещё не существовал → `FailedCreate`, pod не стартует.
|
||||
|
||||
**Решение:** в `registerNamespace` (executor) вызывается `utils.EnsureNamespaceSA`
|
||||
**до** вызова `et.AddNamespace`. SA всегда существует к моменту создания первого pod.
|
||||
|
||||
**Важно:** `EnsureNamespaceSA` — идемпотентная. Повторный вызов = safe no-op.
|
||||
|
||||
### 4. Buildermgr dedup bug
|
||||
|
||||
**Проблема:** `buildermgr.StartNSWatcher` при добавлении NS вызывал `envw.AddNamespace`
|
||||
и `pkgw.AddNamespace`. Но глобальный `DefaultNSResolver().AddNamespace()` вызывался
|
||||
внутри каждого watcher — dedup срабатывал после первого и блокировал второй.
|
||||
|
||||
**Решение:** `buildermgr/namespace_subscriber.go` вызывает `DefaultNSResolver().AddNamespace()`
|
||||
один раз в `registerBuilderNamespace`, а затем оба watcher добавляют NS независимо.
|
||||
|
||||
### 5. Router informer maps — guard против nil panic
|
||||
|
||||
**Проблема:** в `router/httpTriggers.go` `AddNamespace` мог вызываться до инициализации
|
||||
внутренних informer maps → nil pointer dereference.
|
||||
|
||||
**Решение:** добавлена explicit проверка nil перед операцией, с логом предупреждения.
|
||||
|
||||
---
|
||||
|
||||
## RBAC — что и почему
|
||||
|
||||
`deploy/multitenant/rbac.yaml` содержит три ClusterRole:
|
||||
|
||||
### fission-executor-ns-watcher
|
||||
```
|
||||
namespaces: list, watch
|
||||
```
|
||||
Нужен executor для регистрации Namespace informer. Без этого NSWatcher не стартует.
|
||||
|
||||
### fission-router-ns-watcher
|
||||
```
|
||||
namespaces: list, watch
|
||||
```
|
||||
То же для router.
|
||||
|
||||
### fission-executor-sa-provisioner
|
||||
```
|
||||
serviceaccounts: get, list, watch, create, update, patch
|
||||
roles: get, list, watch, create, update, patch
|
||||
rolebindings: get, list, watch, create, update, patch
|
||||
events: create
|
||||
authorization.k8s.io/localsubjectaccessreviews: create
|
||||
```
|
||||
|
||||
Нетривиальные пункты:
|
||||
|
||||
- **events:create** — Kubernetes запрещает создавать `Role`, выдающую право,
|
||||
которого нет у создающего субъекта. `fission-fetcher` получает `events:create`,
|
||||
значит executor тоже должен его иметь.
|
||||
|
||||
- **localsubjectaccessreviews:create** — `setupSAAndRoleBindings` проверяет
|
||||
существующие права через LSAR перед созданием Role. Без этого — 403.
|
||||
|
||||
---
|
||||
|
||||
## Что НЕ изменилось (backward compatibility)
|
||||
|
||||
- `FISSION_RESOURCE_NAMESPACES` env var работает как раньше — namespace-ы из него
|
||||
регистрируются при старте через `Bootstrap()`.
|
||||
- Существующие tenant namespace-ы, добавленные через env var, не нуждаются в label.
|
||||
- Поведение функций, HTTP-триггеров, builder — неизменно.
|
||||
- Helm chart стандартный; RBAC применяется отдельно: `kubectl apply -f deploy/multitenant/rbac.yaml`.
|
||||
|
||||
---
|
||||
|
||||
## Тест-сценарий (Layer 1)
|
||||
|
||||
Проверяет сквозной сценарий без рестарта:
|
||||
|
||||
1. Создать namespace `l1-test-XXXXX`
|
||||
2. Добавить label `fission.io/managed=true`
|
||||
3. Подождать, пока executor зарегистрирует NS (лог `registered namespace`)
|
||||
4. Создать Environment + Function + HTTPTrigger в namespace
|
||||
5. Вызвать функцию через router — ожидаемый ответ `200 OK`
|
||||
|
||||
Все шаги (PASS=5 FAIL=0) проходят стабильно после полного RBAC fix.
|
||||
|
||||
---
|
||||
|
||||
## Порядок деплоя нового форка
|
||||
|
||||
```bash
|
||||
# 1. Применить RBAC (один раз на кластер)
|
||||
kubectl apply -f deploy/multitenant/rbac.yaml
|
||||
|
||||
# 2. Деплоить fission-bundle с нашим образом
|
||||
# (helm upgrade или kubectl apply с новым image tag)
|
||||
|
||||
# 3. Создать tenant
|
||||
kubectl create namespace tenant-abc123
|
||||
kubectl label namespace tenant-abc123 fission.io/managed=true
|
||||
|
||||
# 4. Готово. Можно деплоить функции в tenant-abc123.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Направления дальнейшей работы
|
||||
|
||||
1. **e2e тесты** — автоматизированный `test_layer1.sh`-подобный тест в Go
|
||||
2. **Helm chart** — включить `deploy/multitenant/rbac.yaml` как условный template
|
||||
3. **Мониторинг** — expose namespace lifecycle events в metrics (Prometheus)
|
||||
4. **Remove lifecycle** — сейчас при удалении NS стратегия `track-only`;
|
||||
нужен `dispatch-remove` + cleanup informers
|
||||
5. **Feature branch portability** — при выходе Fission 1.23 сделать rebase
|
||||
этой ветки поверх нового upstream тега
|
||||
Reference in New Issue
Block a user