Развертывание и проксирование

В финале прошлого урока была строка-обещание: двадцать четвёртый урок спускается в инфраструктуру конкретно, Envoy покажут конфигом, а не обзором. Конфиг ниже — реальный, минимальный и рабочий: от него один шаг до продакшн-версии, и всё, что в нём появится, вы уже умеете объяснять к концу урока. Зачем вообще это нужно? Пока клиент вашего gRPC-сервиса — другой Go-процесс, серверу хватает порта 50051 из четвёртого урока. Но как только в списке потребителей появляются браузер, мобильное приложение, ingress и проверки здоровья — у сервера появляется слой, который не должен жить в Go-коде. Запрос «envoy grpc» в поиске — это почти всегда история про один и тот же зазор: между HTTP/2-клиентом снаружи и вашим сервером внутри кто-то должен стоять, и этот кто-то обязан понимать gRPC до конца, включая трейлеры. Разберём четыре вещи. Первая — словарь Envoy: listener, routes, cluster, upstream, и почему gRPC-проксирование требует http2_protocol_options на ноге к серверу. Вторая — TLS-терминация: шифруем до прокси, внутри периметра plaintext, и это осознанный компромисс из двенадцатого урока. Третья — grpc web: мост для браузера через grpc_web_filter и честное сравнение с Connect. Четвёртая — ingress с аннотацией backend-protocol и health-пробы прокси по grpc.health.v1. Бизнес-код во всех этих историях не меняется — проверяйте сами: ни один YAML этого урока не трогает хендлеры.

Прежде чем разбирать YAML, зафиксируем, что прокси покупает, а чем платим. Покупает три вещи. Первая — единая граница: один публичный порт и один сертификат на все сервисы, вместо того чтобы выдавать TLS-адреса каждому процессу; смена сертификата превращается из передеплоя Go-сервиса в перезапуск прокси. Вторая — протокольные мосты: браузер, который мы уже знаем по прошлому уроку как клиента без доступа к трейлерам, дотягивается до сервиса только через прокси-режим gRPC-Web — и это задача прокси, а не сервера. Третья — фильтры и проверки: ограничение путей, CORS для браузерных клиентов, активные health-пробы — всё это конфигурация, которую можно менять без пересборки сервиса. Теперь цена. Прокси — это лишний hop: плюс латентность на каждый вызов, плюс процесс, который тоже падает, обновляется и потребляет память. И — главное, почему не всякий reverse proxy годится: gRPC опирается на трейлеры HTTP/2, а их умеют прозрачно проводить очень немногие прокси. Документация Envoy говорит об этом в лоб: «gRPC makes use of trailers to convey request status. Envoy is one of very few HTTP proxies that correctly supports trailers and is thus one of the few proxies that can transport gRPC requests and responses» — gRPC передаёт статус вызова в трейлерах, и Envoy — один из очень немногих HTTP-прокси, которые поддерживают трейлеры корректно и потому вообще могут переносить gRPC-запросы и ответы. Сама природа протокола та же, что мы знаем с первого урока: «At the transport layer it uses HTTP/2 or above for request/response multiplexing» — на транспортном уровне HTTP/2 и мультиплексирование запросов и ответов. Выбор Envoy здесь не вкусовщина: это прокси, спроектированный под HTTP/2 с первого дня.

Конфигурация Envoy пугает объёмом, но строится из пяти слов, которые стоит выучить сразу — дальше весь урок будет на них держаться. Listener — точка входа: IP-адрес и порт, на которых прокси принимает соединения; всё, что клиент видит снаружи, начинается с listener-а. Внутри listener-а — цепочка сетевых фильтров, и для HTTP-трафика она почти всегда состоит из одного фильтра: http_connection_manager (HCM), который разбирает HTTP и решает, что делать с запросом дальше. HCM смотрит в routes — таблицу маршрутов: виртуальные хосты с доменами и правилами вида «путь с таким префиксом — в такой cluster». Для gRPC путь запроса самодостаточен: метод вызова уезжает по HTTP/2 в пути вида /пакет.Сервис/Метод, поэтому одно правило с префиксом /shop.v1.OrderService/ накрывает все методы сервиса сразу — ни один маршрут не надо описывать руками. Cluster — набор upstream-эндпоинтов, куда Envoy отправит вызов: конкретные адрес и порт вашего gRPC-сервера. Термины downstream и upstream задают направление: downstream — сторона клиента, upstream — сторона сервера; почти каждая ловушка этого урока живёт на одной из этих двух ног. И последнее слово — фильтры HTTP: цепочка, через которую проходит каждый запрос внутри HCM, где router — обязательный последний элемент, который собственно отправляет запрос в cluster. Конфигурация бывает статической (всё в одном файле) и динамической — через xDS, когда listener-ы и cluster-ы приезжают от управляющего сервера; мы работаем со статической, потому что механика у них одна.

