eve-deploy-debugging

Eve のデプロイとデバッグ

以下の手順で、アプリの問題をすばやくデプロイして診断します。

環境のセットアップ

• 管理者にステージング API URL を確認します。
• プロファイルを作成して使用します。

eve profile create staging --api-url https://api.eve.example.com
eve profile use staging

インフラストラクチャの変更ポリシー

共有インフラストラクチャに対して、kubectl apply、helm install、または Kubernetes リソースを直接作成する操作は決して実行しないでください。インフラストラクチャの変更はすべて Terraform 経由で行います。アプリケーションのデプロイ管理には Eve CLI（eve env、eve env deploy）を使用してください。基盤となる k8s リソースはプラットフォームが管理します。

デプロイの流れ（ステージング）

# Create env if needed
eve env create staging --project proj_xxx --type persistent

# Deploy (requires --ref with 40-char SHA or a ref resolved against --repo-dir)
eve env deploy staging --ref main --repo-dir .

# When environment has a pipeline configured, the above triggers the pipeline.
# Use --direct to bypass pipeline and deploy directly:
eve env deploy staging --ref main --repo-dir . --direct

# Pass inputs to pipeline:
eve env deploy staging --ref main --repo-dir . --inputs '{"key":"value"}'

デプロイのポーリングの流れ

eve env deploy が呼び出されると、次のように動作します。

1. 直接デプロイ（パイプラインなし）：deployment_status が直接返されます。ready === true になるまでヘルスエンドポイントをポーリングします。
2. パイプラインデプロイ：pipeline_run_id が返されます。すべてのステップが完了するまで GET /pipelines/{name}/runs/{id} をポーリングし、その後ヘルスを確認します。

デプロイが完了したとみなされる条件：ready === true かつ active_pipeline_run === null。

デプロイを監視する

eve job list --phase active
eve job follow <job-id>              # Real-time SSE streaming
eve job watch <job-id>               # Poll-based status updates
eve job diagnose <job-id>            # Full diagnostic
eve job result <job-id>              # Final result
eve job runner-logs <job-id>         # Raw worker logs

リアルタイムデバッグ（3 ターミナル方式）

# Terminal 1: Pipeline/job progress
eve job follow <job-id>

# Terminal 2: Environment health
eve env diagnose <project> <env>

# Terminal 3: System-level logs
eve system logs

デバッグのワークフロー

ジョブが開始しない

1. 依存関係を確認します：eve job dep list <job-id>
2. ブロックされているか確認します：eve job show <job-id> → blocked_by を確認します
3. 環境の準備状況を確認します：eve env show <project> <env>
4. オーケストレーターを確認します：eve system orchestrator status

ジョブが失敗した

1. エラーを取得します：eve job diagnose <job-id>
2. ログを確認します：eve job follow <job-id> または eve job runner-logs <job-id>
3. ビルドの失敗の場合：eve build diagnose <build-id>
4. シークレットの失敗の場合：eve secrets list --project <project_id>

ジョブが実行中のまま止まっている

1. 入力待ちか確認します：eve job show <job-id> → effective_phase
2. スレッドのメッセージを確認します：eve thread messages <thread-id>
3. ランナーポッドを確認します：eve system pods

システムの問題

1. API のヘルス状態：eve system health
2. オーケストレーター：eve system orchestrator status
3. 最近のイベント：eve system events

デプロイの失敗（構造化診断）

デプロイが失敗した場合は、未加工の HTTP エラーではなく、構造化された出力を優先してください。

eve env diagnose <project> <env>

eve env diagnose は、型付きの last_deploy_failure（kind、service、pod、namespace、message）、稼働中の K8s 状態、およびデプロイ済みリリースと最新の同期との差を示す manifest_hash を表示します。再実行する前に、適用済みリリースとのずれを見つけるために使用してください。CLI は失敗を単なる HTTP request failed の背後に隠さなくなりました。

カスタムドメイン

カスタムホスト名はマニフェストの x-eve.ingress.domains で宣言し、初回デプロイ時にバインドします。これらを操作するには、次のようにします。

eve domain list --env <env>          # what is bound where
eve domain verify <hostname>         # DNS check + cert state + next steps
eve domain status <hostname>         # which env owns it today
eve domain transfer <hostname> --to <env>   # move ownership across envs in same project
eve domain unbind <hostname>         # release so the next deploy claims it

所有権は 環境スコープで、最初のバインドが優先されます。ホスト名を指定して最初にデプロイした環境がそのホスト名を所有し、同じホスト名を参照する他の環境は owned by environment "<A>" をログに記録して、レンダリングをスキップします。移動するには transfer と再デプロイを使用するか、environments.<env>.overrides で環境ごとにスコープを設定してください。

