Back to Details

truefoundry-secrets

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.
<objective>
路由提示：如果用户意图不明确，请使用references/intent-clarification.md中的通用澄清模板。
<objective>

Secrets

密钥

Manage TrueFoundry secret groups and secrets. Secret groups organize secrets; individual secrets hold key-value pairs.
管理TrueFoundry密钥组和密钥。密钥组用于对密钥进行分类整理，单个密钥存储键值对。

When to Use

适用场景

List, create, update, or delete secret groups and individual secrets on TrueFoundry, including pre-deploy secret setup and value rotation.
</objective> <instructions>
Security Policy: Credential Handling
  • The agent MUST NOT accept, store, log, echo, or display raw secret values in any context.
  • Always instruct the user to set secret values as environment variables before running commands.
  • If the user provides a raw secret value directly in conversation, warn them and refuse to use it. Instruct them to set it as an env var instead.
  • When displaying secrets, show only "(set)" or the first 4 characters followed by "***".
在TrueFoundry上列出、创建、更新或删除密钥组以及单个密钥，包括部署前的密钥设置和值轮换。
</objective> <instructions>
安全政策：凭证处理
  • Agent在任何场景下都不得接收、存储、记录、回显或展示明文密钥值。
  • 始终告知用户在运行命令前先将密钥值设置为环境变量。
  • 如果用户直接在对话中提供明文密钥值，需发出警告并拒绝使用，同时指导用户将其设置为环境变量。
  • 展示密钥时，仅显示"(set)"或者前4个字符加"***"。

List Secret Groups

列出密钥组

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.
使用直接API时，请将
TFY_API_SH
设置为该技能
scripts/tfy-api.sh
文件的完整路径。每个Agent对应的路径可查看
references/tfy-api-setup.md
。

Via Tool Call

通过工具调用

tfy_secrets_list()
tfy_secrets_list(secret_group_id="group-id")  # get group + secrets
tfy_secrets_list(secret_id="secret-id")        # get one secret
tfy_secrets_list()
tfy_secrets_list(secret_group_id="group-id")  # get group + secrets
tfy_secrets_list(secret_id="secret-id")        # get one secret

Via Direct API

通过直接API

bash
undefined
bash
undefined

Set the path to tfy-api.sh for your agent (example for Claude Code):

Set the path to tfy-api.sh for your agent (example for Claude Code):

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

List all secret groups

List all secret groups

$TFY_API_SH GET /api/svc/v1/secret-groups
$TFY_API_SH GET /api/svc/v1/secret-groups

Get a specific group

Get a specific group

$TFY_API_SH GET /api/svc/v1/secret-groups/GROUP_ID
$TFY_API_SH GET /api/svc/v1/secret-groups/GROUP_ID

List secrets in a group

List secrets in a group

$TFY_API_SH POST /api/svc/v1/secrets '{"secretGroupId":"GROUP_ID","limit":100,"offset":0}'
$TFY_API_SH POST /api/svc/v1/secrets '{"secretGroupId":"GROUP_ID","limit":100,"offset":0}'

Get a specific secret

Get a specific secret

$TFY_API_SH GET /api/svc/v1/secrets/SECRET_ID
undefined
$TFY_API_SH GET /api/svc/v1/secrets/SECRET_ID
undefined

Presenting Secrets

密钥展示格式

Secret Groups:
| Name          | ID       | Secrets |
|---------------|----------|---------|
| prod-secrets  | sg-abc   | 5       |
| dev-secrets   | sg-def   | 3       |
Security: Never display secret values in full. Show only the first few characters or indicate "(set)". The agent must NEVER log, echo, or output raw secret values in any context.
Secret Groups:
| Name          | ID       | Secrets |
|---------------|----------|---------|
| prod-secrets  | sg-abc   | 5       |
| dev-secrets   | sg-def   | 3       |
安全要求： 永远不要完整展示密钥值，仅显示前几个字符或者标注"(set)"。Agent在任何场景下都绝对不能记录、回显或输出明文密钥值。

Create Secret Group

创建密钥组

Security: Credential Handling
  • The agent must NEVER accept, echo, or transmit raw secret values inline.
  • Never ask the user to paste secret values in chat.
  • Always instruct the user to store secret values in environment variables first, then reference those variables.
  • If the user provides a raw secret value directly, warn them and suggest using an env var instead.
安全政策：凭证处理
  • Agent绝对不能接收、回显或传输内联的明文密钥值。
  • 永远不要要求用户在聊天框中粘贴密钥值。
  • 始终指导用户先将密钥值存储到环境变量中，再引用这些变量。
  • 如果用户直接提供明文密钥值，需发出警告，建议改用环境变量。

