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

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

Helm Chart Deployment

Helm Chart 部署

Deploy any Helm chart to TrueFoundry -- databases, caches, message queues, vector databases, monitoring tools, or any other OCI-compatible Helm chart. TrueFoundry supports any chart as long as the cluster can pull it from the registry.

Two paths:

CLI (
```
tfy apply
```
) -- Write a YAML manifest and apply it. Works everywhere.
REST API (fallback) -- When CLI unavailable, use
```
tfy-api.sh
```
.

可向TrueFoundry部署任意Helm chart——数据库、缓存、消息队列、向量数据库、监控工具，或任何其他兼容OCI的Helm chart。只要集群可以从镜像仓库拉取对应chart，TrueFoundry就可以提供支持。

两种部署路径：

CLI (
```
tfy apply
```
) -- 编写YAML清单并执行应用命令，全场景可用。
REST API（备选方案）-- 当CLI不可用时，使用
```
tfy-api.sh
```
完成部署。

When to Use

适用场景

User explicitly wants a Helm chart deployment for a database (PostgreSQL, MySQL, MongoDB, etc.)
User wants to install a cache (Redis, Memcached)
User wants to deploy a message queue (RabbitMQ, Kafka, NATS)
User says "install helm chart", "deploy via helm"
User wants infrastructure components, not application code
User wants to deploy a vector database (Qdrant, Milvus, Weaviate, Chroma)
User wants to deploy monitoring tools (Prometheus, Grafana)
User has a custom/private Helm chart to deploy
User wants to deploy ANY infrastructure component available as a Helm chart

If user intent is "deploy Postgres/Redis/database" without saying Helm, ask which strategy they want:

Helm chart infrastructure (
```
helm
```
skill)
Containerized service deployment (
```
deploy
```
skill)

用户明确需要通过Helm chart部署数据库（PostgreSQL、MySQL、MongoDB等）
用户需要安装缓存（Redis、Memcached）
用户需要部署消息队列（RabbitMQ、Kafka、NATS）
用户提到「安装helm chart」、「通过helm部署」
用户需要部署基础设施组件，而非应用代码
用户需要部署向量数据库（Qdrant、Milvus、Weaviate、Chroma）
用户需要部署监控工具（Prometheus、Grafana）
用户有自定义/私有Helm chart需要部署
用户需要部署任何以Helm chart形式提供的基础设施组件

如果用户意图是「部署Postgres/Redis/数据库」但未提到Helm，询问用户期望的部署策略：

Helm chart基础设施部署（
```
helm
```
skill）
容器化服务部署（
```
deploy
```
skill）

When NOT to Use

不适用场景

User wants to deploy application code -> prefer
```
deploy
```
skill; ask if the user wants another valid path
User explicitly asks for Docker/container/image-based database deployment -> use
```
deploy
```
containerized service path (not Helm)
User wants to check what's deployed -> prefer
```
applications
```
skill; ask if the user wants another valid path
User wants to view logs -> prefer
```
logs
```
skill; ask if the user wants another valid path

</objective> <context>

用户需要部署应用代码 -> 优先使用
```
deploy
```
skill；询问用户是否需要其他有效部署路径
用户明确要求基于Docker/容器/镜像的数据库部署 -> 使用
```
deploy
```
容器化服务路径（而非Helm）
用户需要查看已部署的内容 -> 优先使用
```
applications
```
skill；询问用户是否需要其他有效路径
用户需要查看日志 -> 优先使用
```
logs
```
skill；询问用户是否需要其他有效路径

</objective> <context>

Prerequisites

前置要求

Always verify before deploying:

Credentials --
```
TFY_BASE_URL
```
and
```
TFY_API_KEY
```
must be set (env or
```
.env
```
)
Workspace --
```
TFY_WORKSPACE_FQN
```
required. Never auto-pick. Ask the user if missing.

CLI -- Check if

tfy

CLI is available:

tfy --version

. If not,

pip install 'truefoundry==0.5.0'

.

For credential check commands and .env setup, see

references/prerequisites.md

.

部署前请始终验证以下条件：

凭证 -- 必须配置
```
TFY_BASE_URL
```
和
```
TFY_API_KEY
```
（环境变量或
```
.env
```
文件）
工作空间 -- 必须提供
```
TFY_WORKSPACE_FQN
```
。禁止自动选择，缺失时必须询问用户。
CLI -- 检查
```
tfy
```
CLI是否可用：执行
```
tfy --version
```
。如果未安装，执行
```
pip install 'truefoundry==0.5.0'
```
。

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

