Add useful develop docs for humans and AIs

gmelikov · gmelikov · commit 0a4adc1b56b6 · 2026-07-01T17:11:10.000Z
diff --git a/AGENTS.md b/AGENTS.md
@@ -179,6 +179,11 @@ All source files must include Apache 2.0 license header:
 
 ### Documentation
 
+- Before working on element/manifest/reconciliation internals, read
+  `docs/core-developer-guide/index.md` (element/resource model, `ElementEngine`,
+  reconciliation loop, manifest value rendering).
+- Before debugging a stuck element, node, or config delivery, read
+  `docs/usage/troubleshooting.md`.
 - Update `docs/` for CLI changes
 - Run `tox -e cli_docs` to regenerate CLI docs
 - Run `make mdlint` for Markdown linting
@@ -188,5 +193,6 @@ All source files must include Apache 2.0 license header:
 
 - **Source**: `exordos_core/`
 - **Tests**: `exordos_core/tests/`
-- **Documentation**: `docs/`
+- **Documentation**: `docs/` — see `docs/core-developer-guide/index.md` (architecture)
+  and `docs/usage/troubleshooting.md` (debugging) first
 - **Build output**: `output/`
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/docs/core-developer-guide/index.md b/docs/core-developer-guide/index.md
@@ -0,0 +1,81 @@
+---
+title: Core Developer Guide
+---
+
+This guide describes the internal architecture of Exordos Core: how elements, manifests, and resources are
+stored and reconciled onto compute nodes. It's aimed at people working on Exordos Core itself. If you want
+to build an element on top of the platform instead, see the
+[Application Developer Guide](../app-developer-guide/index.md).
+
+## Elements, manifests, and resources
+
+Installing an element (`exordos em elements install <manifest.yaml>`) creates a handful of related
+records, all defined in `exordos_core/elements/dm/models.py`:
+
+| Model | Table | Purpose |
+|---|---|---|
+| `Manifest` | `em_manifests` | The parsed YAML manifest (resources, imports, exports, requirements) |
+| `Element` | `em_elements` | The installed element (name, version, status) |
+| `Resource` | `em_resources` | A single declared resource inside an element |
+| `Import` | `em_imports` | Which resource of which element is imported |
+| `Export` | `em_exports` | A resource published for other elements to import |
+
+## The element engine
+
+`ElementEngine` is an in-memory registry of every installed element and its resources, loaded from the
+database via `load_from_database()`. Each element is a `Namespace`, and resources inside it are addressed
+by their link string (for example `$my_element.compute.nodes.$my_node`). The registry is reloaded whenever
+a manifest is installed, upgraded, or uninstalled, and lazily on the reconciliation loop's first iteration.
+
+## Reconciliation: from declared resource to running node
+
+Reconciliation is driven by `ElementManagerBuilder` (`elements/services/builders.py`), a service loop that
+ticks roughly every 3 seconds:
+
+1. Iterate every resource known to the element engine.
+2. Render the resource's `value` into a `target_state`, resolving `$link` references and `f"..."`
+   interpolations (see [Manifest value rendering](#manifest-value-rendering)).
+3. Create or update a `TargetResource` row (table `ua_target_resources`, from `gcl_sdk`) — this is the
+   contract with the node-side agent.
+4. A Universal Agent running on the target compute node watches `ua_target_resources` for records of its
+   own `kind`, applies them to the real system (systemd unit, VM, disk, config file, and so on), and
+   writes back an `actual_resource`.
+5. `ElementManagerBuilder` compares the hash of `actual_resource` against `target_state` and updates
+   `Resource.status` accordingly.
+6. An element's overall status is derived from the status of all its resources.
+
+## Status lifecycle
+
+`Element` and `Resource` share a `Status` enum with three values: `NEW → IN_PROGRESS → ACTIVE`. There is no
+`ERROR` state at this level — a resource that can't converge simply stays `IN_PROGRESS`.
+
+Some resource kinds track a richer lifecycle of their own. `Service` (table `em_services`) and `Config`
+(table `config_configs`) both add an `ERROR` status alongside `NEW`/`IN_PROGRESS`/`ACTIVE`, since those
+subsystems can detect and report a failed apply.
+
+## Manifest value rendering
+
+`_render_value` (`elements/dm/models.py`) turns a manifest string into a concrete value:
+
+- A string starting with `$` is resolved as a resource link.
+- A string starting with `f"` is treated as an inline template: `{$element.type.$name:field}`
+  placeholders inside it are substituted.
+- Any other string is returned unchanged.
+
+A manifest author who forgets the `f"` prefix does not get a silently empty value — the literal `{$...}`
+text is left in the rendered output, wherever that value ends up (a config file, a service command line,
+and so on). See [Troubleshooting](../usage/troubleshooting.md) for the symptoms this produces.
+
+## Core resource types
+
+- `$core.compute.nodes` / `$core.compute.sets` — virtual machines and node groups (KVM/QEMU)
+- `$core.em.services` — systemd services on a node or node set
+- `$core.vs.variables` — the Variable Store, used for platform-wide defaults
+- `$core.config.configs` — files delivered to a node; requires `project_id` and `body.kind`, see
+  [Troubleshooting](../usage/troubleshooting.md)
+
+## See also
+
+- [Manifest reference](../em/manifest.md)
+- [Service as a Service API](../em/service.md)
+- [Troubleshooting](../usage/troubleshooting.md)
diff --git a/docs/core-developer-guide/index.ru.md b/docs/core-developer-guide/index.ru.md
@@ -0,0 +1,82 @@
+---
+title: Руководство для разработчиков ядра
+---
+
+Это руководство описывает внутреннюю архитектуру Exordos Core: как элементы, манифесты и ресурсы
+хранятся и приводятся в соответствие (reconcile) на вычислительных нодах. Оно предназначено для тех, кто
+работает над самим Exordos Core. Если вы хотите разработать элемент поверх платформы, см.
+[Руководство для разработчиков приложений](../app-developer-guide/index.ru.md).
+
+## Элементы, манифесты и ресурсы
+
+Установка элемента (`exordos em elements install <manifest.yaml>`) создаёт набор связанных записей,
+описанных в `exordos_core/elements/dm/models.py`:
+
+| Модель | Таблица | Назначение |
+|---|---|---|
+| `Manifest` | `em_manifests` | Разобранный YAML-манифест (resources, imports, exports, requirements) |
+| `Element` | `em_elements` | Установленный элемент (имя, версия, статус) |
+| `Resource` | `em_resources` | Отдельный задекларированный ресурс внутри элемента |
+| `Import` | `em_imports` | Какой ресурс какого элемента импортирован |
+| `Export` | `em_exports` | Ресурс, опубликованный для импорта другими элементами |
+
+## Element engine
+
+`ElementEngine` — реестр в памяти со всеми установленными элементами и их ресурсами, загружаемый из базы
+данных через `load_from_database()`. Каждый элемент представлен как `Namespace`, а ресурсы внутри него
+адресуются по строке-ссылке (например, `$my_element.compute.nodes.$my_node`). Реестр перезагружается при
+установке, обновлении или удалении манифеста, а также лениво — на первой итерации цикла reconciliation.
+
+## Reconciliation: от задекларированного ресурса до работающей ноды
+
+Reconciliation выполняет `ElementManagerBuilder` (`elements/services/builders.py`) — сервисный цикл,
+тикающий примерно раз в 3 секунды:
+
+1. Перебрать все ресурсы, известные element engine.
+2. Отрендерить `value` ресурса в `target_state`, разрешив ссылки `$link` и интерполяции `f"..."` (см.
+   [Рендеринг значений манифеста](#рендеринг-значений-манифеста)).
+3. Создать или обновить запись `TargetResource` (таблица `ua_target_resources` из `gcl_sdk`) — это
+   контракт с агентом на стороне ноды.
+4. Universal Agent, работающий на целевой вычислительной ноде, следит за `ua_target_resources` на предмет
+   записей своего `kind`, применяет их к реальной системе (systemd-юнит, VM, диск, конфигурационный файл
+   и т.д.) и записывает обратно `actual_resource`.
+5. `ElementManagerBuilder` сравнивает хэш `actual_resource` с `target_state` и обновляет
+   `Resource.status` соответственно.
+6. Итоговый статус элемента выводится из статусов всех его ресурсов.
+
+## Жизненный цикл статусов
+
+`Element` и `Resource` используют общий enum `Status` с тремя значениями: `NEW → IN_PROGRESS → ACTIVE`.
+На этом уровне нет статуса `ERROR` — ресурс, который не может сойтись, просто остаётся в `IN_PROGRESS`.
+
+У некоторых типов ресурсов есть собственный, более богатый жизненный цикл. `Service` (таблица
+`em_services`) и `Config` (таблица `config_configs`) добавляют статус `ERROR` к `NEW`/`IN_PROGRESS`/
+`ACTIVE`, поскольку эти подсистемы способны обнаружить и сообщить о неудачном применении.
+
+## Рендеринг значений манифеста
+
+`_render_value` (`elements/dm/models.py`) превращает строку из манифеста в конкретное значение:
+
+- Строка, начинающаяся с `$`, разрешается как ссылка на ресурс.
+- Строка, начинающаяся с `f"`, трактуется как inline-шаблон: плейсхолдеры `{$element.type.$name:field}`
+  внутри неё подставляются.
+- Любая другая строка возвращается без изменений.
+
+Автор манифеста, забывший префикс `f"`, не получает молча пустое значение — буквальный текст `{$...}`
+остаётся в результирующем выводе, где бы это значение ни оказалось (в конфигурационном файле, в командной
+строке сервиса и т.д.). См. [Диагностику проблем](../usage/troubleshooting.ru.md) — там описаны симптомы,
+к которым это приводит.
+
+## Основные типы ресурсов ядра
+
+- `$core.compute.nodes` / `$core.compute.sets` — виртуальные машины и группы нод (KVM/QEMU)
+- `$core.em.services` — systemd-сервисы на ноде или группе нод
+- `$core.vs.variables` — Variable Store, используется для платформенных значений по умолчанию
+- `$core.config.configs` — файлы, доставляемые на ноду; требует `project_id` и `body.kind`, см.
+  [Диагностику проблем](../usage/troubleshooting.ru.md)
+
+## См. также
+
+- [Справочник по манифесту](../em/manifest.ru.md)
+- [Service as a Service API](../em/service.md)
+- [Диагностика проблем](../usage/troubleshooting.ru.md)
diff --git a/docs/usage/local_deployment.md b/docs/usage/local_deployment.md
@@ -107,18 +107,19 @@ ssh ubuntu@10.20.0.2
 Use the admin credentials to obtain an access token from the IAM service:
 
 ```bash
-curl --location 'http://10.20.0.2:11010/v1/iam/clients/00000000-0000-0000-0000-000000000000/actions/get_token/invoke' \
+curl --location 'http://10.20.0.2:80/api/core/v1/iam/clients/default/actions/get_token/invoke' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'username=<ADMIN_USERNAME>' \
     --data-urlencode 'password=<ADMIN_PASSWORD>' \
-    --data-urlencode 'client_id=ExordosCoreClientId' \
-    --data-urlencode 'client_secret=ExordosCoreSecret' \
     --data-urlencode 'scope=' \
     --data-urlencode 'ttl=86400'
 ```
 
-The response contains an `access_token` field. Use this token as a `Bearer` token in all subsequent API requests.
+The `clients/default` path is rewritten by Core's load balancer (port 80) to the real IAM client and has
+`X-Client-Id`/`X-Client-Secret` injected automatically, so no client credentials need to be passed here —
+see the equivalent setup in `exordos_ecosystem/web/README.md`. The response contains an `access_token`
+field. Use this token as a `Bearer` token in all subsequent API requests.
 
 ### CLI access
 
diff --git a/docs/usage/local_deployment.ru.md b/docs/usage/local_deployment.ru.md
@@ -107,18 +107,19 @@ ssh ubuntu@10.20.0.2
 Используйте учётные данные администратора для получения токена доступа от сервиса IAM:
 
 ```bash
-curl --location 'http://10.20.0.2:11010/v1/iam/clients/00000000-0000-0000-0000-000000000000/actions/get_token/invoke' \
+curl --location 'http://10.20.0.2:80/api/core/v1/iam/clients/default/actions/get_token/invoke' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'username=<ADMIN_USERNAME>' \
     --data-urlencode 'password=<ADMIN_PASSWORD>' \
-    --data-urlencode 'client_id=ExordosCoreClientId' \
-    --data-urlencode 'client_secret=ExordosCoreSecret' \
     --data-urlencode 'scope=' \
     --data-urlencode 'ttl=86400'
 ```
 
-В ответе содержится поле `access_token`. Используйте этот токен как `Bearer`-токен во всех последующих запросах к API.
+Путь `clients/default` переписывается балансировщиком Core (порт 80) на реальный IAM-клиент, а
+`X-Client-Id`/`X-Client-Secret` подставляются автоматически — учётные данные клиента передавать не нужно,
+см. аналогичную настройку в `exordos_ecosystem/web/README.md`. В ответе содержится поле `access_token`.
+Используйте этот токен как `Bearer`-токен во всех последующих запросах к API.
 
 ### Доступ через CLI
 
diff --git a/docs/usage/troubleshooting.md b/docs/usage/troubleshooting.md
@@ -0,0 +1,101 @@
+---
+title: Troubleshooting
+---
+
+This page collects common issues when developing and deploying elements on Exordos Core, and how to diagnose them.
+
+## A resource is stuck in `IN_PROGRESS`
+
+An element's resources go through the lifecycle `NEW → IN_PROGRESS → ACTIVE`. If a resource stays in
+`IN_PROGRESS`, the platform has not been able to reconcile the declared state with reality yet.
+
+Check the resource state:
+
+```bash
+exordos em resources list
+exordos em resources show <uuid>
+```
+
+If the resource never leaves `IN_PROGRESS`, the compute node it targets may never have come up. Check the
+node and hypervisor status:
+
+```bash
+exordos compute nodes list
+exordos compute hypervisors list
+```
+
+See [Local Deployment](local_deployment.md) for hypervisor setup requirements.
+
+## `$core.config.configs` fails instead of rendering
+
+Both `project_id` and `body.kind` are required fields on a `Config` resource — neither has a default.
+Omitting `body.kind` (for example `text`) makes the manifest fail with an `UnknownType: Unknown kind for
+value: ...` error instead of producing an empty or partial file.
+
+```yaml
+$core.config.configs:
+  my_config:
+    project_id: "12345678-c625-4fee-81d5-f691897b8142"
+    path: /etc/my_element_init.txt
+    target:
+      kind: node
+      node: $core.compute.nodes.$my_node:uuid
+    body:
+      kind: text # required, no default
+      content: |
+        ...
+```
+
+## Values inside a config body are not substituted
+
+Manifest string values are only interpolated in two cases:
+
+- A value starting with `$` is treated as a full resource link, for example
+  `"$core.vs.variables.$default_cores:value"`.
+- A value starting with `f"` is treated as an inline template, where `{$element.type.$name:field}`
+  placeholders are substituted inside a larger string.
+
+Any other string — including a multi-line `content:` block — is passed through verbatim. If you forget the
+`f"` prefix, the `{$...}` placeholders are **not** silently dropped: they stay in the rendered output as
+literal text. If a delivered file ends up containing `{$core.secret.passwords.$my_password:value}` instead
+of an actual password, this is almost always a missing `f"` prefix.
+
+```yaml
+body:
+  kind: text
+  content: |
+    f"MY_PASS={$core.secret.passwords.$my_password:value}"
+```
+
+## Bootstrap script reads an empty config file
+
+Content delivered through `$core.config.configs` is written to the target node as a plain file write: the
+file is created (truncated) first, and the content is written afterwards — this is not an atomic
+operation. A bootstrap script that starts before the content has arrived reads an empty file.
+
+Always wait for the file to be **non-empty**, not just for it to exist:
+
+```bash
+while [ ! -s /etc/my_element_init.txt ]; do
+    echo "Waiting for config..."
+    sleep 2
+done
+source /etc/my_element_init.txt
+```
+
+If a script already checks `-s` and still reads an empty file, compare the content stored in the database
+with what is on disk:
+
+```bash
+psql exordos_core -c "SELECT body FROM config_configs WHERE path = '/etc/my_element_init.txt';"
+ssh ubuntu@<node-ip> "sudo cat /etc/my_element_init.txt"
+```
+
+If the database value is empty, the manifest itself has a rendering problem — see the previous section. If
+the database has content but the file on disk doesn't, the node hasn't received it yet — wait, or re-run
+the bootstrap script manually once it has.
+
+## See also
+
+- [Manifest reference](../em/manifest.md)
+- [Core Developer Guide](../core-developer-guide/index.md)
diff --git a/docs/usage/troubleshooting.ru.md b/docs/usage/troubleshooting.ru.md
diff --git a/mkdocs.yml b/mkdocs.yml
