Contents
Linkerdとは何か – サービスメッシュの概要とメリット
Linkerd は CNCF が認定する 軽量なサービスメッシュ です。
マイクロサービス間の通信をプロキシ層で抽象化し、トラフィック管理・可観測性・セキュリティ機能をデフォルトで提供します。本稿では、Linkerd がどのように動作し、なぜ本番環境で採用すべきかを簡潔に解説したうえで、実際のインストール手順へとつなげます。
- トラフィック管理 – リクエストのリトライ、タイムアウト、ロードバランシングをコード変更なしで適用可能。
- 可観測性 – メトリクス・分散トレース・ログが自動取得され、Prometheus や Grafana と簡単に統合できる。
- セキュリティ – 相互 TLS（mTLS）による暗号化と認証がデフォルトで有効化されているため、通信の安全性を即座に確保できる。
これらの特長により、開発者はビジネスロジックに集中し、運用担当者は安定かつ安全なサービス運用を実現できます。
インストール前提条件と環境準備
Linkerd をクラスターへ導入する前に、必須ツールやリソース要件が満たされているか確認します。このセクションで示すチェック項目は、インストール失敗を未然に防ぐための重要なステップです。
kubectl と kubeconfig の確認
kubectl がインストール済みで、対象クラスタへの認証情報が正しく設定されているかを確かめます。
|
1 2 3 4 5 6 |
# クライアントバージョン (2.0 以上推奨) kubectl version --client # 現在のコンテキスト表示 kubectl config current-context |
kubectlが見つからない場合は、Kubernetes公式ドキュメント に従いインストールしてください。- 複数クラスタを扱う場合は
kubectl config use-context <name>で目的のコンテキストに切り替えます。
Kubernetes バージョン・リソース要件
Linkerd の公式ドキュメント（2026‑06 時点）では、Kubernetes 1.24 以上かつ 1.30 未満 がサポート対象と明記されています。実際に使用しているクラスタがこの範囲に入っているかを kubectl version --short で確認してください。
| コンポーネント | 最低 CPU | 最低メモリ |
|---|---|---|
| control‑plane (linkerd-controller) | 200 m | 256 Mi |
| proxy (sidecar) | 100 m | 128 Mi |
クラスター全体で 最低 1 vCPU、2 GiB の余裕リソースがあることを推奨します。kubectl top nodes やクラウドプロバイダーのモニタリング画面で現在の使用率を確認し、必要に応じてノード数やインスタンスタイプを調整してください。
公式 CLI（linkerd）を使ったインストール手順
Linkerd の公式 CLI は単一バイナリで配布され、OS に合わせたアーカイブを取得して PATH に配置するだけで利用できます。ここでは ハードコードされた URL を避け、常に最新安定版を自動取得 する方法と、主要プラットフォームすべてへの対応手順をご紹介します。
最新バージョンの取得方法（動的取得）
GitHub のリリース API から現在の stable タグを取得し、そのタグ名を元にダウンロード URL を組み立てます。jq がインストールされている前提です。
|
1 2 3 4 5 6 |
# 最新安定版タグ (例: stable-2.16.0) を取得 VERSION=$(curl -s https://api.github.com/repos/linkerd/linkerd2/releases/latest \ | jq -r '.tag_name') echo "Latest Linkerd version: $VERSION" |
この変数 VERSION を使えば、以降のダウンロードコマンドは常に最新バイナリを指すようになります。
OS 別バイナリ取得とインストール
| OS / アーキテクチャ | ダウンロード例（シェル） | インストール手順 |
|---|---|---|
| Linux amd64 | curl -L https://github.com/linkerd/linkerd2/releases/download/${VERSION}/linkerd2-cli-linux-amd64-${VERSION}.tar.gz |
tar -xzf linkerd2-cli-linux-amd64-${VERSION}.tar.gz && sudo mv linkerd /usr/local/bin/ |
| Linux arm64 | curl -L https://github.com/linkerd/linkerd2/releases/download/${VERSION}/linkerd2-cli-linux-arm64-${VERSION}.tar.gz |
同上 |
| macOS amd64 | brew install linkerd（Homebrew が自動で最新バージョンを取得） |
Homebrew が PATH に追加します |
| macOS arm64 (Apple Silicon) | curl -L https://github.com/linkerd/linkerd2/releases/download/${VERSION}/linkerd2-cli-darwin-arm64-${VERSION}.tar.gz |
tar -xzf … && sudo mv linkerd /usr/local/bin/ |
| Windows amd64 | iwr https://github.com/linkerd/linkerd2/releases/download/${VERSION}/linkerd2-cli-windows-amd64-${VERSION}.zip -OutFile linkerd.zip |
エクスプローラで解凍し、linkerd.exe を C:\Program Files\Linkerd\ に配置後、PATH に追加 |
| Windows arm64 | iwr https://github.com/linkerd/linkerd2/releases/download/${VERSION}/linkerd2-cli-windows-arm64-${VERSION}.zip -OutFile linkerd.zip |
同上 |
インストールが完了したらバージョンを確認し、期待通りのタグが表示されることを確かめます。
|
1 2 3 |
linkerd version # => linkerd version: stable-2.16.0 (領域は例) |
CRD と Namespace の作成
CLI が提供する CRD（CustomResourceDefinition）と専用 Namespace を先に作成すると、後続のインストールがスムーズです。
|
1 2 3 4 5 6 |
# CRD 適用 linkerd install --crds | kubectl apply -f - # Linkerd 用 Namespace 作成 kubectl create namespace linkerd |
制御プレーンのデプロイ
単一パイプラインで制御プレーンをクラスターに適用します。--set フラグで必要に応じたリソース上限やプローブ設定も追加可能です。
|
1 2 |
linkerd install | kubectl -n linkerd apply -f - |
インストールの検証
デプロイ後は以下コマンドでヘルスチェックと Pod の状態を確認します。問題があれば linkerd check が詳細な診断情報を出力してくれます。
|
1 2 3 4 5 6 7 8 9 |
# 前提条件チェック（省略可） linkerd check --pre # 本番環境全体の健全性チェック linkerd check # Pod の状態確認 kubectl get pods -n linkerd |
すべてのポッドが Running かつ READY が 1/1 であれば、インストールは成功です。
Helm チャートでのインストール手順
Helm を使うと values.yaml に設定を集約でき、複数環境への展開が容易になります。以下では公式チャートの追加からカスタマイズ、デプロイまでの流れを示します。
Helm リポジトリの追加とバージョン固定
|
1 2 3 4 5 6 7 |
helm repo add linkerd https://helm.linkerd.io/stable helm repo update # 現在の stable バージョンを確認（例: 2.16.0） HELM_VER=$(helm search repo linkerd/linkerd2 --versions | head -n2 | tail -n1 | awk '{print $2}') echo "Using Helm chart version: $HELM_VER" |
values.yaml の設定例
以下は実務でよく使われる項目を抜粋したサンプルです。controllerImage.version には先ほど取得した ${VERSION} を流用してください。
|
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 |
# values.yaml controllerImage: version: "${VERSION}" # 動的に置換することが推奨 proxyInjectAnnotation: true resources: controller: limits: cpu: 500m memory: 512Mi requests: cpu: 200m memory: 256Mi proxy: limits: cpu: 250m memory: 256Mi requests: cpu: 100m memory: 128Mi # RBAC / PSP の微調整例 podSecurityContext: runAsUser: 2102 fsGroup: 2102 |
Helm によるデプロイ
values.yaml をローカルに保存したら、以下コマンドでインストールします。Namespace が未作成の場合は --create-namespace オプションを付与してください。
|
1 2 3 4 5 6 |
helm install linkerd2 linkerd/linkerd2 \ --namespace linkerd \ --create-namespace \ -f values.yaml \ --version "$HELM_VER" |
デプロイ完了後は helm status linkerd2 -n linkerd でリリース情報を確認し、kubectl get pods -n linkerd でポッドの状態をチェックします。
Helm でのアップグレードと削除
新バージョンが公開されたら、まず values.yaml の controllerImage.version を更新し、次のコマンドでロールアウトします。
|
1 2 3 4 5 |
helm upgrade linkerd2 linkerd/linkerd2 \ --namespace linkerd \ -f values.yaml \ --version "$HELM_VER" |
削除はシンプルです。Namespace も合わせて削除したい場合は --cascade オプションを併用します。
|
1 2 3 |
helm uninstall linkerd2 -n linkerd kubectl delete namespace linkerd |
サンプルアプリケーションのメッシュ化と検証
実際にサービスメッシュが機能しているか確認するため、公式サンプル httpbin を用いた手順を示します。以前の記事で emojivoto.yml が混在していましたが、本稿では httpbin のマニフェストに統一しています。
httpbin マニフェストの取得
|
1 2 |
curl -sL https://run.linkerd.io/httpbin.yaml -o httpbin.yaml |
※公式リポジトリは随時更新されるため、上記 URL が 404 になる場合は https://github.com/linkerd/linkerd2/tree/main/example 配下の最新ファイルを参照してください。
Sidecar 注入とデプロイ
|
1 2 3 4 5 6 |
# デモ用 Namespace 作成 kubectl create namespace demo # Linkerd の自動注入（inject）と適用 linkerd inject httpbin.yaml | kubectl apply -n demo -f - |
kubectl get pods -n demo で各 Pod に linkerd-proxy コンテナが付与されていることを確認します。
動作確認
httpbin のエンドポイントに対して curl を実行し、期待通りの JSON が返ってくるか検証します。Service 名は httpbin です。
|
1 2 3 |
curl -s http://httpbin.demo:80/status/200 | jq . # => {"status":200} |
さらに Linkerd の可観測性機能を確認するため、Dashboard を一時的に起動し UI でトラフィックが表示されるかチェックします。
|
1 2 3 |
linkerd dashboard & # ブラウザで http://localhost:50750 にアクセス |
よくあるエラーと対処法
| エラーパターン | 主な原因 | 推奨対策 |
|---|---|---|
RBAC: permission denied |
ServiceAccount が必要権限を欠如 | kubectl apply -f https://run.linkerd.io/install/rbac.yaml を再適用 |
podsecuritypolicy validation failed |
クラスタで PSP が有効化され、proxy の権限がブロック | values.yaml か CLI の --set securityContext.runAsUser=2102 で PSP に合わせる |
Linkerd control plane version mismatch |
Kubernetes バージョンがサポート外 (例: 1.31) | クラスタを 1.24–1.30 の範囲にアップグレード、または公式リリースノートで互換性確認 |
proxy-init: permission denied |
ノードの SELinux が enforcing モード | linkerd install --set proxyInit.ignoreSELinux=true で一時的に回避（本番環境ではポリシー調整が望ましい） |
エラーメッセージは必ず linkerd check の出力、あるいは kubectl describe pod <pod> -n demo で取得できます。公式トラブルシューティングガイド（https://linkerd.io/2.16/reference/check/）を併せて参照してください。
アップグレード・アンインストール手順（CLI / Helm 共通）
Linkerd のバージョンが上がった際の手順と、不要になった場合の削除方法をまとめます。どちらの導入方法でも基本的な流れは同一です。
CLI 版アップグレード
- 最新タグ取得（前述の
VERSION変数） - バイナリ更新
curl … | tar -xz && sudo mv linkerd /usr/local/bin/ - 制御プレーンだけを置き換える
|
1 2 |
linkerd upgrade | kubectl -n linkerd apply -f - |
- 再度ヘルスチェック
linkerd checkを実行し、問題がなければ自動的に sidecar がロールアウトします。
Helm 版アップグレード
|
1 2 3 4 5 6 |
# values.yaml の version 行を新しい ${VERSION} に更新 helm upgrade linkerd2 linkerd/linkerd2 \ --namespace linkerd \ -f values.yaml \ --version "$HELM_VER" |
アップグレード後は helm status と linkerd check を併せて確認してください。
アンインストール
| 方法 | コマンド |
|---|---|
| CLI (CRD も含めて完全に削除) | bash\nlinkerd uninstall | kubectl -f -\nkubectl delete crd serviceprofiles.linkerd.io serverauthorizations.policy.linkerd.io\n |
| Helm | bash\nhelm uninstall linkerd2 -n linkerd\nkubectl delete namespace linkerd\n |
CLI 版は CRD が残らないように明示的に削除する必要があります。Helm 版は Namespace 削除でほぼ完了しますが、カスタムリソースが残っている場合は kubectl get crd | grep linkerd で確認し、手動で削除してください。
まとめ
- Linkerd は軽量かつ安全なサービスメッシュ で、トラフィック制御・可観測性・mTLS をデフォルト提供します。
- インストール前に
kubectlと Kubernetes バージョン（1.24–1.30）・リソース要件を必ず確認し、公式 CLI または Helm のいずれかで導入できます。 - 最新版取得は GitHub API を利用した動的スクリプト で行うことで、ハードコードされた URL に起因するリンク切れを防げます。
- OS 別バイナリ表に Linux/arm64・Windows/ARM など主要プラットフォームを網羅し、全環境で同一手順が適用可能です。
- サンプルは httpbin を使用し、
linkerd inject→kubectl applyの流れで Sidecar が正しく注入されたことを確認します。 - エラーは
linkerd checkとkubectl describeで速やかに診断でき、公式トラブルシューティングページが有用です。 - アップグレードは CLI でも Helm でも 制御プレーンだけの差し替え が基本で、作業後は再度ヘルスチェックを実施します。
- 完全削除は CLI の
linkerd uninstallと CRD 手動削除、または Helm のhelm uninstall + namespace 削除で行います。
上記手順に沿って実装すれば、Kubernetes クラスタへ安全・確実に Linkerd を導入し、サービスメッシュの恩恵を最大限に活用できる はずです。ぜひご自身の環境で試してみてください。