deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.

路由说明：对于不明确的用户意图，请使用references/intent-clarification.md中的通用澄清模板。

Deploy to TrueFoundry

部署到TrueFoundry

Route user intent to the right deployment workflow. Load only the references you need.

将用户意图路由到正确的部署工作流，仅加载你需要的参考文档。

Intent Router

意图路由器

User Intent	Action	Reference
"deploy", "deploy my app", "ship this"	Single HTTP service	deploy-service.md
"attach this deployment to mcp gateway", "register deployed mcp service", "connect deployment to mcp gateway"	Post-deploy MCP registration	Use `mcp-servers` skill after deployment endpoint is known
"mount this file", "mount config file", "mount certificate file", "mount key file"	Single service with file mounts (no image rebuild)	deploy-service.md
"tfy apply", "apply manifest", "deploy from yaml"	Declarative manifest apply	deploy-apply.md
"deploy everything", "full stack", docker-compose	Multi-service orchestration	deploy-multi.md
"async service", "queue consumer", "worker"	Async/queue service	deploy-async.md
"deploy LLM", "serve model"	Model serving intent (may be ambiguous)	Ask user: dedicated model serving ( `llm-deploy` ) or generic service deploy ( `deploy` )
"deploy helm chart"	Helm chart intent	Confirm Helm path and collect chart details, then proceed with `helm` workflow
"deploy postgres docker", "dockerized postgres", "deploy redis docker", "database in docker/container"	Containerized database intent	Proceed with `deploy` workflow (do not route to Helm)
"deploy database", "deploy postgres", "deploy redis"	Ambiguous infra intent	Ask user: Helm chart ( `helm` ) or containerized service ( `deploy` )

Load only the reference file matching the user's intent. Do not preload all references.

用户意图	操作	参考文档
"deploy", "deploy my app", "ship this"	单HTTP服务部署	deploy-service.md
"attach this deployment to mcp gateway", "register deployed mcp service", "connect deployment to mcp gateway"	部署后MCP注册	拿到部署端点后使用 `mcp-servers` skill
"mount this file", "mount config file", "mount certificate file", "mount key file"	带文件挂载的单服务部署（无需重建镜像）	deploy-service.md
"tfy apply", "apply manifest", "deploy from yaml"	声明式清单应用	deploy-apply.md
"deploy everything", "full stack", docker-compose	多服务编排	deploy-multi.md
"async service", "queue consumer", "worker"	异步/队列服务部署	deploy-async.md
"deploy LLM", "serve model"	模型服务部署意图（可能存在歧义）	询问用户：专用模型服务部署( `llm-deploy` )还是通用服务部署( `deploy` )
"deploy helm chart"	Helm chart部署意图	确认Helm路径并收集chart详情，然后执行 `helm` 工作流
"deploy postgres docker", "dockerized postgres", "deploy redis docker", "database in docker/container"	容器化数据库部署意图	执行 `deploy` 工作流（不要路由到Helm）
"deploy database", "deploy postgres", "deploy redis"	不明确的基础设施意图	询问用户：使用Helm chart( `helm` )部署还是容器化服务( `deploy` )部署

仅加载与用户意图匹配的参考文件，不要预加载所有参考文档。

Prerequisites (All Workflows)

前置条件（所有工作流通用）

bash

undefined

bash

undefined

1. Check credentials

1. 检查凭证

grep '^TFY_' .env 2>/dev/null || true env | grep '^TFY_' 2>/dev/null || true

2. Derive TFY_HOST for CLI (MUST run before any tfy command)

2. 为CLI生成TFY_HOST（执行任何tfy命令前必须运行）

export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

3. Check CLI

3. 检查CLI

tfy --version 2>/dev/null || echo "Install: pip install truefoundry"

4. Check for existing manifests

4. 检查现有清单文件

ls tfy-manifest.yaml truefoundry.yaml 2>/dev/null


- `TFY_BASE_URL` and `TFY_API_KEY` must be set (env or `.env`).
- **`TFY_HOST` must be set before any `tfy` CLI command.** The export above handles this automatically.
- `TFY_WORKSPACE_FQN` required. **HARD RULE: Never auto-pick a workspace. Always ask the user to confirm, even if only one workspace exists or a preference is saved.** See `references/prerequisites.md` for the full workspace confirmation flow.
- For full credential setup, see `references/prerequisites.md`.

> **WARNING:** Never use `source .env`. The `tfy-api.sh` script handles `.env` parsing automatically. For shell access: `grep KEY .env | cut -d= -f2-`

