Linkerd のインストールとセットアップ

サポート対象バージョン: Linkerd 2.16+ 最終更新: February 22, 2026

概要

このドキュメントでは、Kubernetes クラスターに Linkerd をインストールするさまざまな方法を扱います。CLI ツールのインストール、Control Plane のインストール、高可用性（HA）構成、Viz、Jaeger、Multicluster を含む拡張機能のインストールを包括的に説明します。

前提条件

Kubernetes バージョン

Linkerd バージョン	最小 Kubernetes バージョン	推奨 Kubernetes バージョン
2.16.x	1.25+	1.28+
2.15.x	1.24+	1.27+
2.14.x	1.22+	1.26+

クラスター要件

# Minimum Requirements
CPU: 100m (entire control plane)
Memory: 200Mi (entire control plane)
Nodes: 1+ (3+ recommended for production)

# Recommended Requirements (Production)
CPU: 500m - 1000m
Memory: 500Mi - 1Gi
Nodes: 3+ (HA configuration)

ネットワーク要件

• TCP ポート 443: Webhook 通信
• TCP ポート 8443: Proxy injector
• TCP ポート 8089: Tap API
• クラスター内での DNS 名前解決

事前検証

# Run pre-flight checks if Linkerd CLI is installed
linkerd check --pre

# Expected output:
# kubernetes-api
# --------------
# √ can initialize the client
# √ can query the Kubernetes API
#
# kubernetes-version
# ------------------
# √ is running the minimum Kubernetes API version
#
# pre-kubernetes-setup
# --------------------
# √ control plane namespace does not already exist
# √ can create non-namespaced resources
# √ can create ServiceAccounts
# √ can create Services
# √ can create Deployments
# √ can create CronJobs
# √ can create ConfigMaps
# √ can create Secrets
# √ can read Secrets
# √ can read extension-apiserver-authentication configmap
# √ no clock skew detected
#
# Status check results are √

Linkerd CLI のインストール

Linux/macOS（curl）

# Install latest stable version
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh

# Add to PATH
export PATH=$HOME/.linkerd2/bin:$PATH

# Permanently add to PATH (bash)
echo 'export PATH=$HOME/.linkerd2/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Permanently add to PATH (zsh)
echo 'export PATH=$HOME/.linkerd2/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

特定バージョンのインストール

# Install specific version (e.g., 2.16.0)
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh -s -- --version stable-2.16.0

# Install edge version
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh

macOS（Homebrew）

# Install via Homebrew
brew install linkerd

# Upgrade
brew upgrade linkerd

Windows（Chocolatey）

# Install via Chocolatey
choco install linkerd2

# Upgrade
choco upgrade linkerd2

Windows（手動インストール）

# Download in PowerShell
$version = "stable-2.16.0"
$arch = "windows-amd64"
$url = "https://github.com/linkerd/linkerd2/releases/download/$version/linkerd2-cli-$version-$arch.exe"

Invoke-WebRequest -Uri $url -OutFile linkerd.exe

# Add to PATH or move to desired location
Move-Item linkerd.exe C:\tools\linkerd.exe

インストールの確認

# Check version
linkerd version

# Example output:
# Client version: stable-2.16.0
# Server version: unavailable (when server not installed)

Control Plane のインストール

基本インストール（CLI）

# Step 1: Install CRDs
linkerd install --crds | kubectl apply -f -

# Step 2: Install control plane
linkerd install | kubectl apply -f -

# Verify installation
linkerd check

# Expected output:
# kubernetes-api
# --------------
# √ can initialize the client
# √ can query the Kubernetes API
#
# linkerd-existence
# -----------------
# √ 'linkerd-config' config map exists
# √ heartbeat ServiceAccount exist
# √ control plane replica sets are ready
# √ no unschedulable pods
# √ control plane pods are ready
# √ cluster networks contains all pods
# √ cluster networks contains all services
#
# linkerd-config
# --------------
# √ control plane Namespace exists
# √ control plane ClusterRoles exist
# √ control plane ClusterRoleBindings exist
# √ control plane ServiceAccounts exist
# √ control plane CustomResourceDefinitions exist
# √ control plane MutatingWebhookConfigurations exist
# √ control plane ValidatingWebhookConfigurations exist
# √ proxy-init container runs as root user if docker container runtime is used
#
# linkerd-identity
# ----------------
# √ certificate config is valid
# √ trust anchors are using supported crypto algorithm
# √ trust anchors are within their validity period
# √ trust anchors are valid for at least 60 days
# √ issuer cert is using supported crypto algorithm
# √ issuer cert is within its validity period
# √ issuer cert is valid for at least 60 days
# √ issuer cert is issued by the trust anchor
#
# linkerd-webhooks-and-apisvc-tls
# -------------------------------
# √ proxy-injector webhook has valid cert
# √ proxy-injector cert is valid for at least 60 days
# √ sp-validator webhook has valid cert
# √ sp-validator cert is valid for at least 60 days
# √ policy-validator webhook has valid cert
# √ policy-validator cert is valid for at least 60 days
#
# linkerd-version
# ---------------
# √ can determine the latest version
# √ cli is up-to-date
#
# control-plane-version
# ---------------------
# √ can retrieve the control plane version
# √ control plane is up-to-date
# √ control plane and cli versions match
#
# Status check results are √

