RFC-0242：設定功能

RFC-0242：設定功能
狀態	已接受
領域	元件架構
說明	將設定功能新增至元件架構
毛皮變化	986276
作者	dgilhooley@google.com
審查人員	aaronwood@google.com geb@google.com markdittmer@google.com surajmalhotra@google.com wittrock@google.com
提交日期 (年-月-日)	2024-02-05
審查日期 (年-月-日)	2024-04-11

摘要

概述負載平衡器中的設定功能用途 這種語法，以及會在 CML 檔案中加入的語法， 具體做法是指示 Kubernetes 建立並維護 一或多個代表這些 Pod 的物件

另請注意，本文件將取代前述項目中之部分 設定 RFC，如前文章節所述。

提振精神

Fuchsia 中的元件使用「結構化設定」取得 設定值今日的設定值大多會從 個別元件父項元件可以 設定值，但多數元件 Fuchsia 為靜態的。

新增這個功能有多種動機：

• 允許靜態父項進行子項設定。
• 將單一設定值轉送至多個元件。
• 從 CML 檔案提供設定值。

第一個設定功能的客戶是系統組裝， 可讓您免除技術債。技術債 ，因為目前無法將設定提供給 。系統組件目前 開啟 Fuchsia 套件，編輯其設定值檔案， 重新包裝這是指技術債，因為這會變更 套件，設定值檔案就理論上為「私人」API 的 安裝不易更新的元件

針對無法重建的樹狀結構中，設定功能 可讓您設定這些元件目前沒有方法 在靜態拓撲中編輯這些元件的設定。

這項功能在日後許多設定用途中可能會很實用。

相關人員

講師：neelsa@google.com

審查者：

• 系統組件：aaronwood@google.com
• 元件架構：geb@google.com
• 安全性：Markdittmer@google.com
• 驅動程式架構：surajmalhotra@google.com
• 元件架構：wittrock@google.com

社交：這個問題已經與元件架構團隊討論。 再寫入 RFC。

需求條件

設定功能可讓 CML 作者將設定值 靜態元件這些物件允許將設定值轉送到 來建立多個元件可以使用同一個值轉送值 透過拓撲讓間接祖係指定值，其中 現有的功能只允許直接父項指定值。

設定功能應遵循現有的元件架構功能 與系統的其餘部分一致

設計

大部分的設計是使用 CML 語法來宣告及轉送設定 技術。設定能力在 CML設定能力會轉送至要使用的元件 基礎架構使用設定能力的元件將能查看 值，當元件使用現有的結構體啟動時的值 設定程式庫

以下是定義設定能力的範例：

// Configuration capabilities can be defined in any component.
// When a configuration capability is defined, a value must be set for it.
capabilities: [
  {
    // Define the name of the capability.
    config: "fuchsia.netstack.UseNetstack3",
    // Define the type of the configuration.
    type: "bool",
    // When defining a configuration capability, there *must* be a value.
    // If the route for the configuration capability ends at this definition, the
    // value of the capability will always be this value.
    value: "true"
  },
  // The below shows a string config.
  {
      config: "fuchsia.config.MyString",
      type: "string",
      max_size: 100,
      value: "test",
  },
  // The below shows a vector config.
  {
      config: "fuchsia.config.MyUint8Vector",
      type: "vector",
      element: { type: "uint8" },
      max_count: 100,
      value: [1, 2, 3 ],
  },
]

config 能力中的 type、element、max_count、max_size 欄位 與它們在 config 節中的用途相同。包含以下所有值 capabilities 區塊支援 config 節支援。

type 欄位支援下列功能：

• 布林值
• uint8、uint16、uint32、uint64
• int8、int16、int32、int64
• string
• 向量

使用區塊支援相同的 type、element、max_count 和 max_size 做為功能區塊

以下是使用設定能力的語法範例：

// Using a configuration capability means that this configuration will show
// up in the component's structured config at runtime with the specified `key`
// name.
// NOTE: Using a configuration capability will override the value in the Config
// Value File (CVF) and the value obtained from the "mutability" setting.
use: [
  {
    config: "fuchsia.netstack.LaunchProcess",
    // This is the name that the component will see in its Structured Config
    // struct. If the `use` is optional this must match a name in the "config"
    // block of the component's manifest.
    key: "can_launch_process",
    // The using field needs the type information so that the component's
    // Config Value File format can be created.
    type: "bool",
    // From is identical to other capabilities.
    from: "parent",
  },
  // The below shows a vector config.
  {
    config: "fuchsia.netstack.MyUint8Vector",
    key: "my_vector",
    type: "vector",
    element: { type: "uint8" },
    max_count: 100,
    from: "parent",
  },
  // The below shows a string config.
  {
    config: "fuchsia.netstack.MyString",
    key: "my_string",
    type: "string",
    max_size: 256,
    from: "parent",
  },
]