Самая частая ошибка первого Envoy-конфига перед gRPC: всё написано правильно, listener работает, маршруты сходятся — а клиент получает ошибки протокола, и unary-вызовы, и стримы. Причина в ноге к серверу: по умолчанию Envoy говорит с upstream по HTTP/1.1, а gRPC требует HTTP/2. Логика Envoy здесь строгая, и документация cluster-а объясняет её дословно: «Even if default HTTP2 protocol options are desired, this field must be set so that Envoy will assume that the upstream supports HTTP/2 when making new HTTP connection pool connections» — даже если вам нужны настройки HTTP/2 по умолчанию, поле должно быть выставлено явно, чтобы Envoy считал upstream говорящим на HTTP/2 при создании новых соединений. Дальше — ещё честнее: «Currently, Envoy only supports prior knowledge for upstream connections» — сейчас Envoy поддерживает только prior knowledge для upstream-соединений: никаких догадок и автоматического апгрейда, сервер обязан быть HTTP/2-объявленным заранее. И третья деталь, которая валит продовые конфиги: «Even if TLS is used with ALPN, http2_protocol_options must be specified» — даже если используется TLS с ALPN, http2_protocol_options обязателен: сам факт TLS-соединения HTTP/2 до бэкенда не включает. Симптом на клиенте — недетерминированные UNAVAILABLE и обрывы вместо внятного ответа: сервер grpc-go ждёт HTTP/2-преамбулу, а получает HTTP/1.1-запрос. Одним абзацем честности: поле http2_protocol_options в новых версиях считается устаревшим в пользу общего механизма HttpProtocolOptions через typed_extension_protocol_options — но семантика та же самая: «upstream обязан говорить HTTP/2», и в тысячах существующих конфигов вы встретите именно эту форму. Выучить нужно принцип, форму легко поменять. И бонус, важный для конца урока: та же строка документации замечает — «As an aside this allows HTTP/2 connections to happen over plain text» — это попутно разрешает HTTP/2-соединения поверх открытого текста: h2c, на котором строится вся TLS-терминация ниже.

TLS-терминация — это когда шифрованное соединение заканчивается на прокси: он расшифровывает трафик, применяет свои правила и дальше идёт к серверу как обычный HTTP/2-клиент. Базу вы умеете из урока про TLS: там вы собирали TLS вручную — tls.Config, сертификат на сервере, взаимная аутентификация по CN. Теперь у границы появился профессиональный терминатор, и собранное там не выбрасывается — наоборот: именно потому, что вы понимаете, что проверяет рукопожатие, вы способны рассудить, что именно делает прокси. Конфигурационно это две независимые строки: transport_socket с сертификатом на listener-е (нога клиент—прокси) и — ничего — на cluster-е (нога прокси—сервер остаётся plaintext). Легальность plaintext-ноги — не баг, а свойство: мы уже читали в документации cluster-а, что http2_protocol_options «As an aside this allows HTTP/2 connections to happen over plain text» — HTTP/2 поверх открытого текста разрешён, и это ровно тот h2c, по которому Envoy пойдёт к вашему серверу. Такой расклад — стандартный компромисс периметра: сертификат и его обновление живут в одном месте, серверный код не знает о TLS вовсе, а дальше работает правило «внутри периметра доверенной сети plaintext — границу охраняет сама граница». Честность требует назвать цену: терминатор видит все заголовки и все сообщения — metadata, токены, содержимое вызовов; компрометация прокси означает компрометацию трафика. Если этот риск неприемлем, вариантов два, и оба вам уже знакомы: закрыть ногу прокси—сервер TLS из двенадцатого урока вручную или отдать её mesh-у прошлого урока с его mTLS между сайдкарами. Заодно закрывается мост к двадцать второму уроку: keepalive-политики между прокси и сервером теперь настраиваются в конфиге прокси — ловушка too_many_pings из прошлого урока при переезде под прокси живёт там же.

