來源池增強功能

origin_pool 相關 schema 的豐富化中繼資料。有關擴充定義，請參閱 OpenAPI 擴充。

豐富化的 Schema

模式

所有符合 origin_pool.*SpecType 的 schema 均會接受豐富化處理：

origin_poolCreateSpecType
origin_poolReplaceSpecType
origin_poolGetSpecType

必填欄位

欄位	適用操作	備註
`metadata.name`	所有操作	1-63 個字元，小寫英數字元，模式：`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`metadata.namespace`	所有操作	命名空間識別碼
`spec.origin_servers`	建立	最少 1 個項目
`spec.port`	建立	1-65535，無伺服器預設值

最小可行設定

{
  "metadata": {
    "name": "my-origin-pool",
    "namespace": "default"
  },
  "spec": {
    "origin_servers": [
      {
        "public_name": {
          "dns_name": "backend.example.com"
        }
      }
    ],
    "port": 443
  }
}

伺服器套用的預設值

標記為 x-f5xc-server-default: true 的欄位，當請求中省略時，其 default 值由 F5 XC API 伺服器套用。

頂層欄位

欄位	預設值	類型	描述
`no_tls`	`{}`	object	停用至來源的 TLS
`healthcheck`	`[]`	array	未設定健康檢查
`loadbalancer_algorithm`	`ROUND_ROBIN`	enum	輪詢負載平衡
`endpoint_selection`	`DISTRIBUTED`	enum	使用所有端點（本地 + 遠端）

advanced_options 預設值

當未指定 advanced_options 時，伺服器的行為如同設定了以下值：

欄位	預設值	類型	描述
`connection_timeout`	`2000`	integer	連線逾時（毫秒）
`http_idle_timeout`	`300000`	integer	HTTP 閒置逾時（毫秒，5 分鐘）
`same_as_endpoint_port`	`{}`	object	健康檢查使用端點連接埠
`default_circuit_breaker`	`{}`	object	預設斷路器設定
`disable_outlier_detection`	`{}`	object	停用異常值偵測
`no_panic_threshold`	`{}`	object	無恐慌閾值
`disable_subsets`	`{}`	object	停用子集負載平衡
`auto_http_config`	`{}`	object	自動 HTTP 協定協商
`disable_proxy_protocol`	`{}`	object	停用代理協定
`disable_lb_source_ip_persistance`	`{}`	object	停用 LB 來源 IP 持久性

巢狀物件預設值

路徑	預設值	描述
`origin_servers[].labels`	`{}`	空的標籤物件
`origin_servers[].public_name.refresh_interval`	`0`	使用系統預設 DNS 重新整理

UI 與伺服器預設值的差異

F5 XC 網頁 UI 的預選值與省略欄位時 API 套用的值不同。

欄位	UI 預選值	伺服器套用值	備註
`loadbalancer_algorithm`	`LB_OVERRIDE`	`ROUND_ROBIN`	省略該欄位時，透過 UI 建立的資源與透過 API 建立的資源結果不同

列舉值

loadbalancer_algorithm

值	描述	備註
`ROUND_ROBIN`	每個健康端點依輪詢順序選取	伺服器預設值
`LEAST_REQUEST`	選取活躍請求數最少的端點
`RING_HASH`	使用端點名稱的環形雜湊進行一致性雜湊
`RANDOM`	隨機選取健康端點
`LB_OVERRIDE`	雜湊策略繼承自上層負載平衡器	UI 預設值

endpoint_selection

值	描述	備註
`DISTRIBUTED`	同時考慮遠端和本地端點	伺服器預設值
`LOCAL_ONLY`	僅使用本地端點
`LOCAL_PREFERRED`	優先使用本地，若無法使用則回退至遠端

OneOf 欄位群組

互斥欄位群組。每個群組中只能指定一個欄位：

群組	欄位	伺服器預設值
連接埠設定	`port`, `automatic_port`, `lb_port`	`port`（明確指定）
至來源的 TLS	`no_tls`, `use_tls`	`no_tls`
健康檢查連接埠	`same_as_endpoint_port`, `health_check_port`	`same_as_endpoint_port`
斷路器	`default_circuit_breaker`, `disable_circuit_breaker`, `circuit_breaker`	`default_circuit_breaker`
異常值偵測	`disable_outlier_detection`, `outlier_detection`	`disable_outlier_detection`
恐慌閾值	`no_panic_threshold`, `panic_threshold`	`no_panic_threshold`
子集負載平衡	`disable_subsets`, `enable_subsets`	`disable_subsets`
HTTP 協定	`auto_http_config`, `http1_config`, `http2_options`	`auto_http_config`
代理協定	`disable_proxy_protocol`, `proxy_protocol_v1`, `proxy_protocol_v2`	`disable_proxy_protocol`
LB 來源 IP	`disable_lb_source_ip_persistance`, `enable_lb_source_ip_persistance`	`disable_lb_source_ip_persistance`
連線池	`enable_conn_pool_reuse`, `disable_conn_pool_reuse`	`enable_conn_pool_reuse`

欄位限制

欄位	類型	限制
`spec.port`	integer	1-65535
`spec.advanced_options.connection_timeout`	integer	0-1,800,000 毫秒
`spec.advanced_options.http_idle_timeout`	integer	0-600,000 毫秒
`spec.advanced_options.panic_threshold`	integer	0-100（百分比）
`metadata.name`	string	1-63 個字元，模式：`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`

UI 設定選項

F5 XC 網頁主控台為來源池提供 15 個設定選項：

#	UI 標籤	API 欄位路徑	類型	伺服器預設值
1	來源伺服器連接埠	`spec.[port\|automatic_port\|lb_port]`	OneOf	`port`（明確指定）
2	連線池重用	`spec.[enable_conn_pool_reuse\|disable_conn_pool_reuse]`	OneOf	`enable_conn_pool_reuse`
3	健康檢查連接埠	`spec.advanced_options.[same_as_endpoint_port\|health_check_port]`	OneOf	`same_as_endpoint_port`
4	負載平衡器演算法	`spec.loadbalancer_algorithm`	enum	`ROUND_ROBIN`
5	端點選取	`spec.endpoint_selection`	enum	`DISTRIBUTED`
6	至來源的 TLS	`spec.[no_tls\|use_tls]`	OneOf	`no_tls`
7	連線逾時	`spec.advanced_options.connection_timeout`	integer	2000 毫秒
8	HTTP 閒置逾時	`spec.advanced_options.http_idle_timeout`	integer	300000 毫秒
9	斷路器	`spec.advanced_options.[default_circuit_breaker\|disable_circuit_breaker\|circuit_breaker]`	OneOf	`default_circuit_breaker`
10	異常值偵測	`spec.advanced_options.[disable_outlier_detection\|outlier_detection]`	OneOf	`disable_outlier_detection`
11	恐慌閾值	`spec.advanced_options.[no_panic_threshold\|panic_threshold]`	OneOf	`no_panic_threshold`
12	子集負載平衡	`spec.advanced_options.[disable_subsets\|enable_subsets]`	OneOf	`disable_subsets`
13	HTTP 協定	`spec.advanced_options.[auto_http_config\|http1_config\|http2_options]`	OneOf	`auto_http_config`
14	代理協定	`spec.advanced_options.[disable_proxy_protocol\|proxy_protocol_v1\|proxy_protocol_v2]`	OneOf	`disable_proxy_protocol`
15	LB 來源 IP 持久性	`spec.advanced_options.[disable_lb_source_ip_persistance\|enable_lb_source_ip_persistance]`	OneOf	`disable_lb_source_ip_persistance`

資料存取

OpenAPI 規格

檔案	內容
`docs/specifications/api/virtual.json`	`origin_poolCreateSpecType`, `origin_poolReplaceSpecType`, `origin_poolGetSpecType`
`docs/specifications/api/openapi.json`	包含所有 schema 的合併規格

validation.json 結構

defaults.resources.origin_pool
├── server_applied      # 帶有 x-f5xc-server-default: true 的欄位
├── recommended         # 帶有 x-f5xc-recommended-value 的欄位
├── advanced_options    # 巢狀 advanced_options 預設值
├── oneof_choices       # OneOf 預設選項
└── ui_vs_server        # UI 與伺服器的差異

來源伺服器類型

來源伺服器可使用不同的類型變體指定。類型決定了需要哪些額外欄位。

已實作的類型

類型	描述	必填欄位	狀態
`public_name`	具有公用 DNS 名稱的來源伺服器	`dns_name`	✅ 完整
`public_ip`	具有公用 IP 位址的來源伺服器	`ip`（IPv4）	✅ 完整

範例：public_name

{
  "origin_servers": [
    {
      "public_name": {
        "dns_name": "backend.example.com"
      }
    }
  ]
}

範例：public_ip

{
  "origin_servers": [
    {
      "public_ip": {
        "ip": "8.8.8.8"
      }
    }
  ]
}

待辦事項：依賴站點的來源伺服器類型

以下來源伺服器類型在實作前需要完成「站點」資源邏輯的開發：

類型	描述	必填欄位	狀態
`private_ip`	具有私有/公用 IP 及站點資訊的來源伺服器	`ip`, `site_locator`, `network_choice`, `snat_pool`	🔲 待站點邏輯
`private_name`	具有 DNS 名稱及站點資訊的來源伺服器	`dns_name`, `site_locator`, `network_choice`, `snat_pool`	🔲 待站點邏輯
`k8s_service`	具有站點資訊的 Kubernetes 服務	`service_name`, `site_locator`, `network_choice`	🔲 待站點邏輯
`consul_service`	具有站點資訊的 HashiCorp Consul 服務	`service_name`, `site_locator`, `network_choice`	🔲 待站點邏輯

實作需求

在完整記錄這些類型之前，需完成以下工作：

站點資源探索 - 記錄 site 資源 schema 及 site_locator 模式
網路選擇列舉 - 記錄 network_choice 的受限值（site_local_inside、site_local_outside 等）
SNAT 池選項 - 記錄 SNAT 池設定模式
跨資源參考 - 定義 origin_pool 如何參考站點資源

追蹤

設定佔位符：config/discovered_defaults.yaml → origin_pool.origin_server_types.enums
相關衝刺：站點資源 schema 豐富化

變更日誌

版本	日期	變更內容
2.1.2	2026-01-18	新增來源伺服器類型章節，包含 public_name/public_ip；為依賴站點的類型新增待辦標記
2.1.1	2026-01-18	改寫為純 API 參考；移除下游程式碼範例
2.1.0	2026-01-18	更新為 validation.json 中的統一預設值結構
2.0.33	2026-01-17	初始來源池增強功能文件