truefoundry-gitops

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中的通用澄清模板。

GitOps with TrueFoundry

基于TrueFoundry的GitOps

Set up GitOps-style deployments with TrueFoundry. Store deployment configurations as YAML specs in Git and auto-deploy on push using

tfy apply

in CI/CD pipelines.

使用TrueFoundry搭建GitOps风格的部署流程，将部署配置作为YAML规范存储在Git中，在CI/CD流水线中使用

tfy apply

实现代码推送后自动部署。

When to Use

适用场景

Set up automated Git-based deployments with

tfy apply

. Store TrueFoundry YAML specs in Git and auto-deploy on push/merge via CI/CD pipelines.

使用

tfy apply

搭建基于Git的自动化部署流程，将TrueFoundry YAML规范存储在Git仓库中，通过CI/CD流水线在代码推送/合并时自动部署。

When NOT to Use

不适用场景

User wants to deploy manually from local code → prefer
```
deploy
```
skill; ask if the user wants another valid path
User wants to deploy an LLM model → prefer
```
llm-deploy
```
skill; ask if the user wants another valid path
User wants to check what's deployed → prefer
```
applications
```
skill; ask if the user wants another valid path
User wants to deploy a Helm chart → prefer
```
helm
```
skill; ask if the user wants another valid path
User just wants to check TrueFoundry connection → prefer
```
status
```
skill; ask if the user wants another valid path

</objective> <context>

用户希望从本地代码手动部署 → 优先使用
```
deploy
```
skill；询问用户是否需要其他可行路径
用户希望部署LLM模型 → 优先使用
```
llm-deploy
```
skill；询问用户是否需要其他可行路径
用户希望查看已部署的内容 → 优先使用
```
applications
```
skill；询问用户是否需要其他可行路径
用户希望部署Helm chart → 优先使用
```
helm
```
skill；询问用户是否需要其他可行路径
用户仅想检查TrueFoundry连接状态 → 优先使用
```
status
```
skill；询问用户是否需要其他可行路径

</objective> <context>

Prerequisites

前置条件

Always verify before setting up GitOps:

Credentials —
```
TFY_BASE_URL
```
and
```
TFY_API_KEY
```
must be set (env or
```
.env
```
)
TrueFoundry CLI —
```
tfy
```
CLI must be available in the CI/CD environment (pin an exact version, avoid floating installs)
Git repository — A Git repo to store deployment specs

For credential check commands and .env setup, see

references/prerequisites.md

. Use the

status

skill to verify connection before proceeding.

</context> <instructions>

搭建GitOps前请始终确认以下条件：

凭证 — 必须设置
```
TFY_BASE_URL
```
和
```
TFY_API_KEY
```
（环境变量或
```
.env
```
文件）
TrueFoundry CLI — CI/CD环境中必须安装
```
tfy
```
CLI（请固定具体版本，避免浮动安装）
Git仓库 — 用于存储部署规范的Git仓库

凭证检查命令和.env配置方法请查看

references/prerequisites.md

，操作前请使用

status

skill验证连接状态。

</context> <instructions>

How GitOps Works with TrueFoundry

TrueFoundry的GitOps工作原理

GitOps treats Git as the single source of truth for deployment configurations. The workflow is:

Store specs in Git — All TrueFoundry resource YAML specs live in the repository
Review via pull requests — Changes are reviewed before merging, with
```
tfy apply --dry-run
```
validating specs in CI
Auto-deploy on merge — When specs are merged to the default branch,
```
tfy apply
```
deploys them automatically
Full audit trail — Git history tracks every change, who made it, and when

GitOps将Git作为部署配置的唯一可信源，工作流程如下：

在Git中存储规范 — 所有TrueFoundry资源YAML规范都存放在代码仓库中
通过拉取请求评审 — 变更合并前需要经过评审，CI中通过
```
tfy apply --dry-run
```
验证规范有效性
合并后自动部署 — 当规范合并到默认分支时，
```
tfy apply
```
会自动完成部署
完整审计轨迹 — Git历史记录会追踪每一次变更、变更人及变更时间