references/prerequisites.md

。

User Confirmation Checklist

用户确认清单

Before deploying a Helm chart, ALWAYS confirm these with the user:

Chart source -- Which chart? (suggest from common charts table)
Chart registry -- Public (official chart registries) or private registry?
Chart version -- Specific version or latest?
Release name -- What to call this deployment? (default: chart name + random suffix)
Namespace/Workspace -- Which workspace FQN? (never auto-pick)
Environment -- Is this for dev, staging, or production? (affects resource defaults)
Configuration -- Critical values to set:
- Passwords/credentials -- Use strong random values or reference TrueFoundry secrets
- Storage size -- Persistent volume size (e.g., 10Gi, 20Gi)
- Resources -- CPU/memory limits and requests
- Replicas -- Number of instances (1 for dev, 3+ for prod)
- Network -- Expose externally or internal-only?
Auto-shutdown -- Should the deployment auto-stop after inactivity? (useful for dev/staging to save costs)

Do NOT deploy with minimal defaults without asking. Production databases need proper sizing, credentials, and persistence configuration.

</context> <instructions>

部署Helm chart前，请务必与用户确认以下内容：

Chart来源 -- 使用哪个chart？（可从常用chart表格中推荐）
Chart仓库 -- 公开（官方chart仓库）还是私有仓库？
Chart版本 -- 指定版本还是最新版本？
发布名称 -- 本次部署的命名是什么？（默认值：chart名称+随机后缀）
命名空间/工作空间 -- 使用哪个工作空间FQN？（禁止自动选择）
环境 -- 部署用于开发、测试还是生产环境？（会影响资源默认配置）
配置 -- 需要设置的关键参数：
- 密码/凭证 -- 使用高强度随机值，或引用TrueFoundry密钥
- 存储大小 -- 持久卷容量（例如10Gi、20Gi）
- 资源配额 -- CPU/内存的上限和请求值
- 副本数 -- 实例数量（开发环境1个，生产环境3个及以上）
- 网络 -- 对外暴露还是仅内部访问？
自动停机 -- 部署是否需要在无活动后自动停止？（适用于开发/测试环境，可节约成本）

禁止使用最小默认配置不询问用户直接部署。 生产环境数据库需要合理的资源配置、凭证管理和持久化配置。

</context> <instructions>

Finding & Sourcing Helm Charts

查找与获取Helm Charts

For chart sources, OCI URLs, registries, version discovery, and the chart selection guide, see references/helm-chart-sources.md.

Key points: TrueFoundry supports

oci-repo

(recommended),

helm-repo

, and

git-helm-repo

source types. Do NOT use Bitnami charts. Always search Artifact Hub for the official chart from the project maintainers or use the chart publisher's own OCI registry.

Security: Helm charts from public registries are third-party code that runs in your cluster. Only use charts from trusted sources. Always pin chart versions — never use
latest
or floating tags. Review chart values before deploying. Verify the chart publisher is the official project maintainer. Do not allow the agent to discover and deploy charts from Artifact Hub without user confirmation of the chart source and version.

关于chart来源、OCI URL、仓库、版本查找以及chart选择指南，请参考references/helm-chart-sources.md。

核心要点：TrueFoundry支持

oci-repo

（推荐）、

helm-repo

和

git-helm-repo

三类来源。禁止使用Bitnami charts。 始终在Artifact Hub搜索项目维护者提供的官方chart，或使用chart发布方自己的OCI仓库。

安全提示： 公开仓库的Helm charts是运行在你的集群中的第三方代码。仅使用可信来源的chart。始终固定chart版本——禁止使用
latest
或浮动标签。部署前审核chart参数配置。确认chart发布者是官方项目维护者。在用户未确认chart来源和版本的情况下，不允许Agent从Artifact Hub查找并部署chart。

Deploy Flow

部署流程

1. Gather Configuration

1. 收集配置信息

Ask the user for critical configuration values. For a PostgreSQL example:

I'll deploy PostgreSQL to TrueFoundry. Let me confirm a few things:

1. Chart version: Use postgresql 15.x (latest stable)? Or specific version?
2. Database name: What should the default database be called? (default: postgres)
3. Password: I'll generate a strong random password. Or do you have a TrueFoundry secret group to reference?
4. Storage: How much persistent storage? (default: 10Gi for dev, 50Gi+ for prod)
5. Resources:
   - CPU: 0.5 cores for dev, 2+ for prod?
   - Memory: 512Mi for dev, 2Gi+ for prod?
6. Replicas: 1 for dev, 3+ for prod high availability?
7. Access: Internal-only (default) or expose externally?

向用户询问关键配置参数。以PostgreSQL为例：

我将为您在TrueFoundry上部署PostgreSQL。需要和您确认几个信息：

1. Chart版本：使用postgresql 15.x（最新稳定版）？还是指定特定版本？
2. 数据库名称：默认数据库命名为什么？（默认值：postgres）
3. 密码：我将生成一个高强度随机密码，或者您是否有要引用的TrueFoundry密钥组？
4. 存储：需要多大的持久化存储？（默认值：开发环境10Gi，生产环境50Gi以上）
5. 资源配额：
   - CPU：开发环境0.5核，生产环境2核及以上？
   - 内存：开发环境512Mi，生产环境2Gi及以上？
6. 副本数：开发环境1个，生产环境3个及以上实现高可用？
7. 访问权限：仅内部访问（默认）还是对外暴露？

2. Generate YAML Manifest

2. 生成YAML清单

Create a YAML manifest with user-confirmed values:

yaml

name: postgres-prod
type: helm
source:
  type: oci-repo
  version: "16.7.21"
  oci_chart_url: oci://REGISTRY/CHART_NAME  # Search Artifact Hub for the official chart
values:
  auth:
    postgresPassword: GENERATED_OR_SECRET_REF
    database: myapp
  primary:
    persistence:
      enabled: true
      size: 50Gi
    resources:
      requests:
        cpu: "2"
        memory: 2Gi
      limits:
        cpu: "4"
        memory: 4Gi
  readReplicas:
    replicaCount: 2
workspace_fqn: cluster-id:workspace-name

使用用户确认的参数创建YAML清单：

yaml

name: postgres-prod
type: helm
source:
  type: oci-repo
  version: "16.7.21"
  oci_chart_url: oci://REGISTRY/CHART_NAME  # 在Artifact Hub搜索官方chart获取
values:
  auth:
    postgresPassword: GENERATED_OR_SECRET_REF
    database: myapp
  primary:
    persistence:
      enabled: true
      size: 50Gi
    resources:
      requests:
        cpu: "2"
        memory: 2Gi
      limits:
        cpu: "4"
        memory: 4Gi
  readReplicas:
    replicaCount: 2
workspace_fqn: cluster-id:workspace-name

3. Write and Preview Manifest

3. 编写并预览清单

Write the manifest to

tfy-manifest.yaml

:

bash

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

Show the preview output to the user.

将清单写入

tfy-manifest.yaml

：

bash

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

将预览结果展示给用户。

4. Apply

4. 执行部署

After user confirms:

bash

tfy apply -f tfy-manifest.yaml

用户确认后执行：

bash

tfy apply -f tfy-manifest.yaml

Fallback: REST API

备选方案：REST API

If

tfy

CLI is not available, convert the YAML manifest to JSON and deploy via REST API. See

references/cli-fallback.md

for the conversion process.

Important: The

workspaceId

must be the internal workspace ID (not the FQN). Get it from the

workspaces

skill:

GET /api/svc/v1/workspaces?fqn=WORKSPACE_FQN

-> use the

id

field.

When using direct API, set

TFY_API_SH

to the full path of this skill's

scripts/tfy-api.sh

. See

references/tfy-api-setup.md

for paths per agent.

如果

tfy

CLI不可用，将YAML清单转换为JSON，通过REST API部署。转换流程请参考

references/cli-fallback.md

。

重要提示：

workspaceId

必须是内部工作空间ID（而非FQN）。可通过

workspaces

skill获取：

GET /api/svc/v1/workspaces?fqn=WORKSPACE_FQN

-> 使用返回的

id

字段。

使用直接API部署时，将

TFY_API_SH

设置为当前skill的

scripts/tfy-api.sh

完整路径。不同Agent对应的路径请参考

references/tfy-api-setup.md

。

Via Tool Call

通过工具调用部署

