Contents
前提条件と環境準備
このセクションでは、Istio が期待どおりに動作するための Kubernetes バージョン と CLI ツール のインストール手順を示します。バージョンが要件未満の場合、CRD の適用や Admission Webhook が失敗し、コントロールプレーンやサイドカーが正常に起動できません。
1. Kubernetes バージョンの確認
Istio は Kubernetes 1.24 以降 を公式にサポートしています（2024‑04 時点）。それ以前のバージョンでは、gateway.networking.k8s.io/v1beta1 など新しい API が利用できず、CRD の作成が失敗する可能性があります【¹】。実運用環境では、最低でも 1.24 以上 を推奨します。
|
1 2 |
kubectl version --short # Client と Server のバージョンを確認 |
ポイント：クラスターが要件を満たさない場合は、アップグレード手順（
kubeadm upgradeやマネージドサービスのバージョン切替）を先に実施してください。
2. 必要な CLI ツールのインストール
以下のツールはすべて公式バイナリから取得することで、OS に依存せず同一バージョンを保証できます。パッケージマネージャー経由だとリポジトリ更新が遅れるケースがあるため、手動ダウンロードを推奨します。
| ツール | 推奨取得方法 | 確認コマンド |
|---|---|---|
kubectl |
https://dl.k8s.io/release/ から最新安定版 (v1.28.x 等) をダウンロード |
kubectl version --client --short |
helm |
Helm 公式スクリプト get-helm-3 を実行 |
helm version --short |
istioctl |
Istio のリリースページから対象バージョンのスクリプトを取得 | istioctl version |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# 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 (v3.15) 例 curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash # istioctl (例: v1.22.x) ISTIO_VERSION=1.22.0 curl -L https://istio.io/downloadIstio | ISTIO_VERSION=$ISTIO_VERSION sh - sudo mv istio-$ISTIO_VERSION/bin/istioctl /usr/local/bin/ |
ポイント：インストール後はすべてのツールでバージョンが期待通りか再度確認し、要件を満たしていることを確実にしてください。
Istio コントロールプレーンのインストール
この章では、Istio のコントロールプレーンを デフォルトプロファイル でデプロイする手順と、istioctl と Helm の選択基準を比較します。どちらの方法でも同一の CRD が適用されますが、運用ポリシーに合わせて最適なツールを選んでください。
1. デフォルトプロファイルでのインストール
default プロファイルは、Pilot、IngressGateway、Telemetry のみを有効化した 最小構成 です。軽量かつ本番環境でも安全に使用できることが公式ドキュメントで推奨されています【²】。
|
1 2 3 4 |
istioctl install --set profile=default \ --set values.global.proxy.autoInject=enabled \ --set values.pilot.traceSampling=100 |
autoInject=enabled：Namespace ラベルに基づく自動サイドカー注入を有効化traceSampling=100：トレースデータの全件取得（テスト環境向け）
ポイント：インストール完了後は
kubectl get pods -n istio-systemでistiodとistio-ingressgatewayが稼働していることを確認します。
2. istioctl と Helm の比較
| 項目 | istioctl | Helm |
|---|---|---|
| 手順の簡潔さ | 単一コマンドで CRD・コンポーネント同時適用 | Chart の追加・インストールが必要 |
| バージョン管理 | istioctl が内部的に同梱するバージョンを使用 |
Chart バージョンで柔軟に切り替え可能 |
| カスタマイズ性 | --set オプションは限定的 |
values.yaml で細部まで設定可能 |
| アップグレード支援 | istioctl upgrade が公式フロー |
helm upgrade に任せられる |
| 推奨シナリオ | ハンズオンや単一クラスターの高速導入 | CI/CD パイプライン・マルチクラスター運用 |
結論：短期間で検証したい場合は
istioctl、長期的に複数クラスタを統一管理したい場合は Helm が適しています。
Namespace への自動サイドカー注入とサンプルアプリのデプロイ
この章では、Namespace 単位での自動サイドカー注入 を有効化し、公式サンプル (httpbin と sleep) を用いたマイクロサービス構成を実装します。Pod に istio-proxy が付与されていることを確認できれば、以降の mTLS 設定へスムーズに移行できます。
1. Namespace の自動注入を有効化
istio-injection=enabled ラベルが付与された Namespace は、新規作成 Pod に自動的に Envoy サイドカーを挿入します。手動で sidecar.istio.io/inject: "true" を記述する必要がなく、運用負荷が大幅に削減されます。
|
1 2 3 4 5 6 7 |
# Namespace 作成 & ラベル付与 kubectl create namespace demo kubectl label namespace demo istio-injection=enabled # ラベル確認 (結果例: ...istio-injection=enabled...) kubectl get namespace demo --show-labels |
ポイント：ラベルが正しく設定されたことを必ず確認し、次のデプロイに進んでください。
2. サンプルアプリ (httpbin + sleep) のデプロイ
以下のマニフェストは公式リポジトリから直接取得する例です。両方の Pod に自動的に istio-proxy コンテナが付与されることを確認します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
# httpbin デプロイ (サービスとデプロイが同時に作成) kubectl apply -n demo -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml # sleep デプロイ（curl が入った軽量コンテナ） cat <<'EOF' | kubectl apply -n demo -f - apiVersion: v1 kind: ServiceAccount metadata: name: sleep --- apiVersion: apps/v1 kind: Deployment metadata: name: sleep spec: replicas: 1 selector: matchLabels: app: sleep template: metadata: labels: app: sleep spec: serviceAccountName: sleep containers: - name: sleep image: curlimages/curl:8.7.1 command: ["/bin/sleep","3650d"] EOF |
確認手順：Pod が istio-proxy を含んでいるかを一覧表示します。
|
1 2 3 |
kubectl get pods -n demo -o jsonpath="{range .items[*]}{.metadata.name}{'\t'}{.spec.containers[*].name}{'\n'}{end}" # 期待出力例: httpbin-xxxxxx httpbin istio-proxy |
ポイント：
istio-injection=enabledが機能し、両アプリにサイドカーが注入されたことを確認できたら次の章へ進みます。
mTLS 設定と検証
このセクションでは、デフォルトの PERMISSIVE モードから STRICT への切り替え手順、サービス単位での強制適用例、および実際に暗号化が有効かどうかを確認するツール群を紹介します。
1. 全 Namespace を STRICT に変更
PeerAuthentication リソースは Namespace レベル のデフォルト TLS モードを定義します。以下のマニフェストで demo Namespace 全体に対し mTLS を必須 (STRICT) とします【³】。
|
1 2 3 4 5 6 7 8 9 |
apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: name: demo-strict namespace: demo # 空文字列にすると全クラスター対象になる spec: mtls: mode: STRICT |
|
1 2 |
kubectl apply -f peer-authentication-demo-strict.yaml |
モード確認：
|
1 2 3 |
istioctl authn tls-check demo httpbin # 出力例: TLS mode: ISTIO_MUTUAL (STRICT) |
ポイント：
PeerAuthenticationが適用された Namespace では、平文通信がブロックされ、すべてのサービス間トラフィックが mTLS に強制変換されます。
2. Service 単位で DestinationRule により明示的に mTLS を指定
個別サービスだけを対象にしたい場合は DestinationRule の tls.mode: ISTIO_MUTUAL（STRICT と同等）を利用します。以下は httpbin サービスへの適用例です。
|
1 2 3 4 5 6 7 8 9 10 11 |
apiVersion: networking.istio.io/v1beta1 kind: DestinationRule metadata: name: httpbin-mtls namespace: demo spec: host: httpbin.demo.svc.cluster.local trafficPolicy: tls: mode: ISTIO_MUTUAL # 等価に mtls.mode=STRICT |
|
1 2 |
kubectl apply -f destinationrule-httpbin.yaml |
ポイント：
PeerAuthenticationが上位レベルでPERMISSIVEのままであっても、DestinationRule により対象サービスだけを強制的に mTLS 化できます。
3. 動作検証ツールの活用
| ツール | 主な用途 | 実行例 |
|---|---|---|
istioctl authn tls-check |
単一リクエストの TLS モードを即時確認 | istioctl authn tls-check demo httpbin |
| Kiali (Web UI) | サービス間リンクが緑（TLS）か可視化 | kubectl -n istio-system port-forward svc/kiali 20001:20001 → http://localhost:20001 |
| Prometheus | メトリクスで mTLS 状態を集計 | istio_requests_total{mtls="true"} で成功率確認 |
ベストプラクティス：CLI で即時チェックし、Kiali と Prometheus のダッシュボードで継続的に mTLS が有効であることをモニタリングします。
段階的マイグレーションと Ingress Gateway の TLS/mTLS 設定
外部トラフィックは HTTPS で受け付け、内部通信は mTLS に統一する構成例を示します。段階的にポリシーを適用すれば、既存サービスへの影響を最小限に抑えられます。
1. 公式ガイドに沿ったマイグレーション手順
Istio は Mesh → Namespace → Service の順でポリシーの粒度を細かくしていくことを推奨しています【⁴】。以下は 4 フェーズに分割した例です。
| フェーズ | 適用対象 | ポリシー例 | 検証ポイント |
|---|---|---|---|
| 1 | Mesh 全体 (デフォルト) | PeerAuthentication mode: PERMISSIVE（既定） |
既存通信はそのまま |
| 2 | 特定 Namespace | PeerAuthentication mode: STRICT を対象 Namespace に適用 |
該当 Namespace のみ TLS 必須 |
| 3 | 個別 Service | DestinationRule で tls.mode: ISTIO_MUTUAL 設定 |
サービス単位の暗号化確認 |
| 4 | Mesh 全体に統一 | PeerAuthentication を全クラスター対象に STRICT に変更 |
すべてのトラフィックが mTLS |
各フェーズで istioctl authn tls-check と Kiali の可視化を行い、障害が出たら直前の段階にロールバックします。
2. Ingress Gateway 用 TLS 証明書の作成・適用
外部から HTTPS 接続を受け付けるため、IngressGateway に Kubernetes Secret として証明書を登録し、Gateway リソースで参照させます。以下は自己署名証明書の簡易例です（実運用では cert-manager などと連携してください）。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
# 1. 証明書・秘密鍵作成 (OpenSSL) openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -subj "/CN=example.com/O=demo" \ -keyout tls.key -out tls.crt # 2. Secret 作成 kubectl create secret tls example-credential \ --cert=tls.crt --key=tls.key -n istio-system # 3. Gateway リソースで証明書を参照 cat <<'EOF' | kubectl apply -f - apiVersion: networking.istio.io/v1beta1 kind: Gateway metadata: name: external-gateway namespace: istio-system spec: selector: istio: ingressgateway # デフォルトの IngressGateway servers: - port: number: 443 name: https protocol: TLS tls: mode: SIMPLE # 外部からの TLS 終端のみ credentialName: example-credential hosts: - "example.com" EOF |
ポイント：
mode: SIMPLEは外部 → IngressGateway のみ TLS を行い、内部は mTLS に切り替える前提です。
3. VirtualService で内部トラフィックを mTLS 化
Ingress が TLS 終端した後も、Envoy サイドカー同士の通信は暗号化されたままとするために VirtualService 側で tls.mode: ISTIO_MUTUAL を指定します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
apiVersion: networking.istio.io/v1beta1 kind: VirtualService metadata: name: httpbin-vs namespace: demo spec: hosts: - "example.com" gateways: - istio-system/external-gateway http: - match: - uri: prefix: "/" route: - destination: host: httpbin.demo.svc.cluster.local port: number: 8000 # 内部通信は mTLS (ISTIO_MUTUAL) で暗号化 tls: mode: ISTIO_MUTUAL |
ポイント：外部から
https://example.com/にアクセスすると、Ingress が TLS 復号し、その後 Envoy サイドカー同士が相互認証（mTLS）で httpbin へリクエストを転送します。
トラブルシューティングとベストプラクティス
導入段階でよく遭遇する問題と、安定運用のために抑えておきたいチェックポイントをまとめます。問題が起きた際は 「原因特定 → 再適用 → 検証」 の順序で対処すると効率的です。
1. サイドカー未注入の主な原因と対策
| 原因 | 確認手順 | 対応 |
|---|---|---|
| Namespace ラベル欠如 | kubectl get namespace demo --show-labels |
kubectl label namespace demo istio-injection=enabled --overwrite |
| Admission Webhook エラー | kubectl logs -n istio-system -l app=istiod | grep admission |
Webhook のエラーログを確認し、証明書や API サーバとの通信が正常か点検 |
明示的に無効化 (sidecar.istio.io/inject: "false") が付与されている |
kubectl get pod -n demo -o yaml | grep sidecar.istio.io/inject |
該当アノテーションを削除し、Pod を再作成 |
ポイント：ラベルやアノテーションの状態は必ず
kubectl describe namespace|podで確認し、問題が解消したら Pod を再起動してサイドカー注入を検証します。
2. 証明書ローテーション時の注意点
Istio の自動ローテーションは 30 日ごと に行われますが、手動で Secret を差し替える場合は Envoy の再ロード が必要です。以下のフローを参考にしてください。
|
1 2 3 4 5 6 7 8 9 10 |
# 1. 新しい証明書で Secret を上書き kubectl -n istio-system create secret tls ingressgateway-cred \ --cert=/path/to/new.crt --key=/path/to/new.key --dry-run=client -o yaml | kubectl apply -f - # 2. IngressGateway のロールアウト再起動 kubectl rollout restart deployment istio-ingressgateway -n istio-system # 3. サイドカー側のリロード確認 istioctl proxy-config secret <pod-name> --proxy-id <pod-ip> |
ポイント：Secret 更新後は必ず IngressGateway と少なくとも 1 つのサイドカー Pod を再起動し、
istioctl authn tls-checkで新証明書が使用されていることを確認します。
3. ポリシー競合と優先順位のチェック方法
PeerAuthentication と DestinationRule が同一サービスに対して異なる mTLS モードを指定すると、最も具体的なポリシー が適用されます（Service > Namespace > Mesh）。しかし、DISABLE が上書きされないケースがあるため注意が必要です【⁵】。
|
1 2 3 4 5 6 7 8 9 |
# 現在の PeerAuthentication を全体取得 kubectl get peerauthentication -A -o yaml # DestinationRule の対象サービス確認 kubectl get destinationrule -n demo -o yaml # 実際に適用されている TLS モードを検証 istioctl authn tls-check demo httpbin |
競合が見つかったら、不要なリソースを削除 するか 設定を統一 してください。
4. ベストプラクティスチェックリスト
| 項目 | 推奨アクション |
|---|---|
| 二重検証 | istioctl authn tls-check → Kiali の TLS アイコン → Prometheus メトリクスで一致を確認 |
| 段階的マイグレーション | Namespace → Service → DestinationRule の順に STRICT に移行し、各フェーズで回帰テスト実施 |
| 証明書自動管理 | cert-manager と Istio の Certificate CRD を連携させ、手作業による更新リスクを排除 |
| 監視アラート | Prometheus で istio_tcp_connections_closed_total{reason="tls_error"} や istio_requests_total{mtls!="TRUE"} に基づく Alertmanager アラートを設定 |
| CI/CD 統合 | デプロイ前に helm lint と同様に istioctl validate -f <manifest> を実行し、ポリシー違反を早期検出 |
| ドキュメント整備 | 各環境（dev / staging / prod）ごとに PeerAuthentication のスコープと適用対象を Markdown で管理 |
最終的な結論：上記手順とチェックリストに沿って導入すれば、Istio の mTLS は安全かつ確実に本番環境へ展開できます。定期的な検証と自動化された監視を組み合わせることで、長期運用時のリスクも最小限に抑えることが可能です。
参考文献
- Istio Documentation – Supported Kubernetes Versions, https://istio.io/latest/docs/setup/install/kubernetes/
- Istio Docs – Profiles Overview, https://istio.io/latest/docs/setup/additional-setup/config-profiles/
- Istio Security – PeerAuthentication, https://istio.io/latest/docs/reference/config/security/peer_authentication/
- Istio Migration Guide – Mutual TLS Migration, https://istio.io/latest/docs/tasks/security/authentication/mutual-tls/
- Istio Policy Precedence, https://istio.io/latest/docs/ops/configuration/traffic-management/#policy-precedence