Kstack — набор навыков (skill pack) для Claude Code, который помогает выполнять задачи мониторинга, диагностики и аудита кластеров Kubernetes умно и эффективно.
Введение
Kstack — набор навыков для Claude Code, позволяющий выполнять мониторинг, диагностику и аудит кластеров K8s в умном и экономичном режиме. Помимо стандартных инструментов вроде kubectl, он делегирует работу в командной оболочке таким утилитам, как Kubetail, Helm, Trivy, Pluto, — и только потом передаёт результаты в Claude, благодаря чему ответы приходят быстро и расходуют мало токенов. Kstack также определяет сервисы, работающие в кластере, и при необходимости задействует их специализированный инструментарий (например, Cilium, Istio).
После установки kstack в Claude Code становятся доступны следующие навыки:
Мониторинг
-
/cluster-status— снимок состояния кластера (перезапуски подов, состояние узлов, давление на ресурсы) -
/events— последние события, ранжированные по серьёзности
Диагностика
-
/investigate— поиск первопричины по событиям, логам и связанным ресурсам -
/logs— общий сеанс tmux, который переводит запросы на естественном языке в запросы к логам и их анализ (через Kubetail) -
/metrics— получение метрик CPU, памяти и других ресурсов для подов, узлов и рабочих нагрузок -
/exec— общая оболочка tmux внутри пода, узла или эфемерного отладочного контейнера
Аудит
-
/audit-security— RBAC, уровень защиты подов, рекомендации по сужению привилегий -
/audit-network— проверки NetworkPolicy, Service, Ingress, Gateway API, DNS и шифрования -
/audit-cost— сравнение запросов и фактического использования, избыточное выделение ресурсов, простаивающие мощности -
/audit-outdated— устаревшие сервисы, известные CVE, доступные обновления версий
Прочее
-
/cleanup— удалить все ресурсы, созданные kstack в кластере (отладочные контейнеры, клоны подов, задания-наблюдатели) -
/forget— очистить локальный кэш kstack и сбросить всё, что он узнал о кластере(-ах)
Цель проекта — принести возможности ИИ в мониторинг Kubernetes удобным и экономичным способом, оставляя пользователя в полном контроле. Если вы обнаружили ошибку или хотите что-то предложить — создайте задачу (GitHub Issue) или напишите на hello@kubetail.com!
Быстрый старт
Чтобы установить навыки kstack глобально, выполните:
curl -sS https://kstack.sh/install | bashИли установите их локально в конкретную директорию проекта:
curl -sS https://kstack.sh/install | bash -s -- --localПосле установки навыки будут доступны внутри сессий агента:
───────────────────────────────────
❯ /kstack-cluster-status
───────────────────────────────────По умолчанию скрипт устанавливает навыки с префиксом пространства имён kstack-*, однако его можно отключить флагом --no-prefix. Также по умолчанию навыки устанавливаются для всех доступных агентов (например, Claude, Codex, OpenCode), но можно выбрать конкретного агента с помощью флага --agent (см. Installation).
Kstack использует локальный файл kubeconfig для аутентификации, поэтому выполняет действия в кластере с вашими RBAC-правами. Если возникнут проблемы с разрешениями, он сообщит об этом.
Другие агенты ИИ
Kstack работает с любым агентом ИИ, который поддерживает навыки, — не только с Claude. Curl-скрипт автоматически определяет, какие CLI-агенты есть в PATH, и устанавливает навыки для каждого. Чтобы нацелиться на конкретного агента, используйте --agent <name>:
| Агент | Флаг | Путь глобальной установки |
|---|---|---|
OpenAI Codex CLI |
|
|
OpenCode |
|
|
Cursor |
|
|
Factory Droid |
|
|
Slate |
|
|
Kiro |
|
|
Hermes |
|
|
Pi |
|
|
При локальной установке структура зеркалится внутри директории проекта (например, <project>/.codex/skills/) и применяется только тогда, когда агент запускается из этой директории. Исключение составляет Pi — его локальная директория навыков: <project>/.pi/skills/ (без сегмента agent/).
Справочник по навыкам
Каждый навык вызывается командой /<name> внутри сессии агента. По умолчанию все навыки работают только на чтение — любое действие, изменяющее состояние кластера, требует явного подтверждения. Навыки учитывают текущий контекст локального kubeconfig и соблюдают ограничения RBAC.
Глобальные флаги (поддерживаются каждым навыком):
| Флаг | Описание |
|---|---|
|
Переопределить текущий контекст kubeconfig |
|
Ограничить выполнение одним пространством имён (по умолчанию — все доступные) |
|
Выводить структурированный результат для передачи в другие инструменты |
|
Открыть справочную документацию по навыку в браузере |
Мониторинг
/cluster-status
Плотный снимок состояния кластера — условия узлов, агрегаты по подам и ранжированный список проблем, на которые действительно стоит обратить внимание.
Что проверяется: идентификация кластера (контекст, версия Kubernetes, платформа); условия узлов Ready/MemoryPressure/DiskPressure/PIDPressure и SchedulingDisabled; разделение на узлы управляющей плоскости (control plane) и рабочие узлы; фаза и статус Ready подов во всех пространствах имён; поды с ненулевым числом перезапусков; ранжированный список топ-5 проблем по серьёзности.
Как работает: параллельно запускает kubectl version, kubectl get nodes -o json и kubectl get pods -A -o json, записывая результаты в кэш для каждого контекста (cluster.json, nodes.json, pods.json). Агрегация и ранжирование по серьёзности выполняются на стороне клиента. Дополнительные вопросы («перечисли поды», «поды на <узле>», «какие узлы помечены taint») обрабатываются чтением кэша через jq без повторного вызова навыка.
Параметры:
-
--refresh— получить свежие данные, обойдя и обновив кэш (по умолчанию:false) -
--ttl <duration>— обновлять кэш только если он старше<duration>(по умолчанию:15m)
/events
Последние события кластера, сгруппированные по причине и ранжированные по серьёзности — чтобы полезный сигнал не тонул в шуме Pulled/Created/Started.
Что проверяется: события типа Warning во всех пространствах имён, сгруппированные по (reason, involvedObject.kind, namespace); заметные события типа Normal (Killing, Preempting, NodeNotReady, Rebooted, Rebooted, FailedScheduling) с «болтливыми» причинами (Pulled, Created, Started, Scheduled, SuccessfulCreate), свёрнутыми в итоговую строку. Каждая группа содержит количество событий, временны́е метки первого и последнего, последнее сообщение и затронутые объекты.
Как работает: один вызов kubectl get events --all-namespaces (к events.k8s.io/v1, с сортировкой на стороне сервера по lastTimestamp), результат сохраняется в кэш как events.json. Агрегация и ранжирование выполняются на стороне клиента. Последующие вопросы («только payments», «события на pod/checkout-7c9», «показать подавленные») обрабатываются через jq по кэшу — при этом владельцы объектов проходятся на один уровень вверх (Pod → ReplicaSet → Deployment), чтобы события, инициированные контроллером, не были пропущены.
Параметры:
-
--refresh— получить свежие данные, обойдя и обновив кэш (по умолчанию:false) -
--ttl <duration>— обновлять кэш только если он старше<duration>(по умолчанию:5m)
Справка: kstack.sh/reference/skills/events
Диагностика
/investigate
Запустить анализ первопричины для неисправного или подозрительного ресурса. При вызове навык выполняет скрипт, собирающий начальный пакет данных, и передаёт сводку агенту. После этого можно задавать уточняющие вопросы на естественном языке — агент сам решает, ответить из имеющихся данных, запросить что-то новое или обратиться к другому инструменту.
Что собирается: спецификация и статус проблемных ресурсов; события на этих ресурсах и их владельцах (ReplicaSet и Deployment для Pod, CronJob для Job и т.д.); логи текущих и предыдущих контейнеров, усечённые до строк, наиболее вероятно содержащих сведения об ошибке; очевидные связанные ресурсы (backing Service, имена смонтированных ConfigMap/Secret, привязанные PVC, указанный ServiceAccount); узел, на котором запланированы поды, — если это актуально.
Как работает: навык загружает пакет данных из Kubernetes API и объясняет агенту, как их интерпретировать (коды завершения, причины событий, типичные комбинации состояний), когда при уточняющих вопросах нужно повторно запрашивать данные, а не рассуждать по устаревшему пакету, и когда передавать управление навыкам /logs, /exec или /metrics.
Аргументы:
-
<target>—<kind>/<name>(например,pod/checkout-7c9) или описание на естественном языке (the api deployment,why is checkout crashing). Необязательно — навык запросит, если не указано.
Параметры: отсутствуют. Логи, временны́е окна и ресурсы задаются через естественный язык в запросе или уточняющих вопросах.
/logs
Инструмент получения логов на базе ИИ. Опишите, что ищете, на естественном языке — агент найдёт нужные поды, выберет временно́е окно и построит фильтр grep, чтобы получить только нужные строки. Поток выполняется внутри окна tmux, к которому подключены и вы, и агент.
Как работает: агент переводит ваше описание в запрос Kubetail, запускает отсоединённую сессию tmux (например, kstack-logs-api-server), пытается открыть новое окно терминала с подключением к ней и выводит команду tmux attach в чат как резервный вариант. Вы и агент делите одну панель — можно прокручивать, искать или наблюдать за живым потоком; агент читает его экономно, чтобы беречь токены.
Требования: tmux в $PATH агента и Kubetail, установленный в кластере (навык предложит установить его через Helm, если он отсутствует).
Аргументы:
-
<target>— описание на естественном языке того, что нужно получить (api,errors from the last hour on api,checkout for "timeout" in last 15m). Необязательно — навык запросит, если не указано.
Параметры:
-
--attach— подключить агента к существующей tmux-сессии kstack вместо создания новой -
--detach— запустить новую сессию в отсоединённом режиме (окно терминала не открывается, подключение вручную)
Справка: kstack.sh/reference/skills/logs
/metrics
Инструмент получения метрик на базе ИИ. Опишите, что хотите увидеть, — агент разрешит нужную цель, выберет разумное временно́е окно и вернёт компактную сводку. Работает только на чтение и никогда не изменяет состояние кластера.
Как работает: агент переводит ваше описание в запрос к подходящему источнику (metrics-server или Prometheus), возвращает сводную статистику (p50, p95, max) вместо того, чтобы прогонять полный ряд данных через модель, и показывает разрешённый запрос до его выполнения, если область охвата выглядит шире задуманного. Если нужно разобраться, почему метрика изменилась — передаёт управление /logs; для контекста первопричины — /investigate; для полного анализа правильного распределения ресурсов — /audit-cost.
Аргументы:
-
<target>— описание на естественном языке (api,memory on checkout last 1h,top pods by cpu in payments). Необязательно — навык запросит, если не указано.
Параметры: отсутствуют. Цель, метрику и временно́е окно задают через естественный язык в запросе или уточняющих вопросах.
Справка: kstack.sh/reference/skills/metrics
/exec
Версия kubectl exec на базе ИИ. Опишите цель на естественном языке — агент выберет подходящий механизм: обычный exec в работающий контейнер, эфемерный отладочный контейнер, если у цели нет пригодной оболочки, или привилегированную оболочку на узле. Сессия выполняется внутри окна tmux, к которому подключены и вы, и агент — оба видят вывод и могут вводить команды.
Как работает: агент запускает отсоединённую tmux-сессию (например, kstack-exec-api-server), пытается открыть новое окно терминала с подключением к ней и выводит команду tmux attach в чат как резервный вариант. Агент читает данные из панели экономно, чтобы беречь токены. Скажите ему завершить работу — и он уничтожит tmux-сессию и удалит созданный под.
Требования: tmux в $PATH агента.
Безопасность: /exec поставляется с disable-model-invocation: true — агент никогда не запускает оболочку самостоятельно. Навык выполняется только тогда, когда вы намеренно вводите /exec, учитывая привилегированные режимы выше.
Аргументы:
-
<target>— описание на естественном языке (api,api/sidecar,node worker-3,debug api). Необязательно — навык запросит, если не указано.
Параметры:
-
--image <image>— образ для режимов узла и отладочного контейнера (по умолчаниюnetshoot) -
--attach— подключить агента к существующей tmux-сессии kstack вместо создания новой -
--detach— запустить новую сессию в отсоединённом режиме (окно терминала не открывается, подключение вручную)
Справка: kstack.sh/reference/skills/exec
Аудит
Все навыки аудита формируют ранжированный список находок (серьёзность + доказательства + рекомендуемое исправление).
/audit-security
Проверка RBAC, оценка уровня защиты подов и рекомендации по сужению привилегий. Выявляет избыточно привилегированные идентификаторы и рабочие нагрузки: ServiceAccount с большим доступом, чем им нужно; поды, работающие от root или с host-level escapes; привязки, дающие кластерные права там, где достаточно роли уровня пространства имён.
Как работает: запрашивает только Kubernetes API — без exec и доступа к логам. Находки ранжируются по радиусу поражения (blast radius): кластерные wildcards — выше пространственных, host escapes — выше отсутствующих seccomp. Проверки RBAC статические — они находят то, что предоставляют Role, а не то, что субъекты фактически используют; выявление действительно неиспользуемых разрешений требует анализа журнала аудита, который данный навык не выполняет. Secrets фигурируют только по имени, пространству имён и типу — содержимое никогда не читается.
Аргументы:
-
<scope>— область охвата на естественном языке (rbac,pods in kube-system). Необязательно — пропустите для полной проверки.
Параметры: отсутствуют. Область охвата задаётся через естественный язык в запросе или уточняющих вопросах.
/audit-network
Проверки NetworkPolicy, Service, Ingress, Gateway API, DNS и корректности шифрования. Выявляет сломанные или отсутствующие элементы сетевой конфигурации кластера: экземпляры NetworkPolicy, не совпадающие ни с чем; Service без эндпоинтов; маршруты Ingress и Gateway API, которые не разрешатся; проблемы DNS; рабочие нагрузки, использующие открытый текст там, где доступен сервисный меш.
Как работает: запрашивает Kubernetes API, а также метрики CoreDNS и CRD меша при их наличии. При TLS-проверках различается «содержимое Secret недоступно из-за RBAC» и «истёкший сертификат» — это исключает ложноположительные срабатывания. Находки сгруппированы по рабочему процессу и включают доказательства (селекторы, эндпоинты, ключи ConfigMap), а не только вердикт.
Аргументы:
-
<scope>— область охвата на естественном языке (policies,ingress in prod). Необязательно — пропустите для полной проверки.
Параметры: отсутствуют. Область охвата задаётся через естественный язык в запросе или уточняющих вопросах.
/audit-cost
Рекомендации по устранению избыточного потребления ресурсов и правильному их распределению. Выявляет рабочие нагрузки с избыточным выделением ресурсов, простаивающие рабочие нагрузки, а также хранилище и балансировщики нагрузки, которыми никто не пользуется.
Как работает: параллельно выполняет несколько рабочих процессов, объединяя данные metrics-server и Prometheus с запросами к Kubernetes API для проверки статусов Job/CronJob, привязок PV/PVC и эндпоинтов LoadBalancer. Находки ранжируются по потенциальному эффекту: большие расхождения между запросами и использованием и простаивающие рабочие нагрузки — выше незадействованных PVC и Released PV. Флажок поднимается только для расхождений «запросы vs. использование», которые значимы на практике, — небольшие отклонения считаются шумом. В заголовке всегда указывается источник данных (metrics-server для текущих, Prometheus для исторических) и эффективный период ретроспективного анализа, чтобы читатель мог оценить, насколько стоит доверять рекомендациям.
Аргументы:
-
<scope>— область охвата на естественном языке (requests,idle in staging). Необязательно — пропустите для полной проверки.
Параметры: отсутствуют. Область охвата задаётся через естественный язык в запросе или уточняющих вопросах.
/audit-outdated
Устаревшие компоненты кластера, известные CVE и доступные обновления версий. Выявляет расхождение версий в управляющей плоскости, узлах, образах контейнеров, Helm-чартах, CRD, операторах и поверхности API, на которую ссылаются ваши манифесты.
Как работает: параллельно выполняет рабочие процессы, запрашивая Kubernetes API и внешние индексы (расписания релизов, реестры, Helm-репозитории, базу Trivy, потоки CVE). Находки дедуплицируются по дайджесту образа, чтобы один устаревший образ, используемый во многих подах, не доминировал в отчёте. Записи CVE включают серьёзность и статус в CISA KEV при наличии — попадания в KEV ранжируются выше находок CVSS-high без известной эксплуатации. «Дрейф внутри поддерживаемого окна» и «EOL» отображаются отдельно — первое является рутинным, второе — срочным. Для реестров, не входящих в поддерживаемый список, навык явно сообщает об этом, а не молча пропускает образ.
Аргументы:
-
<scope>— область охвата на естественном языке (images,cves in kube-system). Необязательно — пропустите для полной проверки.
Параметры: отсутствуют. Область охвата задаётся через естественный язык в запросе или уточняющих вопросах.
Прочее
/cleanup
Удалить все ресурсы, созданные kstack в кластере. Дополняет навык /forget, который очищает локальное состояние.
Что удаляется: всё, помеченное аннотацией kstack.kubetail.com/owned-by=kstack — эфемерные отладочные контейнеры и привилегированные поды-оболочки на узлах из /exec, кратковременные служебные поды и любые временные ресурсы RBAC или ConfigMap, созданные для их поддержки. Ресурсы без этой аннотации не затрагиваются — даже если они находятся в том же пространстве имён.
Как работает: агент перечисляет всё найденное, сгруппированное по пространству имён и виду, и просит подтверждения перед удалением. Можно одобрить весь набор или на естественном языке указать, что исключить. Если удаление завершится ошибкой — обычно из-за финализатора или проблемы с разрешениями — агент сообщит, какие ресурсы остались и почему, не предпринимая слепых повторных попыток.
Безопасность: /cleanup поставляется с disable-model-invocation: true — агент никогда не запускает очистку самостоятельно. Навык выполняется только тогда, когда вы намеренно вводите /cleanup, поскольку он удаляет ресурсы кластера.
Параметры: отсутствуют. Для другого кластера используйте глобальный флаг --context <ctx>.
Справка: kstack.sh/reference/skills/cleanup
/forget
Стереть локальное состояние kstack на вашей машине. Со временем kstack накапливает рабочую память о ваших кластерах: результаты недавних запросов, обнаруженные интеграции, отпечатки ресурсов и базовые значения для обнаружения аномалий. Этот навык сбрасывает всё до чистого листа. Кластер не затрагивается; для этого используйте /cleanup.
Что очищается: состояние хранится в ~/.config/kstack/, с разделением по контексту kubeconfig.
-
Кэш (
~/.config/kstack/cache/<context>/) — результаты недавних запросов, буферы логов, таблицы дедупликации, состояние текущих заданий-наблюдателей. Легко восстанавливается, очищается свободно. -
Изученное состояние (
~/.config/kstack/state/<context>/) — обнаруженные интеграции, отпечатки ресурсов, базовые значения, предпочтения для конкретного кластера. Восстанавливается при следующем использовании, но для полного восстановления может потребоваться несколько взаимодействий.
Как работает: по умолчанию очищает кэш и изученное состояние для текущего контекста kubeconfig — сброс staging никогда не затрагивает prod. Для другого кластера используйте глобальный флаг --context <ctx>. Запускайте после перестройки или миграции кластера (чтобы kstack перестал доверять устаревшим отпечаткам), когда базовые значения кажутся устаревшими, когда предыдущая сессия научила его чему-то неверному, или когда передаёте машину другому пользователю и не хотите оставлять кластерное состояние.
Безопасность: /forget поставляется с disable-model-invocation: true — агент никогда не стирает локальное состояние самостоятельно. Навык выполняется только тогда, когда вы намеренно вводите /forget, чтобы кэшированный контекст не потерялся неожиданно.
Параметры:
-
--all— очистить кэш и изученное состояние для всех контекстов, а не только для текущего.
Справка: kstack.sh/reference/skills/forget
Обновление
При запуске навыка kstack агент тихо проверяет наличие новой версии и выводит однострочное уведомление в начале ответа, если она обнаружена. Просто скажите «upgrade kstack» — и агент запустит скрипт обновления kstack; скажите «dismiss», чтобы скрыть уведомление до следующего релиза. Это работает одинаково для глобальной и локальной установок.
Можно также запустить вспомогательный скрипт напрямую:
# Глобальная установка
~/.config/kstack/bin/upgrade
# Локальная установка (из директории проекта)
./.kstack/bin/upgradeОбновления идемпотентны и безопасны для запуска в любое время.
Удаление
Запустите вспомогательный скрипт удаления, поставляемый вместе с установкой:
# Глобальная установка
~/.config/kstack/bin/uninstall
# Локальная установка (из директории проекта)
./.kstack/bin/uninstallОба скрипта запрашивают подтверждение перед удалением. Они очищают корень установки (~/.config/kstack или <project>/.kstack) и все слоты навыков, принадлежащих kstack, оставляя авторские навыки пользователя в тех же директориях агентов нетронутыми.
Разработка
Содержимое инсталлятора находится в src/ (навыки, вспомогательные скрипты, библиотека, схемы). Инструменты разработки — Makefile, scripts/, tests/, CI — расположены в корне репозитория. Если вы хотите дорабатывать kstack, см. CONTRIBUTING.md — полное руководство для участников.
Основные команды разработчика через корневой Makefile:
make install # установка в режиме разработки — рендерит навыки в <repo>/.<agent>/skills/
make test # быстрые уровни bats (unit + integration)
make test-e2e # уровень с кластером (kind + docker)
make test-evals # оценочный набор (требует ANTHROPIC_API_KEY или Claude CLI)
make lint # shellcheck
make clean # удалить артефакты режима разработкиКаждая цель вызывает скрипт из scripts/, который можно также запустить напрямую.
make test требует bats-core (brew install bats-core / apt install bats). Тесты расположены в tests/unit/ (тесты функций через source) и tests/integration/ (сквозные CLI-тесты с изолированным $HOME и локальными чистыми git-репозиториями). CI запускает полный набор на Ubuntu, macOS и Windows для каждого PR — см. .github/workflows/ci.yml.
Участие в проекте
В Kubetail мы создаём наиболее удобную, экономичную и безопасную платформу логирования для Kubernetes и будем рады вашему вкладу! Вот чем можно помочь:
-
UI/UX-дизайн
-
Разработка React-фронтенда
-
Сообщения об ошибках и предложения по функциям
Подробнее о настройке среды разработки и правилах участия — в CONTRIBUTING.md. Пишите на hello@kubetail.com, или присоединяйтесь к нашему серверу Discord или каналу в Slack.
Примечания
-
Проект вдохновлён gstack Гэрри Тана.
Сделано с 🧿 в Стамбуле