Via Tool Call

通过工具调用

undefined
undefined

Prompt user to set secret values as environment variables first

Prompt user to set secret values as environment variables first

tfy_secret_groups_create(payload={"name": "my-secrets", ...})

**Note:** Requires human approval (HITL) via tool call.
tfy_secret_groups_create(payload={"name": "my-secrets", ...})

**注意：** 需要通过工具调用获得人工审批（HITL）。

Via Direct API

通过直接API

bash
undefined
bash
undefined

SECURITY: Never hardcode secret values in commands — they will appear in shell

SECURITY: Never hardcode secret values in commands — they will appear in shell

history and process listings. Read from environment variables or files instead.

history and process listings. Read from environment variables or files instead.

User must set: export DB_PASSWORD="..." before running this command.

User must set: export DB_PASSWORD="..." before running this command.

payload=$(jq -n
--arg name "my-secrets"
--arg integration "INTEGRATION_ID"
--arg db_password "$DB_PASSWORD"
'{ name: $name, integrationId: $integration, secrets: [{key: "DB_PASSWORD", value: $db_password}] }') $TFY_API_SH POST /api/svc/v1/secret-groups "$payload"
undefined
payload=$(jq -n
--arg name "my-secrets"
--arg integration "INTEGRATION_ID"
--arg db_password "$DB_PASSWORD"
'{ name: $name, integrationId: $integration, secrets: [{key: "DB_PASSWORD", value: $db_password}] }') $TFY_API_SH POST /api/svc/v1/secret-groups "$payload"
undefined

Update Secret Group

更新密钥组

Updates secrets in a group. A new version is created for every secret with a modified value. Secrets omitted from the array are deleted. At least one secret is required.
更新分组内的密钥。每个值被修改的密钥都会生成一个新版本。数组中未包含的密钥会被删除。操作时至少需要包含一个密钥。

Via Tool Call

通过工具调用

undefined
undefined

Instruct user to set env vars with new values, then reference them.

Instruct user to set env vars with new values, then reference them.

The agent must NEVER accept raw secret values — always use indirection.

The agent must NEVER accept raw secret values — always use indirection.

tfy_secret_groups_update( id="GROUP_ID", payload={"secrets": [{"key": "DB_PASSWORD", "value": "<secure-input-from-env>"}, {"key": "API_KEY", "value": "<secure-input-from-env>"}]} )

**Note:** Requires human approval (HITL) via tool call.
tfy_secret_groups_update( id="GROUP_ID", payload={"secrets": [{"key": "DB_PASSWORD", "value": "<secure-input-from-env>"}, {"key": "API_KEY", "value": "<secure-input-from-env>"}]} )

**注意：** 需要通过工具调用获得人工审批（HITL）。

Via Direct API

通过直接API

bash
undefined
bash
undefined

SECURITY: Read secret values from environment variables, not inline.

SECURITY: Read secret values from environment variables, not inline.

payload=$(jq -n
--arg db_password "$DB_PASSWORD"
--arg api_key "$NEW_API_KEY"
'{ secrets: [ {key: "DB_PASSWORD", value: $db_password}, {key: "API_KEY", value: $api_key} ] }') $TFY_API_SH PUT /api/svc/v1/secret-groups/GROUP_ID "$payload"
undefined
payload=$(jq -n
--arg db_password "$DB_PASSWORD"
--arg api_key "$NEW_API_KEY"
'{ secrets: [ {key: "DB_PASSWORD", value: $db_password}, {key: "API_KEY", value: $api_key} ] }') $TFY_API_SH PUT /api/svc/v1/secret-groups/GROUP_ID "$payload"
undefined

Delete Secret Group

删除密钥组

Via Tool Call

通过工具调用

tfy_secret_groups_delete(id="GROUP_ID")
Note: Requires human approval (HITL) via tool call.
tfy_secret_groups_delete(id="GROUP_ID")
注意： 需要通过工具调用获得人工审批（HITL）。

Via Direct API

通过直接API

bash
$TFY_API_SH DELETE /api/svc/v1/secret-groups/GROUP_ID
bash
$TFY_API_SH DELETE /api/svc/v1/secret-groups/GROUP_ID

Finding the Integration ID

查找集成ID

Before creating a secret group, you need the secret store integration ID for the workspace's cloud provider:
创建密钥组前，你需要获取工作区云提供商对应的密钥存储集成ID：

