Contents
マルチクラスタ構成の概要と本ガイドの目的
Linkerd の Multicluster Extension を利用すれば、異なる Kubernetes クラスタ間でサービスをシームレスに共有できます。本セクションでは、最新版（執筆時点 v2.15.x）を前提にしたインストール手順と主要 CRD（ServiceMirror と MulticlusterGateway）の正しい使い方を解説します。バージョンや Helm リポジトリ URL は将来的に変わる可能性があるため、実装前に公式サイトで最新情報を必ず確認してください。
前提条件と環境チェック
1. Linkerd コアのインストールが必要
両クラスタに同一バージョン（執筆時点 v2.15.x）かつ stable チャートからインストールされた Linkerd が稼働していることを確認します。
2. バージョンとリポジトリ URL の事前検証
以下のコマンドで Helm リポジトリが正しく登録されているか、利用可能なバージョン一覧を取得してください（実際に使用するバージョンは linkerd version で確認）。
|
1 2 3 4 5 6 |
helm repo add linkerd https://helm.linkerd.io/stable # 安定版リポジトリ（将来変更の可能性あり） helm repo update # 利用可能な Linkerd バージョンを一覧表示 helm search repo linkerd --versions | grep '^linkerd-' |
ポイント：
stableリポジトリは公式が長期サポートするチャートを提供します。edgeリポジトリは試験的機能が含まれるため、運用環境では使用しないことを推奨します。
Multicluster Extension のインストール
2.1 Helm チャートの追加とインストール
公式マルチクラスタ拡張は独立した Helm リポジトリ linkerd-multicluster で提供されています。以下を各クラスタで実行してください。
|
1 2 3 4 5 6 7 8 |
helm repo add linkerd-multicluster https://helm.linkerd.io/multicluster helm repo update # 任意の名前空間 (例: linkerd-mc) にインストール helm upgrade --install \ linkerd-mc linkerd-multicluster/linkerd-multicluster \ --namespace linkerd-mc --create-namespace |
備考：インストール時にバージョンを明示したい場合は
--version <v2.15.x>を付与します。
2.2 CRD の登録
Extension が起動すると同時に必要な CRD が作成されますが、手動で最新の CRD 定義を取得したい場合は次の URL から直接適用できます（公式ドキュメントと同期していることを確認してください）。
|
1 2 |
kubectl apply -f https://run.linkerd.io/multicluster/crds.yaml |
正しい CRD 名称と役割
| CRD 名称 | Kind (API) | 主な役割 |
|---|---|---|
| ServiceMirror | ServiceMirror (multicluster.linkerd.io/v1alpha1) |
リモートクラスタの Service をローカルに「ミラー」し、ClusterIP で名前解決できるようにする |
| MulticlusterGateway | MulticlusterGateway (multicluster.linkerd.io/v1alpha1) |
複数クラスター間のトラフィック入口を提供。TLS 終端とプロキシ転送を行う |
公式ドキュメントでは Gateway という Kind が古いサンプルに残っていることがありますが、現在は
MulticlusterGatewayが正式名称です。混同しないよう注意してください。
MulticlusterGateway と ServiceMirror の具体例
3.1 Namespace と自動インジェクションの設定
Linkerd プロキシを自動で注入するには、対象 Namespace に以下のアノテーションを付与します。linkerd.io/inject=enabled は Pod 単位ではなく Namespace へ適用する必要があります。
|
1 2 3 |
kubectl create namespace linkerd-mc kubectl label namespace linkerd-mc linkerd.io/inject=enabled # 名前空間レベルで自動インジェクト有効化 |
3.2 MulticlusterGateway の YAML（例）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
apiVersion: multicluster.linkerd.io/v1alpha1 kind: MulticlusterGateway metadata: name: cluster-a-gateway namespace: linkerd-mc spec: ports: - port: 4143 # Linkerd が内部で使用する TLS ポート targetPort: 4143 selector: matchLabels: app.kubernetes.io/name: linkerd-multicluster-gateway |
selectorはデプロイされたゲートウェイ Pod のラベルと一致させる必要があります。
3.3 ServiceMirror の YAML（例）
|
1 2 3 4 5 6 7 8 9 10 11 |
apiVersion: multicluster.linkerd.io/v1alpha1 kind: ServiceMirror metadata: name: backend-mirror namespace: default spec: targetClusterName: cluster-a # リモート側クラスター名 service: name: backend namespace: prod |
このリソースにより、cluster-a の prod/backend がローカルクラスタの default/backend-mirror として利用可能になります。
Linkerd Viz（可視化）コンポーネントのインストール
4.1 正しい Helm リポジトリとチャート名
Viz は stable リポジトリに含まれる linkerd-viz チャートで提供されます。edge リポジトリは試験的機能が混在しているため、運用環境では使用しません。
|
1 2 3 4 5 6 7 |
helm repo add linkerd https://helm.linkerd.io/stable # すでに登録済みの場合は省略可 helm repo update helm upgrade --install \ linkerd-viz linkerd/linkerd-viz \ --namespace linkerd-viz --create-namespace |
4.2 Dashboard のローカルアクセス手順
|
1 2 3 |
kubectl -n linkerd-viz port-forward svc/web 8084:8084 & # 背景で実行したらブラウザで http://localhost:8084 にアクセス |
Dashboard の Multicluster タブに ServiceMirror と MulticlusterGateway 間のリクエスト統計が表示されます。
セキュリティベストプラクティス
5.1 Namespace 注釈で自動インジェクトを徹底
|
1 2 3 |
kubectl annotate namespace linkerd-mc \ config.linkerd.io/proxy-inject=enabled # 旧方式の代替として推奨 |
linkerd.io/inject=enabledはレガシーラベルで、将来的に削除される可能性があります。公式は上記アノテーションを推奨しています。
5.2 mTLS の強制と ServerAuthorization 設定
マルチクラスタ間の全トラフィックに mutual TLS を必須化する例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
apiVersion: policy.linkerd.io/v1alpha1 kind: ServerAuthorization metadata: name: mc-gateway-mtls namespace: linkerd-mc spec: client: meshTLS: unauthenticated: false # 認証されていない接続は拒否 server: selector: matchLabels: app.kubernetes.io/name: linkerd-multicluster-gateway |
5.3 証明書有効期限の自動監視
CI/CD パイプラインに組み込めるコマンド例です。
|
1 2 3 |
# 全クラスターで証明書の残存日数を取得 linkerd inspect certs | grep -E 'Expiry|Not After' |
期限が近い場合は linkerd install --identity-issuer=... でローテーション手順を実行します。
動作検証とトラブルシューティング
6.1 基本的な通信テスト
|
1 2 3 4 5 6 7 8 9 |
# ServiceMirror 経由でリモートサービスへ curl curl -s http://backend-mirror.default.svc.cluster.local/healthz # リアルタイムでパケットを観測（tap） linkerd tap svc/backend-mirror -n default --to 5s # サービス単位の統計情報取得（stat） linkerd stat deploy/backend -n default |
期待結果は 200 OK、tap に GET/200 が記録され、stat の成功率が 99.9 % 以上、p50 レイテンシが 30 ms 未満 であることです。
6.2 障害時のチェックリスト
| 項目 | コマンド例 | 確認ポイント |
|---|---|---|
| プロキシログ | kubectl logs -l linkerd.io/control-plane-component=proxy -c proxy -n linkerd --tail=100 |
エラーメッセージや TLS ハンドシェイク失敗 |
| ゲートウェイ Pod 状態 | kubectl get pod -l app=linkerd-multicluster-gateway -n linkerd-mc |
Ready が true か |
| CRD ステータス | kubectl describe servicemirror backend-mirror -n default |
status.conditions の Ready が True |
| mTLS 証明書期限 | linkerd inspect certs |
有効期限が近くないか |
上記を順に確認し、ネットワークポリシーやクラウド側ファイアウォール設定が原因である場合は該当ルールを緩和します。
まとめ
- 最新版（v2.15.x） の Linkerd と公式 stable Helm リポジトリを使用し、バージョンと URL は事前に検証すること。
- 正式名称は
ServiceMirrorとMulticlusterGateway。古いサンプルのGatewayとは混同しない。 - Viz のインストールは stable リポジトリ経由で行い、Dashboard からマルチクラスタトラフィックを可視化する。
- 自動プロキシ注入は Namespace アノテーション
config.linkerd.io/proxy-inject=enabledを利用し、linkerd.io/inject=enabledはレガシーである旨を明示。 - mTLS の強制や証明書有効期限監視を組み込み、セキュリティと可用性を高める。
本手順に沿って環境を構築すれば、Linkerd が提供するマルチクラスタ通信と可観測性の機能を安全かつ安定して運用できるようになります。ぜひ実際のクラスターで試し、得られた知見を社内ナレッジベースに蓄積してください。