tilt

Tilt：Kubernetes 開発ツールキット

Tilt は、ローカルでの Kubernetes 開発ループを自動化します。ファイルを監視し、イメージをビルドして、クラスターにデプロイします。設定は Tiltfile（Python 方言である Starlark）に記述します。リソースは、イメージのビルドと k8s へのデプロイ（またはローカルコマンド）をひとつの管理可能な単位にまとめたものです。

CLI 操作

実行中の Tilt インスタンスとやり取りするために、エージェントが使用するコマンドです。

ライフサイクル

タスク	コマンド
開発環境を起動する	tilt up [-- <Tiltfile args>]
ターミナルでログをストリーミングしながら起動する	tilt up --stream
指定したリソースのみを起動する	tilt up frontend backend
CI／バッチモードで実行する（成功／失敗時に終了）	tilt ci --timeout 30m
デプロイ済みリソースを停止して削除する	tilt down
実行時の Tiltfile 引数を変更する	tilt args -- --flag value
実行時引数をすべてクリアする	tilt args --clear

tilt up の実行中に Ctrl+C を押しても、K8s と Docker Compose のリソースは実行を続けます。ローカルの serve_cmd プロセスは停止します。クリーンアップするには tilt down を使用します。

ログの表示

タスク	コマンド
すべてのログをストリーミングする	tilt logs -f
1 つのリソースのログをストリーミングする	tilt logs -f <resource>
エラーのみを表示する	tilt logs --level error
ビルドログのみを表示する	tilt logs --source build
実行時ログのみを表示する	tilt logs --source runtime
5 分前以降のログを表示する	tilt logs --since 5m
直近 100 行を表示する	tilt logs --tail 100
JSON 形式で出力する（解析用）	tilt logs --json

リソース管理

タスク	コマンド
すべてのリソースを一覧表示する	tilt get uiresources
リソースのステータスを JSON で表示する	tilt get uiresources -o json
リソースの詳細を表示する	tilt describe uiresource <name>
リソースを強制的に再ビルドする	tilt trigger <resource>
無効になっているリソースを有効にする	tilt enable <resource>
リソースを無効にする	tilt disable <resource>
リソースの準備完了を待つ	tilt wait --for=condition=Ready uiresource/<name>

調査とデバッグ

タスク	コマンド
診断情報を表示する（バージョン、クラスター）	tilt doctor
ファイル監視の一覧を表示する	tilt get filewatches
特定のファイル監視の詳細を表示する	tilt describe filewatch <name>
エンジンの状態全体を JSON でダンプする	tilt dump engine
UI の状態全体をダンプする	tilt dump webview
Tilt と同じ方法で Docker ビルドをテストする	tilt docker -- build <args>
API リソースの種類を一覧表示する	tilt api-resources

Tilt API サーバーは、デフォルトで localhost:10350 で動作します。すべての tilt get/describe/trigger コマンドは、このサーバーと通信します。

ビルド方式の選択

状況	関数	主な詳細
標準的な Dockerfile	docker_build(ref, context)	コンテキストディレクトリを監視し、自動で k8s に注入します
カスタムツールチェーン（Bazel、ko、Buildpacks）	custom_build(ref, cmd, deps)	$EXPECTED_REF 環境変数を使用してタグ付けする必要があります
Docker 以外のビルダー（Buildah、kaniko）	custom_build(..., skips_local_docker=True)	ビルダーが個別にプッシュを処理します
Docker Compose サービス	docker_compose(configPaths)	Compose のライフサイクルを管理します
Helm チャート	k8s_yaml(helm('./chart'))	ローカルでレンダリングし、クラスターにデプロイします
Kustomize オーバーレイ	k8s_yaml(kustomize('./overlay'))	ローカルでレンダリングし、クラスターにデプロイします

ライブアップデートの判断フロー

ライブアップデートでは、イメージの完全な再ビルドを、コンテナー内でのファイル同期に置き換えます。所要時間は数分ではなく数秒です。

手順	目的	順序
fall_back_on(files)	これらのファイルが変更された場合に完全な再ビルドを強制します	最初に指定する必要があります
sync(local, remote)	変更されたファイルを実行中のコンテナーにコピーします	fall_back_on の後
run(cmd, trigger=files)	コンテナー内でコマンドを実行します（例：依存関係のインストール）	sync の後
restart_container()	コンテナープロセスを再起動します	最後に指定する必要があります

docker_build('myapp', '.', live_update=[
    fall_back_on(['requirements.txt']),
    sync('./src', '/app/src'),
    run('pip install -r requirements.txt', trigger=['requirements.txt']),
])

