tilt

Tilt：Kubernetes 开发工具包

Tilt 可自动化本地 Kubernetes 开发循环：监视文件、构建镜像并部署到集群。配置存储在 Tiltfile（Starlark，一种 Python 方言）中。一个 资源 将镜像构建和 k8s 部署（或本地命令）打包成一个便于管理的单元。

CLI 操作

Agent 用于与运行中的 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
持续输出单个资源的日志	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 chart	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 .

Top 10 个常见问题

常见问题	解决方法
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'

更多资源

参考文件

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

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

反模式

反模式	解决方法
未经同意启动或停止 Tilt	变更长期运行的开发环境前先征求同意
将 tilt up 当作构建命令	使用 tilt ci 进行批量验证
实时更新没有回退机制	将构建/依赖文件放入 fall_back_on
只通过 Kubernetes YAML 进行调试	检查 uiresources、文件监视和日志
使用 local() 执行受监视的 shell 操作	使用带有显式 deps 的 local_resource

此技能不是什么

• 不是 Kubernetes 入门指南。
• 不代表可以运行、重启或拆除开发环境。
• 不能替代对 tilt doctor 和资源日志的查阅。