Repository Organization

仓库组织结构

Organize your repo with directories for each resource type:

truefoundry-configs/
├── clusters/
│   └── my-cluster/
│       ├── dev-workspace/
│       │   ├── my-api-service.yaml
│       │   ├── my-worker.yaml
│       │   └── my-llm.yaml
│       ├── staging-workspace/
│       │   ├── my-api-service.yaml
│       │   └── my-worker.yaml
│       └── prod-workspace/
│           ├── my-api-service.yaml
│           └── my-worker.yaml
├── integrations/
│   └── custom-integration.yaml
├── teams/
│   └── my-team.yaml
└── virtualaccounts/
    └── my-account.yaml

按照资源类型创建目录来组织仓库结构：

truefoundry-configs/
├── clusters/
│   └── my-cluster/
│       ├── dev-workspace/
│       │   ├── my-api-service.yaml
│       │   ├── my-worker.yaml
│       │   └── my-llm.yaml
│       ├── staging-workspace/
│       │   ├── my-api-service.yaml
│       │   └── my-worker.yaml
│       └── prod-workspace/
│           ├── my-api-service.yaml
│           └── my-worker.yaml
├── integrations/
│   └── custom-integration.yaml
├── teams/
│   └── my-team.yaml
└── virtualaccounts/
    └── my-account.yaml

Key Principles

核心原则

One YAML file per resource — Each TrueFoundry resource (service, job, model, etc.) gets its own file
Filename matches resource name — The YAML filename should match the
```
name
```
field inside the spec
Separate directories per workspace — Keep dev, staging, and prod configs in separate directories
Extract specs from the UI — Use "Edit -> Apply Using YAML" in the TrueFoundry dashboard to get the YAML spec for any existing resource

每个资源对应一个YAML文件 — 每个TrueFoundry资源（服务、任务、模型等）都有独立的配置文件
文件名与资源名称匹配 — YAML文件名需要与规范内部的
```
name
```
字段一致
每个工作区对应独立目录 — 开发、预发、生产环境的配置存放在不同目录中
从UI导出规范 — 可以通过TrueFoundry控制台的「编辑 -> 使用YAML应用」功能获取已有资源的YAML规范

Manifest File Structure

配置文件结构

Each YAML spec follows the standard TrueFoundry manifest format. For example, a service spec:

yaml

type: service
name: my-api-service
image:
  type: image
  image_uri: my-registry/my-app:latest
  command: uvicorn main:app --host 0.0.0.0 --port 8000
ports:
  - port: 8000
    expose: true
    protocol: TCP
    app_protocol: http
    host: my-api-dev.ml.example.truefoundry.cloud
workspace_fqn: my-cluster:dev-workspace
env:
  APP_ENV: development
  LOG_LEVEL: debug
replicas:
  min: 1
  max: 3
resources:
  cpu_request: 0.5
  cpu_limit: 1.0
  memory_request: 512
  memory_limit: 1024

每个YAML规范都遵循标准的TrueFoundry清单格式，例如服务规范示例：

yaml

type: service
name: my-api-service
image:
  type: image
  image_uri: my-registry/my-app:latest
  command: uvicorn main:app --host 0.0.0.0 --port 8000
ports:
  - port: 8000
    expose: true
    protocol: TCP
    app_protocol: http
    host: my-api-dev.ml.example.truefoundry.cloud
workspace_fqn: my-cluster:dev-workspace
env:
  APP_ENV: development
  LOG_LEVEL: debug
replicas:
  min: 1
  max: 3
resources:
  cpu_request: 0.5
  cpu_limit: 1.0
  memory_request: 512
  memory_limit: 1024

Environment-Specific Configs (Dev / Staging / Prod)

环境专属配置（开发/预发/生产）