ライブアップデートが機能しない場合： docker_build のコンテキスト外にあるファイルを変更すると、完全な再ビルドが実行されます。sync() のパス外にあるファイルを変更した場合も、完全な再ビルドが実行されます。最初の tilt up では必ず完全なビルドが実行されます。ライブアップデートには、実行中のコンテナーが必要です。

リソースの設定

# Kubernetes resource with port forwarding and dependencies
k8s_resource('frontend',
    port_forwards=['3000:3000'],
    resource_deps=['api', 'database'],
    labels=['web'],
    trigger_mode=TRIGGER_MODE_MANUAL,
)

# Local resource (build tool, test runner, code generator)
local_resource('codegen',
    cmd='make generate',
    deps=['./proto'],
    labels=['tools'],
)

# Local server (runs continuously)
local_resource('storybook',
    serve_cmd='npm run storybook',
    deps=['./src/components'],
    allow_parallel=True,
    readiness_probe=probe(http_get=http_get_action(port=6006)),
)

並列処理： ローカルリソースはデフォルトで順番に実行されます。互いに独立したリソースには allow_parallel=True を設定します。イメージのビルドはデフォルトで同時に 3 件実行されます。update_settings(max_parallel_updates=N) で調整できます。

依存関係： resource_deps は、依存先が初めて準備完了になるまで処理をブロックします。依存先が一度準備完了になると、そのセッション中は依存するリソースが常に実行可能になります。

デバッグの流れ

Service crashing?     → tilt logs -f <resource> --source runtime
Build failing?        → tilt logs -f <resource> --source build
                        tilt docker -- build <args>  (reproduces Tilt's exact build)
Wrong files rebuild?  → tilt get filewatches
                        tilt describe filewatch <name>
                        Check .tiltignore, watch_settings(ignore=), ignore= param
Force a rebuild?      → tilt trigger <resource>
Resource stuck?       → tilt describe uiresource <name>
                        Check resource_deps chain
                        For CRDs: pod_readiness='ignore'
General diagnostics?  → tilt doctor
Full state dump?      → tilt dump engine | jq .

よくある10の落とし穴

落とし穴	対処法
local() 呼び出しでファイル依存関係が追跡されない	read_file() でラップするか、watch_file() を追加します
ライブ更新のパスが docker_build のコンテキスト外にある	同期するローカルパスがコンテキストディレクトリ内に収まるようにします
ローカルリソースが互いにブロックし合う	独立したリソースでは allow_parallel=True を設定します
resource_deps は更新時に再ゲートしない	初回の準備完了時のみ確認し、現在のバージョンは確認しません
Starlark には while/try-except/class/再帰がない	for ループ、エラー処理には fail()、状態管理には dict を使います
.tiltignore は Docker ビルドコンテキストに影響しない	再ビルドのトリガーとコンテキストの両方から除外するには .dockerignore を使います
custom_build で $EXPECTED_REF が使われない	ビルドスクリプトで、この環境変数を使ってイメージにタグを付ける必要があります
run() のトリガーファイルが sync() ステップに含まれていない	トリガーパスも sync() ステップでカバーする必要があります
最初の tilt up は常にフルビルドを行う	コンテナが実行されるまではライブ更新を利用できません
CRD の Pod が pending 状態のままになる	CRD リソースで pod_readiness='ignore' を設定します

追加のリソース

リファレンスファイル

API シグネチャの詳細や高度なパターンについては、以下を参照してください。

• references/api-reference.md：カテゴリ別に整理された Tiltfile API の完全なカタログ、Starlark 言語に関する注記、ignore メカニズムの比較
• references/patterns.md：複数サービスのアーキテクチャ、環境設定、CI 連携、パフォーマンス最適化、プログラムからの Tilt 操作、拡張機能エコシステム

アンチパターン

アンチパターン	対処法
許可なく Tilt を起動または停止する	長時間稼働する開発環境を変更する前に確認します
tilt up をビルドコマンドとして扱う	一括検証には tilt ci を使います
フォールバックなしでライブ更新する	ビルドファイルと依存関係ファイルを fall_back_on に指定します
Kubernetes YAML だけを使ってデバッグする	uiresources、ファイル監視、ログを確認します
監視対象のシェル処理に local() を使う	deps を明示した local_resource を使います

このスキルに含まれないこと

• Kubernetes の入門ガイドではありません。
• 開発環境を実行、再起動、または終了する許可ではありません。
• tilt doctor とリソースログを読むことの代わりにはなりません。