Health checking protocol

У каждого распределённого приложения рано или поздно появляется метод Ping, и почти каждый автор изобретает его заново: кто-то возвращает пустой ответ, кто-то — версию сборки, кто-то — время аптайма. Проблема самодельного пинга не в коде, а в договорённости: балансировщик, оркестратор и мониторы говорят на разных языках, и каждому приходится объяснять отдельно. Поэтому health protocol встроили в сам gRPC как обычный сервис: пакет grpc.health.v1, и весь он умещается в два сообщения и три метода. Док health-checking формулирует задачу без предисловий: «Health checks are used to probe whether the server is able to handle rpcs» — health-проверка отвечает на вопрос, способен ли сервер обрабатывать RPC вообще, а не «всё ли в порядке с миром»; и сразу проговаривает, что «unhealthy» — тоже валидный ответ: сервер вправе ответить отказом, «because it is not ready to take requests, it is shutting down or some other reason» — не готов принимать запросы, останавливается или что-то ещё. Почему проверка — именно gRPC-сервис, а не отдельный TCP-порт или HTTP-endpoint? У этого выбора три причины, названные в том же документе. Первая: «since it is a GRPC service itself, doing a health check is in the same format as a normal rpc» — проверка едет по тому же транспорту, что и бизнес-вызовы, проходит через те же TLS-учётные данные и межсетевые экраны, и успех проверки действительно означает «RPC по этому соединению ходят». Вторая: «rich semantics such as per-service health status» — один процесс может хостить несколько сервисов, и протокол позволяет спросить здоровье каждого по имени. Третья — проверке доступны обычные коды статусов и дедлайны: клиент может сказать «не успел ответить — считаю нездоровым». Сам proto маленький: HealthCheckRequest с единственным полем service, HealthCheckResponse с полем status и перечислением ServingStatus из четырёх значений — UNKNOWN, SERVING, NOT_SERVING и SERVICE_UNKNOWN, про который в комментарии сказано «Used only by the Watch method» — он существует только для Watch и никогда не возвращается через Check. В файле из репозитория grpc написано, где живут канонические определения: «The canonical version of this proto can be found at» grpc-proto — там же добавился метод List, и в свежих генерациях grpc-go он уже есть; о нём чуть ниже.

Реализация пакета health умещается в меньше двухсот строк, и почти вся логика — это работа с картой. Док пакета объявляет двойную роль сразу: «Package health provides a service that exposes server's health» — сервис здоровья, а тот же импорт включает поддержку клиентских проверок (о второй половине — ниже, в блоке про healthCheckConfig). Структура Server хранит mutex, флаг shutdown, карту статусов statusMap map[string]HealthCheckResponse_ServingStatus и карту подписчиков updates для Watch. Конструктор NewServer заполняет statusMap единственной записью: пустая строка соответствует серверу целиком и по умолчанию равна SERVING — так выполнено правило из комментария proto: «If the caller does not specify a service name, the server should respond with its overall health status». Док health-checking требует того же: «The server should register all the services manually and set the individual status, including an empty service name and its status» — сервер обязан регистрировать все сервисы вручную, включая пустое имя, и следить за их статусами сам; ничего не переключается автоматически, потому что только автору приложения известно, что значит «готов обрабатывать заказы». Для пустого имени правило сформулировано отдельным предложением: «The server should use an empty string as the key for server's overall health status» — пустая строка это здоровье всего процесса, и клиент, которому не интересен конкретный сервис, спрашивает именно её. Check — unary-метод и выглядит скучно: взять RLock, найти service в карте, вернуть статус; незнакомое имя даёт ошибку status.Error(codes.NotFound, «unknown service»). Это контракт протокола, а не прихоть реализации: «If the service name is not registered, the server returns a NOT_FOUND GRPC status» — и в комментарии proto то же самое: незнакомый сервис — это NOT_FOUND, а не NOT_SERVING и не UNKNOWN. Сопоставление имён точное: «The server can just do exact matching of the service name without support of any kind of wildcard matching» — никаких масок и префиксов из коробки; спросить «все сервисы shop.v1.*» не выйдет. Из этого следует невидимая глазу деталь: статус пустого имени НЕ производная от статусов зарегистрированных сервисов. Вы сняли OrderService в NOT_SERVING — Check со service «» по-прежнему вернёт SERVING, пока вы сами не сменили и его. В коде выше мы меняем оба имени руками именно поэтому.

