Contents
前提条件と環境準備
このセクションでは、Istio Ingress Gateway を本番環境に導入するために最低限必要な Kubernetes クラスタのバージョンや、利用するツール（kubectl・helm・istioctl）のインストール手順を確認します。適切なバージョンが揃っていないと、CRD の互換性エラーや API 変更による予期せぬ障害が発生しやすくなるため、最初に環境を整えることが重要です。
Kubernetes クラスタ要件
Kubernetes と Istio のバージョンは 公式でリリース済みの最新安定版 を使用します。2024 年 11 月時点では Istio 1.21.x が最新版であり、Kubernetes v1.26 以降を前提に動作が保証されています。
| 項目 | 推奨バージョン |
|---|---|
| Kubernetes | v1.26 – v1.29 |
| istioctl | 1.21.x |
| Helm | v3.12 以上 |
| kubectl | v1.26 以上 |
バージョン確認コマンド
|
1 2 3 4 |
kubectl version --short helm version --short istioctl version |
kubectl と helm のインストール
公式リリースページからバイナリを取得し、実行権限とパス設定だけで完了します。
|
1 2 3 4 5 6 7 |
# kubectl (Linux x86_64) curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" chmod +x kubectl && sudo mv kubectl /usr/local/bin/ # helm (Linux x86_64) curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash |
Namespace の作成
Istio 本体と Ingress Gateway を別々の名前空間に分離すると、権限管理やリソースの可視化が容易になります。
|
1 2 3 |
kubectl create namespace istio-system # Istio コアコンポーネント用 kubectl create namespace ingress-gateway # Ingress 用 |
Istio 本体および Ingress Gateway のインストール
この章では、istioctl と Helm の二つの方法で Istio 本体と Ingress Gateway をデプロイする手順を示します。どちらの方法でも Sidecar 自動注入 を有効化し、アプリケーション Pod に istio-proxy が自動的に付与されるように設定します。
istioctl を使ったインストール手順
istioctl install は公式が提供する最もシンプルなインストールコマンドです。デフォルトプロファイルを利用すれば、Istio コアと Ingress Gateway が自動的に作成されます。
|
1 2 3 4 5 6 |
# 利用可能なプロファイル一覧（推奨は default または minimal） istioctl profile list # デフォルトプロファイルでインストール istioctl install --set profile=default -y |
Sidecar 自動注入の有効化
istio-injection=enabled ラベルを付与した名前空間にデプロイされた Pod は、作成時に自動的に istio-proxy コンテナが追加されます。
|
1 2 |
kubectl label namespace default istio-injection=enabled |
ラベル付与後の確認方法は以下です。istio-proxy が表示されれば成功です。
|
1 2 |
kubectl get pods -n default -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.containers[*]}{.name}{" "}{end}{"\n"}{end}' | grep istio-proxy |
Helm chart でのインストールとカスタム values.yaml 設定例
Helm を利用すると、CRD のバージョンや Service の種類などを細かく制御できます。以下は Istio 本体 と Ingress Gateway を別々のリリースとしてデプロイする構成です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# values.yaml（gateway 部分のみ抜粋） gateway: enabled: true name: istio-ingressgateway namespace: ingress-gateway type: LoadBalancer # オンプレミスでは NodePort / MetalLB に変更可 ports: - port: 80 targetPort: 8080 name: http2 - port: 443 targetPort: 8443 name: https sidecarInjectorWebhook: enabled: true |
Helm インストールコマンド
|
1 2 3 4 5 6 7 8 9 10 |
helm repo add istio https://istio-release.storage.googleapis.com/charts helm repo update # 基本コンポーネント（CRD・Istiod） helm install istio-base istio/base -n istio-system --create-namespace helm install istiod istio/istiod -n istio-system --values values.yaml # Ingress Gateway helm install istio-ingressgateway istio/gateway -n ingress-gateway --values values.yaml |
Sidecar 注入の確認（Helm 版）
|
1 2 3 |
kubectl get namespace default -o jsonpath='{.metadata.labels}' # 出力に `istio-injection=enabled` が含まれていれば OK |
Gateway と VirtualService の作成と構造解説
Istio のトラフィック制御は Gateway と VirtualService という二つの CRD によって実現します。この章では、最新安定版で推奨されている networking.istio.io/v1beta1 をベースに、それぞれの主要項目とサンプル YAML を解説します。
Gateway リソースの定義
以下は Ingress Gateway 用の最小構成です。v1beta1 がデフォルトで有効化されているため、互換性を保ちつつ新機能も利用できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
apiVersion: networking.istio.io/v1beta1 kind: Gateway metadata: name: my-ingress-gateway namespace: ingress-gateway spec: selector: istio: ingressgateway # デフォルトの IngressGateway ラベル servers: - port: number: 80 name: http protocol: HTTP hosts: - "*" |
- selector は対象となる Envoy Pod（Ingress Gateway）をラベルで指定します。
- servers 配列に公開したいポート・プロトコル・ホスト名を記述し、複数設定すれば HTTP と HTTPS を同時に提供できます。
VirtualService リソースの定義
VirtualService は実際のリクエスト振り分けロジックを記述します。以下は /api パスへのリクエストを my-service へ転送する例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
apiVersion: networking.istio.io/v1beta1 kind: VirtualService metadata: name: my-api-vs namespace: default spec: hosts: - "*" gateways: - ingress-gateway/my-ingress-gateway # フルネームで指定 http: - match: - uri: prefix: "/api" route: - destination: host: my-service.default.svc.cluster.local port: number: 8080 |
- gateways では先ほど作成した
Gatewayのフルネームを列挙し、どのゲートウェイがこの VirtualService を利用するかを明示します。 - match / route によって URI パスとバックエンド Service の組み合わせを定義でき、ヘッダーやクエリパラメータでの高度なマッチングも可能です。
トラフィック公開と動作確認
この章では Ingress Gateway を外部に公開し、実際にリクエストが期待通りにルーティングされるかを検証します。LoadBalancer が利用できないオンプレミス環境向けの代替策も併せて紹介します。
Service タイプ選択と外部 IP の取得方法
istio-ingressgateway はデフォルトで LoadBalancer 種類の Service として作成されます。クラウドプロバイダーが自動的に外部 IP を割り当てる場合は次のコマンドで確認できます。
|
1 2 |
kubectl get svc istio-ingressgateway -n ingress-gateway -o wide |
オンプレミス環境向け代替策
| 方法 | 説明 | 主な設定ポイント |
|---|---|---|
| NodePort | 各ノードの固定ポートを公開し、外部ロードバランサーや DNS でルーティング | type: NodePort に変更し、nodePort: を指定（例: 30080） |
| MetalLB | オンプレミスでも LoadBalancer と同等の IP 割り当てが可能なオープンソース実装 | MetalLB の ConfigMap に address-pool を設定し、Service は従来どおり LoadBalancer を使用 |
| HostNetwork + DaemonSet | Envoy がホストネットワーク上で直接リッスンし、NodePort 不要 | Deployment の hostNetwork: true と dnsPolicy: ClusterFirstWithHostNet を設定（高度な運用が必要） |
MetalLB の簡易インストール例：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.5/manifests/namespace.yaml kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.5/manifests/metallb.yaml # ConfigMap（例: 192.168.10.240‑192.168.10.250 をプール） cat <<EOF | kubectl apply -f - apiVersion: v1 kind: ConfigMap metadata: namespace: metallb-system name: config data: config: | address-pools: - name: default protocol: layer2 addresses: - 192.168.10.240-192.168.10.250 EOF |
エンドポイントのテスト例
外部 IP（または NodePort）取得後に、curl で実際にリクエストを投げます。
|
1 2 3 4 5 6 7 |
# LoadBalancer の場合 EXTERNAL_IP=$(kubectl get svc istio-ingressgateway -n ingress-gateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}') curl -s http://${EXTERNAL_IP}/api/hello | head -n 5 # NodePort の場合（例: 30080） curl -s http://<node-ip>:30080/api/hello |
期待される JSON 応答例：
|
1 2 |
{"message":"Hello from my-service"} |
Istio 状態確認コマンド
- proxy-status：Envoy の構成同期状態を即座に把握できます。
bash
istioctl proxy-status -n default
- proxy-config：特定 Pod のリスナーやルーティングテーブルを詳細に表示。
bash
istioctl proxy-config listeners <pod-name> -n default
- Prometheus メトリクス（導入済みの場合）：
bash
kubectl -n istio-system port-forward svc/prometheus 9090:9090 &
curl -s "http://localhost:9090/api/v1/query?query=istio_requests_total{destination_service=\"my-service.default.svc.cluster.local\"}"
TLS/HTTPS と mTLS 設定、設定変更とロールバック
安全な通信を確保するために、Ingress Gateway の TLS 終端とサービス間の相互認証（mTLS）を有効化します。また、設定ミス時の迅速なロールバック手順も併せて紹介します。
TLS 終端用 Secret の作成と Gateway への適用
まずは証明書と秘密鍵を Kubernetes Secret に格納し、Gateway の tls セクションで参照させます。実運用では cert‑manager と連携させることが推奨されます。
|
1 2 3 4 5 |
kubectl create secret tls istio-ingressgateway-certs \ -n ingress-gateway \ --cert=./tls.crt \ --key=./tls.key |
次に HTTPS 用サーバー定義を Gateway に追加します（v1beta1 を使用）。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
apiVersion: networking.istio.io/v1beta1 kind: Gateway metadata: name: my-secure-gateway namespace: ingress-gateway spec: selector: istio: ingressgateway servers: - port: number: 443 name: https protocol: HTTPS tls: mode: SIMPLE # TLS 終端のみ（PASSTHROUGH は別途設定） credentialName: istio-ingressgateway-certs hosts: - "example.com" |
|
1 2 |
kubectl apply -f secure-gateway.yaml |
サービス間の mTLS 有効化
Namespace 全体で STRICT モードを適用すると、同一 Namespace 内のすべてのサービス間通信が自動的に暗号化されます。
|
1 2 3 4 5 6 7 8 9 |
apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: name: default-strict-mtls namespace: default spec: mtls: mode: STRICT |
|
1 2 |
kubectl apply -f peer-auth.yaml |
設定変更の即時反映と安全なロールバック手順
Istio の CRD は kubectl apply によって即座に Envoy に配信されますが、万一不具合が発生した場合は以下のフローで元に戻します。
- 変更前 YAML を必ず保存（例:
gateway_v1.yaml）。Git で管理すれば履歴が残ります。 - 新しい設定を適用
bash
kubectl apply -f gateway_v2.yaml
- 問題が判明したら直前のファイルで置き換える
bash
kubectl replace -f gateway_v1.yaml
kubectl rollout undo は Deployment 系リソース専用なので、CRD（Gateway・VirtualService）では replace が安全です。
トラブルシューティングとベストプラクティス
実運用でよく遭遇する障害シナリオを整理し、迅速に原因切り分けできるチェックリストと、安定運用のために推奨されるベストプラクティスをまとめます。
代表的な障害ケースと対処法
| 障害シナリオ | 主な原因 | 確認・対処手順 |
|---|---|---|
| Pod が Ready にならない | Sidecar 注入失敗、イメージプルエラー、リソース不足 | kubectl describe pod <pod> → イベントで istio-proxy の起動ログを確認。必要なら istio-injection=disabled に切り替えて Pod を再作成 |
| Envoy 設定が反映されない | Gateway / VirtualService の spec.gateways が不一致、CRD バージョンミスマッチ |
istioctl proxy-config listeners <pod> -n <ns> でリスナー一覧を確認。対象 Gateway 名が正しいかチェック |
| HTTPS アクセスで証明書エラー | Secret 名の誤記、TLS モード設定ミス、証明書期限切れ | kubectl get secret istio-ingressgateway-certs -n ingress-gateway -o yaml でデータが存在するか確認。mode: SIMPLE が正しく設定されていることも併せてチェック |
| mTLS が有効にならない | PeerAuthentication が別 Namespace に限定、mtls.mode が DISABLE になっている |
kubectl get peerauthentication -A で全体を一覧表示し、対象 Namespace の設定が STRICT か確認 |
| LoadBalancer の外部 IP が取得できない | クラウドプロバイダーの制限、Service Type 誤設定、MetalLB 未導入 | kubectl describe svc istio-ingressgateway -n ingress-gateway → イベントでエラーを確認。オンプレミスなら NodePort または MetalLB に切り替え |
運用上のベストプラクティスまとめ
- Namespace 毎に Sidecar 注入を明示的に管理
- 必要な Namespace にだけ
istio-injection=enabledを付与し、テスト環境やバッチジョブは無効化してリソース消費を抑制。 - GitOps による YAML 管理
- 全 CRD（Gateway・VirtualService・PeerAuthentication 等）は Git リポジトリでバージョン管理し、
kubectl apply -f前に CI パイプラインでistioctl verify-installを走らせて構文エラーを防止。 - Observability の標準化
- Prometheus と Grafana は Istio デフォルトのダッシュボードを有効化し、
istio_requests_total,istio_tcp_sent_bytes_totalなど主要メトリクスで SLA を監視。 - TLS 証明書の自動更新
- cert‑manager と Istio の
credentialNameを連携させ、証明書有効期限切れによるサービス停止を未然に防止。 - ロードバランサーの冗長化
- クラウド環境では複数リージョンに跨った LoadBalancer、オンプレミスでは MetalLB の
layer2モードと外部 HAProxy の組み合わせで可用性を確保。
上記手順とチェックポイントを遵守すれば、Istio Ingress Gateway の導入から本番運用までを安全かつ効率的に進められます。