Теперь обещанная история про браузер. Базу вы уже знаете: в connect-курсе есть целый урок «Что такое Connect и gRPC-Web», где подробно разобрано, почему браузерный JavaScript не может говорить на нативном gRPC — fetch не даёт доступа к HTTP/2-трейлерам, где живёт grpc-status, — и как на эту боль отвечает Connect, который обслуживает три протокола из одного хендлера. Здесь мы смотрим на ту же проблему с другой стороны: не глазами серверного разработчика, а глазами прокси. Протокол gRPC-Web придуман самой gRPC-командой, и его спецификация PROTOCOL-WEB.md из репозитория grpc с первого абзаца говорит, кто главный потребитель: «This protocol is designed to make it easy for a proxy to translate between the protocols as this is the most likely deployment model» — протокол спроектирован так, чтобы прокси было легко переводить между протоколами, потому что именно прокси — самая вероятная схема развертывания. Из тех же design goals: «decouple from HTTP/2 framing which is not, and will never be, directly exposed by browsers» — отвязаться от HTTP/2-фрейминга, который браузеры никогда не покажут напрямую. Механика на стороне прокси — фильтр grpc_web_filter, чья страница в документации Envoy коротка: «This is a filter which enables the bridging of a gRPC-Web client to a compliant gRPC server» — фильтр, соединяющий gRPC-Web-клиента с gRPC-сервером. Обзорная страница уточняет механику: «allows a gRPC-Web client to send requests to Envoy over HTTP/1.1 and get proxied to a gRPC server» — gRPC-Web-клиент может прийти к Envoy даже по HTTP/1.1 и получить проксирование к gRPC-серверу. Что именно переводит фильтр? Главное отличие протокола — статус уезжает в теле: «Response status encoded as part of the response body»; по спецификации «8th (MSB) bit of the 1st gRPC frame byte» помечает фрейм как трейлеры, а не как данные, и «Trailers must be the last message of the response, as enforced by the implementation» — трейлеры всегда последнее сообщение ответа. Фильтр упаковывает grpc-status в тело на обратном пути — и браузер, читающий тело, наконец видит статус вызова.

Envoy из этого урока — прокси, который вы конфигурируете вручную. В Kubernetes на границе кластера чаще стоит ingress-controller: объект Ingress описывает, какой хост и путь в какой сервис ведёт, а контроллер (nginx-ingress — самый распространённый) превращает это в конфиг своего прокси. По смыслу это тот же слой, что Envoy выше: listener на 443, маршрутизация по хосту и пути, TLS-терминация по k8s-секрету. Отличие — в умолчаниях: nginx по умолчанию говорит с бэкендом по HTTP/1.1, что для gRPC означает ровно ту же ловушку, что мы разбирали выше, — и лечится аннотацией. Документация ingress-nginx про неё дословно: «Using backend-protocol annotations is possible to indicate how NGINX should communicate with the backend service» — аннотация говорит NGINX, как общаться с бэкендом, — и дальше: «Valid Values: HTTP, HTTPS, AUTO_HTTP, GRPC, GRPCS and FCGI», а также «By default NGINX uses HTTP» — по умолчанию HTTP/1.1, то есть без аннотации gRPC-вызовы до пода не доедут. Значение GRPC включает HTTP/2 к бэкенду без TLS — тот самый h2c из TLS-терминации: внешний сертификат терминируется самим ingress-controller, а нога к поду остаётся plaintext внутри кластера. Значение GRPCS — то же самое, но с TLS и до пода: берите его, когда периметру мало, — серверный сертификат при этом живёт в k8s-секрете и монтируется в под, механика рукопожатия всё та же из двенадцатого урока. Честная оговорка: ingress-controller — это самостоятельный прокси со своим набором слов; Envoy-фрагменты этого урока — словарь Envoy, nginx — словарь nginx, но деление на ноги «снаружи TLS, внутри plaintext» и требование HTTP/2 до gRPC-бэкенда у них общие.

