k8s-mechanic: автоматическое устранение сбоев в Kubernetes

29 сентября 2026 г.

#ai#gitops#opencode#operators#remediation#self-healing

Примечание о переименовании: Ранее проект назывался k8s-mendabot. Он переименован в k8s-mechanic. Группа API для CRD изменилась с remediation.mendabot.io на remediation.mechanic.io. Существующие установки потребуют миграции.

k8s-mechanic — это Kubernetes-контроллер, который следит за сбоями в кластере, автоматически их расследует и открывает pull request’ы в вашем GitOps-репозитории с предложенными исправлениями — всё это без выхода за пределы кластера.

Когда Pod уходит в цикл перезапусков (crash-loop), Deployment деградирует или Node переходит в состояние NotReady, mechanic запускает агента OpenCode прямо внутри кластера. Агент инспектирует живой кластер, находит нужные манифесты в GitOps-репозитории, определяет первопричину и открывает PR. Вы проверяете и мёрджите. Никаких внешних операторов, внешних баз данных, никаких постоянных сервисов за пределами кластера.

Что делает mechanic

  1. Обнаруживает сбои — нативно следит за Pods, Deployments, StatefulSets, PVC, Nodes и Jobs через Kubernetes API

  2. Дедублирует по родительскому объекту — повторяющиеся перезапуски подов из одного Deployment порождают одно расследование, а не по одному на каждый перезапуск

  3. Выжидает перед действием — настраиваемое окно стабилизации (по умолчанию: 120 с) отфильтровывает кратковременные сбои до начала расследования

  4. Расследует внутри кластера — агентный Job запускается с доступом только на чтение (read-only RBAC), клонирует GitOps-репозиторий и инспектирует живой кластер

  5. Открывает PR — со структурированным описанием: краткое изложение, доказательства, первопричина, предлагаемое исправление и уровень уверенности

Три возможных результата на каждый вызов:

Результат Когда Действие

PR с исправлением

Первопричина установлена, уверенность средняя или высокая

Открывает PR с точечным изменением манифеста

PR с расследованием

Первопричина неясна или уверенность низкая

Открывает PR с отчётом о расследовании, помеченный needs-human-review

Комментарий

Для этого отпечатка (fingerprint) уже есть открытый PR

Добавляет комментарий с обновлёнными выводами; новый PR не открывается

Жёсткие ограничения, заложенные в промпт агента: никогда не коммитить напрямую в main; никогда не трогать Kubernetes Secrets в GitOps-репозитории; ровно один результат на один вызов.

Возможности

Агентный рабочий процесс OpenCode — расследования управляются OpenCode, работающим внутри кластера. Поддерживается любой LLM-эндпоинт, совместимый с OpenAI API. Поддержка дополнительных агентных бэкендов запланирована.

Обнаружение сбоев — нативно отслеживает Pods, Deployments, StatefulSets, PVC, Nodes и Jobs. Покрывает CrashLoopBackOff, ImagePullBackOff, OOMKilled, деградировавшие Deployments, непланируемые поды, упавшие Jobs, ошибки провизионирования PVC и неработоспособные Nodes.

Дедупликация — события дедублируются по отпечатку родительского ресурса (sha256(namespace + kind + parentObject + sorted errors)). Повторяющиеся перезапуски подов из одного Deployment порождают одно расследование. Состояние хранится в объектах CRD RemediationJob — переживает перезапуски вотчера, внешнее хранилище не требуется.

Уровни критичности — каждое событие классифицируется как critical, high, medium или low на основе обнаруженного состояния (например: CrashLoopBackOff более 5 перезапусков → critical; OOMKilled → high; деградированный, но доступный Deployment → medium). Переменная окружения MIN_SEVERITY на Deployment вотчера подавляет события ниже заданного порога. Агент получает уровень критичности во время выполнения и соответствующим образом регулирует глубину расследования — максимальная тщательность для critical, консервативные минимальные изменения для low.

Окно стабилизации — настраиваемый период выдержки (по умолчанию: 120 с) подавляет кратковременные сбои до отправки расследования.