プラットフォーム Sentinel アラート

プラットフォームは環境を継続的に監視する Sentinel を実行し、環境の状態が悪化すると Slack アラートを投稿します。Sentinel の通知は調査の出発点として扱ってください。アラートからプロジェクトと環境を特定し、対応する前に eve env diagnose <project> <env> を実行して現在の状態を確認します。自己修復後にアラートが届く場合もあります。

毎日の Sentinel サマリーには、月次コストのセクションが含まれることがあります。全体の内訳を確認するには eve system env-cost --all を使用してください。このコマンドは保存された 環境コストのスナップショットを読み取り、古い推定値や利用できない推定値にラベルを付けます。Slack サマリーの処理経路から OpenCost に直接問い合わせないでください。

よくあるエラーメッセージ

エラー	原因	対処方法
401 Unauthorized	トークンの有効期限切れ	eve auth login
git clone failed	認証情報がない	github_token または ssh_key シークレットを設定します
service not provisioned	環境が作成されていない	eve env create <env>
image pull backoff	レジストリ認証に失敗	BYO／カスタムレジストリを使用している場合は、REGISTRY_USERNAME と REGISTRY_PASSWORD を確認します。マネージドアプリの場合は registry: "eve" を使用します
healthcheck timeout	アプリが起動していない	アプリのログを確認し、マニフェストのポートを検証します

ビルドの失敗

デプロイパイプラインがビルドのステップで失敗した場合：

eve build list --project <project_id>
eve build diagnose <build_id>
eve build logs <build_id>
eve secrets list --project <project_id>     # Required for BYO/custom registry: REGISTRY_USERNAME, REGISTRY_PASSWORD

よくあるビルドの失敗：

• レジストリ認証：BYO／カスタムレジストリの場合は、REGISTRY_USERNAME と REGISTRY_PASSWORD のシークレットを確認してください
• Dockerfile が見つからない：マニフェストの build.context パスを確認してください
• マルチステージビルドの失敗：BuildKit は正しく処理しますが、Kaniko では問題が発生する場合があります
• ワークスペースのエラー：ビルドコンテキストを利用できません。eve build diagnose を確認してください

ワーカーイメージレジストリ

Eve は、以下のバリアントを含むワーカーイメージを、設定済みのプライベートレジストリに公開します：

バリアント	内容
base	Node.js、git、標準の CLI ツール
python	Base + Python ランタイム
rust	Base + Rust ツールチェーン
java	Base + JDK
kotlin	Base + Kotlin コンパイラー
full	すべてのランタイムを組み合わせたもの

バージョンの固定：本番環境では semver タグ（例：v1.2.3）を使用してください。開発環境では SHA タグまたは :latest を使用してください。

プラットフォーム環境変数

Eve は、デプロイされるすべてのサービスコンテナに以下を自動的に注入します：

変数	用途
EVE_API_URL	サーバー間の呼び出しに使用する内部クラスター URL
EVE_PUBLIC_API_URL	ブラウザー向けアプリ用のパブリックイングレス URL（設定されている場合）
EVE_SSO_URL	ユーザー認証用の SSO ブローカー URL（設定されている場合）
EVE_PROJECT_ID	現在のプロジェクト ID
EVE_ORG_ID	現在の組織 ID
EVE_ENV_NAME	現在の環境名

バックエンドからの呼び出しには EVE_API_URL を使用してください。ブラウザー／クライアント側のコードには EVE_PUBLIC_API_URL を使用してください。サービスのマニフェストの environment セクションで明示的に定義すれば、これらの値を上書きできます。

アクセス URL

• URL のパターン：{service}.{orgSlug}-{projectSlug}-{env}.{domain}
• ローカル開発でのデフォルトドメイン：lvh.me
• 正しいドメイン（ステージングか本番か）を管理者に確認してください。

環境別のデバッグ

環境	デバッグ方法
ローカル（k3d）	イングレス経由でサービスに直接アクセスし、eve system logs を実行
Docker Compose	docker compose logs <service> を実行。本番では使用せず、開発専用
Kubernetes	イングレス経由でアクセスし、最後の手段として kubectl -n eve logs を実行

プライベートエンドポイント（Tailscale）

プライベートネットワーク上のサービス（ホームラボの GPU、内部 API、開発マシン）を Eve クラスターに接続します。プラットフォームは、Tailscale のエグレスプロキシをバックエンドとする K8s ExternalName サービスを作成します。