以下是轉送設定能力的語法範例：

// Expose and Offer behave the same as any other capability.
expose: [
  {
    config: "fuchsia.netstack.UseNetstack3",
    as: "fuchsia.mycomponent.UseVersion3",
    from: "self",
  },
]
offer: [
  {
    config: "fuchsia.config.MyString",
    as: "fuchsia.mycomponent.ProcessName",
    from: "self",
    to: "#mychild",
   },
]

選用功能

如果元件目前使用的設定能力，且可用性設為 optional、這項能力是從 void 轉送，然後是元件 ) 會收到設定值檔案 (CVF) 的值。這項功能 支援軟體遷移以更新設定。

淘汰「config」封鎖

在設定功能之前，系統會在 CML 上有 config 個節拍。這項資訊現已由 use的資訊。這表示「結構化設定」 為元件產生的結構定義會是欄位的聯集 use 區塊和 config 段落中宣告的。

所有結構化設定用戶端都遷移至設定後 CML 中的設定區塊支援功能，將停止支援這項功能。

淘汰「mutability: parent」精選內容

在設定功能之前，您可以將設定值宣告為 mutability: parent，可讓元件的父項 並變更該值

這項功能的使用者會遷移至「use」設定能力 。一旦所有使用者遷移完畢，這項功能就會 已移除

實作

這些 CML 功能的實作相對簡單且容易 先在幾個 CL 裡完成用戶端可以透過設定 功能，因為這不會影響現有的 設定功能

我們必須確保審查人員瞭解設定功能 可以驗證特定產品是否有指定的設定

成效

元件架構導致元件啟動速度可能會稍微變慢 需要對元件使用的設定功能執行轉送。 如果功能來自於元件所在的元件 請先下載這個檔案。解決後應該無助於解決 元件。

人體工學

這項新 CML 能力的人體工學與現有資源相同 即便沒有技術背景，也能因這些工具的功能而受益新增及轉送設定能力是較為詳細的做法 該語法選擇與現有能力語法相符 我們會盡可能選擇與現有語法 config 區塊語法。如果兩種語法發生衝突時，現有的 建議使用的能力語法比對現有語法會降低認知能力 因為他們熟悉元件架構

CF 團隊可能會決定將 config 模塊保留為 宣告設定能力，或視需要新增其他語法糖 需要更精準的人體工學

回溯相容性

這是新功能。可與現有結構化架構回溯相容 設定功能

值得注意的是，如果將設定能力轉送至元件 的優先順序一律高於 CVF 檔案中的值。如果元件有 沒有可選設定能力路徑且路徑不存在，那麼 值。

安全性考量

這項功能不會影響安全性。使用嚴密的檢查工具 來調查 CML 這個新的能力類型

可能還以為這種方式設定功能更加顯眼 是元件套件中 編輯值的現有策略

如果元件使用了必要的設定能力，而另一個元件 就無法啟動該元件。這不應是 而這些路徑 可以透過靜態驗證方式確定正確無誤

隱私權注意事項

此提案不應對隱私權產生任何影響。

測試

這項功能需要單元和整合測試。一般測試區 是：

• 剖析新的 CML 語法。
• 透過拓撲轉送新能力。
• 嘗試啟動缺少設定功能的元件。
• 嘗試啟動含有錯誤設定能力的元件 類型。
• 透過設定能力啟動動態元件。

此功能需要將下列測試新增至 Scrutiny：

• 測試 Scrutiny 可以解析設定功能值。
• 測試不同設定值來源的優先順序/覆寫邏輯。
• 測試設定功能、設定區塊與 可變動性

這些測試都不需要使用新的測試基礎架構。

說明文件

您必須更新 Fuchsia.dev，才能提供設定相關說明文件 即便沒有技術背景，也能因這些工具的功能而受益現有的能力說明文件將做為範本 新的說明文件

