Posted inDevOps

mirrordでKubernetesマイクロサービスをデバッグ：本番クラスタのコンテキストでローカルコードを直接実行

DevOps tutorial - IT technology blog
DevOps tutorial - IT technology blog

リモート環境におけるマイクロサービスデバッグの苦痛

わずか1行のバグ修正をステージング環境にプッシュしたとします。その後、CIによるバイナリのコンパイル、650MBのDockerイメージのビルド、デプロイチェックの完了まで12分間待たされます。ようやくPodが起動したかと思いきや、サービスは即座にクラッシュ。原因はVaultのシークレットの欠落や、解決できない内部DNSレコードでした。「print文を追加し、コミットし、CI/CDを待ち、ログをtailで追う」という従来の手順は、スプリントごとに何時間ものエンジニアリング時間を奪い去っています。

根本的な原因は環境ドリフト（環境間の差異）にあります。現代のマイクロサービスは孤立して動いているわけではありません。

一般的なバックエンドサービスは、CoreDNS、Istioサイドカー、AWS IAM Roles for Service Accounts (IRSA)、マネージドRedisインスタンス、マウントされたKubernetes Secretsなどに依存しています。Docker ComposeやMinikubeを使ってその複雑なインフラ全体をローカルに再現しようとすると、何百行もの壊れやすいYAMLを書くことになり、数週間もすれば陳腐化してしまいます。求められているのは、動作確認のためだけに中途半端にテストされたコードをデプロイすることなく、IDEのデバッガをクラスタ内の実トラフィックに直接アタッチすることです。

ローカルコードとKubernetesのギャップを埋める3つのアプローチ

開発ワークステーションとリモートクラスタのギャップを埋めるため、開発チームは通常、以下の3つの戦略のいずれかを採用します。

1. ビルド・プッシュ・デプロイのループ

コードを変更するたびに、コンテナのビルド、レジストリへのプッシュ、ローリングアップデートがトリガーされます。SkaffoldやTiltのような自動化ツールを使用すればイテレーション時間を2〜3分に短縮できますが、それでも集中は途切れてしまいます。午後のインシデント対応中に細かい調整を20回繰り返せば、Dockerデーモンの処理を待つだけで1時間以上が無駄になります。

2. トラフィックプロキシ（Telepresenceとポートフォワード）

kubectl port-forwardを実行すれば単一Podへのアウトバウンド通信は処理できますが、order-db.staging.svc.cluster.localのようなクラスタ内部のホスト名を解決することはできず、クラスタ内の他のサービスからローカルマシンに到達することもできません。

Telepresenceのような双方向プロキシツールは、リモートのデプロイメントをルーティングプロキシPodに置き換えることでこれを解決します。しかし、稼働中のデプロイメントを置き換えるとクラスタの状態が変更され、広範なクラスタ管理者権限が必要になる上、同じ共有ネームスペースでQAテストを実施しているチームメンバーの作業を妨害することがよくあります。

3. プロセスレベルのシステムコールインターセプト（mirrord）

mirrordはコンテナの再デプロイを完全に回避します。Podを置き換える代わりに、LinuxではLD_PRELOAD、macOSではダイナミックローダーのフックを使用して、開発マシン上で直接アプリケーションプロセスにフックします。

同時に、mirrordはクラスタ内のターゲットワークロードの隣に、一時的で低権限のエージェントPod（またはエフェメラルコンテナ）を起動します。ローカルコードがネットワーク呼び出しを開始したり、環境変数を要求したり、ファイルを読み込んだりするたびに、mirrordがローカルでシステムコールをインターセプトし、クラスタ側のエージェント経由でプロキシします。

mirrordのメリットとデメリット

メリット

  • クラスタの状態を変更しない（Zero cluster mutation）: mirrordがデプロイする一時的なエージェントのメモリ消費量はわずか15〜30MB程度で、デバッグを停止すると即座に消去されます。デプロイメントマニフェスト、サービス定義、レプリカ数を変更することは一切ありません。
  • 実トラフィックのミラーリング: 複製モード（duplicate mode）では、ターゲットPodへのインバウンドTCPおよびHTTPパケットをローカルポートに直接コピーします。クラスタ上の実際のPodは何の影響も受けることなくステージングトラフィックを処理し続けます。
  • コンテキストの自動注入: 手動で.envファイルを管理することなく、環境変数、マウントされたSecret、ConfigMapが自動的に解決されます。
  • ブロックされないブレークポイント: メモリの状態を確認するためにVS Code、GoLand、IntelliJで実行を10分間一時停止しても問題ありません。本物のPodはクラスタ宛てのリクエストを処理し続けるため、アップストリームの呼び出し元に504 Gateway Timeoutエラーを返すことはありません。
  • ステージング環境の安定性: 複数の開発者が同じ共有ステージングネームスペースに同時に接続しても、お互いの作業を妨げたりクラスタ状態を破損させたりすることがありません。

デメリット

  • データベースへの二重書き込みリスク: トラフィックを無条件にミラーリングすると、書き込み処理が稼働中のPodとローカルマシンの両方で2回実行されてしまいます。ステートフルなワークフローでは、データベースレコードの重複を防ぐためにHTTPヘッダーフィルターを使用したトラフィックのスチール（横取り）設定を行う必要があります。
  • Goランタイムにおけるシステムコールのインターセプト: Go言語のプログラムは標準のCランタイムライブラリ（libc）をバイパスしてカーネルのシステムコールを直接発行します。これをインターセプトするため、mirrordはメモリ内のバイナリ命令にパッチを適用するかptraceを使用する必要があり、集中的なI/O処理中にわずかなオーバーヘッドが発生します。
  • RBACの制約: 開発者はターゲットネームスペース内でエフェメラルコンテナを起動したり、Job/Podを作成したりするためのKubernetes権限が引き続き必要です。