tfy_applications_create_deployment(
    manifest={
        "name": "postgres-prod",
        "type": "helm",
        "source": {
            "type": "oci-repo",
            "version": "16.7.21",
            "oci_chart_url": "oci://REGISTRY/CHART_NAME"
        },
        "values": {...},
        "workspace_fqn": "cluster-id:workspace-name"
    },
    options={
        "workspace_id": "ws-internal-id",
        "force_deploy": false
    }
)

Note: This requires human approval (HITL) when using tool calls.

tfy_applications_create_deployment(
    manifest={
        "name": "postgres-prod",
        "type": "helm",
        "source": {
            "type": "oci-repo",
            "version": "16.7.21",
            "oci_chart_url": "oci://REGISTRY/CHART_NAME"
        },
        "values": {...},
        "workspace_fqn": "cluster-id:workspace-name"
    },
    options={
        "workspace_id": "ws-internal-id",
        "force_deploy": false
    }
)

注意： 使用工具调用时需要人工审批（HITL）。

Via Direct API

通过直接API部署

bash

TFY_API_SH=~/.claude/skills/truefoundry-helm/scripts/tfy-api.sh

bash

TFY_API_SH=~/.claude/skills/truefoundry-helm/scripts/tfy-api.sh

First, get workspace ID from FQN

首先通过FQN获取工作空间ID

$TFY_API_SH GET "/api/svc/v1/workspaces?fqn=${TFY_WORKSPACE_FQN}"

Then deploy (JSON body)

然后执行部署（JSON请求体）

$TFY_API_SH PUT /api/svc/v1/apps '{ "manifest": { "name": "postgres-prod", "type": "helm", "source": { "type": "oci-repo", "version": "16.7.21", "oci_chart_url": "oci://REGISTRY/CHART_NAME" }, "values": { "auth": {"postgresPassword": "...", "database": "myapp"}, "primary": { "persistence": {"enabled": true, "size": "50Gi"}, "resources": { "requests": {"cpu": "2", "memory": "2Gi"}, "limits": {"cpu": "4", "memory": "4Gi"} } } }, "workspace_fqn": "cluster-id:workspace-name" }, "workspaceId": "WORKSPACE_ID_HERE" }'

undefined

$TFY_API_SH PUT /api/svc/v1/apps '{ "manifest": { "name": "postgres-prod", "type": "helm", "source": { "type": "oci-repo", "version": "16.7.21", "oci_chart_url": "oci://REGISTRY/CHART_NAME" }, "values": { "auth": {"postgresPassword": "...", "database": "myapp"}, "primary": { "persistence": {"enabled": true, "size": "50Gi"}, "resources": { "requests": {"cpu": "2", "memory": "2Gi"}, "limits": {"cpu": "4", "memory": "4Gi"} } } }, "workspace_fqn": "cluster-id:workspace-name" }, "workspaceId": "WORKSPACE_ID_HERE" }'

undefined

5. Report Connection Details

5. 反馈连接信息

After successful deployment, provide the user with connection details (host, port, database, credentials). For connection DNS patterns and default ports by chart type, see references/helm-chart-sources.md (Connection Details by Chart section).

部署成功后，向用户提供连接信息（主机地址、端口、数据库名、凭证）。不同chart类型的连接DNS规则和默认端口请参考references/helm-chart-sources.md（Chart对应连接信息章节）。

Example Configurations

配置示例

For full YAML manifest examples (Redis, MongoDB, RabbitMQ, Qdrant, Elasticsearch), secrets management patterns, and environment-specific defaults, see references/helm-chart-examples.md.

完整YAML清单示例（Redis、MongoDB、RabbitMQ、Qdrant、Elasticsearch）、密钥管理方案、环境适配默认配置请参考references/helm-chart-examples.md。

Advanced: Kustomize & Additional Manifests

高级功能：Kustomize与额外清单

For Kustomize patches and deploying additional Kubernetes manifests alongside Helm charts, see references/helm-advanced.md.

关于Kustomize补丁、以及与Helm chart一同部署额外Kubernetes清单的方法，请参考references/helm-advanced.md。

After Deploy

部署后操作

After applying the Helm manifest, verify status automatically without asking an extra prompt.

Preferred verification path:

MCP tool call first:

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

Fallback to API:

bash

$TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=RELEASE_NAME'

Helm chart deployed successfully!

Next steps:
1. Deployment status verified and reported automatically
2. View logs: Use `logs` skill if there are issues
3. Connect from your app: Use the service DNS provided above
4. Store credentials: Use TrueFoundry secrets for app access

