tilt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tilt — Kubernetes Dev Toolkit

Tilt — Kubernetes 开发工具包

Tilt automates the local Kubernetes development loop: watch files, build images, deploy to cluster. Configuration lives in a

Tiltfile

(Starlark, a Python dialect). A resource bundles an image build + k8s deploy (or a local command) into a single manageable unit.

Tilt 可自动化本地 Kubernetes 开发循环：监听文件、构建镜像、部署到集群。配置信息存储在

Tiltfile

（基于Starlark，一种Python方言）中。资源将镜像构建 + Kubernetes部署（或本地命令）捆绑为一个可管理的单元。

CLI Operations

CLI 操作

The commands an agent uses to interact with a running Tilt instance.

以下是Agent与运行中的Tilt实例交互时使用的命令。

Lifecycle

生命周期

Task	Command
Start dev environment	`tilt up [-- <Tiltfile args>]`
Start with terminal log streaming	`tilt up --stream`
Start specific resources only	`tilt up frontend backend`
Run in CI/batch mode (exits on success/failure)	`tilt ci --timeout 30m`
Stop and delete deployed resources	`tilt down`
Change runtime Tiltfile args	`tilt args -- --flag value`
Change runtime args (clear all)	`tilt args --clear`

On Ctrl+C from

tilt up

: K8s and Docker Compose resources keep running. Local

serve_cmd

processes stop. Use

tilt down

to clean up.

任务	命令
启动开发环境	`tilt up [-- <Tiltfile 参数>]`
启动并在终端流式输出日志	`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时：Kubernetes和Docker Compose资源会继续运行。本地

serve_cmd

进程会停止。使用

tilt down

来清理资源。

Viewing Logs

查看日志

Task	Command
Stream all logs	`tilt logs -f`
Stream logs for one resource	`tilt logs -f <resource>`
Show only errors	`tilt logs --level error`
Show build logs only	`tilt logs --source build`
Show runtime logs only	`tilt logs --source runtime`
Logs since 5 minutes ago	`tilt logs --since 5m`
Last 100 lines	`tilt logs --tail 100`
JSON output (for parsing)	`tilt logs --json`

任务	命令
流式输出所有日志	`tilt logs -f`
流式输出单个资源的日志	`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`

Resource Management

资源管理

Task	Command
List all resources	`tilt get uiresources`
Resource status as JSON	`tilt get uiresources -o json`
Describe a resource in detail	`tilt describe uiresource <name>`
Force rebuild a resource	`tilt trigger <resource>`
Enable a disabled resource	`tilt enable <resource>`
Disable a resource	`tilt disable <resource>`
Wait for resource readiness	`tilt wait --for=condition=Ready uiresource/<name>`

任务	命令
列出所有资源	`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>`

Inspection & Debugging

检查与调试

Task	Command
Diagnostics (versions, cluster)	`tilt doctor`
Inspect file watches	`tilt get filewatches`
Describe a specific file watch	`tilt describe filewatch <name>`
Full engine state dump (JSON)	`tilt dump engine`
Full UI state dump	`tilt dump webview`
Test Docker build as Tilt would	`tilt docker -- build <args>`
List API resource types	`tilt api-resources`

The Tilt API server runs on

localhost:10350

by default. All

tilt get/describe/trigger

commands talk to it.

任务	命令
诊断（版本、集群信息）	`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

命令都会与它通信。

Build Strategy Selector

构建策略选择器

Situation	Function	Key detail
Standard Dockerfile	`docker_build(ref, context)`	Watches context dir, auto-injects into k8s
Custom toolchain (Bazel, ko, Buildpacks)	`custom_build(ref, cmd, deps)`	Must tag with `$EXPECTED_REF` env var
Non-Docker builder (Buildah, kaniko)	`custom_build(..., skips_local_docker=True)`	Builder handles push independently
Docker Compose services	`docker_compose(configPaths)`	Manages compose lifecycle
Helm charts	`k8s_yaml(helm('./chart'))`	Renders locally, deploys to cluster
Kustomize overlays	`k8s_yaml(kustomize('./overlay'))`	Renders locally, deploys to cluster

场景	函数	关键细节
标准Dockerfile	`docker_build(ref, context)`	监听上下文目录，自动注入到Kubernetes中
自定义工具链（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'))`	本地渲染，部署到集群

Live Update Decision Tree

实时更新决策树

Live update replaces full image rebuilds with in-place container file syncs — seconds instead of minutes.

Step	Purpose	Ordering
`fall_back_on(files)`	Force full rebuild when these files change	Must come first
`sync(local, remote)`	Copy changed files into running container	After fall_back_on
`run(cmd, trigger=files)`	Execute command in container (e.g., install deps)	After sync
`restart_container()`	Restart the container process	Must come last