Ограничение параллелизма — maxConcurrentJobs (по умолчанию: 3) ограничивает число одновременно выполняемых агентных Jobs. Избыточные события встают в очередь в статусе Pending и отправляются по мере освобождения слотов.

Настраиваемый промпт агента — промпт расследования монтируется из ConfigMap и может быть полностью переопределён через prompt.coreOverride / prompt.agentOverride в values.yaml.

Метрики Prometheus — опциональный Service с метриками и ServiceMonitor для Prometheus Operator для наблюдаемости за здоровьем вотчера.

Автоматическое закрытие разрешённых событий — когда событие в Kubernetes устраняется (Deployment восстанавливается, PVC провизионируется, Node возвращается в Ready), вотчер автоматически закрывает открытый агентом GitHub PR. Работает как для активных задач (Pending/Dispatched/Running), так и для уже завершившихся, чей PR устарел после самовосстановления кластера. Использует токен установки GitHub App напрямую через REST API — CLI gh в вотчере не требуется. Отключить можно через watcher.prAutoClose: false.

Дедупликация с учётом слияния PR — когда открытый mechanic’ом PR мёрджится, RemediationJob получает статус «захоронен» с коротким TTL (1 час) вместо стандартного 7-дневного. Это предотвращает повторное расследование того же события сразу после слияния, пока GitOps-reconciler применяет исправление и кластер стабилизируется.

Режим сухого прогона (dry-run) — установите watcher.dryRun: true, чтобы запустить полный пайплайн расследования без открытия PR. Агент создаёт отчёт о расследовании, который записывается в ConfigMap с именем mechanic-dryrun-<fingerprint>. Полезно для проверки поведения mechanic в staging или валидации новой LLM-модели перед включением в production.

Защита от истечения токена GitHub App — основной контейнер агента проверяет срок действия installation token перед началом работы. Если токен истёк или истекает в течение 60 секунд, задача сразу завершается с понятной ошибкой, а не тихо падает глубоко в процессе расследования.

Обязательная валидация манифестов — перед фиксацией любых изменений в GitOps-репозитории агент запускает kubeconform (и kustomize build для overlay-изменений) для каждого изменённого манифеста. Если валидация не проходит, агент открывает PR-заглушку с меткой validation-failed и полным выводом ошибки вместо того, чтобы коммитить невалидный манифест.

Безопасность

Редактирование секретов — текст ошибок, извлечённый из состояния кластера (поле Waiting.Message пода, сообщения о состоянии ноды и т. д.), прогоняется через фильтр редактирования перед сохранением в RemediationJob или передачей агенту. Паттерны включают учётные данные в URL, base64-значения длиной ≥ 40 символов и распространённые префиксы ключей секретов (password=, token=, api-key= и т. д.).

Обнаружение prompt-инъекций — поле Finding.Errors ограничено 500 символами на запись и обёрнуто в явный конверт недоверенных данных в промпте. Эвристики инъекций (ignore.*previous.*instructions) обнаруживаются и логируются; можно настроить полное подавление события (INJECTION_DETECTION_ACTION=suppress).

Сетевая политика агента — опциональный NetworkPolicy ограничивает исходящий трафик агентного Job’а только до API-сервера кластера, GitHub и LLM-эндпоинта. Включается через networkPolicy.enabled: true в values.yaml. Требует CNI с поддержкой NetworkPolicy (Cilium, Calico и т. д.).

RBAC агента только на чтение — агент имеет только права get/list/watch на уровне кластера. Создавать, изменять или удалять ресурсы Kubernetes он не может. Все изменения кластера проходят через Git и ваш GitOps-reconciler.

RBAC агента в рамках namespace — AGENT_RBAC_SCOPE=namespace переключает агента с кластерного ClusterRole на Role с областью видимости в рамках namespace, ограничивая читаемые агентом данные только указанными namespace’ами.

Структурированный журнал аудита — все решения о подавлении и отправке генерируют структурированные строки лога с audit: true, доступные для запроса из любой системы агрегации логов (Loki, Elasticsearch, Datadog) для расследования инцидентов.