インストールマニフェストのプレビュー

# Preview resources to be installed
linkerd install --crds > linkerd-crds.yaml
linkerd install > linkerd-control-plane.yaml

# Review and apply
kubectl apply -f linkerd-crds.yaml
kubectl apply -f linkerd-control-plane.yaml

Helm を使用したインストール

Helm を使用すると、よりきめ細かな構成が可能になります。

Helm リポジトリの追加

# Add Linkerd Helm repository
helm repo add linkerd https://helm.linkerd.io/stable
helm repo update

# Repository for edge versions
helm repo add linkerd-edge https://helm.linkerd.io/edge

証明書の生成

Helm でインストールする場合は、証明書を指定する必要があります。

# Install step CLI (for certificate generation)
# macOS
brew install step

# Linux
wget https://dl.step.sm/gh-release/cli/docs-cli-install/v0.25.0/step-cli_0.25.0_amd64.deb
sudo dpkg -i step-cli_0.25.0_amd64.deb

# Generate Trust Anchor (Root CA)
step certificate create root.linkerd.cluster.local ca.crt ca.key \
  --profile root-ca \
  --no-password \
  --insecure \
  --not-after=87600h  # 10 years

# Generate Issuer certificate
step certificate create identity.linkerd.cluster.local issuer.crt issuer.key \
  --profile intermediate-ca \
  --not-after=8760h \  # 1 year
  --no-password \
  --insecure \
  --ca ca.crt \
  --ca-key ca.key

Helm による CRD のインストール

# Install CRDs
helm install linkerd-crds linkerd/linkerd-crds \
  -n linkerd \
  --create-namespace \
  --wait

Helm による Control Plane のインストール

# Install control plane
helm install linkerd-control-plane linkerd/linkerd-control-plane \
  -n linkerd \
  --set-file identityTrustAnchorsPEM=ca.crt \
  --set-file identity.issuer.tls.crtPEM=issuer.crt \
  --set-file identity.issuer.tls.keyPEM=issuer.key \
  --wait

Helm values ファイルの使用

# values.yaml
# Proxy resource settings
proxy:
  resources:
    cpu:
      request: 100m
      limit: 1000m
    memory:
      request: 64Mi
      limit: 250Mi

# Proxy log level
proxyLogLevel: warn,linkerd=info

# Proxy log format
proxyLogFormat: plain

# Identity settings
identity:
  issuer:
    clockSkewAllowance: 20s
    issuanceLifetime: 24h0m0s

# Control plane resources
controllerResources: &controller_resources
  cpu:
    request: 100m
    limit: 1000m
  memory:
    request: 50Mi
    limit: 250Mi

destinationResources: *controller_resources
identityResources: *controller_resources
proxyInjectorResources: *controller_resources

# Pod anti-affinity settings
enablePodAntiAffinity: false

# Namespace metadata
namespace:
  labels:
    linkerd.io/control-plane-ns: linkerd

# Install with values file
helm install linkerd-control-plane linkerd/linkerd-control-plane \
  -n linkerd \
  -f values.yaml \
  --set-file identityTrustAnchorsPEM=ca.crt \
  --set-file identity.issuer.tls.crtPEM=issuer.crt \
  --set-file identity.issuer.tls.keyPEM=issuer.key \
  --wait

高可用性（HA）インストール

本番環境には高可用性構成を推奨します。

CLI を使用した HA インストール

# Install with HA profile
linkerd install --crds | kubectl apply -f -
linkerd install --ha | kubectl apply -f -

Helm を使用した HA インストール

# ha-values.yaml
# HA base settings
enablePodAntiAffinity: true

