#kubernetes#envoy-gateway#gateway-api#envoy-proxy#ingress

K8S Envoy Gateway シリーズ概要: Ingress よりモダンなトラフィック入口

12 min read

Kubernetes の外部トラフィックを触ったことがあるなら、最初に Ingress から入った可能性は高いと思います。実際ちゃんと動きますし、多くの場面では本当にそれで十分です。ですが、要件が少し複雑になってくると、たとえば複数 listener、複数チームでの運用、gRPC、TCP、TLS passthrough、細かなトラフィックポリシーなどにぶつかった瞬間、結局は「annotation で延命する」が常態化しがちです。YAML は呪文集みたいになり、保守する側も封印を解いている気分になります。

そこで登場するのが Gateway API + Envoy Gateway です。これが新しい道具立てです。複雑さを増やすのではなく、これまで一つに絡まりがちだった責務をきれいに分離してくれるので、入口トラフィック、ルーティングルール、TLS セキュリティ設定、プロトコル種別、チームごとの責任分界をずっと整理して考えやすくなります。

つまり何なのか

まずは一文でまっすぐ言うとこうです。

  • Envoy Proxy: 実際にトラフィックを受けてリクエストを転送するデータプレーン。Gateway Proxy と呼ばれることもあります
  • Envoy Gateway: Envoy Proxy をあなたの代わりに管理するコントロールプレーン
  • Gateway API: Kubernetes 上でトラフィックルールを宣言するための標準インターフェース

イメージとしてはこうです。

  • Gateway API は要件を書く場所
  • Envoy Gateway は翻訳して采配するマネージャー
  • Envoy Proxy は実際に入口に立つガード

この分離の利点は、低レベルな Envoy の設定を手で組まなくてよいこと、さらに各 controller 独自の private annotation を全部暗記しなくてよいことです。Kubernetes リソースとして宣言すれば、Envoy Gateway がそれを Envoy Proxy が実行できる設定へ変換してくれます。

Gateway と Ingress の違い

短く言うと、Ingress が時代遅れになったわけではないけれど、ガバナンスが必要な中規模以上のシステムでは Gateway API のほうが向いています。

比較項目 Ingress Gateway API
Ingress モデル 多くは入口とルーティングを 1 オブジェクトにまとめる GatewayClass、Gateway、Route に分離
表現力 主に HTTP/HTTPS。高度な機能は annotation 依存 複数の Route type をネイティブに表現でき、field も明確
拡張モデル 多くの機能が controller 独自 annotation 依存 標準 field を持ち、CRD による拡張点もある
プロトコル対応 基本は HTTP/Web 中心 HTTPRoute、GRPCRoute、TCPRoute、TLSRoute をサポート
チーム分担 Platform と app の設定が混ざりやすい Platform team が入口、app team が route を持ちやすい
可搬性 annotation が特定 controller に縛られがち より標準化され、実装間でも読みやすい

要件が例えば次の程度なら:

  • 単一サイトかシンプルな API
  • 基本的な path/host ルーティング
  • 小規模チーム

Ingress のままでも十分です。ですが、要件が次のようになってくると:

  • 一つの入口で複数プロトコルを扱う
  • 複数 listener、ドメイン、証明書がある
  • HTTP と gRPC が共存する
  • Platform の入口管理と app の route 権限を分けたい
  • annotation の寄せ集めではなく、ちゃんと API っぽく読める設定にしたい

Gateway API がかなり魅力的に見えてきます。

なぜ Ingress ではなくこちらなのか

Gateway API の公式な狙いは、スケールした Ingress のよくある痛みを解消することです。

  • より高い表現力: Routing、TLS、traffic policy、protocol type がより明確
  • より高い可搬性: controller 固有の private annotation への依存を減らせる
  • より自然な責務分離: Platform team が入口を持ち、app team が route を持つ

たとえば Ingress の設定は、しばしばこんな感じになります。

metadata:
  annotations:
    some.ingress.controller/rewrite-target: /
    some.ingress.controller/auth-type: basic
    some.ingress.controller/ssl-redirect: "true"

動かないわけではありません。でも要件が増えるほど、annotation は謎めいた YAML 黒魔術になりやすい。Gateway API はそれを正規の field に引き上げてくれます。読むと「願望リスト」ではなく「設定」に見えます。

レイヤー構造

公式の概念ページでは Envoy Gateway を 3 層に分けています。この図は頭に入れておく価値があります。

  • User Configuration: あなたが書く Gateway API リソースと Envoy Gateway 拡張 CRD
  • Envoy Gateway Controller: それらを読み取り、実行可能な設定へ変換する
  • Envoy Proxy: 実際のライブトラフィックを処理するデータプレーン

実運用では、SSH で proxy に入って低レベル設定をいじるより、ほとんどの時間をこの「宣言レイヤー」の更新に使います。これが Kubernetes-native であることの美しさです。