Сканирование CVE с помощью Trivy — образы mechanic-watcher и mechanic-agent сканируются при каждом релизе с помощью Trivy (уровни CRITICAL и HIGH, без учёта неисправленных уязвимостей). Сборка завершается неудачей при обнаружении любой исправимой уязвимости. Неустранимые CVE в сторонних предсобранных бинарниках (инструменты, ещё не выпущенные с нужной версией Go) отслеживаются в .trivyignore с обязательными датами истечения для повторной оценки.

Краткосрочные GitHub-учётные данные — агент никогда не хранит долгоживущий PAT. Installation token GitHub App (TTL 1 час) обменивается в init-контейнере и никогда не передаётся в основной контейнер агента.

Усиленный режим (hardened mode)

Усиленный режим (agent.hardenKubectl: true в values.yaml, по умолчанию выключен) добавляет дополнительные ограничения на чтение поверх всегда активных настроек, описанных ниже.

Всегда активны (независимо от усиленного режима)

Контроль Что делает

Блокировка write-команд kubectl

apply, create, delete, edit, patch, replace, scale, label, annotate, taint, drain, cordon, uncordon, rollout restart/undo — все завершаются с кодом 1. Все изменения кластера проходят через Git и ваш GitOps-reconciler.

Редактирование вывода kubectl

Весь вывод kubectl пропускается через бинарник redact. Любое значение, совпадающее с известным паттерном секрета (base64 ≥ 40 символов, password=…, token=… и т. д.), заменяется на [REDACTED]. Обёртка завершается с ошибкой, если redact отсутствует.

Редактирование вывода инструментов

helm, flux, sops, talosctl, yq, stern, kubeconform, kustomize, age, age-keygen и gh — у всех есть обёртки-теневые копии в PATH, пропускающие вывод через redact. Обёртки закрываются при ошибке — если бинарник redact отсутствует, инструмент завершается с кодом 1.

Отсутствие секретов в переменных окружения

В окружении процесса агента нет учётных данных или ключей API. Все секретные материалы записываются в файлы до запуска агента и полностью исключаются из окружения.

Только в усиленном режиме

Контроль Что добавляет

Блокировка секретов в kubectl

get secret(s), describe secret(s) и get all блокируются. Kubernetes Secrets никогда не попадают в контекст LLM через kubectl.

Блокировка kubectl exec / port-forward

exec и port-forward блокируются. Агент не может открывать интерактивные сессии или пробрасывать порты к рабочим нагрузкам кластера.

Тестирование на утечки данных

Средства контроля безопасности проверяются в регулярных red-team-прогонах. Результаты и полный реестр утечек при exfiltration-тестировании находятся в docs/SECURITY/EXFIL_LEAK_REGISTRY.md.

Быстрый старт

Предварительные требования

  • Kubernetes >= 1.28

  • Helm >= 3.14

  • GitHub App, установленное в вашем GitOps-репозитории с правами: Contents (write), Pull Requests (write), Issues (write)

  • API-ключ LLM, совместимого с OpenAI API

Права GitHub App

Право Уровень Назначение

Contents

Write

Клонирование репозитория, создание веток, публикация изменений

Pull requests

Write

Создание pull request’ов и комментариев к ним

Issues

Write

Ссылки на issues в описаниях PR

1. Создайте необходимые Secrets

kubectl create namespace mechanic

github-app

Secret github-app должен содержать три ключа:

apiVersion: v1
kind: Secret
metadata:
  name: github-app
  namespace: mechanic
stringData:
  app-id: "<App ID>"             # числовой ID со страницы https://github.com/settings/apps/<your-app-name>
  installation-id: "12345678"   # числовой ID из URL установки (см. ниже)
  private-key: |
    <содержимое .pem-файла, скачанного из настроек GitHub App>

App ID отображается на странице настроек вашего GitHub App по адресу https://github.com/settings/apps/<your-app-name>;. Каждый пользователь создаёт свой собственный GitHub App; автор проекта не имеет доступа к вашим учётным данным, токенам или репозиторию.