ls tfy-manifest.yaml truefoundry.yaml 2>/dev/null


- 必须设置`TFY_BASE_URL`和`TFY_API_KEY`（环境变量或`.env`文件中）。
- **执行任何`tfy`CLI命令前必须设置`TFY_HOST`，上述export命令会自动处理该配置。**
- 需要`TFY_WORKSPACE_FQN`。**硬性规则：绝对不要自动选择工作区，即使只有一个工作区存在或已保存偏好，也要始终要求用户确认。** 完整的工作区确认流程请查看`references/prerequisites.md`。
- 完整的凭证设置流程请查看`references/prerequisites.md`。

> **警告：** 不要使用`source .env`，`tfy-api.sh`脚本会自动处理`.env`解析。需要获取shell变量时使用：`grep KEY .env | cut -d= -f2-`

Quick Ops (Inline)

快速操作（内联）

Apply a manifest (most common)

应用清单（最常用）

bash

undefined

bash

undefined

tfy CLI expects TFY_HOST when TFY_API_KEY is set

当设置了TFY_API_KEY时，tfy CLI需要TFY_HOST参数

export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

Preview changes

预览变更

tfy apply -f tfy-manifest.yaml --dry-run --show-diff

Apply

应用变更

tfy apply -f tfy-manifest.yaml

undefined

tfy apply -f tfy-manifest.yaml

undefined

Deploy from source (local code or git)

从源码部署（本地代码或git）

bash

undefined

bash

undefined

tfy CLI expects TFY_HOST when TFY_API_KEY is set

当设置了TFY_API_KEY时，tfy CLI需要TFY_HOST参数

export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

tfy deploy builds remotely — use for local code or git sources

tfy deploy会执行远程构建 — 适用于本地代码或git源部署

tfy deploy -f truefoundry.yaml --no-wait


> **`tfy apply` does NOT support `build_source`.** Use `tfy deploy -f` for source-based deployments.

tfy deploy -f truefoundry.yaml --no-wait


> **`tfy apply`不支持`build_source`参数，** 基于源码的部署请使用`tfy deploy -f`。

Minimal service manifest template

最小服务清单模板

yaml

name: my-service
type: service
image:
  type: image
  image_uri: docker.io/myorg/my-api:v1.0
ports:
  - port: 8000
    expose: true
    app_protocol: http
resources:
  cpu_request: 0.5
  cpu_limit: 1
  memory_request: 512
  memory_limit: 1024
  ephemeral_storage_request: 1000
  ephemeral_storage_limit: 2000
env:
  LOG_LEVEL: info
replicas: 1
workspace_fqn: "WORKSPACE_FQN_HERE"

yaml

name: my-service
type: service
image:
  type: image
  image_uri: docker.io/myorg/my-api:v1.0
ports:
  - port: 8000
    expose: true
    app_protocol: http
resources:
  cpu_request: 0.5
  cpu_limit: 1
  memory_request: 512
  memory_limit: 1024
  ephemeral_storage_request: 1000
  ephemeral_storage_limit: 2000
env:
  LOG_LEVEL: info
replicas: 1
workspace_fqn: "WORKSPACE_FQN_HERE"

Check deployment status

检查部署状态

bash

TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'

Or use the

applications

skill.

bash

TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'

也可以使用

applications

skill。

Post-Deploy Verification (Automatic)

部署后验证（自动执行）

After any successful deploy/apply action, verify deployment status automatically without asking an extra prompt.

Preferred verification path:

Use MCP tool call first:

tfy_applications_list(filters={"workspace_fqn": "WORKSPACE_FQN", "application_name": "SERVICE_NAME"})

If MCP tool calls are unavailable, fall back to:

bash

TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'

Always report the observed status (

BUILDING

DEPLOYING

DEPLOY_SUCCESS

DEPLOY_FAILED

, etc.) in the same response.

任何部署/应用操作成功后，无需额外询问用户，自动验证部署状态。

优先验证路径：

优先使用MCP工具调用：

tfy_applications_list(filters={"workspace_fqn": "WORKSPACE_FQN", "application_name": "SERVICE_NAME"})

如果无法使用MCP工具调用，回退到：

bash

TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'

始终在同一条响应中返回观测到的状态（

BUILDING

、

DEPLOYING

、

DEPLOY_SUCCESS

、

DEPLOY_FAILED

等）。