Maintain separate YAML files per environment. Common differences:

Setting	Dev	Staging	Prod
`replicas.min`	1	1	2+
`replicas.max`	1	3	10+
`resources.cpu_request`	0.25	0.5	1.0+
`resources.memory_request`	256	512	1024+
`env.LOG_LEVEL`	debug	info	warn
`ports.host`	`-dev.`	`-staging.`	`-prod.`
`workspace_fqn`	`cluster:dev-ws`	`cluster:staging-ws`	`cluster:prod-ws`

Example directory layout:

clusters/my-cluster/
├── dev-workspace/
│   └── my-service.yaml       # min resources, 1 replica, debug logging
├── staging-workspace/
│   └── my-service.yaml       # moderate resources, autoscaling, info logging
└── prod-workspace/
    └── my-service.yaml        # full resources, HA replicas, warn logging

每个环境维护独立的YAML文件，常见的配置差异如下：

配置项	开发环境	预发环境	生产环境
`replicas.min`	1	1	2+
`replicas.max`	1	3	10+
`resources.cpu_request`	0.25	0.5	1.0+
`resources.memory_request`	256	512	1024+
`env.LOG_LEVEL`	debug	info	warn
`ports.host`	`-dev.`	`-staging.`	`-prod.`
`workspace_fqn`	`cluster:dev-ws`	`cluster:staging-ws`	`cluster:prod-ws`

目录布局示例：

clusters/my-cluster/
├── dev-workspace/
│   └── my-service.yaml       # 最低资源配置，1个副本，debug日志级别
├── staging-workspace/
│   └── my-service.yaml       # 中等资源配置，自动扩缩容，info日志级别
└── prod-workspace/
    └── my-service.yaml        # 全量资源配置，高可用副本，warn日志级别

Using

tfy apply

in CI/CD Pipelines

在CI/CD流水线中使用

tfy apply

The

tfy apply

command is the core of GitOps with TrueFoundry.

tfy apply

命令是TrueFoundry GitOps的核心。

Basic Usage

基础用法

bash

undefined

bash

undefined

Install TrueFoundry CLI (pin exact version to prevent supply-chain attacks)

安装TrueFoundry CLI（固定具体版本避免供应链攻击）

pip install 'truefoundry==0.5.3'

Authenticate (uses TFY_HOST and TFY_API_KEY env vars)

身份认证（使用环境变量TFY_HOST和TFY_API_KEY）

TFY_HOST is the TrueFoundry platform URL (same as TFY_BASE_URL)

TFY_HOST是TrueFoundry平台URL（与TFY_BASE_URL相同）

Dry run — validate without deploying

试运行 — 仅验证不部署

tfy apply --file path/to/spec.yaml --dry-run

Apply — deploy the spec

应用配置 — 部署规范

tfy apply --file path/to/spec.yaml

undefined

tfy apply --file path/to/spec.yaml

undefined

Applying Multiple Files

应用多个文件

To apply all changed files in a CI/CD pipeline, detect which files were modified in the commit or PR:

bash

undefined

要在CI/CD流水线中应用所有变更的文件，可以检测提交或PR中修改的文件：

bash

undefined

Apply each changed YAML file

应用每个变更的YAML文件

while IFS= read -r file; do [ -z "$file" ] && continue case "$file" in *.yaml) ;; *) echo "Skipping non-yaml path: $file"; continue ;; esac

Keep apply scope constrained to your config tree