В health-сервере нет ни таймеров, ни наблюдателей за зависимостями: ничего не меняется само. Единственный способ обновить статус — SetServingStatus(service, status), и док это подчёркивает: «The server should register all the services manually and set the individual status». Ручной режим выглядит разочаровывающе примитивно, но это осознанный дизайн: определение «готов ли сервис» требует знания предметной области — миграции применены, кэш прогрет, пул соединений набран, — и ни одна библиотека этого не угадает. Что происходит при остановке процесса? Метод Shutdown делает две вещи разом: переводит ВСЕ записи карты, включая пустое имя, в NOT_SERVING и ставит флаг shutdown, после которого статусы замораживаются. Док-комментарий честен: «Shutdown sets all serving status to NOT_SERVING, and configures the server to ignore all future status changes» — все статусы в NOT_SERVING, и все будущие изменения игнорируются. Игнорирование видно в логах: попытка после Shutdown вписать новый статус приведёт к записи вида «health: status changing for … is ignored because health service is shutdown», статус останется прежним. Обратная операция Resume зеркальна: «Resume sets all serving status to SERVING, and configures the server to accept all future status changes» — всё обратно в SERVING и снова принимать изменения; она нужна редко, но снимает вопрос «а можно ли оживить health после Shutdown» — можно, но только парой Resume, а не одиночным SetServingStatus. Отдельный метод List вернул бы всю карту разом: «List provides a non-atomic snapshot of the health of all the available services» — несогласованный снимок всех сервисов; если записей становится слишком много, сервер ответит RESOURCE_EXHAUSTED, как и обещает proto: «The server may respond with a RESOURCE_EXHAUSTED error if too many services exist». Порог виден в исходнике: константа maxAllowedServices = 100, и при превышении List вернёт ResourceExhausted с сообщением «server health list exceeds maximum capacity» и числом. Сотня сервисов на один процесс — приличный потолок; микросервису с двумя-тремя границами хватает с запасом.

Check отвечает «как сейчас», и опрашивать его каждую секунду — значит плодить unary-вызовы и терять изменения между опросами. Для подписчиков есть Watch — server streaming: «The server will immediately send back a message indicating the current serving status» — сервер немедленно отсылает текущий статус первым сообщением, а дальше: «It will then subsequently send a new message whenever the service's serving status changes» — по каждому изменению. Протокол описывает и поведение на незнакомое имя, и здесь оно отличается от Check: «server will send a message setting the serving status to SERVICE_UNKNOWN but will not terminate the call» — подписка на несуществующий сервис не роняет стрим: придёт SERVICE_UNKNOWN, и если сервис позже появится через SetServingStatus, подписчик получит настоящий статус в тот же стрим. Watch — единственный метод, которому разрешён этот статус; Check на то же имя ответил бы NotFound. Завершение стрима протокол тоже регламентирует, и это редкий случай, когда клиенту прямо предписана ретрай-политика: «If the call terminates with status UNIMPLEMENTED, then clients should assume this method is not supported and should not retry the call. If the call terminates with any other status (including OK), clients should retry the call with appropriate exponential backoff» — Unimplemented значит «на этом сервере Watch нет, не дёргайте его больше», любой другой финал, даже чистый OK, — повод переподписаться с бэкоффом. Внутри server.go механика собрана на каналах: карта updates хранит для каждого сервиса карту «стрим → канал на одно сообщение»; setServingStatusLocked при изменении статуса сначала вычищает из канала непрочитанный старый апдейт — комментарий объясняет, когда такое бывает: «the client is not reading and the server gets flow control limited» — клиент читает медленнее, чем сервер пишет, и канал мог остаться занятым, — затем кладёт свежий статус. В цикле чтения стоит дедупликация: lastSentStatus сравнивается с новым значением, и повтор одинаковых статусов в сеть не уходит; обрыв отправки или завершение контекста закрывают подписчика с Canceled «Stream has ended.», а defer вычищает канал из карты. Итог: Watch — это точный, но тонкий инструмент, и в следующем блоке он внезапно оказывается внутри самого клиента grpc-go, а не только в вашем коде.