Optional Post-Deploy: Attach to MCP Gateway

可选部署后操作：绑定到MCP网关

If the deployed service exposes an MCP endpoint, ask if the user wants to register it in MCP gateway right away.

Handoff checklist to

mcp-servers

skill:

deployment/service name
endpoint URL (
```
https://.../mcp
```
or in-cluster URL)
transport (
```
streamable-http
```
or
```
sse
```
)
auth mode (
```
header
```
,
```
oauth2
```
, or
```
passthrough
```
)

如果部署的服务暴露了MCP端点，询问用户是否要立即将其注册到MCP网关。

移交到

mcp-servers

skill的检查清单：

部署/服务名称
端点URL（
```
https://.../mcp
```
或集群内URL）
传输协议（
```
streamable-http
```
或
```
sse
```
）
认证模式（
```
header
```
、
```
oauth2
```
或
```
passthrough
```
）

REST API fallback (when CLI unavailable)

REST API回退方案（CLI不可用时）

See

references/cli-fallback.md

for converting YAML to JSON and deploying via

tfy-api.sh

将YAML转换为JSON并通过

tfy-api.sh

部署的流程请查看

references/cli-fallback.md

。

Auto-Detection: Single vs Multi-Service

自动检测：单服务vs多服务

Before creating any manifest, scan the project:

Check for
```
docker-compose.yml
```
/
```
compose.yaml
```
— if found, likely multi-service
Look for multiple
```
Dockerfile
```
files across the project
Check for service directories with their own dependency files in
```
services/
```
,
```
apps/
```
,
```
frontend/
```
,
```
backend/
```

Single service → Load
```
references/deploy-service.md
```
Multiple services → Load
```
references/deploy-multi.md
```

创建任何清单之前，扫描项目：

检查是否存在
```
docker-compose.yml
```
/
```
compose.yaml
```
— 如果存在，大概率是多服务项目
查找项目中是否存在多个
```
Dockerfile
```
文件
检查
```
services/
```
、
```
apps/
```
、
```
frontend/
```
、
```
backend/
```
目录下是否存在带独立依赖文件的服务目录

单服务 → 加载
```
references/deploy-service.md
```
多服务 → 加载
```
references/deploy-multi.md
```

Secrets Handling

密钥处理

Never put sensitive values directly in manifests. Store them as TrueFoundry secrets and reference with

tfy-secret://

format:

yaml

env:
  LOG_LEVEL: info                                              # plain text OK
  DB_PASSWORD: tfy-secret://my-org:my-service-secrets:DB_PASSWORD  # sensitive

Pattern:

tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY>

where TENANT_NAME is the subdomain of

TFY_BASE_URL

Use the

secrets

skill for guided secret group creation. For the full secrets workflow, see

references/deploy-service.md

(Secrets Handling section).

绝对不要将敏感值直接写入清单， 将其存储为TrueFoundry密钥并使用

tfy-secret://

格式引用：

yaml

env:
  LOG_LEVEL: info                                              # 普通明文可以直接写
  DB_PASSWORD: tfy-secret://my-org:my-service-secrets:DB_PASSWORD  # 敏感值引用

格式为：

tfy-secret://<租户名称>:<密钥组名称>:<密钥键名>

，其中租户名称是

TFY_BASE_URL

的子域名。

引导式创建密钥组可使用

secrets

skill，完整的密钥工作流请查看

references/deploy-service.md

的密钥处理部分。

File Mounts (Config, Secrets, Shared Data)

文件挂载（配置、密钥、共享数据）

When users ask to mount files into a deployment, prefer manifest

mounts

over Dockerfile edits:

```
type: secret
```
for sensitive file content (keys, certs, credentials)
```
type: config_map
```
for non-sensitive config files
```
type: volume
```
for writable/shared runtime data

See

references/deploy-service.md

(File Mounts section) for the end-to-end workflow.

当用户要求将文件挂载到部署中时，优先使用清单的

mounts

配置而不是修改Dockerfile：

```
type: secret
```
用于敏感文件内容（密钥、证书、凭证）
```
type: config_map
```
用于非敏感配置文件
```
type: volume
```
用于可写/共享运行时数据

端到端工作流请查看

references/deploy-service.md

的文件挂载部分。

Shared References

通用参考文档

These references are available for all workflows — load as needed:

