From 58adfb19955d9d4663427223a8943c964c89d433 Mon Sep 17 00:00:00 2001
From: Georgy Moshkin <gmoshkin@picodata.io>
Date: Wed, 21 Feb 2024 16:19:39 +0300
Subject: [PATCH] topology_management.md: add stubs for governor algorithm

---
 docs/architecture/proc_api.md            | 10 +++---
 docs/architecture/topology_management.md | 42 ++++++++++++++++++++++++
 docs/overview/glossary.md                |  5 ++-
 3 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/docs/architecture/proc_api.md b/docs/architecture/proc_api.md
index 0f3367a2..b0740646 100644
--- a/docs/architecture/proc_api.md
+++ b/docs/architecture/proc_api.md
@@ -336,7 +336,7 @@ fn proc_replication(is_master, replicaset_peers) -> Lsn
 
 Этy хранимую процедуру вызывает только [governor](../overview/glossary.md#governor)
 в рамках алгоритма автоматической смены топологии кластера (подробнее он описан
-[здесь](пока-нигде-не-описан)).
+[здесь](./topology_management.md#governor)).
 
 Первоисточником принадлежности инстанса к тому или иному репликасету является
 информация в системной таблице [_pico_instance](./system_tables.md#_pico_instance),
@@ -380,7 +380,7 @@ fn proc_replication_promote(vclock, timeout)
 
 Этy хранимую процедуру вызывает только [governor](../overview/glossary.md#governor)
 в рамках алгоритма автоматической смены текущего мастера репликасета
-(подробнее он описан [здесь](пока-нигде-не-описан)).
+(подробнее он описан [здесь](./topology_management.md#governor)).
 
 Получив такой запрос инстанс дожидается пока его локальный
 [vclock](../overview/glossary.md#vclock) не догонит vclock предыдущей
@@ -407,7 +407,7 @@ fn proc_replication_demote() -> Vclock
 
 Этy хранимую процедуру вызывает только [governor](../overview/glossary.md#governor)
 в рамках алгоритма автоматической смены текущего мастера репликасета
-(подробнее он описан [здесь](пока-нигде-не-описан)).
+(подробнее он описан [здесь](./topology_management.md#governor)).
 
 Получив такой запрос инстанс сразу переходит в read-only режим и отправляет в
 ответ текущее значение своего [vclock](../overview/glossary.md#vclock), которое
@@ -441,7 +441,7 @@ fn proc_sharding(raft_term, raft_index, timeout, do_reconfigure)
 
 Этy хранимую процедуру вызывает только [governor](../overview/glossary.md#governor)
 в рамках алгоритма автоматической смены топологии кластера (подробнее он описан
-[здесь](пока-нигде-не-описан)).
+[здесь](./topology_management.md#governor)).
 
 **ОСТОРОЖНО:** детали реализации и параметры запроса с большой вероятностью
 скоро устареют.
@@ -478,7 +478,7 @@ fn proc_sharding_bootstrap(raft_term, raft_index, timeout)
 
 Этy хранимую процедуру вызывает только [governor](../overview/glossary.md#governor)
 в рамках алгоритма автоматической смены топологии кластера (подробнее он описан
-[здесь](пока-нигде-не-описан)).
+[здесь](./topology_management.md#governor)).
 
 За жизненный цикл кластера эта процедуры вызывается ровно один раз как
 только в кластере появляется первый репликасет удовлетворяющий соответствующему
diff --git a/docs/architecture/topology_management.md b/docs/architecture/topology_management.md
index 10a9e5e6..78e4c4c2 100644
--- a/docs/architecture/topology_management.md
+++ b/docs/architecture/topology_management.md
@@ -1,5 +1,6 @@
 # Управление топологией
 
+<!--------------------------------------------------------------------------—-->
 ## Общие сведения {: #intro }
 
 Топологией кластера в Picodata называется совокупность конфигураций
@@ -37,6 +38,7 @@
 Все изменения грейдов в кластере регистрируются в [журнале
 аудита](../reference/audit_events.md).
 
+<!--------------------------------------------------------------------------—-->
 ## Сценарии управления топологией {: #scenarios }
 
 ### Добавление инстанса в кластер {: #joining }
@@ -94,3 +96,43 @@
 
 Дальнейшие действия по выводу инстанса из эксплуатации выполняет
 `governor`.
+
+
+<!--------------------------------------------------------------------------—-->
+## Governor - централизованное управление кластером {: #governor }
+
+Большинство механизмов связанных с отказоустойчивостью в Picodata так или иначе
+связаны с компонентом governor. С технической точки зрения governor -- это
+поток управления (fiber) всегда выполняющийся на [raft-лидере](../overview/glossary.md#raft_leader).
+Дальше перечислены ответственности губернатора.
+
+
+### Автоматическое переключение узлов голосующих в raft {: #governor_raft_failover }
+
+Governor следит за выполнение ограничений описанных [здесь](./raft_failover.md#raft_voter_failover).
+
+
+### Автоматическое назначение мастеров репликасетов {: #replicaset_master_switchover }
+
+Work in progress
+
+
+### Автоматическое назначение весов шардирования {: #replicaset_weight_change }
+
+Work in progress
+
+
+### Первичное распределение бакетов {: #governor_vshard_bootstrap }
+
+Work in progress
+
+
+### Автоматическое изменение конфигурации vshard {: #governor_vshard_cfg }
+
+Work in progress
+
+
+### Применение изменений кластерной схемы данных {: #governor_schema_change }
+
+Governor гарантирует отказоустойчивость изменений кластерной схемы данных.
+Подробнее алгоритм описан [здесь](./clusterwide_schema.md#two_phase_algorithm).
diff --git a/docs/overview/glossary.md b/docs/overview/glossary.md
index bb9574bd..75cea7f8 100644
--- a/docs/overview/glossary.md
+++ b/docs/overview/glossary.md
@@ -226,7 +226,10 @@ Vclock репликасет-лидера играет важную роль в 
 
 ### Губернатор (governor) {: #governor }
 
-**Governor (губернатор)** — внутренняя централизованная сущность, управляющая конфигурациями и жизненными циклами инстансов в соответствие с изменениями их грейдов. "Губернатор" выполняется на лидере raft-группы.
+**Governor (губернатор)** — алгоритм автоматического централизованного управления конфигурациями инстансов
+(подробнее [здесь](../architecture/topology_management.md#governor)).
+С точки зрения реализации governor это поток управления (fiber) всегда выполняющийся на [raft-лидере](#raft_leader).
+Governor управляет жизненными циклами инстансов реагируя на изменения их [грейдов](#grade).
 
 ### Крейт (crate) {: #crate }
 
-- 
GitLab