# Register a private endpoint
eve endpoint add \
  --name lmstudio \
  --provider tailscale \
  --tailscale-hostname mac-mini.tail12345.ts.net \
  --port 1234 \
  --org org_xxx

# List and inspect
eve endpoint list --org org_xxx
eve endpoint show lmstudio --org org_xxx

# Diagnose connectivity
eve endpoint diagnose lmstudio

# Remove
eve endpoint remove lmstudio --org org_xxx

各エンドポイントには、クラスター内で安定した DNS 名が割り当てられます：http://{orgSlug}-{name}.eve-tunnels.svc.cluster.local:{port}。シークレットを介してアプリ／エージェントに組み込みます：

eve secrets set LLM_BASE_URL \
  "http://myorg-lmstudio.eve-tunnels.svc.cluster.local:1234/v1" \
  --scope project

診断では、オペレーターのステータス、K8s サービスの存在、DNS 解決、TCP 接続、HTTP ヘルスを確認します。

ワーカーツールチェーンのオンデマンド利用

デフォルトのワーカーイメージは base です（Node.js、git、すべてのハーネスを含み、約 800MB）。ツールチェーン（Python、Rust、Java、Kotlin、メディア）は、大容量イメージに同梱するのではなく、init コンテナを介してオンデマンドで注入されます。

デプロイへの影響：エージェントのジョブでツールチェーンが必要な場合、ランナーポッドは小さな事前ビルド済みイメージからツールチェーンのバイナリをコピーする init コンテナを起動します。初回のプルでは約 5～10 秒追加されますが、同じノード上でのそれ以降のジョブではキャッシュ済みのイメージが使用されます。

ツールチェーンの問題をデバッグする：

# Check if toolchains are declared in agent config
# agents.yaml: toolchains: [python]

# If a toolchain binary is missing at runtime:
# 1. Verify agent config has the toolchain declared
# 2. Check init container logs on the runner pod
# 3. Verify toolchain images are available in the registry

完全なイメージ（すべてのツールチェーンを同梱）を使用するには、EVE_WORKER_VARIANT=full を設定するか、ローカルで --variant full を使用してください。

アプリのデプロイ解除／削除のライフサイクル

環境を削除してリソースをクリーンアップします：

# Undeploy services from an environment (stops pods, keeps env record)
eve env undeploy <project> <env>

# Delete the environment entirely (removes env record, managed DB, secrets)
eve env delete <project> <env>

マネージド DB が接続されている場合、eve env delete によってプロビジョニングが解除されます。環境に紐づくシークレットはクリーンアップされます。環境のパイプライン履歴は監査ログに残ります。

アプリレベルのクリーンアップを行うには、プロジェクトを削除します：

eve project delete <project-id>

これにより、環境、シークレット、パイプライン履歴、ビルド成果物が連鎖的に削除されます。

ワークスペースのクリーンアップ

エージェントのワークスペース向けの本番ディスク管理：

• EVE_WORKSPACE_MAX_GB — ワークスペース全体の上限
• EVE_WORKSPACE_MIN_FREE_GB — クリーンアップを開始するしきい値
• EVE_SESSION_TTL_HOURS — 古いセッションを自動削除
• 上限に近づくとLRU方式で削除し、アイドル状態のセッションはTTLに基づいてクリーンアップ
• K8s：試行ごとのPVCは完了時に削除

マネージドDBのTLS

マネージドPostgresでは、信頼できるCAチェーンがアプリに提供されるようになりました。サービスコードで rejectUnauthorized: false や ssl: { rejectUnauthorized: false } を設定しないでください。検証済みTLSがデフォルトです。クライアントで証明書の検証エラーが発生した場合は、サービスが独自に作成したDSNではなく ${managed.<db>.url} を読み込んでいることを確認してください。

固定送信元IP（許可リスト登録済みの送信元IP）

ベンダーが固定送信元IPを必要とする場合は、マニフェストでサービスにプラットフォーム管理の固定送信元IPを有効にしてください：

services:
  poller:
    x-eve:
      networking:
        egress: stable      # default is 'nat'

デプロイヤーは hostNetwork: true を指定して、固定送信元IP用ノードグループでPodをスケジュールします。これにより、トラフィックはそのノードのIGW経由で送信されます。必要な場合にのみ有効にしてください（NATをバイパスし、スケジューリングが制限されます）。フィールドの全体像については eve-manifest-authoring を参照してください。

関連スキル

• ローカル開発ループ：eve-local-dev-loop
• シークレット：eve-auth-and-secrets
• マニフェストの変更：eve-manifest-authoring