Reference	Contents
`manifest-schema.md`	Complete YAML field reference (single source of truth)
`manifest-defaults.md`	Per-service-type defaults with YAML templates
`cli-fallback.md`	CLI detection and REST API fallback pattern
`cluster-discovery.md`	Extract cluster ID, base domains, available GPUs
`resource-estimation.md`	CPU, memory, GPU sizing rules of thumb
`health-probes.md`	Startup, readiness, liveness probe configuration
`gpu-reference.md`	GPU types and VRAM reference
`container-versions.md`	Pinned container image versions
`prerequisites.md`	Credential setup and .env configuration
`rest-api-manifest.md`	Full REST API manifest reference

这些参考文档适用于所有工作流 — 按需加载：

参考文档	内容
`manifest-schema.md`	完整YAML字段参考（唯一可信源）
`manifest-defaults.md`	各服务类型默认配置及YAML模板
`cli-fallback.md`	CLI检测及REST API回退方案
`cluster-discovery.md`	提取集群ID、基础域名、可用GPU信息
`resource-estimation.md`	CPU、内存、GPU容量估算经验规则
`health-probes.md`	启动探针、就绪探针、存活探针配置
`gpu-reference.md`	GPU类型及显存参考
`container-versions.md`	固定版本的容器镜像列表
`prerequisites.md`	凭证设置及.env配置
`rest-api-manifest.md`	完整REST API清单参考

Workflow-Specific References

工作流专属参考文档

Reference	Used By
`deploy-api-examples.md`	deploy-service
`deploy-errors.md`	deploy-service
`deploy-scaling.md`	deploy-service
`load-analysis-questions.md`	deploy-service
`codebase-analysis.md`	deploy-service
`tfy-apply-cicd.md`	deploy-apply
`tfy-apply-extra-manifests.md`	deploy-apply
`compose-translation.md`	deploy-multi
`dependency-graph.md`	deploy-multi
`multi-service-errors.md`	deploy-multi
`multi-service-patterns.md`	deploy-multi
`service-wiring.md`	deploy-multi
`async-errors.md`	deploy-async
`async-queue-configs.md`	deploy-async
`async-python-library.md`	deploy-async
`async-sidecar-deploy.md`	deploy-async

参考文档	使用者
`deploy-api-examples.md`	单服务部署
`deploy-errors.md`	单服务部署
`deploy-scaling.md`	单服务部署
`load-analysis-questions.md`	单服务部署
`codebase-analysis.md`	单服务部署
`tfy-apply-cicd.md`	声明式清单应用
`tfy-apply-extra-manifests.md`	声明式清单应用
`compose-translation.md`	多服务部署
`dependency-graph.md`	多服务部署
`multi-service-errors.md`	多服务部署
`multi-service-patterns.md`	多服务部署
`service-wiring.md`	多服务部署
`async-errors.md`	异步/队列服务部署
`async-queue-configs.md`	异步/队列服务部署
`async-python-library.md`	异步/队列服务部署
`async-sidecar-deploy.md`	异步/队列服务部署

Composability

可组合能力

Find workspace: Use
```
workspaces
```
skill
Check what's deployed: Use
```
applications
```
skill
View logs: Use
```
logs
```
skill
Manage secrets: Use
```
secrets
```
skill
Deploy Helm charts: Use
```
helm
```
skill
Deploy LLMs: Use
```
llm-deploy
```
skill
Register deployment in MCP gateway: Use
```
mcp-servers
```
skill
Test after deploy: Use
```
service-test
```
skill

查找工作区：使用
```
workspaces
```
skill
检查已部署内容：使用
```
applications
```
skill
查看日志：使用
```
logs
```
skill
管理密钥：使用
```
secrets
```
skill
部署Helm charts：使用
```
helm
```
skill
部署LLM：使用
```
llm-deploy
```
skill
将部署注册到MCP网关：使用
```
mcp-servers
```
skill
部署后测试：使用
```
service-test
```
skill

Success Criteria

成功标准

User confirmed service name, resources, port, and deployment source before deploying
Deployment URL and status reported back to the user
Deployment status verified automatically immediately after apply/deploy (no extra prompt)
Health probes configured for production deployments
Secrets stored securely (not hardcoded in manifests)
For multi-service: all services wired together and working end-to-end

部署前用户已确认服务名称、资源配置、端口和部署源
已向用户返回部署URL和状态
应用/部署操作完成后立即自动验证部署状态（无需额外询问）
生产环境部署已配置健康探针
密钥已安全存储（未硬编码在清单中）
多服务部署场景：所有服务已完成互联且端到端可用