Installation ID — числовой суффикс в URL при просмотре установки приложения: https://github.com/organizations/<org>/settings/installations/<id>; (для личных аккаунтов: https://github.com/settings/installations/<id>;). Его также возвращает запрос GET https://api.github.com/app/installations, аутентифицированный JWT приложения.

Приватный ключ используется только в init-контейнере агентного Job’а для обмена на краткосрочный installation token (TTL 1 час). В основной контейнер агента он никогда не передаётся.

llm-credentials-opencode

Secret llm-credentials-opencode хранит полную конфигурацию OpenCode в ключе provider-config. В правильной схеме model — это ключ верхнего уровня (формат: "<provider-id>/<model-id>"); options находится внутри provider.<name>, а не в корне.

На данный момент единственным доступным агентным провайдером является OpenCode; поддержка дополнительных вариантов будет добавлена позже.

Нативный OpenAI (api.openai.com)

apiVersion: v1
kind: Secret
metadata:
  name: llm-credentials-opencode
  namespace: mechanic
stringData:
  provider-config: |
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "openai": {
          "apiKey": "sk-<your-openai-api-key>"
        }
      },
      "model": "openai/gpt-4o"
    }

Произвольный эндпоинт, совместимый с OpenAI (self-hosted, Ollama, Azure и т. д.)

Для любого эндпоинта, отличного от api.openai.com, или с именем модели, не зарегистрированным во встроенном провайдере OpenAI, необходимо определить кастомный провайдер с "npm": "@ai-sdk/openai-compatible". Встроенный провайдер openai нельзя переиспользовать для другого базового URL.

apiVersion: v1
kind: Secret
metadata:
  name: llm-credentials-opencode
  namespace: mechanic
stringData:
  provider-config: |
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "myprovider": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "My Provider",
          "options": {
            "baseURL": "https://my-llm-endpoint/v1",
            "apiKey": "sk-<your-api-key>"
          },
          "models": {
            "my-model-id": {
              "name": "My Model Name"
            }
          }
        }
      },
      "model": "myprovider/my-model-id"
    }

Примечание: Агент также принимает конфигурацию через переменную окружения OPENCODE_CONFIG_CONTENT (полная JSON-строка). Это слой конфигурации с наивысшим приоритетом, который переопределяет Secret. Все стандартные ключи схемы OpenCode валидны (model, provider, $schema и т. д.).

Другие провайдеры

OpenCode поддерживает 75+ провайдеров. Любой провайдер с OpenAI-совместимым API (Ollama, LM Studio, llama.cpp, Azure OpenAI, Groq, Together AI, OpenRouter, DeepSeek и многие другие) работает по паттерну кастомного провайдера, показанному выше. Для встроенных провайдеров (Anthropic, Amazon Bedrock, Google Vertex AI, GitHub Copilot и т. д.) структура конфигурации немного отличается — см. полный каталог провайдеров в документации OpenCode:

2. Установите через Helm

helm install mechanic oci://ghcr.io/lenaxia/charts/mechanic \
  --namespace mechanic \
  --create-namespace \
  --set gitops.repo=myorg/my-gitops-repo \
  --set gitops.manifestRoot=kubernetes

Или из локального клона:

helm install mechanic charts/mechanic/ \
  --namespace mechanic \
  --set gitops.repo=myorg/my-gitops-repo \
  --set gitops.manifestRoot=kubernetes

3. Проверьте установку

kubectl get deployment -n mechanic
kubectl get rjob -n mechanic
# Показать события жизненного цикла конкретного RemediationJob:
kubectl describe rjob <name> -n mechanic

Конфигурация

Справочник по значениям Helm

Все ключи values.yaml и их значения по умолчанию:

Ключ По умолчанию Описание

image.repository

ghcr.io/lenaxia/mechanic-watcher

Репозиторий образа вотчера

image.tag

"" (используется Chart.appVersion)

Тег образа вотчера

image.pullPolicy

IfNotPresent

Политика загрузки образа

agent.image.repository