Начнём с простого: проверить здоровье чужого или своего сервера из Go-кода можно за десять строк, и это обычный unary-вызов из пятого урока. Клиентская заглушка создаётся grpc_health_v1.NewHealthClient(conn), дальше Check с контекстом и дедлайном. Про дедлайн протокол говорит в обязательном тоне: «Clients should set a deadline when calling Check, and can declare the server unhealthy if they do not receive a timely response» — задайте срок, и если ответ не приехал вовремя, сервер считается нездоровым. Док health-checking добавляет ту же мысль с другой стороны: «A client can declare the server as unhealthy if the rpc is not finished after some amount of time» — отсутствие ответа за отведённое время приравнивается к «unhealthy», и это осознанное упрощение: зависший сервер неотличим от мёртвого, и для проверяющего разницы нет. Второе правило для клиента — не зависеть от того, реализован ли health вообще: «The client should be able to handle the case where server does not have the Health service» — ответ Unimplemented означает «сервер жив, но протокол не знает», и трактовать его как аварию обычно неверно. Разбор кода ошибки из тринадцатого урока здесь и есть вся логика: NotFound — имя не регистрировалось (сервер жив, статуса для этого сервиса нет), Unimplemented — health-сервиса нет вовсе, DeadlineExceeded — не успел (нездоров), NOT_SERVING в успешном ответе — сервис осознанно сняли с обслуживания. Отдельный нюанс, который стоит помнить: Check — это сетевой вызов как любой другой, и он сам инициирует ленивое подключение канала из пятого урока; проверка «жив ли сервер» перед отправкой бизнес-вызова в половине случаев просто устанавливает соединение, и её результат говорит скорее о сети и бэклоге, чем о здоровье бизнес-логики.

Теперь то, ради чего health-сервер ставят даже на бэкендах без оркестратора. Service config из пятнадцатого и шестнадцатого уроков умеет включать клиентскую health-проверку на уровне соединений: поле healthCheckConfig с вложенным serviceName. Комментарий в service_config.go описывает поле коротко: «serviceName is the service name to use in the health-checking request» — это ровно то имя, которое клиент положит в HealthCheckRequest, когда будет проверять SubConn. Форма в JSON привычная: «healthCheckConfig»: { «serviceName»: «shop.v1.OrderService» } — на уровне всего service config или внутри methodConfig. Запуск проверки требует одновременного выполнения четырёх условий, перечисленных в clientconn.go дословно: стартует она, только когда «it is not disabled by the user with the WithDisableHealthCheck DialOption», когда «internal.HealthCheckFunc is set by importing the grpc/health package», когда «a service config with non-empty healthCheckConfig field is provided» и когда «the load balancer requests it». Второе условие самое коварное: функция проверки подключается в init() пакета health, и это тот самый импорт, о котором предупреждает док пакета — «must be imported to enable support for client-side health checks». Забудете импорт в клиентском бинарнике — канал честно напишет в лог «Health check is requested but health check function is not set» и продолжит работать без проверки: соединение станет Ready обычным порядком. Сама проверка живёт в health/client.go и смотрит здоровье через Watch: метод захардкожен как «/grpc.health.v1.Health/Watch», и дальше три ветки поведения. Ответ SERVING — SubConn объявляется Ready; любой другой статус — TransientFailure с ошибкой «connection active but health check failed. status=%s» — заметьте, соединение живо, нездоров именно сервис. Ошибка стрима, кроме Unimplemented, — тоже TransientFailure: «connection active but received health check RPC error: %v». А вот Unimplemented — особая ветка: «Reports healthy for the LBing purposes if health check is not implemented in the server» — сервер без health-сервиса считается здоровым, и это защита от ситуации, когда вы включили healthCheckConfig на клиентах раньше, чем добавили health на все бэкенды. Разрывы и переподписки гасятся экспоненциальным бэкоффом backoff.DefaultExponential, счётчик попыток сбрасывается при каждом полученном сообщении. Отключить механизм разом можно опцией WithDisableHealthCheck — её док: «disables the LB channel health checking for all SubConns of this ClientConn». Шестнадцатый урок упоминал, что round_robin включает health listener для своих детей, — это ровно про четвёртое условие: политика попросила проверку, клиент держит Watch на каждом SubConn, и нездоровый бэкенд не попадает в пикер, хотя TCP-соединение с ним живо.