推奨設定：選択的トラフィックスチール（横取り）

共有ステージングクラスタでは、一般トラフィックには影響を与えず、デバッグ対象のリクエストのみをスチール（横取り）するようにmirrordを設定します。これにリモートファイルシステムへの読み取り専用アクセスを組み合わせることで、共有ストレージを変更することなく、稼働中の設定をローカルプロセスから読み取ることができます。

この設定により、主に4つの安全対策が実現します。

  • ローカルプロセスは、カスタムHTTPヘッダー（x-debug-session: trueなど）が付与されたリクエストのみをインターセプトします。
  • CIパイプラインやQAエンジニアからの通常のテストトラフィックは、中断されることなく実際のPodに届き続けます。
  • 実行時にリモートPodのボリュームマウントからSecretや設定ファイルが直接読み取られます。
  • データベースの書き込みは1度だけ行われ、デバッグセッションのスコープ内に安全に限定されます。

この設定をプロジェクトのルートに.mirrord/mirrord.jsonとして保存します。

{
  "$schema": "https://raw.githubusercontent.com/metalbear-co/mirrord/main/mirrord-schema.json",
  "target": {
    "path": {
      "deployment": "payment-service"
    },
    "namespace": "staging"
  },
  "feature": {
    "network": {
      "incoming": {
        "mode": "steal",
        "http_filter": {
          "header_filter": "x-debug-session: true"
        }
      },
      "outgoing": true,
      "dns": true
    },
    "fs": {
      "mode": "read"
    },
    "env": true
  }
}

実践ガイド：ステップバイステップで進めるサービスのデバッグ

ステップ1：mirrord CLIのインストール

公式のインストールスクリプトまたはパッケージマネージャーを使用して、開発マシンにバイナリをインストールします。

# LinuxおよびmacOS向けのインストールスクリプト
curl -fsSL https://inputs.metalbear.co/mirrord/install.sh | bash

# またはmacOSでHomebrewを使用する場合
brew install metalbear-co/mirrord/mirrord

バイナリが正常に動作することを確認し、インストールされたバージョンをチェックします。

mirrord --version

ステップ2：Kubernetesコンテキストの認証確認

mirrordは現在アクティブな~/.kube/configの認証情報を使用します。対象クラスタのコンテキストを確認し、ターゲットPodが正常であることを確認します。

kubectl config current-context
kubectl get pods -n staging -l app=payment-service

ステップ3：クラスタコンテキスト内でローカルプロセスを実行

コンテナイメージをビルドする代わりに、mirrord経由でローカルコードを起動します。mirrordがローカルプロセスにアタッチし、クラスタエージェントを起動して、I/Oリダイレクトを自動的に構成します。

# Python FastAPIサービスをローカルで実行する場合
mirrord exec --config-file .mirrord/mirrord.json -- uvicorn app:app --port 8080

# またはNode.jsマイクロサービスを実行する場合
mirrord exec --config-file .mirrord/mirrord.json -- npm run dev

起動時、CLIには接続の詳細が表示されます。

mirrord: ネームスペース staging のターゲット deployment/payment-service に接続しました
mirrord: ネットワークトラフィックのミラーリングと環境変数の転送準備が完了しました
[Local Server] http://localhost:8080 で実行中

ステップ4：環境変数とクラスタ名前解決の検証

ローカルでポートフォワードトンネルを設定することなく、ローカルプロセスから内部のKubernetesリソースにアクセスできることを確認します。

import os
import requests

# ホスト名はKubernetesのCoreDNS経由で直接解決されます
DB_HOST = os.getenv("DATABASE_HOST", "postgres.internal.svc.cluster.local")
API_KEY = os.getenv("PAYMENT_GATEWAY_SECRET")

def check_status():
    print(f"Pod環境変数からのデータベースホスト: {DB_HOST}")
    print(f"クラスタから注入されたシークレット: {API_KEY[:4]}****")
    
    # 送信呼び出しはクラスタエージェントPodから発信され、そのセキュリティグループとネットワークポリシーを継承します
    resp = requests.get("http://auth-service.staging.svc.cluster.local/health", timeout=5)
    print(f"認証サービスのヘルスステータス: {resp.status_code}")

if __name__ == "__main__":
    check_status()

ステップ5：フィルタリングされたトラフィックでのテスト

ヘッダーフィルターをテストするために、ステージング環境のIngressエンドポイントに対して2種類の異なるcurlリクエストを送信します。

# 1. 通常のリクエスト：リモートのKubernetes Podに直接渡されます
curl -X POST https://staging.example.com/api/v1/payments \
  -H "Content-Type: application/json" \
  -d '{"amount": 49.99}'

# 2. デバッグリクエスト：スチール（横取り）され、ローカルのデバッガに直接ルーティングされます
curl -X POST https://staging.example.com/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "x-debug-session: true" \
  -d '{"amount": 49.99}'

ローカルのデバッガが2つ目のリクエストを即座にキャッチします。Dockerの再ビルド、イメージのプッシュ、Podの再起動を一切行うことなく、ステップ実行、メモリの検査、稼働中サービスに対する修正の検証をわずか数秒で実行できます。

Share:
Tags: