---
title: "準備您的 Helm chart"
description: "將應用程式封裝為 ARX 能安裝的 chart：ARX 從哪裡讀取它、平台綁定所依賴的標籤與持久化設定，以及如何對照 arx.yaml 檢查 chart"
canonical_url: "https://developer.ardge.com/zh-tw/guide/isv/prepare-helm-chart"
---
# 準備您的 Helm chart
> 將應用程式封裝為 ARX 能安裝的 chart：ARX 從哪裡讀取它、平台綁定所依賴的標籤與持久化設定，以及如何對照 arx.yaml 檢查 chart
## 概觀
chart 才是真正運行在系統上的東西。ARX 於安裝時渲染它、套用 template 附帶的 values 檔，接著由 operator 把 `arx.yaml` 宣告的平台資源接進它所建立的 pod。
本文說明 chart 必須提供哪些東西，這些綁定才接得上，以及發布前如何檢查。
## 您將學到
- ARX 從哪裡讀取您的 chart，以及會套用哪個 values 檔
- 為 pod 加上標籤，讓平台能夠指定它們
- 提供儲存綁定會寫入的持久化設定
- 對照 `arx.yaml` 檢查 chart
## 適用版本
- ARX OS 1.0 以上
## 開始之前
- 您的應用程式已封裝為容器 image，且該 image 能從 ARX 系統可連線的位址取得
- 您能將 chart 發布到 ARX 系統可連線的 OCI registry 或 http/https chart repository
- 您已確定應用程式需要哪些平台資源，請見[準備您的 arx.yaml](https://developer.ardge.com/zh-tw/guide/isv/prepare-arx-yaml)
**下載 skills**：套件為 [arx-isv-skills-v0.6.4.zip](https://developer.ardge.com/skills/arx-isv-skills-v0.6.4.zip)（約 185 KB）——解壓後將裡面的資料夾複製到您專案的 `.claude/skills/`。
## ARX 從哪裡讀取您的 chart
app template 的 `deployment` 區塊指明 repository、chart 與要套用在其上的 values 檔。系統認得兩種 repository type：OCI registry 用 `oci`，http/https chart repository 用 `default`：
```yaml
deployment:
type: helm
helmRepository:
type: oci
name: your-registry
url: oci://registry.example.com/charts
helmChart:
chart: your-app
version: "2.0.1"
valuesFiles:
- manifests/values.yaml
```
`valuesFiles` 列出相對於 template 目錄的路徑，慣例是 `manifests/values.yaml`。請在該檔中對照 chart 自身的 `values.yaml`，只覆寫這次部署需要調整的項目，如此 chart 維持通用，ARX 專屬的設定則與 template 放在一起。
**兩個版本，兩件事**：`metadata.version` 是 marketplace 顯示、也是判斷升級所依據的應用程式版本；`helmChart.version` 則是部署它的 chart 版本。系統不會互相檢查這兩者。
## 為 pod 加上標籤
平台以 pod 的 `app.kubernetes.io/component` 標籤指定對象。`arx.yaml` 各區塊的 `components` 篩選的是這個標籤，network service 的 `selectorLabelValue` 比對的也是它。
請為 chart 中的每個工作負載都設定這個標籤。若您的 chart 使用其他標籤 key，請在 network service 中宣告 `selectorLabel`，讓平台改用您的標籤——宣告後 `selectorLabelValue` 即為必填。
## 提供您宣告的連接埠
`network` 區塊中的每個 service 都會指明它服務的連接埠。您的 pod 必須恰好監聽這些連接埠，並帶有 service 選取的標籤。
固定的 `nodePort` 是叢集層級配置的，因此若同一個 repository 中已有其他應用程式指定了相同的值，後安裝的那個必定失敗。除非確實需要固定值，否則請省略 `nodePort`，交由系統動態配置。
## 提供持久化設定
`arx.yaml` 的一個儲存槽會以兩種不同方式接進 chart，兩者都寫對，PVC 才會綁上：
- **nameTemplate 必須算出 chart 實際建立的 PVC 名稱。** operator 之後就是靠它找到該 PVC。它是純 Go `text/template`，不是 Helm 的方言——沒有 Sprig，因此 chart 的 `fullname` helper 無法照抄。請推算它在這個 release 下會算出什麼名稱，並在 `manifests/values.yaml` 中釘住 chart 的名稱覆寫，讓結果是一個您說得出來的名字
- **storageClass、accessMode，以及選用的 subPath 與 label，是指向 chart values.yaml 的點分路徑**，而不是值本身。chart 必須提供這些設定，路徑也必須能解析。若 chart 期待的是清單而非純量，請設定 `accessModeFormat: list`
## 對照 arx.yaml 檢查 chart
template 驗證器提供 chart 檢查：它會拉取每個應用程式的 chart，確認其 `arx.yaml` 宣告的 values 路徑能在 chart 的 `values.yaml` 中解析，並確認宣告 `accessModeFormat: string` 的槽位指向的是純量。
凡是宣告了 `storage` 的應用程式都請執行這項檢查——路徑解析不到時，operator 會在安裝時靜默地沒有接上 PVC，過程中不會有任何明顯的失敗。這項檢查不涵蓋 `nameTemplate`，因為它算出的是物件名稱而非 values 路徑，那部分仍需由您自行確認。
## 下一步
將 template 匯入 ARX 系統、安裝應用程式，並在實機上測試
## Sitemap
See the full [sitemap](https://developer.ardge.com/sitemap.md) for all pages.