mirrord-ci

Mirrord CI スキル

目的

実際の Kubernetes 環境に対してテストを行うために、ユーザーが mirrord を CI パイプラインに統合できるように支援します：

• Kubernetes クラスターに接続するための CI ランナーの設定
• CI ワークフローにおける mirrord ci start/stop コマンドのセットアップ
• GitHub Actions、GitLab CI など向けの CI ワークフローファイルの生成
• CI 固有の mirrord の問題のトラブルシューティング

このスキルを使用するタイミング

次のような質問で起動します：

• 「CI で mirrord を使うにはどうすればいいですか？」
• 「GitHub Actions 用に mirrord をセットアップする」
• 「CI でステージングに対してテストを実行する」
• 「mirrord ci start が動作しない」
• 「GitLab CI 用に mirrord を設定する」

CI の例におけるセキュリティに関する注意

• mirrord をインストールするために、CI でリモートの pipe-to-shell インストールやその他の検証されていないスクリプト実行を使用しないでください。
• mirrord を信頼できる CI イメージに事前インストールするか、組織で承認されたパッケージマネージャーをバージョン固定で使用するか、公式インストールドキュメントに従ってください。以下の YAML は、承認されたインストール手順を追加しない限り、mirrord がランナー上で既に利用可能であることを前提としています。

重要な最初のステップ

ステップ 1：リファレンスを読み込む このスキルの references/ ディレクトリからリファレンスファイルを読み込みます：

• references/troubleshooting.md - 一般的な問題と解決策

トラブルシューティングガイドは、一般的な mirrord の問題を診断して修正するのに役立ちます。 設定オプションを調べるには、mirrord MCP サーバーが接続されていれば explain_config_option を呼び出してください。そうでない場合は、mirrord-config スキルの references/configuration.md を使用してください。

