---
title: "準備您的 arx.yaml"
description: "在 arx.yaml 中宣告應用程式需要的平台資源：模型 API gateway、網路、儲存與桌面捷徑，以及這些資源的連線資訊如何送進您的 pod"
canonical_url: "https://developer.ardge.com/zh-tw/guide/isv/prepare-arx-yaml"
---
# 準備您的 arx.yaml

> 在 arx.yaml 中宣告應用程式需要的平台資源：模型 API gateway、網路、儲存與桌面捷徑，以及這些資源的連線資訊如何送進您的 pod

## 概觀

`arx.yaml` 是應用程式向平台申請所需資源的地方。平台會在安裝時配置這些資源，並將連線資訊注入您的 pod，因此模型存取、網路、儲存與桌面項目都是自動接好的，不需要在客戶場域手動設定。

本文說明您可以在其中宣告的區塊。讓 chart 承接另一端的做法，則是下一步的內容。

## 您將學到

- 您的工作負載如何取得模型 API 的 endpoint 與金鑰
- 如何宣告應用程式需要的網路與儲存資源
- 如何把應用程式放上 ARX 桌面

## 適用版本

- ARX OS 1.0 以上

## 開始之前

- 您的應用程式已封裝為容器 image，且該 image 能從 ARX 系統可連線的位址取得
- 您已確認應用程式提供哪些連接埠、需要哪些儲存空間，以及是否呼叫模型

開始前請先下載 skills。`arx.yaml` 是透過它們撰寫的，以下每一節也都會指出套件中對應的參考文件：`arx-marketplace-templates/references/arx-binding.md`。

<note>

**下載 skills**：套件為 [arx-isv-skills-v0.6.4.zip](https://developer.ardge.com/skills/arx-isv-skills-v0.6.4.zip)（約 185 KB）——解壓後將裡面的資料夾複製到您專案的 `.claude/skills/`。

</note>

<tip>

**交由 AI Agent 代為撰寫 arx.yaml**：當您確定應用程式需要哪些平台資源後，`arx-marketplace-templates` skill 會依它內附的 schema 產生這個檔案。下 prompt 時請描述資源而不是 YAML，例如：`use arx-marketplace-templates to write arx.yaml for my app: an HTTP service on port 5678, one 10Gi read-write volume, the AI gateway injected as OPENAI_API_BASE_URL and OPENAI_API_KEY, and a desktop shortcut that opens it in an iframe`。

</tip>

## arx.yaml 宣告什麼

`arx.yaml` 與 manifest 放在一起，是應用程式與平台之間的契約：您宣告需要的平台資源，平台負責配置並將連線資訊注入您的 pod。

```yaml
apiVersion: arx.ardge.com/v1
kind: ArxBinding
spec:                    # 至少一個區塊
  network: { ... }
  storage: [ ... ]
  desktop: { ... }
  ai: { ... }
```

多數區塊共用兩個慣例：

- `components` 以 pod 的 `app.kubernetes.io/component` 標籤指定注入對象。省略它則注入該 release 的所有 pod
- `inject` 將平台的欄位對應到應用程式讀取它的環境變數名稱，變數名稱必須是 `UPPER_SNAKE_CASE`

以下每一節都會指出要閱讀 `arx-binding.md` 中的哪個區塊。

## 模型 API 注入

`ai` 區塊將平台的 AI gateway 交給您的工作負載：一組 OpenAI 相容的 base URL 與金鑰，注入為您指定的環境變數。

```yaml
spec:
  ai:
    components: [worker]
    inject:                      # 兩者皆必填
      baseUrl: OPENAI_API_BASE_URL
      apiKey: OPENAI_API_KEY
```

完整欄位請見 `arx-binding.md` 的 `ai` 一節。這些值是什麼、應用程式如何使用，請見[透過 API 呼叫 ARX 上的地端模型](https://developer.ardge.com/zh-tw/guide/isv/api-model-calls)。

## 網路設定

`network` 區塊宣告應用程式需要的 Kubernetes Service。`network.services` 底下的每個 key 都會成為其他區塊引用的 `serviceRef`，因此這個區塊通常寫在最前面。

請見 `arx-binding.md` 的 `network` 一節。

## 儲存設定

`storage` 區塊把 chart 的持久化設定綁到平台管理的 PVC——每個儲存槽一項，各自載明槽位名稱、算出 PVC 名稱的樣板，以及讀寫或唯讀。

請見 `arx-binding.md` 的 `storage` 一節。

遠端儲存需先在裝置端掛載，該流程請見[在 Storage Manager 中為應用程式掛載遠端儲存](https://developer.ardge.com/zh-tw/guide/isv/mount-remote-storage)。

## 桌面捷徑

`desktop` 區塊把應用程式放上 ARX 桌面：最多四個捷徑，各自帶有名稱、以 iframe 或新分頁開啟，以及指向的 service 與路徑。

```yaml
spec:
  desktop:
    shortcuts:
      - label: my-app
        open: [iframe, newtab]
        serviceRef: http
        scheme: http
        path: /
```

請見 `arx-binding.md` 的 `desktop` 一節。

## 下一步

<card-group>
<card icon="i-lucide-box" title="準備您的 Helm chart" to="https://developer.ardge.com/zh-tw/guide/isv/prepare-helm-chart">

封裝這些綁定要接進去的 chart，並提供它們依賴的標籤與持久化設定

</card>
</card-group>


## Sitemap

See the full [sitemap](https://developer.ardge.com/sitemap.md) for all pages.