python

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

When live update breaks: Changes to files outside the

docker_build

context trigger a full rebuild. Changes outside any

sync()

path also trigger a full rebuild. First

tilt up

always does a full build — live update requires a running container.

实时更新通过容器内文件同步替代完整镜像重建——耗时从分钟级缩短到秒级。

步骤	目的	顺序
`fall_back_on(files)`	当这些文件变更时强制完整重建	必须放在最前面
`sync(local, remote)`	将变更的文件复制到运行中的容器内	在fall_back_on之后
`run(cmd, trigger=files)`	在容器内执行命令（例如安装依赖）	在sync之后
`restart_container()`	重启容器进程	必须放在最后

python

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

始终会执行完整构建——实时更新需要容器处于运行状态才能生效。

Resource Configuration

资源配置

python

undefined

python

undefined

Kubernetes resource with port forwarding and dependencies

带端口转发和依赖的Kubernetes资源

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)), )


**Parallelism:** Local resources run serially by default. Set `allow_parallel=True` for independent resources. Image builds default to 3 concurrent — adjust with `update_settings(max_parallel_updates=N)`.

**Dependencies:** `resource_deps` gates on first-ever readiness only — once a dependency is ready once, dependents unlock permanently for that session.

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`仅在首次就绪时生效——一旦依赖项首次就绪，在本次会话中依赖它的资源将永久解锁。

Debugging Flow

调试流程

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 .

服务崩溃？     → tilt logs -f <resource> --source runtime
构建失败？        → tilt logs -f <resource> --source build
                        tilt docker -- build <args> （复现Tilt的构建流程）
文件重建异常？  → tilt get filewatches
                        tilt describe filewatch <name>
                        检查.tiltignore、watch_settings(ignore=)、ignore=参数
强制重建？      → tilt trigger <resource>
资源卡住？       → tilt describe uiresource <name>
                        检查resource_deps依赖链
                        对于CRD：设置pod_readiness='ignore'
常规诊断？  → tilt doctor
导出完整状态？      → tilt dump engine | jq .

Top 10 Pitfalls

十大常见陷阱

Pitfall	Fix
`local()` calls don't track file deps	Wrap with `read_file()` or add `watch_file()`
Live update paths outside docker_build context	Ensure sync local paths fall within context dir
Local resources block each other	Set `allow_parallel=True` on independent resources
`resource_deps` doesn't re-gate on updates	It only checks first-ever readiness, not current version
Starlark has no while/try-except/class/recursion	Use for loops, `fail()` for errors, dicts for state
`.tiltignore` doesn't affect Docker build context	Use `.dockerignore` to exclude from both rebuild triggers AND context
`$EXPECTED_REF` not used in custom_build	Build script MUST tag the image with this env var
`run()` trigger files not in a `sync()` step	Trigger paths must also be covered by a sync step
First `tilt up` always does full build	Live update cannot work until a container is running
CRD pods stuck in pending	Set `pod_readiness='ignore'` on CRD resources

陷阱	解决方法
`local()` 调用不跟踪文件依赖	用 `read_file()` 包裹或添加 `watch_file()`
实时更新路径在docker_build上下文之外	确保同步的本地路径在上下文目录内
本地资源相互阻塞	对独立资源设置 `allow_parallel=True`
`resource_deps` 不会在更新时重新生效	它仅检查首次就绪状态，不检查当前版本
Starlark不支持while/try-except/class/递归	使用for循环、 `fail()` 处理错误、用字典存储状态
`.tiltignore` 不影响Docker构建上下文	使用 `.dockerignore` 同时排除重建触发器和上下文
custom_build中未使用 `$EXPECTED_REF`	构建脚本必须使用此环境变量为镜像打标签
`run()` 的触发文件不在 `sync()` 步骤中	触发路径必须被某个sync步骤覆盖
首次 `tilt up` 始终执行完整构建	实时更新需要容器运行后才能生效
CRD Pod卡在Pending状态	在CRD资源上设置 `pod_readiness='ignore'`

Additional Resources

其他资源

Reference Files

参考文档

For detailed API signatures and advanced patterns, consult:

references/api-reference.md
— Complete Tiltfile API catalog organized by category, Starlark language notes, ignore mechanism comparison
references/patterns.md
— Multi-service architectures, environment config, CI integration, performance optimization, programmatic Tilt interaction, extension ecosystem

如需详细的API签名和高级模式，请参考：

references/api-reference.md
— 按类别组织的完整Tiltfile API目录、Starlark语言说明、忽略机制对比
references/patterns.md
— 多服务架构、环境配置、CI集成、性能优化、程序化Tilt交互、扩展生态系统