Kubernetes проверяет контейнеры периодическими пробами, которые выполняет kubelet, и у него три вида задач. Liveness — про рестарт: «Liveness probes determine when to restart a container», и правило жёсткое: «If a container fails its liveness probe more times than the configured tolerance, the kubelet restarts that container» — провал подряд больше failureThreshold, контейнер убивают и перезапускают. Readiness — про трафик: провал не рестартует ничего, «the kubelet marks the container as not ready, and the Pod stops receiving traffic from matching Services» — Pod просто перестаёт получать трафик от подходящих Service'ов, пока проба не станет успешной снова. Startup — про долгий старт: пока она не прошла, «Kubernetes does not execute liveness or readiness probes until the startup probe succeeds» — остальные пробы ждут, чтобы медленно стартующее приложение не убили на размине. Между liveness и readiness есть важная деталь асимметрии: «Liveness probes do not wait for readiness probes to succeed» — живучесть проверяется своим графиком независимо от готовности. С v1.27 у kubelet есть нативная gRPC-проба (в документации — «Stable since Kubernetes v1.27»): если приложение реализует gRPC Health Checking Protocol, kubelet сам делает вызов Check — «The diagnostic is considered successful if the status of the response is SERVING» — и всё, что не SERVING, включая ошибки, считается провалом. Конфигурация минимальна: поле grpc с портом, опционально service — имя для HealthCheckRequest. Полезные мелочи из документации, каждая стоит часа отладки. Адрес: «The probes run against the pod IP address or its hostname» и дальше — «Be sure to configure your gRPC endpoint to listen on the Pod's IP address»: сервер, слушающий только localhost:50051, health-пробу kubelet'а не пройдёт — вспомните развилку из четвёртого урока про «:50051» против «localhost:50051». Транспорт: «The probes connect over plaintext by default» — plaintext без TLS, режим TLS появился позже как отдельная альфа-возможность за feature gate GRPCContainerProbeTLS, и даже тогда «the kubelet connects over TLS with InsecureSkipVerify» — сертификат не проверяется. Имя порта: «gRPC probes do not support named ports» — только число, никаких name из блока ports. Ошибки: «There are no error codes for built-in probes. All errors are considered as probe failures» — и отдельно про конфигурацию: «Configuration problems (for example: incorrect port or service, unimplemented health checking protocol) are considered a probe failure» — неверный порт или несуществующий service это провал пробы, а не Exception в логах kubelet. Наконец, поле service — официальный способ развести пробы на одном health-сервере: документация предлагает называть сервисы по назначению, «myservice-liveness» с разделителем через дефис, чтобы один endpoint отвечал на liveness и readiness по-разному, не поднимая два порта.

Нативные gRPC-пробы появились не сразу, и до v1.27 стандартным ответом была утилита grpc-health-probe из экосистемы: статически скомпилированный бинарник, который кладут в образ и вызывают exec-пробой. Её контракт — одна фраза из README: утилита «makes a RPC to /grpc.health.v1.Health/Check» и, если в ответе SERVING, выходит с кодом успеха, иначе — с ненулевым. Сам README уже признаёт: «Kubernetes has now built-in gRPC health checking», и советует нативный механизм, — но перечисляет случаи, когда утилита жива: «older versions of Kubernetes, or using advanced configuration (such as custom metadata, TLS or finer timeout tuning), or not using Kubernetes at all». Флаги покрывают то, чего в нативной пробе нет: обязательный -addr в форме host:port, -service для имени сервиса, -connect-timeout и -rpc-timeout (оба по умолчанию одна секунда), -rpc-header для метаданных из десятого урока, -tls с набором сертификатных флагов и даже -user-agent со значением по умолчанию «grpc_health_probe». Коды выхода стоит помнить наизусть, потому что именно их читает exec-проба: единица — неверные аргументы, двойка — не установилось соединение (StatusConnectionFailure), тройка — RPC не прошёл (StatusRPCFailure), четвёрка — «rpc succeeded but indicates unhealthy service» (StatusUnhealthy): вызов дошёл, но статус не SERVING. В манифесте это выглядит как readinessProbe и livenessProbe с exec.command вида «/bin/grpc_health_probe -addr=:50051 -service=shop.v1.OrderService», а сам бинарник скачивают в Dockerfile из релизов и делают chmod +x. У exec-проб есть цена, о которой документация Kubernetes предупреждает отдельно: каждый запуск — fork нескольких процессов, и при плотной упаковке подов и частых пробах это заметная нагрузка на CPU узла — ещё одна причина переехать на нативную gRPC-пробу. Тонкость с таймаутами тоже задокументирована: при выключенном feature gate ExecProbeTimeout утилита не уважает timeoutSeconds пробы (который по умолчанию одна секунда), тогда как встроенная проба на таймауте честно провалится — настраивайте -rpc-timeout явно, не полагаясь на окружение.