# Control plane replicas
controllerReplicas: 3

# Destination controller settings
destination:
  replicas: 3
  resources:
    cpu:
      request: 100m
      limit: 1000m
    memory:
      request: 50Mi
      limit: 250Mi

# Identity controller settings
identity:
  replicas: 3
  resources:
    cpu:
      request: 100m
      limit: 1000m
    memory:
      request: 10Mi
      limit: 250Mi

# Proxy Injector settings
proxyInjector:
  replicas: 3
  resources:
    cpu:
      request: 100m
      limit: 1000m
    memory:
      request: 50Mi
      limit: 250Mi

# PodDisruptionBudget settings
podDisruptionBudget:
  maxUnavailable: 1

# Proxy resources (increased for HA)
proxy:
  resources:
    cpu:
      request: 100m
      limit: 1000m
    memory:
      request: 64Mi
      limit: 250Mi

# Pod anti-affinity
podAntiAffinity:
  preferredDuringSchedulingIgnoredDuringExecution:
  - weight: 100
    podAffinityTerm:
      labelSelector:
        matchLabels:
          linkerd.io/control-plane-component: destination
      topologyKey: kubernetes.io/hostname

# Topology spread constraints
topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        linkerd.io/control-plane-ns: linkerd

# Install with HA values
helm install linkerd-control-plane linkerd/linkerd-control-plane \
  -n linkerd \
  -f ha-values.yaml \
  --set-file identityTrustAnchorsPEM=ca.crt \
  --set-file identity.issuer.tls.crtPEM=issuer.crt \
  --set-file identity.issuer.tls.keyPEM=issuer.key \
  --wait

HA 構成の確認

# Check control plane Pod distribution
kubectl get pods -n linkerd -o wide

# Check PodDisruptionBudget
kubectl get pdb -n linkerd

# Verify anti-affinity (deployed on different nodes)
kubectl get pods -n linkerd -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName

拡張機能のインストール

Viz 拡張機能（ダッシュボードとメトリクス）

Viz 拡張機能は Linkerd の可観測性機能を提供します。

CLI を使用したインストール

# Install Viz extension
linkerd viz install | kubectl apply -f -

# Verify installation
linkerd viz check

# Open dashboard
linkerd viz dashboard &

Helm を使用したインストール

# Viz extension Helm installation
helm install linkerd-viz linkerd/linkerd-viz \
  -n linkerd-viz \
  --create-namespace \
  --wait

Viz values のカスタマイズ

# viz-values.yaml
# Prometheus settings
prometheus:
  enabled: true
  resources:
    cpu:
      request: 300m
      limit: 1000m
    memory:
      request: 300Mi
      limit: 1Gi
  persistence:
    enabled: true
    storageClass: gp3
    size: 10Gi

# Disable Grafana (when using external Grafana)
grafana:
  enabled: false

# Dashboard settings
dashboard:
  replicas: 1
  resources:
    cpu:
      request: 100m
      limit: 500m
    memory:
      request: 50Mi
      limit: 250Mi
  # Disable authentication (development only)
  # enforcedHostRegexp: ""

# Tap settings
tap:
  replicas: 1
  resources:
    cpu:
      request: 100m
      limit: 1000m
    memory:
      request: 50Mi
      limit: 250Mi

# Metrics API settings
metricsAPI:
  replicas: 1
  resources:
    cpu:
      request: 100m
      limit: 500m
    memory:
      request: 50Mi
      limit: 250Mi

# Install with custom values
helm install linkerd-viz linkerd/linkerd-viz \
  -n linkerd-viz \
  --create-namespace \
  -f viz-values.yaml \
  --wait

Jaeger 拡張機能（分散トレーシング）

CLI を使用したインストール

# Install Jaeger extension
linkerd jaeger install | kubectl apply -f -

# Verify installation
linkerd jaeger check

Helm を使用したインストール

# Jaeger extension Helm installation
helm install linkerd-jaeger linkerd/linkerd-jaeger \
  -n linkerd-jaeger \
  --create-namespace \
  --wait

Jaeger values のカスタマイズ

# jaeger-values.yaml
# Collector settings
collector:
  replicas: 1
  resources:
    cpu:
      request: 100m
      limit: 500m
    memory:
      request: 50Mi
      limit: 250Mi

# Jaeger UI/Query settings
jaeger:
  replicas: 1
  resources:
    cpu:
      request: 100m
      limit: 500m
    memory:
      request: 50Mi
      limit: 250Mi