ghcr.io/lenaxia/mechanic-agent

Репозиторий образа агента

agent.image.tag

"" (используется Chart.appVersion)

Тег образа агента

gitops.repo

обязательно

GitOps-репозиторий в формате org/repo

gitops.manifestRoot

обязательно

Путь до корня манифестов в репозитории

watcher.stabilisationWindowSeconds

120

Секунды, в течение которых событие должно сохраняться перед отправкой

watcher.maxConcurrentJobs

3

Максимальное число одновременных агентных Jobs

watcher.minSeverity

low

Минимальный уровень критичности для отправки: critical, high, medium или low

watcher.remediationJobTTLSeconds

604800

TTL для завершённых объектов RemediationJob (7 дней)

watcher.sinkType

github

Тип sink для создания PR

watcher.logLevel

info

Уровень логирования: debug, info, warn, error

watcher.llmProvider

openai

Гейт готовности LLM: openai включает его; пустое значение отключает

watcher.injectionDetectionAction

log

Действие при срабатывании эвристики prompt-инъекции: log или suppress

watcher.maxInvestigationRetries

3

Максимальное число повторных попыток Job на RemediationJob перед окончательным сбоем

watcher.agentRBACScope

cluster

Область действия RBAC агента: cluster или namespace

watcher.agentWatchNamespaces

""

Разделённые запятыми namespace’ы для области действия RBAC агента. Обязательно при agentRBACScope=namespace

watcher.watchNamespaces

""

Разделённые запятыми namespace’ы, за которыми следит вотчер. Пустое значение = все namespace’ы

watcher.excludeNamespaces

""

Разделённые запятыми namespace’ы, которые вотчер игнорирует. Пустое значение = без исключений

agentType

opencode

Тип агентного runner’а: opencode (рабочий) или claude (заглушка, пока не функционален). Определяет, какой Secret llm-credentials-<agentType> используется. Имена Secret’ов — константы времени компиляции, переопределить через Helm values нельзя.

prompt.coreOverride

""

Полное переопределение основного промпта (заменяет встроенный files/prompts/core.txt)

prompt.agentOverride

""

Полное переопределение промпта агента (заменяет встроенный files/prompts/<agentType>.txt)

rbac.create

true

Создавать ресурсы RBAC

createNamespace

false

Создать Release.Namespace, если он не существует

metrics.enabled

false

Открыть Service с метриками на порту 8080

metrics.serviceMonitor.enabled

false

Создать ServiceMonitor для Prometheus Operator

metrics.serviceMonitor.interval

30s

Интервал сбора метрик Prometheus

metrics.serviceMonitor.scrapeTimeout

10s

Таймаут сбора метрик Prometheus

metrics.serviceMonitor.labels

{}

Дополнительные метки для ServiceMonitor

networkPolicy.enabled

false

Ограничить исходящий трафик агентного Job только до API-сервера, GitHub и LLM-эндпоинта

networkPolicy.apiServerPort

6443

Порт Kubernetes API-сервера (некоторые дистрибутивы используют 443)

networkPolicy.additionalEgressRules

[]

Дополнительные правила для исходящего трафика, добавляемые как есть (например, для ограничения LLM-эндпоинта по CIDR)

watcher.prAutoClose

true

Автоматически закрывать GitHub PR при устранении лежащего в основе события. Установите false, чтобы оставлять PR открытыми для ручного просмотра

watcher.dryRun

false

Запустить полный пайплайн расследования без открытия PR. Отчёты записываются в ConfigMap mechanic-dryrun-<fingerprint>

agent.hardenKubectl

false

Включить усиленный режим — блокирует kubectl get/describe secret, get all, exec и port-forward в дополнение к всегда активным блокировкам записи

Валидация конфигурации

Вотчер проверяет конфигурацию при старте и выдаёт понятные сообщения об ошибках.

Числовые проверки:

  • MAX_CONCURRENT_JOBS: должно быть > 0

  • REMEDIATION_JOB_TTL_SECONDS: должно быть > 0

  • STABILISATION_WINDOW_SECONDS: должно быть ≥ 0