case "$file" in truefoundry-configs/*) ;; ) echo "Skipping out-of-scope path: $file"; continue ;; esac echo "Applying $file..." tfy apply --file "$file" done < <(git diff --name-only HEAD~1 HEAD -- '.yaml')

undefined

while IFS= read -r file; do [ -z "$file" ] && continue case "$file" in *.yaml) ;; *) echo "跳过非YAML路径: $file"; continue ;; esac

限定apply的范围为配置目录

case "$file" in truefoundry-configs/*) ;; ) echo "跳超出范围的路径: $file"; continue ;; esac echo "正在应用 $file..." tfy apply --file "$file" done < <(git diff --name-only HEAD~1 HEAD -- '.yaml')

undefined

Handling Deleted Files

处理已删除的文件

When a YAML spec file is deleted from the repo, the corresponding resource should be removed. The CI/CD pipeline should detect deleted files and handle them:

bash

undefined

当YAML规范文件从仓库中删除时，对应的资源也应该被移除。CI/CD流水线需要检测已删除的文件并进行处理：

bash

undefined

Warn about deleted files

对已删除的文件发出警告

while IFS= read -r file; do [ -z "$file" ] && continue echo "WARNING: $file was deleted. Remove the resource manually from the TrueFoundry dashboard." done < <(git diff --name-only --diff-filter=D HEAD~1 HEAD -- '*.yaml')

undefined

while IFS= read -r file; do [ -z "$file" ] && continue echo "警告: $file 已被删除，请手动从TrueFoundry控制台移除对应的资源。" done < <(git diff --name-only --diff-filter=D HEAD~1 HEAD -- '*.yaml')

undefined

CI/CD Integration

CI/CD集成

For complete workflow files for each CI provider:

GitHub Actions: See references/gitops-github-actions.md -- PR validation (dry-run) and merge-to-deploy workflows, plus required secrets setup.
GitLab CI: See references/gitops-gitlab-ci.md -- validate and deploy stages with caching.
Bitbucket Pipelines: See references/gitops-bitbucket-pipelines.md -- PR validation and branch-based deploy.

All providers require

TFY_HOST

and

TFY_API_KEY

as repository secrets/variables.

各CI提供商的完整工作流文件请查看：

GitHub Actions: 查看references/gitops-github-actions.md — 包含PR验证（试运行）和合并部署工作流，以及所需的密钥配置说明。
GitLab CI: 查看references/gitops-gitlab-ci.md — 包含带缓存的验证和部署阶段配置。
Bitbucket Pipelines: 查看references/gitops-bitbucket-pipelines.md — 包含PR验证和基于分支的部署配置。

所有提供商都需要将

TFY_HOST

和

TFY_API_KEY

配置为仓库密钥/变量。

CI Security Hardening (Required)

CI安全加固（必填）

Run deploy jobs only on trusted contexts (for example, default-branch merges), not untrusted fork PRs.
Keep
```
TFY_API_KEY
```
scoped minimally and rotated regularly.
Prefer protected environments/branches for production applies.
Avoid printing env vars or command traces that can expose secret material.

仅在可信上下文（例如默认分支合并）中运行部署任务，不要在不可信的Fork PR中运行。
最小化
```
TFY_API_KEY
```
的权限范围并定期轮换。
生产环境部署优先使用受保护的环境/分支。
避免打印可能泄露敏感信息的环境变量或命令追踪日志。

Step-by-Step: Setting Up GitOps (Summary)

分步搭建GitOps（摘要）

Verify TrueFoundry connection — Use the
```
status
```
skill to confirm credentials
Create the repo structure — Set up directories for your resource types (clusters, teams, etc.)
Export existing specs — In the TrueFoundry dashboard, go to each resource -> Edit -> Apply Using YAML. Save each spec as a YAML file in the repo.
Add CI/CD workflows — Copy the appropriate workflow files for your CI provider (see above)
Set repository secrets — Add
```
TFY_HOST
```
and
```
TFY_API_KEY
```
as secrets/variables in your CI provider
Test with a dry run — Open a PR with a small change to verify the validation pipeline works
Merge and deploy — Merge the PR and confirm the apply pipeline deploys successfully

</instructions>

<success_criteria>

验证TrueFoundry连接 — 使用
```
status
```
skill确认凭证有效
创建仓库结构 — 为各资源类型（集群、团队等）创建对应目录
导出已有规范 — 在TrueFoundry控制台，进入每个资源 -> 编辑 -> 使用YAML应用，将每个规范保存为仓库中的YAML文件
添加CI/CD工作流 — 复制对应CI提供商的工作流文件（见上文）
配置仓库密钥 — 在CI提供商中添加
```
TFY_HOST
```
和
```
TFY_API_KEY
```
作为密钥/变量
试运行测试 — 提交一个小变更打开PR，验证验证流水线正常运行
合并部署 — 合并PR，确认应用流水线部署成功

</instructions>

<success_criteria>

Success Criteria

成功标准

The user has a Git repository with TrueFoundry YAML specs organized by environment (dev/staging/prod)
The CI/CD pipeline validates specs on pull requests using
```
tfy apply --dry-run
```
The CI/CD pipeline auto-deploys specs on merge to the default branch using
```
tfy apply
```
The agent has provided the user with the correct CI workflow files for their CI provider (GitHub Actions, GitLab CI, or Bitbucket Pipelines)
Repository secrets (
```
TFY_HOST
```
,
```
TFY_API_KEY
```
) are configured in the CI provider
The user can verify the pipeline works by opening a PR with a small YAML change and seeing validation pass

</success_criteria>

用户拥有按环境（开发/预发/生产）组织的、存储TrueFoundry YAML规范的Git仓库
CI/CD流水线在拉取请求阶段使用
```
tfy apply --dry-run
```
验证规范有效性
CI/CD流水线在合并到默认分支时使用
```
tfy apply
```
自动部署规范
Agent已为用户提供其CI提供商（GitHub Actions、GitLab CI或Bitbucket Pipelines）对应的正确CI工作流文件
仓库密钥（
```
TFY_HOST
```
、
```
TFY_API_KEY
```
）已在CI提供商中完成配置
用户可以通过提交包含小YAML变更的PR，看到验证通过，确认流水线正常运行

</success_criteria>

Composability

可组合性

Verify connection first: Use
```
status
```
skill to check TrueFoundry credentials
Find workspace FQN: Use
```
workspaces
```
skill to get workspace FQNs for your specs
Check existing deployments: Use
```
applications
```
skill to see what is already deployed
Deploy LLM models via GitOps: Use
```
llm-deploy
```
skill to generate the manifest YAML, then store it in Git
Manage secrets: Use
```
secrets
```
skill to set up secret groups referenced in your specs
View deployment logs: Use
```
logs
```
skill to debug deployments after apply

</references> <troubleshooting>

优先验证连接: 使用
```
status
```
skill检查TrueFoundry凭证有效性
查找工作区FQN: 使用
```
workspaces
```
skill获取配置所需的工作区FQN
检查已有部署: 使用
```
applications
```
skill查看已部署的资源
通过GitOps部署LLM模型: 使用
```
llm-deploy
```
skill生成清单YAML，再存储到Git中
管理密钥: 使用
```
secrets
```
skill配置规范中引用的密钥组
查看部署日志: 应用配置后使用
```
logs
```
skill调试部署问题

</references> <troubleshooting>

Error Handling

错误处理

tfy apply Failed — Invalid Spec

tfy apply失败 — 规范无效

tfy apply returned a validation error.
Check:
- YAML syntax is valid (no tabs, proper indentation)
- Required fields are present (type, name, workspace_fqn)
- Resource references exist (workspace, secrets, etc.)
Run: tfy apply --file spec.yaml --dry-run

tfy apply返回验证错误。
检查：
- YAML语法有效（无制表符、缩进正确）
- 必填字段存在（type、name、workspace_fqn）
- 资源引用存在（工作区、密钥等）
执行：tfy apply --file spec.yaml --dry-run

tfy apply Failed — Authentication Error

tfy apply失败 — 认证错误

401 Unauthorized from tfy apply.
Check:
- TFY_HOST is set correctly (the platform URL, e.g., https://your-org.truefoundry.cloud)
- TFY_API_KEY is valid and not expired
- Secrets are configured correctly in your CI provider

tfy apply返回401未授权。
检查：
- TFY_HOST配置正确（平台URL，例如https://your-org.truefoundry.cloud）
- TFY_API_KEY有效且未过期
- CI提供商中的密钥配置正确

tfy apply Failed — Workspace Not Found

tfy apply失败 — 未找到工作区

Workspace FQN in the spec does not exist.
Check:
- workspace_fqn field matches an existing workspace
- Use the workspaces skill to list available workspaces

规范中的工作区FQN不存在。
检查：
- workspace_fqn字段与现有工作区匹配
- 使用workspaces skill列出可用的工作区

CI Pipeline Not Triggering

CI流水线未触发

Workflow not running on push/PR.
Check:
- File path filters match your YAML file locations
- Branch filters match your default branch name
- CI provider secrets are set (TFY_HOST, TFY_API_KEY)

代码推送/PR时工作流未运行。
检查：
- 文件路径过滤器匹配你的YAML文件位置
- 分支过滤器匹配你的默认分支名称
- CI提供商密钥已配置（TFY_HOST、TFY_API_KEY）

Filename / Spec Name Mismatch

文件名/规范名称不匹配

The YAML filename should match the 'name' field inside the spec.
Example: my-service.yaml should contain name: my-service
This is a convention for clarity — tfy apply uses the internal name, not the filename.

</troubleshooting>

YAML文件名需要与规范内部的'name'字段匹配。
示例：my-service.yaml中应该包含name: my-service
这是为了清晰性的约定 — tfy apply使用内部名称，而非文件名。

</troubleshooting>

truefoundry-gitops

Original

Translation

GitOps with TrueFoundry

基于TrueFoundry的GitOps

When to Use

适用场景

When NOT to Use

不适用场景

Prerequisites

前置条件

How GitOps Works with TrueFoundry

TrueFoundry的GitOps工作原理

Repository Organization

仓库组织结构

Key Principles

核心原则

Manifest File Structure

配置文件结构

Environment-Specific Configs (Dev / Staging / Prod)

环境专属配置（开发/预发/生产）

Using tfy apply in CI/CD Pipelines

在CI/CD流水线中使用tfy apply

Basic Usage

基础用法

Install TrueFoundry CLI (pin exact version to prevent supply-chain attacks)

安装TrueFoundry CLI（固定具体版本避免供应链攻击）

Authenticate (uses TFY_HOST and TFY_API_KEY env vars)

身份认证（使用环境变量TFY_HOST和TFY_API_KEY）

TFY_HOST is the TrueFoundry platform URL (same as TFY_BASE_URL)

TFY_HOST是TrueFoundry平台URL（与TFY_BASE_URL相同）

Dry run — validate without deploying

试运行 — 仅验证不部署

Apply — deploy the spec

应用配置 — 部署规范

Applying Multiple Files

应用多个文件

Apply each changed YAML file

应用每个变更的YAML文件

Keep apply scope constrained to your config tree

限定apply的范围为配置目录

Handling Deleted Files

处理已删除的文件

Warn about deleted files

对已删除的文件发出警告

CI/CD Integration

CI/CD集成

CI Security Hardening (Required)

CI安全加固（必填）

Step-by-Step: Setting Up GitOps (Summary)

分步搭建GitOps（摘要）

Success Criteria

成功标准

Composability

可组合性

Error Handling

错误处理

tfy apply Failed — Invalid Spec

tfy apply失败 — 规范无效

tfy apply Failed — Authentication Error

tfy apply失败 — 认证错误

tfy apply Failed — Workspace Not Found

tfy apply失败 — 未找到工作区

CI Pipeline Not Triggering

CI流水线未触发

Filename / Spec Name Mismatch

文件名/规范名称不匹配

Using
`tfy apply`
in CI/CD Pipelines

在CI/CD流水线中使用
`tfy apply`