Вся практика health-проверок держится на одном различии: готовность (readiness) отвечает «можно ли слать мне трафик прямо сейчас», живучесть (liveness) — «жил ли процесс или его пора убить». Первое — обратимое состояние: Pod ушёл с трафика и вернулся, ничего не потеряно. Второе — необратимое действие: рестарт убивает все in-flight вызовы, теряет кэши и прогретые состояния. Из этого следуют конкретные правила. NOT_SERVING — это про готовность: сервис осознанно не принимает запросы (выкатка, прогрев, деградация конкретного под-сервиса), и правильный потребитель — readiness или клиентский Watch. Вешать NOT_SERVING на liveness значит просить о самоубийстве при каждом осознанном снятии с трафика. Liveness через health-протокол должен оставаться тупым и дешёвым: пустое имя, отсутствие зависимости от внешних систем. Классическая ошибка — liveness, который проверяет соединение с базой: база мигнула, все Pod'ы провалили liveness разом, кластер сам себя перезапустил в момент, когда достаточно было подождать; readiness на базу в спорных случаях тоже осторожен — снятие с трафика всех инстансов из-за одной зависимости оставляет сервис пустым, и SRE-практика советует сигнализировать о собственном здоровье, а не о здоровье окружения. Второе правило — про старт. health.NewServer сразу пишет «» -> SERVING, и если RegisterHealthServer случился до того, как бизнес-сервис прогрелся, health лжёт первые секунды жизни. Паттерн: сразу после старта выставить NOT_SERVING (или вообще не регистрировать имя сервиса до готовности — незарегистрированное имя провалит readiness через NotFound, а liveness по пустому имени продолжит считать процесс живым), затем SERVING по факту прогрева. Третье правило — про дедлайны и чужие серверы: proto требует «Clients should set a deadline when calling Check», а док напоминает «The client should be able to handle the case where server does not have the Health service». Проверка без дедлайна зависает вместе с сервером и теряет смысл; проверка, падающая от Unimplemented, ломает клиентов, которые ни при чём. И последнее: UNKNOWN — нулевое значение перечисления, и в норме сервер его не шлёт; если в логах появился UNKNOWN, ищите не статус, а баг в коде статусов.

Честная оговорка про формат, одна на урок: в самоучителе есть песочница с интерпретатором Go, но сеть в браузере недоступна — сервер, kubelet и балансировщики в браузере не запустить, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет. Всё разобранное проверяется локально за вечер на паре из четвёртого и пятого уроков. Три эксперимента. Первый: добавьте health-сервер к OrderService, запустите клиент с Watch на пустое имя и в отдельном терминале дёрните SetServingStatus — увидите, как подписка получает изменения без опроса; затем завершите процесс через Shutdown и попробуйте вернуть статус — в логах появится сообщение об игнорировании. Второй: включите healthCheckConfig в service config клиента и по логам убедитесь, что соединение Ready против сервера без health-сервиса; добавьте RegisterHealthServer, снимите OrderService в NOT_SERVING и посмотрите, как вызовы начнут ждать TransientFailure — а с WaitForReady из пятого урока ждут готовности вместо отказа. Третий: запустите grpc_health_probe -addr=:50051 -service=shop.v1.OrderService локально и проверьте коды выхода: SERVING — ноль, затем NOT_SERVING — четвёрка, затем чужой порт — двойка. Дальше по маршруту: восемнадцатый урок — рефлексия сервера: grpcurl, серверная рефлексия и отладка живого сервиса; после health он предсказуем — тем же способом «встроенного сервиса» gRPC добавит серверу самоназвание и каталог методов, чтобы дёргать его руками без заглушек. Перед ним освежите урок про балансировку — health listener на SubConn'ах станет понятнее с пикером в голове, — и урок про клиент — Check в этом уроке был обычным вызовом поверх NewClient. Полный маршрут курса — на странице gRPC-Go.