Проверки перечислений (enum):

  • MIN_SEVERITY: должно быть одним из critical, high, medium, low (при отсутствии — по умолчанию low)

Проверки формата:

  • GITOPS_REPO: должно быть в формате owner/repo

Как это работает

%%{init: {'flowchart': {'curve': 'linear'}}}%%
flowchart TD
    subgraph watcher["mechanic-watcher — Deployment"]
        SPR["SourceProviderReconcilers<br/>one per resource type<br/>─────────────────────<br/>watches Pods, Deployments,<br/>StatefulSets, PVCs, Nodes, Jobs<br/>extracts findings<br/>deduplicates by fingerprint"]
        RJR["RemediationJobReconciler<br/>─────────────────────<br/>watches RemediationJob CRDs<br/>enforces MAX_CONCURRENT_JOBS<br/>syncs Job status back"]
    end

    RJ["RemediationJob CRDs<br/>rjob<br/>─────────────────────<br/>durable dedup state<br/>survives restarts"]

    AJ["mechanic-agent Job<br/>one per finding<br/>─────────────────────<br/>init: git clone repo<br/>main: opencode run<br/>  kubectl read-only<br/>  gh pr create"]

    GH["GitOps repository<br/>GitHub"]

    SPR -->|creates| RJ
    RJ -->|watched by| RJR
    RJR -->|creates| AJ
    AJ -->|opens PR| GH

Что делает агент

Агент запускает OpenCode внутри кластера с RBAC только на чтение и выполняет структурированное расследование:

  1. Проверяет наличие открытого PR для данного отпечатка — если найден, добавляет комментарий и завершает работу

  2. Выполняет kubectl describe и kubectl get events для проблемного ресурса

  3. Инспектирует связанные ресурсы (родительский Deployment, Endpoints, PV и т. д.)

  4. Находит нужные манифесты в склонированном GitOps-репозитории

  5. Проверяет состояние Flux/Helm с помощью flux get all и helm list

  6. Определяет первопричину и присваивает уровень уверенности (high / medium / low)

  7. Валидирует предлагаемые изменения с помощью kubeconform и kustomize build

  8. Открывает pull request со структурированным описанием: краткое изложение, доказательства, первопричина, исправление, уровень уверенности

CRD RemediationJob

Каждое уникальное событие отслеживается объектом RemediationJob (rjob).

kubectl get rjob -n mechanic
NAME                          PHASE       KIND         PARENT                  JOB                                   AGE
mechanic-a3f9c2b14d8e         Succeeded   Pod          Deployment/my-app       mechanic-agent-a3f9c2b14d8e           8m
mechanic-7bc1d3e90f21         Dispatched  Deployment   Deployment/api-server   mechanic-agent-7bc1d3e90f21           2m
mechanic-f4e2a1c85b67         Failed      Node         Node/worker-03                                                1h

Жизненный цикл RemediationJob

stateDiagram-v2
    [*] --> Pending : finding detected

    Pending --> Dispatched : concurrent-job slot available
    Pending --> Cancelled : source object deleted

    Dispatched --> Running : Job pod scheduled

    Running --> Succeeded : agent Job completed
    Running --> Failed : exit non-zero or deadline exceeded
    Running --> Cancelled : source object deleted

    Failed --> Dispatched : retry (RetryCount < MaxRetries)
    Failed --> PermanentlyFailed : RetryCount >= MaxRetries
    Succeeded --> [*]
    Cancelled --> [*]
    PermanentlyFailed --> [*]

  • Pending — событие обнаружено, ожидает слота для параллельного выполнения

  • Dispatched — создан batch/v1 Job, ожидает планирования пода

  • Running — под агента выполняется

  • Succeeded — агентный Job завершился; status.prRef содержит URL открытого PR (если он был открыт)

  • Failed — агентный Job завершился неудачей (ненулевой код выхода или истёк дедлайн); помещается в очередь повторно, если RetryCount < MaxRetries

  • PermanentlyFailed — RetryCount достиг MaxRetries; дальнейших запусков нет; отображается через kubectl describe rjob <name>

  • Cancelled — исходный объект был удалён во время расследования