# Sampling settings
webhook:
  collectorSvcAddr: collector.linkerd-jaeger:55678
  collectorSvcAccount: collector

Multicluster 拡張機能

CLI を使用したインストール

# Install Multicluster extension
linkerd multicluster install | kubectl apply -f -

# Verify installation
linkerd multicluster check

Helm を使用したインストール

# Multicluster extension Helm installation
helm install linkerd-multicluster linkerd/linkerd-multicluster \
  -n linkerd-multicluster \
  --create-namespace \
  --wait

Multicluster values

# multicluster-values.yaml
# Gateway settings
gateway:
  replicas: 1
  resources:
    cpu:
      request: 100m
      limit: 500m
    memory:
      request: 50Mi
      limit: 250Mi
  # LoadBalancer settings (for EKS)
  serviceType: LoadBalancer
  loadBalancerIP: ""
  # When using NLB
  serviceAnnotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
    service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"

# Service Account settings
remoteMirrorServiceAccountName: linkerd-service-mirror-remote-access

Amazon EKS 固有の構成

EKS クラスターの準備

# Create EKS cluster (using eksctl)
eksctl create cluster \
  --name linkerd-cluster \
  --version 1.28 \
  --region us-west-2 \
  --nodegroup-name standard-workers \
  --node-type m5.large \
  --nodes 3 \
  --nodes-min 1 \
  --nodes-max 5 \
  --managed

# Update kubeconfig
aws eks update-kubeconfig --name linkerd-cluster --region us-west-2

EKS CNI の互換性

Linkerd はほとんどの CNI と互換性があります。

# Check Amazon VPC CNI version
kubectl describe daemonset aws-node -n kube-system | grep Image

# Install Linkerd CNI plugin (optional, for use with Amazon VPC CNI)
linkerd install-cni | kubectl apply -f -

EKS IAM 構成

# linkerd-service-account.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: linkerd-destination
  namespace: linkerd
  annotations:
    # When using IRSA (if needed)
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/LinkerdDestinationRole

EKS Ingress のセットアップ（AWS Load Balancer Controller）

# linkerd-viz-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: linkerd-viz
  namespace: linkerd-viz
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-west-2:ACCOUNT_ID:certificate/CERT_ID
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
    alb.ingress.kubernetes.io/healthcheck-path: /ready
spec:
  rules:
  - host: linkerd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web
            port:
              number: 8084

EKS NLB Gateway のセットアップ（Multicluster）

# multicluster-gateway-nlb.yaml
# Helm values
gateway:
  serviceType: LoadBalancer
  serviceAnnotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
    service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"
    service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
    service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip"

EKS Security Group の構成

# Allow required ports in cluster security group
# - TCP 4143: Linkerd proxy
# - TCP 4191: Linkerd proxy metrics
# - TCP 8443: Proxy injector webhook
# - TCP 8089: Tap API

# Add security group rules with eksctl (example)
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxxxxxx \
  --protocol tcp \
  --port 4143 \
  --source-group sg-xxxxxxxxx

インストールの検証とバリデーション

完全なステータスチェック

# Comprehensive status check
linkerd check

# Status check including extensions
linkerd check --proxy

# Viz extension status check
linkerd viz check

# Multicluster extension status check
linkerd multicluster check

# Jaeger extension status check
linkerd jaeger check

コンポーネントのステータスチェック

# Control plane Pod status
kubectl get pods -n linkerd

# Extension Pod status
kubectl get pods -n linkerd-viz
kubectl get pods -n linkerd-jaeger
kubectl get pods -n linkerd-multicluster

# Service status
kubectl get svc -n linkerd
kubectl get svc -n linkerd-viz

# Check CRDs
kubectl get crds | grep linkerd

サンプルアプリケーションによるテスト

# Install emojivoto sample app
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/emojivoto.yml | kubectl apply -f -

# Inject proxy
kubectl get -n emojivoto deploy -o yaml | linkerd inject - | kubectl apply -f -

# Verify deployment
kubectl get pods -n emojivoto

# Check statistics
linkerd viz stat deploy -n emojivoto

# Check real-time traffic
linkerd viz top deploy -n emojivoto

Linkerd のアップグレード

Stable Channel のアップグレード

# Upgrade CLI
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh

# Check new version
linkerd version

# Pre-upgrade check
linkerd check --pre

# Upgrade CRDs
linkerd upgrade --crds | kubectl apply -f -

