Envoy Gateway ベストプラクティス: 本番前に未来の自分を助ける

「動く」と「システムとして安定している」は、まったく別の宇宙の話です。入口層の事故の多くは Envoy Gateway の機能不足ではなく、設定をラフに作りすぎて、運用がずっとサプライズボックス化してしまうことから起きます。この記事では、実践上かなり効く推奨事項を checklist としてまとめます。

推奨プラクティス

1. Gateway を誰が持ち、Route を誰が持つかを明確にする

複数人が関わるなら、責務を分けましょう。

Platform team が GatewayClass, Gateway を管理する
App team が各自の HTTPRoute を管理する

この分担の利点は、入口層のセキュリティや公開面が各 app によって無秩序に変わらず、それでいて app team は routing の柔軟性を持てることです。これこそ Gateway API の設計価値なので、せっかくの分離をまた巨大な YAML の塊に戻さないことです。

2. 最初から TLS をデフォルトとして扱う

「まず HTTP、あとで HTTPS」を前提にしないでください。その「あとで」はだいたい金曜夜の緊急対応になります。

最低限:

外向き listener は HTTPS をデフォルトにする
証明書の取得元と管理プロセスを決めておく
テスト用、self-signed、本番 CA のフローを分ける

すでに cert-manager があるなら連携しましょう。更新のたびに Secret を手 patch するより、証明書ローテーションを自動化したほうが圧倒的に信頼できます。

3. Route ルールは明示的に書き、便利さのために省略しすぎない

次のような rule は便利ですが、ブラックホール化しやすいです。

rules:
  - backendRefs:
      - name: backend
        port: 8080

間違いではありません。ただ、システムが育つにつれて、「何でも受ける」rule が増えるとデバッグがかなり痛くなります。 hostnames を書けるなら書く、path を書けるなら書く。はっきり書くほうが後で助かります。

4. トラフィックは小さく切り、いきなり全振りしない

新 version を出すときは、最初に小さい割合だけ流します。

backendRefs:
  - name: api-v1
    port: 8080
    weight: 90
  - name: api-v2
    port: 8080
    weight: 10

これは「service selector を一撃で全切り替え」するよりずっと穏やかです。問題が起きたときの rollback も圧倒的に速いので、深夜 3 時の自分が本当に感謝します。

5. `status` と event を見る習慣を持つ

YAML を読むだけでは足りません。controller が実際に設定を受け取ったか確認する必要があります。

kubectl get gateway -A
kubectl get httproute -A
kubectl describe gateway eg
kubectl describe httproute app-route

次の種類の問題は spec だけでは見抜きにくいです。

Route が accepted されていない
Cross-namespace reference がブロックされている
Listener status が異常

最悪なのは bug そのものより、「効いたと思っていたが、そもそも一度も取り込まれていなかった」です。

よくある落とし穴

Pitfall 1: Envoy Gateway をただの転送箱だと思う

これは単に packet を A から B に送るだけの箱ではありません。公式ドキュメントでも、Kubernetes-native な API Gateway として位置づけられており、トラフィックやセキュリティポリシーを積み上げる余地があります。Ingress 置き換えだけに使うなら、かなり持て余しています。

Pitfall 2: `ReferenceGrant` なしで Cross-Namespace 証明書を参照する

certificateRefs に namespace field が書けるのを見て、そのまま別 namespace を指して「なぜ何も起きないのか」と悩む人は多いです。原因はたいてい怪奇現象ではなく、ReferenceGrant の不足です。

Pitfall 3: Happy path しか試さない

次だけを確認して終わらせないでください。

curl http://... が 1 回成功する

あわせて次も試してください。

異なる hostname
異なる path
TLS 証明書の妥当性
traffic split の比率が想定通りか

入口層が怖いのは、happy path だけ完璧に見えて、端のケースで即死することです。

Pitfall 4: デモ設定をそのまま本番へ持ち込む

公式 quickstart は学習用としてとても優秀ですが、あくまで quickstart です。本番では最低でも次を足しましょう。

証明書自動化
監視と alerting
変更管理プロセス
Route の命名規約

そうしないと、今日の quickstart は明日の事故の種になります。

最小の本番前 checklist

本番公開前にこれを使ってください。

Gateway listener は HTTP / HTTPS を明確に分けているか
certificate Secret と rotation 手順は明確か
HTTPRoute に明確な hostnames / matches があるか
重要な変更は小さな traffic cut で出しているか
status と event から素早く問題箇所を特定できるか

この 5 つがそろっていれば、「動いてるから大丈夫」の段階よりかなり上です。

一文まとめ

Envoy Gateway の本当の価値は、単にトラフィックを流すことではなく、入口層の設定をより標準化し、分割可能にし、ガバナンスしやすくすることです。機能は一時的ですが、運用は長期戦です。未来の自分に優しくするのは、本当に意味があります。

次の一歩

もしまだ頭の片隅に次の疑問があるなら:

「概念はわかったけど、新しい要件が来たとき実際どの route type を選べばいいの?」

次の記事がそのチートシートです。 👉 Route Type チートシート