Управление через аннотации на ресурсах

Три аннотации управляют поведением mechanic для любого отслеживаемого ресурса (Pod, Deployment, StatefulSet, PVC, Node, Job) или для всего Namespace:

Аннотация Значение Эффект

mechanic.io/enabled

"false"

Постоянно подавлять все события от этого ресурса

mechanic.io/skip-until

"YYYY-MM-DD"

Подавлять события до конца указанного дня (UTC)

mechanic.io/priority

"critical"

Обойти окно стабилизации — отправить немедленно

Примеры:

# Навсегда отключить расследования для deployment
kubectl annotate deployment my-app mechanic.io/enabled=false

# Заглушить шумящую ноду до окончания окна обслуживания
kubectl annotate node worker-03 mechanic.io/skip-until=2026-03-15

# Немедленно отправлять события для критичного deployment (без окна стабилизации)
kubectl annotate deployment api-server mechanic.io/priority=critical

Гейт на уровне Namespace: Аннотирование объекта Namespace применяется ко всем ресурсам в этом namespace. Это подавляет все события вне зависимости от собственных аннотаций ресурса:

# Отключить всю активность mechanic в namespace kube-system
kubectl annotate namespace kube-system mechanic.io/enabled=false

# Подавить все события в staging до указанной даты
kubectl annotate namespace staging mechanic.io/skip-until=2026-04-01

Дата skip-until включительная: события подавляются до полуночи UTC в начале дня, следующего за указанной датой.

Компоненты

Компонент Описание

mechanic-watcher

Go-контроллер (controller-runtime), следящий за ресурсами Kubernetes, управляющий CRD RemediationJob и создающий агентные Jobs

mechanic-agent

Docker-образ, содержащий opencode + kubectl + helm + flux + gh и вспомогательные инструменты для расследования

Инструменты образа агента

Инструмент Версия Назначение

opencode

1.2.10

AI-агентный движок

kubectl

1.35.1

Инспекция кластера (только чтение)

helm

3.20.0

Метаданные chart’ов, рендеринг шаблонов

flux

2.8.0

Статус Flux, trace, diff

kustomize

5.8.1

Рендеринг и валидация Kustomize overlays

gh

последняя стабильная

Создание PR, листинг, комментирование

kubeconform

0.7.0

Валидация схемы манифестов Kubernetes

yq

4.52.4

Обработка YAML

jq

apt

Обработка JSON

stern

1.33.1

Потоковый просмотр логов нескольких подов

sops

3.12.1

Расшифровка секретов, зашифрованных SOPS

age

1.3.1

Расшифровка файлов, зашифрованных age

talosctl

1.12.4

Инспекция нод Talos (требует монтирования talosconfig)

Все бинарники загружаются из официальных релизов с проверкой контрольной суммы SHA256. Агент работает без привилегий root (uid=1000).

Дорожная карта

Функции в активной разработке или запланированные:

Область Функция Статус

Удобство эксплуатации

Kubernetes Events на RemediationJob (kubectl describe rjob показывает жизненный цикл)

Выпущено

Удобство эксплуатации

Режим сухого прогона — расследование без открытия PR

Выпущено

Надёжность

Фаза PermanentlyFailed — ограничение повторов с захоронением-«тупиком»

Выпущено

Надёжность

Быстрое завершение при истечении токена GitHub App

Выпущено

Точность

Фильтрация провайдера по namespace (WATCH_NAMESPACES, EXCLUDE_NAMESPACES)

Выпущено

Точность

Аннотации отказа от расследования на ресурсах (mechanic.io/enabled, mechanic.io/skip-until, mechanic.io/priority)

Выпущено

Точность

Корреляция нескольких сигналов (связанные события группируются в одно расследование)

Выпущено

Точность

Обязательная валидация манифестов перед PR

Выпущено

Влияние

Автоматическое закрытие PR при устранении события

Выпущено

Влияние