# Upgrade control plane
linkerd upgrade | kubectl apply -f -

# Verify upgrade
linkerd check

# Upgrade extensions
linkerd viz upgrade | kubectl apply -f -
linkerd viz check

Helm のアップグレード

# Update Helm repository
helm repo update

# Backup current values
helm get values linkerd-control-plane -n linkerd > current-values.yaml

# Upgrade CRDs
helm upgrade linkerd-crds linkerd/linkerd-crds -n linkerd --wait

# Upgrade control plane
helm upgrade linkerd-control-plane linkerd/linkerd-control-plane \
  -n linkerd \
  -f current-values.yaml \
  --set-file identityTrustAnchorsPEM=ca.crt \
  --set-file identity.issuer.tls.crtPEM=issuer.crt \
  --set-file identity.issuer.tls.keyPEM=issuer.key \
  --wait

# Upgrade Viz extension
helm upgrade linkerd-viz linkerd/linkerd-viz -n linkerd-viz --wait

Edge Channel

# Install edge version (latest features, more frequent updates)
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh

# Edge Helm repository
helm repo add linkerd-edge https://helm.linkerd.io/edge

Data Plane のアップグレード（Proxy Rolling Restart）

# Restart all meshed workloads to apply new proxy
kubectl rollout restart deploy -n my-namespace

# Or specific Deployment only
kubectl rollout restart deploy/my-app -n my-namespace

# Check proxy version
linkerd viz stat deploy -n my-namespace -o wide

トラブルシューティング

一般的なインストール問題

Webhook 接続の失敗

# Symptom: Proxy injection not working
# Cause: Cannot connect to webhook service

# Solution 1: Check webhook service
kubectl get svc -n linkerd linkerd-proxy-injector

# Solution 2: Check webhook configuration
kubectl get mutatingwebhookconfiguration linkerd-proxy-injector-webhook-config -o yaml

# Solution 3: Check network policies
kubectl get networkpolicy -n linkerd

証明書の問題

# Symptom: Identity-related errors
# Certificate errors when running linkerd check

# Solution: Check certificate status
linkerd check --proxy

# Check trust anchor expiration
kubectl get secret linkerd-identity-trust-roots -n linkerd -o json | \
  jq -r '.data["ca-bundle.crt"]' | base64 -d | \
  openssl x509 -noout -dates

# Check issuer certificate
kubectl get secret linkerd-identity-issuer -n linkerd -o json | \
  jq -r '.data["crt.pem"]' | base64 -d | \
  openssl x509 -noout -dates

リソース不足

# Symptom: Pods stuck in Pending state
# Cause: Insufficient node resources

# Solution: Check resource requests
kubectl describe pod -n linkerd <pod-name>

# Check node resources
kubectl describe nodes | grep -A 5 "Allocated resources"

デバッグコマンド

# Check control plane logs
kubectl logs -n linkerd deploy/linkerd-destination -c destination
kubectl logs -n linkerd deploy/linkerd-identity
kubectl logs -n linkerd deploy/linkerd-proxy-injector

# Check proxy logs
kubectl logs <pod-name> -c linkerd-proxy

# Check events
kubectl get events -n linkerd --sort-by='.lastTimestamp'

# Check proxy status
linkerd diagnostics proxy-metrics <pod-name>

アンインストール

CLI を使用したアンインストール

# Remove extensions first
linkerd viz uninstall | kubectl delete -f -
linkerd jaeger uninstall | kubectl delete -f -
linkerd multicluster uninstall | kubectl delete -f -

# Remove control plane
linkerd uninstall | kubectl delete -f -

Helm を使用したアンインストール

# Remove extensions
helm uninstall linkerd-viz -n linkerd-viz
helm uninstall linkerd-jaeger -n linkerd-jaeger
helm uninstall linkerd-multicluster -n linkerd-multicluster

# Remove control plane
helm uninstall linkerd-control-plane -n linkerd

# Remove CRDs
helm uninstall linkerd-crds -n linkerd

# Remove namespaces
kubectl delete namespace linkerd linkerd-viz linkerd-jaeger linkerd-multicluster

次のステップ

• アーキテクチャ: Linkerd の内部構造を詳しく理解する
• トラフィック管理: ServiceProfile とトラフィック分割の構成
• セキュリティ: mTLS と認可ポリシーのセットアップ

参照

• Linkerd インストールガイド
• Helm Chart ドキュメント
• HA インストールガイド
• EKS ガイド