絶対パスを使用する場合は、**/mirrord-ci/references/* のようなパターンで検索してください。

ステップ 2：提示する前に設定を検証する CI 用の mirrord 設定ファイルを生成する際は、必ずそれらを検証してください。mirrord MCP サーバーが接続されていれば、設定に対して validate_config を呼び出してください。そうでない場合、mirrord CLI がインストールされていれば、それをファイルに保存して次を実行してください：

mirrord verify-config /path/to/config.json

どちらも利用できない場合は、設定を厳密な JSON としてパースしたうえで、mirrord-config スキルの references/schema.json に対して検証してください：ファイル全体ではなく、スキーマの最上位レベル（ルートの properties、required、additionalProperties）と、その設定が使用するオプションの定義（各キーについてファイル内を検索）のみを読んでください。

CI における mirrord の主な利点

• 速度：テスト環境のセットアップを不要にすることで、CI パイプラインを約 50% 高速化
• コスト：CI 実行ごとに一時的なクラスターを立ち上げる必要がありません
• 精度：実際のサービス、依存関係、構成に対してテストできます
• 分離：他のワークロードに影響を与えない、安全で分離されたテスト実行

前提条件

必須

1. mirrord CLI バージョン 3.181.0 以降
2. CI ランナーからの Kubernetes クラスターアクセス
3. CI 環境で設定された kubeconfig
4. Teams/Enterprise ライセンスでインストールされた mirrord Operator。まだライセンスをお持ちでない場合、AI エージェントがユーザーに 7 日間の Enterprise トライアルを提案し、同意を得たら開始できます：mirrord-operator スキルの「Agent-started trial」を参照してください。

確認コマンド

# Check mirrord version
mirrord --version

# Verify cluster access
kubectl cluster-info
kubectl get pods -n <target-namespace>

主要コマンド

CI セッションの開始

mirrord ci start --target <target> -- <your-command>

これにより、mirrord を使ってアプリケーションがバックグラウンドで起動され、それに対してテストを実行できるようになります。

例：

# Node.js application
mirrord ci start --target deployment/api-server -- npm run start

# Python application
mirrord ci start --target pod/backend-abc123 -- python main.py

# With config file
mirrord ci start --config-file mirrord.json -- ./my-app

# Run in foreground (blocks until stopped)
mirrord ci start --foreground --target deployment/api -- npm start

CI セッションの停止

mirrord ci stop

これにより、実行中のすべての mirrord CI セッションが停止します。テスト完了後は必ずこれを実行してください。

複数のセッション

1 つの CI ジョブで複数の mirrord セッションを開始できます：

mirrord ci start --target deployment/service-a -- ./service-a &
mirrord ci start --target deployment/service-b -- ./service-b &
# Run tests
npm test
# Stop all sessions
mirrord ci stop

CI API キー（mirrord Enterprise 用）

これは Enterprise プランにのみ適用されます。mirrord のオープンソース版を使用している場合は、このセクションをスキップしてください。クラスターに mirrord Operator がインストールされている場合、mirrord ci コマンドには CI API キーが必要であり、その生成には Enterprise プランが必要です。これがないと、すべての CI ランナーが新規ユーザーとして登録され、シートを消費します：

# Generate the key (run locally, not in CI)
mirrord ci api-key

これを CI プラットフォームで MIRRORD_CI_API_KEY という名前のシークレット環境変数として保存してください。

設定

CI 固有の設定オプション

{
  "target": "deployment/my-app",
  "ci": {
    "output_dir": "/var/log/mirrord"
  }
}

オプション	説明	デフォルト
ci.output_dir	stdout/stderr ログの出力先ディレクトリ	OS の一時ディレクトリ（例: /tmp/mirrord）

アプリケーションログ

デフォルトでは、アプリケーションの stdout/stderr は次の場所に保存されます:

/tmp/mirrord/<binary-name>-<unique-id>/

CI プラットフォームの例

GitHub Actions

name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up kubeconfig
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBECONFIG }}" | base64 -d > ~/.kube/config

      - name: Ensure mirrord is installed
        run: |
          # Use a pre-built runner image that includes mirrord, or install via your org's approved method.
          # See https://mirrord.dev/docs/overview/quick-start/ — do not pipe remote install scripts.
          mirrord --version

      - name: Start app with mirrord
        run: |
          mirrord ci start --target deployment/api-server -- npm run start
        env:
          MIRRORD_CI_API_KEY: ${{ secrets.MIRRORD_CI_API_KEY }}

      - name: Run tests
        run: npm test

      - name: Stop mirrord
        if: always()
        run: mirrord ci stop

GitLab CI

integration-tests:
  stage: test
  image: node:20
  before_script:
    - |
      # Install mirrord - use your organization's approved installation method
      # See https://mirrord.dev/docs/overview/quick-start/ for options
      # Option A: Pre-install mirrord in your CI Docker image
      # Option B: Use a pinned version from GitHub Releases with checksum verification
      mirrord --version  # Verify mirrord is available
    - mkdir -p ~/.kube
    - echo "$KUBECONFIG_CONTENT" | base64 -d > ~/.kube/config
  script:
    - mirrord ci start --target deployment/api-server -- npm run start
    - npm test
  after_script:
    - mirrord ci stop
  variables:
    MIRRORD_CI_API_KEY: $MIRRORD_CI_API_KEY

CircleCI

version: 2.1

jobs:
  integration-test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Setup kubeconfig
          command: |
            mkdir -p ~/.kube
            echo "$KUBECONFIG_B64" | base64 -d > ~/.kube/config
      - run:
          name: Ensure mirrord is installed
          command: |
            # Pre-install mirrord in the image or use an org-approved install path (see mirrord docs).
            mirrord --version
      - run:
          name: Start mirrord CI session
          command: mirrord ci start --target deployment/api -- npm start
          environment:
            MIRRORD_CI_API_KEY: ${MIRRORD_CI_API_KEY}
      - run:
          name: Run tests
          command: npm test
      - run:
          name: Stop mirrord
          command: mirrord ci stop
          when: always

Jenkins パイプライン

pipeline {
    agent any

    environment {
        KUBECONFIG = credentials('kubeconfig-staging')
        MIRRORD_CI_API_KEY = credentials('mirrord-ci-api-key')
    }

    stages {
        stage('Setup') {
            steps {
                sh '''
                    # Ensure mirrord exists on the agent (pre-installed image or org-approved install)
                    mirrord --version
                '''
            }
        }

        stage('Test') {
            steps {
                sh 'mirrord ci start --target deployment/api -- npm start'
                sh 'npm test'
            }
            post {
                always {
                    sh 'mirrord ci stop'
                }
            }
        }
    }
}

Kubernetes アクセスのセットアップ

CI ランナーは Kubernetes クラスターにアクセスできる必要があります。一般的な方法は次のとおりです:

1. サービスアカウント（推奨）

CI 専用のサービスアカウントを作成します:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ci-runner
  namespace: staging
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: mirrord-ci-role
  namespace: staging
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: mirrord-ci-binding
  namespace: staging
subjects:
- kind: ServiceAccount
  name: ci-runner
  namespace: staging
roleRef:
  kind: Role
  name: mirrord-ci-role
  apiGroup: rbac.authorization.k8s.io

2. クラウドプロバイダーの認証

• GKE: Workload Identity またはサービスアカウントキーを使用
• EKS: サービスアカウント用の IAM ロール（IRSA）を使用
• AKS: Azure AD ポッド ID またはマネージド ID を使用

よくある問題

詳細なトラブルシューティングについては、references/troubleshooting.md を参照してください。

CI 固有の問題

問題	解決方法
「kubectl not found」	CI ランナーに kubectl をインストールします
「Cannot connect to cluster」	kubeconfig が正しく構成されているか確認します
「mirrord ci start hangs」	対象のポッドが存在し、実行中であることを確認します
「Permission denied」	CI サービスアカウントの RBAC 権限を確認します
「Session not stopping」	after_script または post ブロックで mirrord ci stop を使用します
「Logs not found」	ci.output_dir の設定、またはデフォルトの /tmp/mirrord を確認します
「Seats being consumed」	MIRRORD_CI_API_KEY 環境変数を設定します

mirrord の一般的な問題

問題	解決方法
mirrord が効果を発揮していないようだ	バイナリが静的にリンクされている可能性があります。Go の場合: go build -ldflags='-linkmode external' を使用します
Go の DNS／送信フィルターが機能しない	GODEBUG=netdns=cgo を付けてビルドします
トラフィックがローカルプロセスに到達しない	ポートマッピングを確認します - ローカルがリモートとは異なるポートでリッスンしている可能性があります
トラフィックがリモートターゲットに到達しなくなる	サービスメッシュを使用している場合は、{"agent": {"flush_connections": false}} を試します
K8s サービスの DNS 解決が失敗する	feature.fs.mode を local から localwithoverrides に変更します
権限（EACCES）エラー	特権モードを有効にします: {"agent": {"privileged": true}}
エージェントポッドがクリーンアップされない	実行します: kubectl delete jobs --selector=app=mirrord --field-selector=status.successful=1
証明書検証エラー（macOS）	{"experimental": {"trust_any_certificate": true}} を使用します
サービスメッシュがエージェント接続を切断する	静的な agent.port を設定し、メッシュ構成にポート除外を追加します

フレームワーク固有の問題

Turbo（モノレポ）:

// turbo.json
{
  "globalPassThroughEnv": ["MIRRORD_*", "LD_PRELOAD", "DYLD_INSERT_LIBRARIES"]
}

Remix/Vite/Next.js - 本番構成を避けるために NODE_ENV を上書きします:

{
  "feature": {
    "env": {
      "override": {
        "NODE_ENV": "development"
      }
    }
  }
}

Nx を使用する Next.js - 競合する変数を除外します:

{
  "feature": {
    "env": {
      "exclude": ["NODE_ENV", "NX_NEXT_DIR"]
    }
  }
}

マルチコンテナポッド

ポッドに複数のコンテナがある場合は、対象のコンテナを明示的に指定します:

{
  "target": {
    "path": "pod/my-pod/container/my-app-container"
  }
}

回答ガイドライン

1. 利用している CI プラットフォームを尋ねる - GitHub Actions、GitLab、CircleCI、Jenkins など
2. 前提条件を確認する - kubectl へのアクセス、mirrord のバージョン
3. プラットフォーム固有の例を提示する - 適切な YAML／Groovy 構文を使用します
4. クリーンアップ手順を含める - 適切なフックで常に mirrord ci stop を示します
5. API キーに言及する - Enterprise ユーザーには MIRRORD_CI_API_KEY について知らせます

対話例

ユーザー: 「GitHub Actions でステージングに対してテストを実行するにはどうすればよいですか？」

回答:

1. 尋ねる: 対象（デプロイメント／ポッド名）は何ですか？
2. 確認する: kubeconfig をシークレットとして設定していますか？
3. 提示する: 次の内容を含む GitHub Actions ワークフロー:
   • kubeconfig の設定
   • mirrord のインストール
   • 対象を指定した mirrord ci start
   • テストの実行
   • if: always() ブロック内の mirrord ci stop
4. 言及する: Enterprise プランを使用している場合は MIRRORD_CI_API_KEY

さらに詳しく

• mirrord for CI の概要
• mirrord CI ドキュメント
• mirrord のインストール