はじめに

Emissary-Ingress とはトラフィックルーティングやロードバランシングなどの機能を提供する、Envoy Proxy ベースの Kubernetes ネイティブな API Gateway です。また、Emissary-Ingress は CNCF プロジェクトにて 2021 年 4 月 13 日に Incubating レベルのプロジェクトと認定されたプロジェクトです。

Emissary-Ingress was accepted to CNCF on April 13, 2021 at the Incubating maturity level.

引用元: CNCF | Emissary-Ingress

本記事では、Emissary-Ingress quick start を参考に、Minikube を使用してローカル環境の Kubernetes クラスターに Emissary-Ingress をセットアップし、簡単なデモアプリケーションへのルーティングを設定する手順を試します。

想定されるインフラ構成は下図のとおりです。

前提条件

Kubernetes クラスター v1.32.0
Minikube v1.35.0
kubectl v1.33.0
Helm v3.17.3
Emissary-Ingress の Helm Chart v8.12.2
Emissary-Ingress のアプリケーション v3.12.2

1. Kubernetes クラスターの起動

Minikube を使用して下記のコマンドを実行し、Kubernetes クラスターを起動します。
今回は driver に docker を選択することにします。

$ minikube start --driver=docker

起動が完了したら、

$ kubectl config current-context

を実行して、接続先のクラスターが Minikube のクラスターとなっていることを確認します。
確認ができたら、別のウィンドウのシェルで下記のコマンドを実行します。

$ minikube tunnel

このコマンドを実行しないと以降の手順で Emissary-Ingress を起動しても下記の通り、EXTERNAL_IP が pending 状態で、公開 IP が割り当てられなくなってしまうので注意する必要があります。

NAME                     TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE
emissary-ingress         LoadBalancer   ${CLUSTER-IP}   <pending>     80:30753/TCP,443:30383/TCP   Xs

2. Emissary-Ingressのインストール

Helm を使用して Emissary-Ingress をインストールします。

# ローカルに Emissary-Ingress のリポジトリへの紐付けを追加する。
$ helm repo add datawire https://app.getambassador.io
$ helm repo update

# 名前空間の追加とCRDのインストール
$ kubectl create namespace emissary && kubectl apply -f https://app.getambassador.io/yaml/emissary/3.9.1/emissary-crds.yaml
$ kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
# Emissary-Ingress のインストール
$ helm install emissary-ingress --namespace emissary datawire/emissary-ingress && kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress

ここまで完了すると Emissary-Ingress の本体の起動と Emissary-Ingress が使用する CRD のインストールが完了します。

3. トラフィックルーティングの設定

Emissary-Ingress は、Kubernetes Custom Resource Definitions (CRDs)を使用して設定を行います。まず、HTTP通信を受け付けるための Listener リソースを作成します。

$ kubectl apply -f - <<EOF
---
apiVersion: getambassador.io/v3alpha1
kind: Listener
metadata:
 name: emissary-ingress-listener-8080
 namespace: emissary
spec:
 port: 8080
 protocol: HTTP
 securityModel: XFP
 hostBinding:
   namespace:
     from: ALL
EOF

この Listener は、クラスター内のすべての Host と関連付けられ、ポート 8080 で HTTP リクエストを受け付けるように設定されています。

kubectl apply 時に使用するマニフェストは Here Document を使用する意外に、マニフェストファイルとして設定を記述し、そのファイルを読み込むことで Listener を作成することも可能です。

4. デモアプリケーションのデプロイ

次に、「Quote」というデモサービスをデプロイします。

$ kubectl apply -f https://app.getambassador.io/yaml/v2-docs/3.9.1/quickstart/qotm.yaml

上記コマンドにて、サービスとデプロイメントがデフォルト名前空間に作成されます。
実際に、以下のコマンドで実行することでこれらの状態を確認することが可能です。

$ kubectl get services,deployments quote

5. Mapping リソースの作成

Emissary-Ingress に、/backend/ パスへのリクエストを Quote サービスにルーティングする Mapping リソースを作成します。

$ kubectl apply -f - <<EOF
---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
 name: quote-backend
spec:
 hostname: "*"
 prefix: /backend/
 service: quote
 docs:
   path: "/.ambassador-internal/openapi-docs"
EOF

これで事前の準備が完了しました。
実際にローカル環境で Emissary-Ingress へアクセスをして動作確認をします。

6. サービスへのアクセス

以下のコマンドを実行して、ステータスコード 200 がレスポンスとして得ることができればローカルで Emissary-Ingress を動かしてみる作業は完了です。

# 実行コマンド
$ curl -i http://localhost/backend/
# レスポンス(返されるデータはリクエストごとに異なります)
 HTTP/1.1 200 OK
 content-type: application/json
 date: Mon, 28 Apr 2025 15:16:47 GMT
 content-length: 140
 x-envoy-upstream-service-time: 25
 server: envoy
 {
   "server": "mirthful-blackberry-4wk3ol8l",
   "quote": "A small mercy is nothing at all?",
   "time": "2025-04-28T15:16:47.205112Z"
 }

まとめ

今回は Emissary-Ingress を Minikube を使用したローカル環境の Kubernetes クラスターにインストールし、簡単なルーティング設定を行いました。Emissary-Ingressには、非常に高度な Kubernetes ネイティブ API Gateway ソリューションを提供しています。

そのため、実際に本番環境で使用する場合には、以下を一例とした高度な機能の設定追加を検討することが可能です。