</instructions>

<success_criteria>

应用Helm清单后，无需额外询问即可自动验证部署状态。

优先验证路径：

优先调用MCP工具：

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

备选API方案：

bash

$TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=RELEASE_NAME'

Helm chart部署成功！

后续步骤：
1. 部署状态已自动验证并反馈
2. 查看日志：如果出现问题可使用`logs` skill
3. 应用连接：使用上方提供的服务DNS从您的应用访问
4. 凭证存储：使用TrueFoundry密钥管理应用访问凭证

</instructions>

<success_criteria>

Success Criteria

成功标准

The Helm chart is deployed and all pods are running in the target workspace
The agent has confirmed the chart version, resource sizing, and credentials with the user before deploying
Connection details (host, port, credentials) are provided to the user
Deployment status is verified automatically immediately after apply (no extra prompt)
Persistent storage is configured for stateful charts (databases, caches)
The user can connect to the deployed service from their application using the provided DNS

</success_criteria>

Helm chart部署完成，目标工作空间中所有Pod正常运行
部署前Agent已与用户确认chart版本、资源配置和凭证信息
已向用户提供连接信息（主机、端口、凭证）
部署完成后立即自动验证状态（无需额外提示）
有状态chart（数据库、缓存）已配置持久化存储
用户可以通过提供的DNS从应用连接到部署的服务

</success_criteria>

Composability

组合使用说明

Find workspace first: Use
```
workspaces
```
skill to get workspace FQN and ID
Check what's deployed: Use
```
applications
```
skill to list existing Helm releases
Test after deployment: Use
```
service-test
```
skill to validate the deployed service
Manage secrets: Use
```
secrets
```
skill to create secret groups before deploy
View logs: Use
```
logs
```
skill with the HelmRelease application ID
Connect from app: Reference the deployed chart's service DNS in your application's YAML manifest

</references> <troubleshooting>

优先查找工作空间：使用
```
workspaces
```
skill获取工作空间FQN和ID
查看已部署内容：使用
```
applications
```
skill列出已有的Helm发布
部署后测试：使用
```
service-test
```
skill验证部署的服务
管理密钥：部署前使用
```
secrets
```
skill创建密钥组
查看日志：通过HelmRelease应用ID使用
```
logs
```
skill
应用连接：在应用的YAML清单中引用部署的chart服务DNS

</references> <troubleshooting>

Error Handling

错误处理

For error messages and troubleshooting (workspace issues, chart not found, values validation, insufficient resources, PVC binding, connection issues), see references/helm-errors.md.

Additional CLI-specific errors:

tfy: command not found

-- Install with

pip install 'truefoundry==0.5.0'

```
tfy apply
```
validation errors -- Check YAML syntax, ensure required fields (name, type, source, workspace_fqn) are present

</troubleshooting> </output>

错误信息和故障排查（工作空间问题、chart未找到、参数校验失败、资源不足、PVC绑定失败、连接问题）请参考references/helm-errors.md。

额外CLI专属错误：

tfy: command not found

-- 执行

pip install 'truefoundry==0.5.0'

安装

```
tfy apply
```
校验错误 -- 检查YAML语法，确保必填字段（name、type、source、workspace_fqn）已填写

</troubleshooting> </output>

truefoundry-helm

Original

Translation

Helm Chart Deployment

Helm Chart 部署

When to Use

适用场景

When NOT to Use

不适用场景

Prerequisites

前置要求

User Confirmation Checklist

用户确认清单

Finding & Sourcing Helm Charts

查找与获取Helm Charts

Deploy Flow

部署流程

1. Gather Configuration

1. 收集配置信息

2. Generate YAML Manifest

2. 生成YAML清单

3. Write and Preview Manifest

3. 编写并预览清单

4. Apply

4. 执行部署

Fallback: REST API

备选方案：REST API

Via Tool Call

通过工具调用部署

Via Direct API

通过直接API部署

First, get workspace ID from FQN

首先通过FQN获取工作空间ID

Then deploy (JSON body)

然后执行部署（JSON请求体）

5. Report Connection Details

5. 反馈连接信息

Example Configurations

配置示例

Advanced: Kustomize & Additional Manifests

高级功能：Kustomize与额外清单

After Deploy

部署后操作

Success Criteria

成功标准

Composability

组合使用说明

Error Handling

错误处理