API網(wǎng)關(guān)云原生微服務(wù)【免費下載鏈接】kgatewayThe Cloud-Native API Gateway and AI Gateway項目地址https://gitcode.com/gh_mirrors/kg/kgateway點擊查看免費下載kgatewayThe Cloud-Native API Gateway and AI Gateway的策略 CR 基于 Kubernetes Gateway API 的gwv1.PolicyStatus上報狀態(tài)。但由于策略的掛載attachment機制涉及按優(yōu)先級應(yīng)用、合并以及被更高優(yōu)先級策略覆蓋等復(fù)雜語義僅僅一個籠統(tǒng)的狀態(tài)無法區(qū)分策略已被接受和策略已實際生效。本文圍繞設(shè)計文檔 design/11741-policy-status-and-merge-reporting.md系統(tǒng)講解 kgateway 如何通過Accepted與Attached兩個自定義 Condition 分離上報策略的接受與掛載狀態(tài)并在下發(fā)的 Envoy 配置中以MergeOrigins元數(shù)據(jù)記錄每個合并字段的來源策略為策略合并結(jié)果提供可觀測性。讀完本文你將掌握 kgateway 策略狀態(tài)字段的完整語義、三種掛載狀態(tài)的判定規(guī)則與優(yōu)先級順序以及如何從 Kubernetes status 與 Envoy 配置中診斷已接受但未生效的策略問題。背景為什么需要區(qū)分接受與掛載kgateway 的各類策略 CR如 TrafficPolicy、ListenerPolicy、BackendConfigPolicy、DirectResponse 等都使用gwv1.PolicyStatusAPI 作為狀態(tài)載體。在 api/v1alpha1/shared/shared_types.go 中可以看到PolicyStatus由Conditions條件列表最多 8 條與Ancestors祖先狀態(tài)條目最多 16 個組成type PolicyStatus struct { // optional // listTypemap // listMapKeytype // kubebuilder:validation:MaxItems8 Conditions []metav1.Condition json:conditions,omitempty // kubebuilder:validation:MaxItems16 // required Ancestors []PolicyAncestorStatus json:ancestors }PolicyAncestorStatus通過AncestorRef對應(yīng) spec 中的 ParentRef、ControllerName寫狀態(tài)的控制器的域名/路徑標識與Conditions描述策略相對于某個祖先的狀態(tài)。設(shè)計文檔指出舊版狀態(tài) API 存在一個根本性局限它無法區(qū)分策略被接受與策略被掛載。策略掛載是一個復(fù)雜過程多個策略可能以優(yōu)先級順序依次應(yīng)用到同一目標資源支持合并的策略如 TrafficPolicy會與其他策略做合并最終掛載到目標資源上的可能是多個策略合并后的結(jié)果優(yōu)先級較低策略中的部分或全部字段在最終掛載結(jié)果中可能被更高優(yōu)先級策略覆蓋。這會導(dǎo)致一個令人困惑的場景策略被接受Accepted了但由于與其他策略沖突而沒有被實際掛載。只有Accepted而沒有Attached維度的狀態(tài)會讓用戶看到策略一切正常實際上配置卻完全沒有生效。設(shè)計目標與非目標目標使用自定義 Condition 分別上報策略的接受狀態(tài)acceptance與掛載狀態(tài)attachment。使用AttachedCondition 匯總掛載信息。在下發(fā)的 Envoy 配置上增加MergeOrigins元數(shù)據(jù)作為診斷用途。非目標不在狀態(tài) API 中暴露細粒度或高基數(shù)high cardinality的數(shù)據(jù)。不針對策略 CR 上無法解析的targetRefs上報狀態(tài)。核心實現(xiàn)策略狀態(tài)條件類型與原因在 api/v1alpha1/shared/policy_types.go 中定義了完整的條件類型與原因常量這是整個狀態(tài)報告體系的類型基礎(chǔ)const ( // PolicyConditionAccepted 表示策略是否被系統(tǒng)接受或被拒絕以及原因。 // 該條件為 True 的可能原因* Valid // 該條件為 False 的可能原因* Pending、* Invalid、* TargetNotFound PolicyConditionAccepted PolicyConditionType Accepted // PolicyConditionAttached 表示策略是否已掛載到目標資源。 // 該條件為 True 的可能原因* Attached、* Merged // 該條件為 False 的可能原因* Pending、* Overridden、* TargetNotFound PolicyConditionAttached PolicyConditionType Attached PolicyReasonValid PolicyConditionReason Valid PolicyReasonInvalid PolicyConditionReason Invalid PolicyReasonAttached PolicyConditionReason Attached PolicyReasonMerged PolicyConditionReason Merged PolicyReasonOverridden PolicyConditionReason Overridden PolicyReasonPending PolicyConditionReason Pending PolicyReasonPartiallyValid PolicyConditionReason PartiallyValid PolicyReasonTargetNotFound PolicyConditionReason TargetNotFound )兩類條件的分工如下Accepted策略是否被系統(tǒng)接受。True表示有效ValidFalse表示無效Invalid、待處理Pending或目標不存在TargetNotFound。Attached策略是否真正掛載到目標資源。True的可能原因是Attached完全掛載或Merged合并后掛載False的原因則是Pending、Overridden被更高優(yōu)先級策略完全覆蓋或TargetNotFound。注意TargetNotFound的語義當(dāng)策略的targetRefs指向不存在的資源時由于缺失的目標沒有 Gateway 祖先可供上報條件會被上報到策略的合成StatusSummary祖先條目上見下文狀態(tài)寫入路徑。掛載狀態(tài)的判定Attached / Merged / Overridden設(shè)計文檔給出了Attached條件的三態(tài)語義status: True, reason: Attached策略掛載到了全部目標且未與其他策略合并status: True, reason: Merged策略掛載到了全部目標但在一個或多個目標上與其他策略發(fā)生了合并status: False, reason: Overridden策略在一個或多個目標上被更高優(yōu)先級策略覆蓋。由于一個策略可以掛載多個目標且每個目標上的掛載狀態(tài)可能不同同一個策略可能同時處于多種狀態(tài)。Attached條件在聚合時遵循嚴重程度優(yōu)先級OverriddenMergedAttached即策略同時存在多個關(guān)聯(lián)狀態(tài)時以最嚴重者為準。源碼實現(xiàn)PolicyAttachmentState 位掩碼在 pkg/pluginsdk/reporter/types.go 中掛載狀態(tài)被建模為一個可按位組合的枚舉type PolicyAttachmentState int const ( // PolicyAttachmentStatePending 表示策略掛載處于待處理狀態(tài) PolicyAttachmentStatePending PolicyAttachmentState iota // PolicyAttachmentStateAttached 表示整個策略被成功掛載 PolicyAttachmentStateAttached PolicyAttachmentState 1 iota // PolicyAttachmentStateMerged 表示策略與其他策略合并后被掛載 PolicyAttachmentStateMerged // PolicyAttachmentStateOverridden 表示策略與更高優(yōu)先級策略沖突并被完全覆蓋 PolicyAttachmentStateOverridden ) // Has 檢查現(xiàn)有狀態(tài)是否包含給定狀態(tài) func (a PolicyAttachmentState) Has(b PolicyAttachmentState) bool { return ab ! 0 }同一文件還定義了各狀態(tài)對應(yīng)的用戶可見消息常量這些消息會直接出現(xiàn)在 status 條件中PolicyAcceptedMsg Policy accepted PolicyAttachedMsg Attached to all targets PolicyMergedMsg Merged with other policies in target(s) and attached PolicyOverriddenMsg Overridden due to conflict with higher priority policy in target(s) PolicyTargetNotFoundMsg Policy is not attached to targets that could not be resolved在 pkg/reports/policy.go 的addAttachmentCondition函數(shù)中實現(xiàn)了最嚴重狀態(tài)優(yōu)先的聚合邏輯依次檢查Overridden、Merged、Attached命中即設(shè)置對應(yīng)條件從而保證多個目標上不同狀態(tài)的并集被收斂為一個最嚴重的Attached條件switch { case attachmentState.Has(reporter.PolicyAttachmentStateOverridden): // status: False, reason: Overridden meta.SetStatusCondition(existing, metav1.Condition{ Type: string(shared.PolicyConditionAttached), Status: metav1.ConditionFalse, Reason: string(shared.PolicyReasonOverridden), Message: reporter.PolicyOverriddenMsg, }) case attachmentState.Has(reporter.PolicyAttachmentStateMerged): // status: True, reason: Merged ... case attachmentState.Has(reporter.PolicyAttachmentStateAttached): // status: True, reason: Attached ... }狀態(tài)寫入路徑從翻譯到上報接受狀態(tài)與掛載狀態(tài)的報告在 pkg/kgateway/translator/irtranslator/policy.go 中兩個核心函數(shù)分別負責(zé)兩類狀態(tài)reportPolicyAcceptanceStatus對每個關(guān)聯(lián) CR 的策略若存在Errors則上報AcceptedFalse, reasonInvalid消息為策略的錯誤格式化文本否則上報AcceptedTrue, reasonValid消息為Policy accepted。reportPolicyAttachmentStatus對無錯誤的策略根據(jù)mergeOrigins判斷掛載狀態(tài)若mergeOrigins.IsSet()為 false說明沒有發(fā)生合并是直接掛載上報PolicyAttachmentStateAttached否則根據(jù)策略引用在MergeOrigins中的出現(xiàn)次數(shù)映射到OverriddenNone、MergedPartial、AttachedAll。在 pkg/kgateway/translator/irtranslator/gateway.go 的監(jiān)聽器插件執(zhí)行路徑中可以看到兩者的串聯(lián)調(diào)用reportPolicyAcceptanceStatus(reporter, l.PolicyAncestorRef, pols...) policies, mergeOrigins : mergePolicies(pass, pols) // ...應(yīng)用插件... out.Metadata addMergeOriginsToFilterMetadata(gk, mergeOrigins, out.GetMetadata()) reportPolicyAttachmentStatus(reporter, l.PolicyAncestorRef, mergeOrigins, pols...)即在一次合并處理中先上報接受狀態(tài) → 執(zhí)行策略合并得到mergeOrigins→ 應(yīng)用插件產(chǎn)出 Envoy 配置 → 把MergeOrigins寫入過濾器元數(shù)據(jù) → 再上報掛載狀態(tài)。狀態(tài)匯總BuildPolicyStatuspkg/reports/policy.go 的BuildPolicyStatus負責(zé)把翻譯過程中累積的 typed report 轉(zhuǎn)為最終的gwv1.PolicyStatus為每個祖先條目合并Accepted默認值缺失時置為False/Pending、調(diào)用addAttachmentCondition追加Attached條件、保留舊條件以維持lastTransitionTime連續(xù)性并保留不由本報告器擁有的外來條件。未解析 targetRefs 的補充上報設(shè)計文檔的非目標聲明不報告未解析 targetRefs 的狀態(tài)而倉庫中的實現(xiàn)pkg/kgateway/proxy_syncer/policy_target_status.go將這類情況收斂為TargetNotFound條件正向遍歷每個策略的顯式targetRefs通過 krtKubernetes 運行時轉(zhuǎn)換驅(qū)動的 informer 集合解析目標無法解析的引用上報到策略的合成StatusSummary祖先條目上AcceptedFalse/TargetNotFound而不是直接使用缺失引用本身作為祖先——后者會因引用不存在對象而浪費祖先配額。合成祖先的定義位于 pkg/pluginsdk/reporter/types.gofunc PolicyStatusSummaryAncestorRef() gwv1.ParentReference { return gwv1.ParentReference{ Group: new(gwv1.Group(kgateway.GroupName)), Kind: new(gwv1.Kind(PolicyStatusSummaryAncestorName)), Name: PolicyStatusSummaryAncestorName, } }合并來源追蹤MergeOrigins數(shù)據(jù)結(jié)構(gòu)與操作語義在 pkg/pluginsdk/ir/merge.go 中MergeOrigins被定義為策略字段名 → 貢獻該字段的策略引用集合的映射并附帶三個計數(shù)枚舉// MergeOrigins maps policy field names to policy refs that contribute to it // during policy merging type MergeOrigins map[string]sets.Set[string] // MergeOriginsRefCount 用于追蹤策略引用在 MergeOrigins 中的狀態(tài) type MergeOriginsRefCount int const ( // MergeOriginsRefCountNone 表示該引用未出現(xiàn)在任何字段的 MergeOrigins 中 MergeOriginsRefCountNone MergeOriginsRefCount iota // MergeOriginsRefCountPartial 表示該引用出現(xiàn)在部分非全部字段中 MergeOriginsRefCountPartial // MergeOriginsRefCountAll 表示該引用出現(xiàn)在全部字段中 MergeOriginsRefCountAll )MergeOrigins提供的操作與合并策略一一對應(yīng)SetOne(field, ref, mergeOrigins)淺合并shallow merge場景使用——字段被覆蓋后僅記錄新的來源或當(dāng) ref 為 nil 時繼承來源的MergeOrigins。Append(field, ref, mergeOrigins)深合并deep merge場景使用——字段值是多個策略拼接/并集的結(jié)果因此把來源引用追加到已有集合中。GetRefCount(ref)統(tǒng)計某策略引用出現(xiàn)在多少個字段中返回None/Partial/All這正是reportPolicyAttachmentStatus判定Overridden/Merged/Attached的依據(jù)。ToProtoStruct()把MergeOrigins轉(zhuǎn)換為 Envoystructpb.Struct供寫入過濾器元數(shù)據(jù)使用。策略引用的唯一 ID 由AttachedPolicyRef.ID()生成見 pkg/pluginsdk/ir/gw.go其格式為Group delimiter Kind delimiter Namespace delimiter Name并通過 intern 共享底層字符串以減少內(nèi)存占用。各字段的實際合并調(diào)用以 pkg/kgateway/extensions2/plugins/trafficpolicy/merge.go 為例TrafficPolicy 的合并函數(shù)mergeExtProc、mergeExtAuth、mergeRustformation、mergeJwt、mergeCORS、mergeFaultInjection等約 25 個字段級合并器在合并每個字段時同步維護MergeOrigins深合并路徑AugmentedDeepMerge/OverridableDeepMerge調(diào)用mergeOrigins.Append(extProc, p2Ref, p2MergeOrigins)等把參與合并的第二個策略追加為該字段的來源淺合并路徑通過defaultMerge內(nèi)部的mergeOrigins.SetOne(...)記錄字段被哪個策略設(shè)置特殊場景如 buffer 與 HTTP upgrade 互斥沖突解決還會通過delete(mergeOrigins, buffer)移除被剔除字段的來源記錄。寫入 Envoy 元數(shù)據(jù)addMergeOriginsToFilterMetadata見 pkg/kgateway/translator/irtranslator/policy.go在合并結(jié)果非空時將MergeOrigins以merge.group/kind為 key 寫入 EnvoyMetadata.FilterMetadataconst mergeMetadataKeyPrefix merge. func addMergeOriginsToFilterMetadata(gk schema.GroupKind, mergeOrigins ir.MergeOrigins, metadata *envoycorev3.Metadata) *envoycorev3.Metadata { if !mergeOrigins.IsSet() { return metadata } pb : mergeOrigins.ToProtoStruct() ... metadata.FilterMetadata[mergeMetadataKeyPrefixgk.String()] pb return metadata }這樣下發(fā)的 Envoy 監(jiān)聽器配置中就帶上了每個合并字段的來源策略信息供診斷工具分析某個字段最終來自哪個策略。設(shè)計文檔明確表示將來工具可以利用該元數(shù)據(jù)深入洞察策略合并結(jié)果。狀態(tài)示例解讀以下三個示例均取自設(shè)計文檔展示了三種典型場景下Gateway祖先條目的完整狀態(tài)controllerName為kgateway.dev/kgateway。場景一策略成功掛載到全部目標status: ancestors: - ancestorRef: group: gateway.networking.k8s.io kind: Gateway name: test namespace: default conditions: - lastTransitionTime: 2025-07-24T18:06:29Z message: Policy accepted observedGeneration: 1 reason: Valid status: True type: Accepted - lastTransitionTime: 2025-07-24T18:06:29Z message: Attached to all targets observedGeneration: 1 reason: Attached status: True type: Attached controllerName: kgateway.dev/kgatewayAcceptedTrue/Valid表示策略有效AttachedTrue/Attached表示策略未經(jīng)過合并、直接掛載到了所有目標。場景二策略與其他策略合并但部分掛載status: ancestors: - ancestorRef: group: gateway.networking.k8s.io kind: Gateway name: test namespace: default conditions: - lastTransitionTime: 2025-07-24T18:06:29Z message: Policy accepted observedGeneration: 1 reason: Valid status: True type: Accepted - lastTransitionTime: 2025-07-24T18:06:29Z message: Merged with other policies in target(s) and attached observedGeneration: 1 reason: Merged status: True type: Attached controllerName: kgateway.dev/kgatewayAttachedTrue/Merged說明策略已生效但其部分字段與更高優(yōu)先級策略合并——消息Merged with other policies in target(s) and attached與 pkg/pluginsdk/reporter/types.go 中的PolicyMergedMsg完全一致。場景三策略被接受但未掛載status: ancestors: - ancestorRef: group: gateway.networking.k8s.io kind: Gateway name: test namespace: default conditions: - lastTransitionTime: 2025-07-24T18:06:29Z message: Policy accepted observedGeneration: 1 reason: Valid status: True type: Accepted - lastTransitionTime: 2025-07-24T18:06:29Z message: Overridden due to conflict with higher priority policy in target(s) observedGeneration: 1 reason: Overridden status: False type: Attached controllerName: kgateway.dev/kgateway這是設(shè)計文檔最想解決的場景AcceptedTrue/Valid但AttachedFalse/Overridden。策略本身合法卻在目標上被更高優(yōu)先級策略完全覆蓋用戶一眼即可看出策略被接受了但沒有生效而無需逐個比對策略優(yōu)先級。狀態(tài)如何落到 Kubernetes 對象上策略狀態(tài)的最終寫入由狀態(tài)同步層完成。在 pkg/kgateway/proxy_syncer/status.go 中可以看到各來源的報告生成函數(shù)如GenerateBackendPolicyReport為掛載到 Backend 上的策略生成Accepted/Attached條件而 pkg/reports/policy.go 的MergePolicyReports負責(zé)跨貢獻折疊報告當(dāng)ReportMap中某策略已有報告時把src的祖先條目合并進去同一祖先在兩邊都出現(xiàn)時以src的條目替換。寫入端的核心約束見 pkg/reports/policy.go 的注釋是其他控制器擁有的祖先條目被有意保留祖先數(shù)量上限cap與僅替換我方條目邏輯放在寫入路徑statussync.MergePolicyAncestorStatuses執(zhí)行該路徑才能權(quán)威地讀取 live 對象——這保證了多控制器共存時狀態(tài)不被誤刪同時BuildPolicyStatus中的排序保證消費方如 golden-output 翻譯測試拿到確定性輸出。測試與驗證設(shè)計文檔的 Test Plan 要求通過單元測試、translator 測試與 e2e 測試驗證策略 Status API。倉庫中的對應(yīng)測試覆蓋包括pkg/reports/policy_test.go驗證BuildPolicyStatus生成的Attached條件如AttachedTrue/Attached、消息Attached to all targets。pkg/pluginsdk/ir/merge_test.go覆蓋MergeOrigins的Get、SetOne、Append、IsSet、GetRefCount等全部操作方法包括淺合并覆蓋與深合并追加的來源記錄行為。pkg/kgateway/proxy_syncer/policy_target_status_test.go 與 pkg/reports/observed_generation_test.go驗證TargetNotFound上報、observedGeneration與狀態(tài)純度的行為。pkg/kgateway/extensions2/plugins/trafficpolicy/merge_test.go驗證具體字段合并時MergeOrigins的記錄是否符合預(yù)期?？偨Y(jié)kgateway 通過將gwv1.PolicyStatus中的狀態(tài)拆分為Accepted與Attached兩個自定義 Condition徹底解決了策略被接受但未生效難以診斷的問題Accepted反映策略本身的合法性與目標可解析性Attached反映策略是否真正掛載到目標資源并通過Attached、Merged、Overridden三種原因按Overridden Merged Attached的嚴重程度聚合描述合并場景下的最終生效狀態(tài)同時MergeOrigins作為元數(shù)據(jù)寫入下發(fā)的 Envoy 配置記錄了每個合并字段的來源策略為構(gòu)建策略合并結(jié)果洞察類工具提供了數(shù)據(jù)基礎(chǔ)。這套設(shè)計讓運維人員可以用kubectl get policy -o yaml直接讀取狀態(tài)條件快速區(qū)分配置寫錯了AcceptedFalse與配置被覆蓋了AcceptedTrue但AttachedFalse/Overridden顯著提升了多策略疊加場景下的可觀測性與排障效率。贊分享API網(wǎng)關(guān)云原生微服務(wù)【免費下載鏈接】kgatewayThe Cloud-Native API Gateway and AI Gateway項目地址https://gitcode.com/gh_mirrors/kg/kgateway點擊查看免費下載相關(guān)推薦PDF ProcessingPDF Processing Quick start Extract text with pdfplumber: code example Advanced f人工智能AI 應(yīng)用AI 技能/插件AI Agent金融科技ngxtop函數(shù)測試策略基于行為與基于狀態(tài)的測試ngxtop函數(shù)測試策略基于行為與基于狀態(tài)的測試 引言 在軟件開發(fā)中測試是確保代碼質(zhì)量和可靠性的關(guān)鍵環(huán)節(jié)。對于ngxtop這樣的實時Nginx服務(wù)器指標工具運維可觀測性CLIReselect與GraphQL結(jié)合API數(shù)據(jù)的狀態(tài)選擇策略Reselect與GraphQL結(jié)合API數(shù)據(jù)的狀態(tài)選擇策略 你是否在React應(yīng)用中遇到過這樣的困境GraphQL獲取的數(shù)據(jù)需要復(fù)雜處理后才能在UI展示狀態(tài)管理上一篇Lobe Theme 布局模式深度解析雙列視圖與可調(diào)節(jié)畫布比例下一篇5分鐘快速上手BRV框架讓Android列表開發(fā)效率提升300%創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考