Итерация обратной связи по PR (ответы на комментарии ревьюера)

Отложено

Влияние

Ручной запуск по требованию

Отложено

Влияние

Поддержка GitLab и Gitea в качестве sink

На оценке

Источники сигналов

Провайдер на основе Prometheus / Alertmanager

На оценке

Источники сигналов

Провайдер истечения сертификатов cert-manager

На оценке

Полный бэклог продукта с оценками ценности/сложности и заметками по реализации — в docs/BACKLOG/FEATURE_TRACKER.md.

Документация

  • docs/DESIGN/HLD.md — архитектура и принятые проектные решения

  • docs/DESIGN/lld/ — детальные дизайны на уровне компонентов

  • docs/BACKLOG/ — бэклог реализации и трекер функций

  • README-LLM.md — руководство по реализации для LLM

Разработка

Предварительные требования

  • Go 1.24+

  • golangci-lint — расширенный набор линтеров

  • gitleaks — сканер секретов

Установите оба через go install:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
go install github.com/zricethezav/gitleaks/v8@latest

Git-хуки

После клонирования установите pre-commit хук один раз:

make install-hooks

Хук запускается при каждом git commit и выполняет две проверки:

Проверка Инструмент Что обнаруживает

Сканирование секретов

gitleaks

API-ключи, токены, учётные данные в индексируемых файлах

Линтинг

golangci-lint

Ошибки типов, неиспользуемый код, проблемы безопасности, форматирование

Для обхода в экстренной ситуации: git commit --no-verify

Полезные make-цели

Цель Описание

make lint

Быстрая проверка go vet

make lint-full

Полный прогон golangci-lint (аналогично pre-commit)

make lint-secrets

Полное сканирование репозитория на секреты с помощью gitleaks

make lint-security

Проверка безопасности HIGH/CRITICAL с помощью gosec

make test

Полный набор тестов с детектором гонок

make install-hooks

(Пере-)установка git-хуков после клонирования

Сообщество

  • GitHub Discussions — github.com/lenaxia/k8s-mechanic/discussions — вопросы, идеи, обсуждение архитектуры и демонстрации

  • GitHub Issues — сообщения об ошибках и запросы функций

Участие в разработке

См. CONTRIBUTING.md для настройки среды разработки, стандартов кода, требований DCO и информации о том, как найти подходящие первые задачи.

Управление проектом

См. GOVERNANCE.md для ознакомления с лестницей участников проекта, процессом принятия решений и условиями становления мейнтейнером. Текущий список мейнтейнеров находится в MAINTAINERS.md.

Теги репозитория GitHub

В репозитории заданы следующие теги для упрощения обнаружения. Если вы ведёте форк или связанный проект, возможно, стоит применить тот же набор:

kubernetes gitops devops cloud-native operator controller remediation self-healing argocd flux automation

Теги настраиваются через веб-интерфейс GitHub: страница репозитория → значок шестерёнки рядом с «About» → Topics.

Лицензия

Apache 2.0

Практики разработки

В проекте применяются структурированные практики жизненного цикла разработки программного обеспечения (SDLC) на всех этапах:

  • Бэклог как основа — все функции и эпики отслеживаются в docs/BACKLOG/ с явными разбивками по историям, критериями приёмки и оценками ценности/сложности до начала реализации.

  • Проверка безопасности — Эпик 12 включал структурированный аудит безопасности всей поверхности атаки mechanic: редактирование секретов, обнаружение prompt-инъекций, сетевая политика, ограничение RBAC, структурированное логирование аудита и формальный план penetration-тестирования с задокументированными результатами. Все находки уровня HIGH/CRITICAL были устранены до закрытия эпика.

  • Документирование — каждая значимая сессия записывается в docs/WORKLOGS/ с фиксацией принятых проектных решений, заметок по реализации и обоснования изменений по мере их появления.

Разработка ускорена с помощью ИИ (преимущественно OpenCode), что позволяет проекту двигаться быстро, не жертвуя строгостью процессов. Процесс обеспечивает подотчётность работы.

Похожее

© 2026 meganuke