Via Direct API

通过直接API

bash
undefined
bash
undefined

List all secret store provider accounts and their integrations

List all secret store provider accounts and their integrations

bash $TFY_API_SH GET '/api/svc/v1/provider-accounts?type=secret-store'

From the response, look for integrations with `type: "secret-store"`. Each provider account contains an `integrations` array -- pick the integration matching the workspace's cloud provider:
- AWS: `integration/secret-store/aws/secrets-manager` or `integration/secret-store/aws/parameter-store`
- Azure: `integration/secret-store/azure/vault`
- GCP: `integration/secret-store/gcp/secret-manager`

Use the `id` field of the matching integration as the `integrationId` when creating secret groups.
bash $TFY_API_SH GET '/api/svc/v1/provider-accounts?type=secret-store'

从响应中查找`type: "secret-store"`的集成。每个提供商账户都包含一个`integrations`数组——选择与工作区云提供商匹配的集成：
- AWS: `integration/secret-store/aws/secrets-manager` 或 `integration/secret-store/aws/parameter-store`
- Azure: `integration/secret-store/azure/vault`
- GCP: `integration/secret-store/gcp/secret-manager`

使用匹配集成的`id`字段作为创建密钥组时的`integrationId`参数。

Using Secrets in Deployments

在部署中使用密钥

After creating a secret group, reference individual secrets in deployment manifests using the 
tfy-secret://
format:
tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY>
  • TENANT_NAME
    : The subdomain of 
    TFY_BASE_URL
    (e.g., 
    my-org
    from 
    https://my-org.truefoundry.cloud
    )
  • SECRET_GROUP_NAME
    : The name you gave the secret group when creating it
  • SECRET_KEY
    : The key of the individual secret within the group
创建密钥组后，使用
tfy-secret://
格式在部署清单中引用单个密钥：
tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY>
  • TENANT_NAME
    : 
    TFY_BASE_URL
    的子域名（例如
    https://my-org.truefoundry.cloud
    中的
    my-org
    ）
  • SECRET_GROUP_NAME
    : 你创建密钥组时设置的名称
  • SECRET_KEY
    : 分组内单个密钥对应的键名

Example: Manifest with Secret References

示例：包含密钥引用的清单

Given a secret group named 
my-app-secrets
with keys 
DB_PASSWORD
and 
API_KEY
:
yaml
name: my-app
type: service
image:
  type: image
  image_uri: docker.io/myorg/my-app:latest
ports:
  - port: 8000
    expose: false
    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
  DB_PASSWORD: tfy-secret://my-org:my-app-secrets:DB_PASSWORD
  API_KEY: tfy-secret://my-org:my-app-secrets:API_KEY
workspace_fqn: cluster-id:workspace-name
假设有一个名为
my-app-secrets
的密钥组，包含
DB_PASSWORD
和
API_KEY
两个键：
yaml
name: my-app
type: service
image:
  type: image
  image_uri: docker.io/myorg/my-app:latest
ports:
  - port: 8000
    expose: false
    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
  DB_PASSWORD: tfy-secret://my-org:my-app-secrets:DB_PASSWORD
  API_KEY: tfy-secret://my-org:my-app-secrets:API_KEY
workspace_fqn: cluster-id:workspace-name

Workflow: Secrets Before Deploy

工作流：部署前配置密钥

  1. Identify sensitive env vars (passwords, tokens, keys, credentials)
  2. Find the secret store integration ID (see above)
  3. Create a secret group with all sensitive values
  4. Reference secrets in the manifest 
    env
    using 
    tfy-secret://
    format
  5. Deploy with 
    tfy apply -f manifest.yaml
  1. 识别敏感环境变量（密码、令牌、密钥、凭证）
  2. 查找密钥存储集成ID（见上文）
  3. 创建包含所有敏感值的密钥组
  4. 在清单的
    env
    字段中使用
    tfy-secret://
    格式引用密钥
  5. 执行
    tfy apply -f manifest.yaml
    进行部署

Delete Individual Secret

删除单个密钥

Via Tool Call

通过工具调用

tfy_secrets_delete(id="SECRET_ID")
Note: Requires human approval (HITL) via tool call.
tfy_secrets_delete(id="SECRET_ID")
注意： 需要通过工具调用获得人工审批（HITL）。

Via Direct API

通过直接API

bash
$TFY_API_SH DELETE /api/svc/v1/secrets/SECRET_ID
</instructions>
<success_criteria>
bash
$TFY_API_SH DELETE /api/svc/v1/secrets/SECRET_ID
</instructions>
<success_criteria>

