tilt

Tilt

最初に行うこと：エラーを確認する

問題を調査したりデプロイを検証したりする前に、リソースの状態を確認してください。保留中／進行中のリソースとは分けて、まずエラーを確認してください。そうしないと、実際の失敗が20行以上の保留中リソースに埋もれてしまいます。

# 1. Errors only — surface the buildHistory[0].error so you see WHY, not just THAT
tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus)\n  reason: \((.status.buildHistory[0].error // "(no buildHistory error; check tilt logs)") | gsub("\n"; " ") | .[0:240])"'

# 2. In-progress and pending — informational; an in-progress build may flip to error any moment
tilt get uiresources -o json | jq -r '.items[] | select(.status.updateStatus == "in_progress" or .status.updateStatus == "pending" or .status.runtimeStatus == "pending") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus)"'

# 3. Docker-compose container health — MISSED by the error filter above.
#    An `Up (unhealthy)` compose container keeps runtimeStatus=ok/update=ok, so
#    queries 1-2 never flag it; the red UI badge comes from healthStatus here.
tilt get uiresources -o json | jq -r '.items[] | select(.status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): compose healthStatus=unhealthy (HEALTHCHECK failing — service may still be up)"'

# 4. Quick status overview
tilt get uiresources -o json | jq '[.items[].status.updateStatus] | group_by(.) | map({status: .[0], count: length})'

確認時にリソースが in_progress の場合は、正常と判断する前に再度ポーリングしてください。buildHistory[0].error にエラーが記録された状態で、そのまま error に移行することがあります。updateStatus フィールドに反映されるのは現在のビルド試行の状態だけです。updateStatus が none または not_applicable の場合でも、最後のエラーは常に buildHistory[0].error に記録されます。

Docker Compose リソースは見落としやすいポイントです。 その runtimeStatus／updateStatus が反映するのはビルド／起動の状態だけで、コンテナーの Docker HEALTHCHECK は反映されません。そのため、プローブに失敗しているコンテナー（docker ps → Up (unhealthy)）でも runtimeStatus=ok と表示され、クエリ1～2では検出されない一方、Tilt の UI では赤く表示されます。信頼できるシグナルは .status.composeResourceInfo.healthStatus（healthy／unhealthy／サービスにヘルスチェックがない場合は未設定）であり、クエリ3で検出できます。これらのリソースでは k8sResourceInfo: null となります（spec.type == "docker-compose"）。プローブ失敗の原因を調べるには、Docker に切り替えてください。docker inspect <compose-project>-<svc> --format '{{json .State.Health}}' を実行すると、プローブの最後の終了コードと出力を確認できます。よくある原因は、ヘルスチェック用スクリプトがイメージに含まれていない CLI（例：軽量化されたイメージから削除された curl／grpcurl）を呼び出していることです。この場合、サービス自体に問題はなく、プローブが壊れています。

デフォルト以外のポート

Tilt がデフォルト以外のポートで実行されている場合は、--port を追加してください。

tilt get uiresources --port 37035
tilt logs <resource> --port 37035

リソースの状態

# All resources with status
tilt get uiresources -o json | jq '.items[] | {name: .metadata.name, runtime: .status.runtimeStatus, update: .status.updateStatus}'

# Single resource detail
tilt get uiresource/<name> -o json

# Wait for ready
tilt wait --for=condition=Ready uiresource/<name> --timeout=120s

状態の値：

• RuntimeStatus：ok、error、pending、none、not_applicable
• UpdateStatus：ok、error、pending、in_progress、none、not_applicable

ログ

tilt logs <resource>
tilt logs <resource> --since 5m
tilt logs <resource> --tail 100
tilt logs --json                    # JSON Lines output

トリガーとライフサイクル

tilt trigger <resource>             # Force update
tilt up                             # Start
tilt down                           # Stop and clean up

tilt up の実行

zmx スキルのパターンに従ってください。既存のセッションを確認し、Git のルートから名前を決め、（attach ではなく）zmx run を使用します。

PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
SESSION="${PROJECT}-tilt"

if zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
  echo "Tilt session already exists: $SESSION"
else
  zmx run "$SESSION" 'tilt up'
  echo "Started tilt in zmx session: $SESSION"
fi

重要：コード変更のために再起動しないでください

Tilt は自動的にライブリロードします。以下の変更に対して、tilt up の再起動を提案しないでください。

• Tiltfile の編集
• ソースコードの変更
• Kubernetes マニフェストの更新

再起動するのは、Tilt のバージョンアップ、ポート／ホストの変更、クラッシュ、クラスターコンテキストの切り替えの場合に限ります。

参考資料

• TILTFILE_API.md - Tiltfile の作成
• CLI_REFERENCE.md - JSON の使用例を含む CLI の詳細
• https://docs.tilt.dev/