Семнадцатый урок дал вашему серверу health-сервис: grpc.health.v1 с Check и Watch, SetServingStatus на жизненном цикле. С тех пор у него накопились потребители: Kubernetes-пробы, healthCheckConfig канала из шестнадцатого урока — и теперь ещё прокси. Идея активной проверки: Envoy не ждёт, пока живой трафик наткнётся на мёртвый бэкенд, а сам по расписанию шлёт каждому endpoint-у запрос и по ответу решает, держать ли его в ротации. Формат проверки — знакомый: документация health_check.proto описывает grpc_health_check как «grpc.health.v1.Health-based healthcheck» — проверку на базе grpc.health.v1.Health, того самого протокола из семнадцатого урока. Поле service_name в ней объяснено честно: «An optional service name parameter which will be sent to gRPC service in grpc.health.v1.HealthCheckRequest message» — необязательное имя сервиса, которое уедет в HealthCheckRequest; пустое значение спрашивает статус сервера целиком, конкретное — статус одного сервиса, как в SetServingStatus. Пороги делают проверку устойчивой к дребезгу: два провала подряд выводят endpoint из ротации, два успеха подряд возвращают. Отличите активные проверки от пассивных: outlier detection — это статистика по реальному трафику (ошибки и таймауты реальных вызовов), его Envoy включает рядом, но они требуют трафика, тогда как активные пробы работают даже на простаивающем бэкенде. В прошлом уроке health уже был координатором релизного конвейера — здесь он выполняет ту же работу на ступени прокси: неготовый под, выведенный в NOT_SERVING, перестаёт получать трафик от прокси до восстановления. Один контракт, ещё один потребитель — ничего нового серверу отдавать не нужно.

Честная оговорка про формат, одна на урок: в самоучителе есть песочница с интерпретатором Go, но сеть в браузере недоступна — прокси, TLS-сертификаты и ingress-controller в ней не поднять, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет; проверяют вас quiz, predict, fill, order и карточки, а руками делайте локально — всё по силам вечеру. Эксперимент первый, Envoy: возьмите сервер из четвёртого урока, запустите Envoy с конфигом из этого урока (в docker это одна команда с -v на envoy.yaml) и пройдите grpcurl-ом через 8080; затем уберите http2_protocol_options и убедитесь, что всё сломалось — лучшей демонстрации важности этого ключа не придумать. Эксперимент второй, gRPC-Web: добавьте grpc_web_filter в http_filters и напишите десяток строк на JavaScript с fetch из predict-задания; в devtools найдите последний фрейм тела и проверьте бит 10000000b. Эксперимент третий, TLS: выпустите самоподписанный сертификат openssl-ом как в двенадцатом уроке, повесьте на listener transport_socket и сравните две ноги tcpdump-ом или в логах: снаружи — шифрованные байты, внутри — читаемый HTTP/2. Эксперимент четвёртый, health: выведите сервер в NOT_SERVING через SetServingStatus и посмотрите по admin-логам Envoy, как endpoint выйдет из ротации после двух провалов и вернётся после восстановления.

Инфраструктурный слой курса закрыт: сервер не менялся весь урок, зато у него появились listener, routes и cluster, TLS на границе, мост для браузера и пробы по grpc.health.v1 — всё в YAML, всё без единой строки бизнес-кода. Остаётся применить всё сразу: двадцать пятый урок — итоговый проект, двусторонний чат и файловый сервис на bidi-стримах и стриминговых загрузках, где вам понадобится весь курс разом: контракты из второго урока, стримы из седьмого и девятого, дедлайны из четырнадцатого, тесты из двадцать первого. С одним предупреждением из этого урока: стримы через прокси едут, но bidi через gRPC-Web ограничен платформой браузера — нативные клиенты проезжают всё, браузерным клиентам честно проектируйте границы. Полный маршрут курса со всеми уроками — в оглавлении gRPC-курса: до финала один шаг.