Success Criteria

成功标准

  • The user can list all secret groups and see their contents in a formatted table
  • The user can create a new secret group with a specified name
  • The user can update secrets in a group (rotate values, add/remove keys)
  • The user can delete a secret group or an individual secret
  • The agent has never displayed full secret values — only masked or "(set)" indicators
  • The user can inspect individual secrets within a group by ID
  • The agent has confirmed any create/update/delete operations before executing
</success_criteria>
<references>
  • 用户可以列出所有密钥组，并通过格式化表格查看其内容
  • 用户可以创建指定名称的新密钥组
  • 用户可以更新分组内的密钥（轮换值、添加/删除键）
  • 用户可以删除密钥组或单个密钥
  • Agent从未展示完整的密钥值——仅显示掩码后的内容或"(set)"标识
  • 用户可以通过ID查看分组内的单个密钥
  • Agent在执行任何创建/更新/删除操作前已获得用户确认
</success_criteria>
<references>

Composability

可组合性

  • Before deploy: Create secret groups, then reference in deployment config
  • After listing: Get individual secrets by ID for inspection
  • With applications: Reference secret groups in application env vars
</references> <troubleshooting>
  • 部署前： 创建密钥组，然后在部署配置中引用
  • 列出后： 通过ID获取单个密钥进行查看
  • 与应用配合： 在应用环境变量中引用密钥组
</references> <troubleshooting>

Error Handling

错误处理

Secret Group Not Found

密钥组未找到

Secret group ID not found. List groups first to find the correct ID.
Secret group ID not found. List groups first to find the correct ID.

Permission Denied

权限被拒绝

Cannot access secrets. Check your API key permissions.
Cannot access secrets. Check your API key permissions.

Secret Already Exists

密钥已存在

Secret group with this name already exists. Use a different name.
Secret group with this name already exists. Use a different name.

At Least One Secret Required

至少需要一个密钥

Cannot update secret group with zero secrets. Include at least one secret in the payload.
Cannot update secret group with zero secrets. Include at least one secret in the payload.

No Secret Store Configured

未配置密钥存储

No secret store configured for this workspace. Contact your platform admin.
No secret store configured for this workspace. Contact your platform admin.

Key Name Restrictions (Azure Key Vault)

键名限制（Azure Key Vault）

Key name does not support underscores (_)
Azure Key Vault does not allow underscores in secret key names. Use hyphens (
DB-PASSWORD
) or choose a different secret store integration (AWS Secrets Manager supports underscores).
Key name does not support underscores (_)
Azure Key Vault不允许密钥键名中出现下划线。请使用连字符（例如
DB-PASSWORD
），或选择其他密钥存储集成（AWS Secrets Manager支持下划线）。

Azure Key Vault: Secret Stuck in Soft-Delete State

Azure Key Vault：密钥处于软删除状态

Error: Secret <name> is already in a deleted state / conflict with soft-deleted resource
Azure Key Vault has a default 90-day soft-delete retention. The TrueFoundry API cannot purge soft-deleted secrets — only the Azure portal or CLI can.
Recovery options:
  1. Purge via Azure Portal: Go to Key Vault → Manage deleted secrets → Purge
  2. Purge via Azure CLI: 
    az keyvault secret purge --vault-name <vault> --name <secret-name>
  3. Use a different name: Create a new secret group with a different name (fastest workaround)
Note: If the platform's Key Vault has soft-delete protection but not purge protection, options 1/2 work. If purge protection is also enabled, you must wait out the retention period (up to 90 days).
Error: Secret <name> is already in a deleted state / conflict with soft-deleted resource
Azure Key Vault默认有90天的软删除保留期。TrueFoundry API无法清除软删除的密钥——仅能通过Azure门户或CLI操作。
恢复选项：
  1. 通过Azure门户清除： 进入Key Vault → 管理已删除的密钥 → 清除
  2. 通过Azure CLI清除： 
    az keyvault secret purge --vault-name <vault> --name <secret-name>
  3. 使用其他名称： 创建名称不同的新密钥组（最快的解决方案）
注意： 如果平台的Key Vault开启了软删除保护但未开启清除保护，选项1/2可用。如果同时开启了清除保护，你必须等待保留期结束（最长90天）。

Missing Required Fields

缺少必填字段

Unprocessable entity. Ensure all secrets have both "key" and "value" fields.
</troubleshooting>
Unprocessable entity. Ensure all secrets have both "key" and "value" fields.
</troubleshooting>