缺點、替代方案和未知

替代方法：實作設定覆寫服務

原創 結構化設定 RFC 我們提議的結構化設定，直接來自元件套件。 RFC 明確指出 "其他元件所設定的設定資料 (父項元件除外) 和管理元件)替代方法是繼續使用 以能力為基礎的設定配置

其中一個缺點是設定功能，而非覆寫 服務就是設定功能比較詳細而複雜。 想要在全球各地導入實作項目，一開始會比較簡單。 然而 Fuchsia 發現，以量為基礎的系統最終 長期下來可以輕鬆理解內容如果能夠 假設只有一部分的元件會使用特定設定 也能在兩個不同元件中使用兩個不同的值 設定功能可讓您更輕鬆表達及理解 也就是 Fuchsia 其他地方使用的 軟體式系統使用現有的 CML 就能更容易理解 他們認為元件架構 工具。

缺點：許多其他用途欄位

在 use 區塊中保留類型資訊，會額外新增 6 個欄位 這些憑證只適用於設定功能

這 6 個欄位可以結合到 1 個欄位與子欄位 但是新增這些欄位是不錯的做法，因為能讓語法靠近 現有的 config 區塊語法。

缺點：比對類型資訊與轉送

將設定結構定義加入 use 宣告的缺點之一是 use 區塊會定義類型資訊，並定義轉送。 有些元件可能會希望沒有指定 轉送，然後在不同的情境中以不同方式轉送設定。 如果類型資訊與 Use 封鎖。

如果元件作者想要變更其類型的定義方式，就必須修改 其 use 區塊，而不是僅修改其 config 區塊。

如果設定定義和轉送的組合成為永久性 開發人員遇到困難，元件架構團隊可以再審視 決策。

替代做法：保留 config 區塊中的設定類型定義

替代方法是不設定「類型」use宣告中的欄位，以及 而是依賴現有「config」欄中的類型資訊封鎖。這是 之前的 RFC 版本這個替代方法可用來解決 當前混淆類型資訊與路線的缺點更輕鬆簡單 可讓用戶端集中定義設定，並將其轉送到另一個位置 (可能包括不同的 CML 資料分割，根據 不同設定)。

目前採用的結構化設定，其中元件 管理員「推送」元件設定，也就是元件 管理員必須確保轉送能力的類型 「目標結構化設定」欄位中的值。我們認為 會放在 use 宣告中，因為這與 功能宣告。元件管理員執行轉送作業時 請確定類型資訊會向上對齊 資訊應包含在路線的兩端 (「功能」和「用途」)。

另一個保留 use 宣告類型資訊的原因是 可以保留 use 宣告中的所有資訊 不需要相符的「config」封鎖項目這樣一來，資訊就會 單一位置，所以更易於稽核。

替代方法：use 宣告中的 as 欄位

具備封裝的「結構化設定」欄位名稱和類型資訊 在 config 區塊內，as 則可用來指定 現有運算能力這與大多數非 path 使用者 「重新命名」都是以 CML 為主

系統已改用 key 字詞，因為該欄位的運作方式與 其他 as 欄位的值。as 通常為選用項目，但 key 為必要項目。key必須 如果能力為選用，則與 config 區塊中現有的鍵相符。

不明：利用功能找出現有的結構化資料設定不一致問題

現有的「結構化設定」在 不符合其他功能的運作方式

有一個不一致，就是該程式會嚴重依賴 元件資訊清單中定義的結構化設定。就在目前 是取決於程式的資訊清單，而「結構化設定」會 這個關係環環相扣。由此可見， 設定建構規則必須在元件之間新增額外層。 元件資訊清單和程式循環次數不一致的情況 就會解決這些問題，但應該可以解決 的補充程序。

另一個不一致的情況是，結構化設定已「推送」加入 元件，其中其他功能會「提取」作為 每個元件都能存取關於這種不一致的問題 RFC。此 RFC 的目的是在 元件資訊清單。這個 RFC 不會改變程式之間的介面 和結構化設定，以將需要的遷移作業次數 受到限制。

在這之後， Fuchsia 會更妥善地解決這些不一致的問題 以及瞭解其使用情形。更多內容 客戶資料可協助我們解決棘手問題，並進行後續變更。

既有藝術品和參考資料

之前的結構化設定 rfcs：

• rfc-0127
• rfc-0146
• rfc-0215