Словарь

Термины в том значении, в котором их использует система и эта документация. Одно значение на термин.

Выполнение

Пайплайн — единица автоматизации в graphene: программа на языке общего назначения, собранная с SDK. Описывает и процесс, и нужные ему ресурсы — объявляет их, выполняет действия на машинах и владеет тем, что создала. Один пайплайн — одно имя и один бинарь.

Ран (run) — одно выполнение пайплайна и владелец по умолчанию всего, что оно создало. Восстановим: после падения продолжается с места остановки. Идентификатор называет ровно один ран: повторный старт присоединяется к существующему.

Роль — то, чем занят конкретный экземпляр бинаря пайплайна: run — ведёт ран, machine — выполняет действия на машине агента. Код одинаковый; роль назначает окружение запуска.

Managed / inplace — два способа дать рану исполнителя. Managed: сервер сам запускает контейнер из указанного образа и сам убирает его после завершения. Inplace: пользователь запускает бинарь сам, где угодно; сервер только стартует процесс рана.

Действие (activity) — функция, адресованная агенту и выполняемая на его машине; может быть адресована и набору агентов сразу. Упавшее действие повторяется, успешно завершённое — не выполняется повторно.

Записывающий проход (recording pass) — однократное выполнение функции пайплайна перед стартом рана: ничего не исполняется, объявления действий и ресурсов регистрируются, чтения возвращают оптимистичные нули. Благодаря ему объявления живут прямо в коде, без отдельной регистрации; цена — код обязан переживать проход с нулевыми данными.

Записи

Ресурс — всё, что имеет durable-запись и владельца: агент, артефакт, объект Kubernetes, любой тип из ресурсной библиотеки. Создаётся объявлением в пайплайне; без записи ресурс создать нельзя.

Запись (entity) — реализация ресурса: живой durable-процесс, который хранит spec и state, исполняет команды по очереди и периодически сверяет реальность с желаемым состоянием. На один ресурс — ровно одна запись: повторное объявление присоединяется к существующей.

Spec / State — две половины записи. Spec — желаемая конфигурация, задаётся объявлением. State — наблюдаемое состояние, пишется только самой записью по ходу её жизни.

Фаза — положение записи в жизненном цикле: creating, ready, deleting, deleted, create_failed, delete_failed. ready означает, что ресурс сошёлся к желаемому состоянию и его выходы доступны.

Хэндл (handle) — то, что возвращает объявление ресурса: немедленно и не блокируя. Выходы ресурса доступны только через Ready: первое чтение ждёт готовности, ошибка готовности валит ран в этой точке. Неготовый ресурс невозможно использовать по построению.

Присоединённый ресурс (attached) — хэндл ЧУЖОГО ресурса: распознан, не создан. Читается как любой хэндл, но не может быть родителем или ребёнком в дереве владения: чужое нельзя ни обременить, ни отдать.

Ресурсная библиотека — обычный модуль поверх SDK, приносящий свои типы ресурсов: объекты Kubernetes, docker, что угодно. Библиотечный ресурс — полноправный: та же запись, то же владение, те же метки.

Владение

Владелец — тот, вместе с кем ресурс умирает: другой ресурс, ран или стенд. Ровно один; по умолчанию — создавший ран. Владелец — часть записи ресурса и виден в любой момент.

Дерево владения — граф, который образуют владельцы. Задаётся при объявлении (Parent, Children), меняется передачей. Владение отдают — его не забирают.

Каскадное удаление — удаление владельца удаляет всё его поддерево, глубже — раньше: виртуальная машина прежде подсети, подсеть прежде сети.

Передача (transfer) — смена владельца ресурса вместе с его поддеревом: другому ресурсу или стенду, опционально — со сроком жизни у нового владельца. Единственный способ для ресурса пережить свой ран.

Стенд (stand) — постоянный владелец, который есть у каждого пайплайна. Ресурсы, переданные стенду, переживают свой ран — так живёт долгосрочная инфраструктура пайплайна между запусками.

Срок жизни (TTL) — граница пребывания ресурса у нового владельца, заданная при передаче. По истечении сервер удаляет поддерево сам. Без срока ресурс живёт до явного удаления.

Машины

Агент — процесс на машине пользователя и одновременно ресурс — запись, связывающая реальную машину с этим процессом. Подключается к серверу только исходящим соединением — машина не открывает портов. Объявление агента не создаёт машину: запись ждёт подключения агента (или ставит его по SSH, если задано).

Факты машины — то, что агент сообщил о реальной машине: адреса, ОС, ресурсы. Хранятся отдельно от записи; запись держит только ссылку.

Возможность (capability) — одно умение машины, записанное на её запись публикатором: установщиком, человеком, образом. Никогда не «обнаруживается». Имеет имя, метки, информативную версию и признак готовности. Принадлежит машине: ран установщика может умереть, docker остаётся установленным.

Требование (need) — требование возможности у агента: имя плюс ограничения на метки (равенство и «одно из»). Версии никогда не сравниваются. Готовность агента ждёт выполнения всех требований — отказ приходит до отправки работы, а не после её падения.

Данные

Артефакт — ресурс, байты которого лежат в хранилище блобов, а запись хранит digest. Загружается из рана; чужой артефакт можно присоединить.

Блоб — байты, адресованные содержимым: ключ — хеш. Digest считает сервер при загрузке — клиент не может его подделать.

Секрет — именованное значение на сервере, заведённое администратором. В спеках, логах и истории ходит только имя; значение получает исполняющий код в момент использования и обратно не возвращает.

Выборка

Метка (label) — пара ключ=значение на любой записи и на ране. Семантика меток метрик: выборка и группировка, никогда не данные. Задаётся при объявлении, меняется командой записи.

Системная метка — метка с зарезервированным префиксом graphene.io/; пишется только системой. graphene.io/run — ран, создавший запись (стабильна при передачах, в отличие от владельца).

Селектор — тип + фаза + владелец + метки; каждое заданное поле должно совпасть.

Control plane

Сервер — control plane graphene и единственная точка входа: один порт, через который ходят агенты, процессы ранов, браузер и CLI. Внутренняя инфраструктура (durable-ядро, реестр образов, хранилище блобов) снаружи не видна и не адресуема; TLS терминирует прокси перед сервером.

Namespace — единица изоляции. Токен привязан к одному namespace или ко всем (администраторы). Записи, раны и секреты разных namespace не видят друг друга.

Токен — единственный вид credentials. Три роли: admin, run, agent; токен агента дополнительно привязан к одному агенту. Каждый токен привязан к namespace (админский — ко всем).