このシリーズで学ぶこと

このシリーズは「まず動かし、その後で掘る」順番で進みます。この概要を含めて全 10 本です。

  1. クイックスタート: Envoy Gateway をインストールし、最初の HTTP リクエストを end-to-end で通す
  2. コア概念: GatewayClass、Gateway、Listener、Envoy Proxy の役割を理解する
  3. 実践 HTTP ルーティング: HTTPRoute を深掘り。host、path、header、filter、timeout
  4. TLS とセキュリティ: HTTPS を設定し、certificateRefs、TLS termination、TLSRoute を理解する
  5. ベストプラクティス: 本番前に押さえておきたい重要な習慣
  6. Route Type チートシート: HTTPRoute、GRPCRoute、TCPRoute、TLSRoute の選び分けを素早く判断する
  7. Listener 設計ガイド: マルチポート、複数 hostname、複数入口の設計パターン
  8. 複数 namespace とチーム分担: allowedRoutes、ReferenceGrant、共有入口のガバナンスを理解する
  9. ステータスとデバッグ手引き: Accepted、ResolvedRefs、Programmed を読み、最短のトラブルシュート経路をたどる

「とりあえず Envoy Gateway がどんなものか体感したい」なら、次の記事にそのまま進んでください。用語を全部暗記するより、まず動かすほうが早いです。筋トレと同じで、YouTube を 30 本見るよりまずジムに行くほうが強いです。

これから出てくる主要リソース

初学者がつまずきやすいのは、Gateway API は Gateway と HTTPRoute だけだと思い込むことです。実際にはリソースのファミリーがあります。

GatewayClass

「この cluster でどの Gateway 実装を使うか」を定義します。 Envoy Gateway では controllerName が正しい controller を指していることが重要です。

Gateway

「この入口がどう見えるか」を定義します。 たとえば、どの port を開けるか、どの protocol を受けるか、TLS をどう付けるか、どの route を許可するか、などです。

Listener

Listener は Gateway の中でも最重要クラスの一つです。 Gateway の外向きスロットのようなもので、各スロットが次を定義します。

  • port
  • protocol
  • hostname
  • TLS config
  • allowedRoutes

Gateway を黒箱のように捉える人は多いですが、実際に入口の挙動を決めているのは、その中の各 listener です。

Route ファミリー

  • HTTPRoute: HTTP/HTTPS トラフィック。最も一般的
  • GRPCRoute: gRPC トラフィック。service/method でマッチできる
  • TCPRoute: 生の TCP トラフィック。HTTP の意味は解釈しない
  • TLSRoute: TLS SNI ベースでルーティング。TLS passthrough でよく使う

すべての route に共通すること: 「ドアを開ける」のではなく、「入ってきた後にどう流すか」を決めるのが route です。

最小メンタルモデル

この地図を頭に置いてください。

GatewayClass  # この cluster でどの Gateway 実装を使うか
Gateway       # この入口がどの listener を開くか
Listener      # port / protocol / hostname / TLS のスロット
Route         # 入ってきた後のトラフィック分配方法
Service       # cluster 内で実際にリクエストを処理する backend
Envoy Proxy   # 最終的にトラフィックを扱うデータプレーン

最小の例はこうです。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo
spec:
  parentRefs:
    - name: eg
  hostnames:
    - "www.example.com"
  rules:
    - backendRefs:
        - name: backend
          port: 3000

今すべての field を暗記する必要はありません。何をしているかだけ把握すれば十分です。

  • parentRefs: このルールがどの Gateway にぶら下がるか
  • hostnames: どのドメインに対してこのルールを適用するか
  • backendRefs: どの Service に流すか

ひと目でわかる: どの Route を使うか

要件 推奨リソース
Web サイト、REST API、header/path routing HTTPRoute
gRPC service/method routing GRPCRoute
純粋な TCP サービス（独自 protocol や非 HTTP） TCPRoute
end-to-end TLS を保ち、Gateway で復号しない TLSRoute

この判断表はかなり実用的です。YAML を書く前にまず自分へこう聞いてください。

「今扱っているのは HTTP なのか、gRPC なのか、それとも生の TCP/TLS トラフィックなのか?」

一文まとめ

Envoy Gateway は、また一つ覚えるだけの用語ではありません。Kubernetes の外部トラフィックを「とりあえず動く」から「ちゃんと工学っぽいシステム」へ引き上げるためのやり方です。

💡 このスタックが初めてなら、最初からすべての CRD を覚えようとしなくて大丈夫です。まずインストールして、最初のリクエストを通してから概念に戻るほうが、吸収速度はかなり上がります。

次の一歩

次の記事では実際に手を動かします。cluster に Envoy Gateway をインストールして、最初の Gateway + HTTPRoute を通してみましょう。 👉 クイックスタート