Ingress NGINX 注解风险等级与作用域全解annotations-risk 治理指南【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读Ingress NGINX Controller 通过nginx.ingress.kubernetes.io/*前缀的注解Annotation为用户提供路由重写、认证、限流、金丝雀发布等能力但不同注解对底层 Nginx 配置的控制深度天差地别——有的只接受布尔值或枚举有的却允许注入任意 Nginx 指令甚至 Lua 代码。本文基于仓库中 annotations-risk.md 的官方风险清单系统梳理每个注解的风险等级Low / Medium / High / Critical与作用域ingress / location并结合解析器源码说明风险等级如何在运行时被强制执行、管理员如何通过annotations-risk-level收紧或放宽策略。读完本文你将掌握风险分级的判定依据、整张注解风险对照表的正确解读、以及如何在多租户集群中落地注解安全治理。为什么要为注解标注风险与作用域Ingress NGINX 的注解体系非常庞大完整清单见 annotations.md每个注解都会在控制器生成 Nginx 配置模板时被翻译成具体的指令。从安全治理角度看注解面临两个核心问题注入能力差异巨大部分注解只接受严格枚举值如auth-type只能是basic或digest而configuration-snippet、server-snippet、stream-snippet这类注解允许用户直接写入任意 Nginx 配置片段甚至可能通过 Lua 指令执行任意代码。若多租户集群中的普通用户被允许设置这类注解就可能绕过 RBAC 读取集群内的全部 Secret对应 CVE-2021-25742 一类问题。生效粒度不同注解可能作用于整个 Ingress 资源scope 为ingress影响 server / upstream 级别配置也可能只作用于某个 location 块scope 为location仅影响特定路径的请求处理。annotations-risk.md就是为此而生的官方参考表它为每一个注解声明了风险等级与作用域既是管理员制定准入策略的依据也是控制器内部校验逻辑的说明书——源码中每个注解的解析器都登记了同样的Risk与Scope元数据。风险等级Risk的定义与判定依据风险等级在源码中被定义为四档枚举定义位于 internal/ingress/annotations/parser/validators.goconst ( AnnotationRiskLow AnnotationRisk iota AnnotationRiskMedium AnnotationRiskHigh AnnotationRiskCritical )判定依据在 internal/ingress/annotations/parser/main.go 的注释中有明确说明Risk defines a risk of this annotation being exposed to the user. Annotations with bool fields, or to set timeout are usually low risk. Annotations that allows string input without a limited set of options may represent a high risk.翻译过来即只接受布尔值、数字或超时时间这类受限输入的注解通常是 Low 风险允许不受限字符串输入的注解通常是 High 风险。各等级的实际含义等级含义典型代表Low值域受限bool、枚举、数字、超时无法注入额外指令canary、ssl-redirect、proxy-read-timeoutMedium允许有限字符集的字符串可影响请求行为但注入面可控auth-secret、cors-allow-origin、rewrite-targetHigh允许正则、URL 或可展开的 Nginx 变量可显著改变请求路径server-alias、auth-url、mirror-target、upstream-hash-byCritical直接注入原始 Nginx / Lua 配置片段等于把配置权限交给用户configuration-snippet、auth-snippet、server-snippet、stream-snippet、modsecurity-snippet源码中的风险标注示例每个注解解析器在Validate方法中为其字段登记风险与校验器。例如internal/ingress/annotations/alias/main.go 中server-alias被标记为AnnotationRiskHigh注释写道 High as this allows regex chars——因为服务器别名允许正则字符可能扩大匹配范围甚至与预期主机名之外的流量匹配。internal/ingress/annotations/auth/main.go 中auth-secret被标记为 MediumMedium as it allows a subset of chars。internal/ingress/annotations/authreq/main.go 中auth-snippet被标记为AnnotationRiskCritical与文档表格完全一致。这说明annotations-risk.md表格并非拍脑袋而是与各解析器内AnnotationConfig.Risk字段一一对应的可执行事实。作用域Scope的含义作用域决定注解翻译后的配置注入位置定义于 internal/ingress/annotations/parser/main.goAnnotationScopeLocation AnnotationScope location AnnotationScopeIngress AnnotationScope ingresslocation注解只影响对应 Ingress 规则中某个路径location 块的请求处理。例如proxy-body-size、auth-url、denylist-source-range等。同一主机下不同路径可以各自携带不同的 location 级注解。ingress注解影响整个 Ingress 对象的 server / upstream 配置例如server-alias为该 server 增加别名、canary系列决定金丝雀规则、mirror-host/mirror-target流量镜像目标、session-affinity系列会话粘滞、proxy-ssl-*到后端的 TLS 配置等。值得注意的是同一组内的不同注解作用域可能不同例如 Rewrite 组中rewrite-target的 scope 是ingress而app-root、force-ssl-redirect是locationUpstreamHashBy 组中upstream-hash-by是location可针对特定路径做一致性哈希而其子集相关注解也是location。解读表格时不应按组一概而论而要逐条查看。完整注解风险对照表以下为 annotations-risk.md 中的官方全量表按 Group 分组Risk 为风险等级Scope 为作用域。这是管理员评估哪些注解可以开放给哪些用户的第一手依据GroupAnnotationRiskScopeAliasesserver-aliasHighingressAllowlistallowlist-source-rangeMediumlocationBackendProtocolbackend-protocolLowlocationBasicDigestAuthauth-realmMediumlocationBasicDigestAuthauth-secretMediumlocationBasicDigestAuthauth-secret-typeLowlocationBasicDigestAuthauth-typeLowlocationCanarycanaryLowingressCanarycanary-by-cookieMediumingressCanarycanary-by-headerMediumingressCanarycanary-by-header-patternMediumingressCanarycanary-by-header-valueMediumingressCanarycanary-weightLowingressCanarycanary-weight-totalLowingressCertificateAuthauth-tls-error-pageHighlocationCertificateAuthauth-tls-match-cnHighlocationCertificateAuthauth-tls-pass-certificate-to-upstreamLowlocationCertificateAuthauth-tls-secretMediumlocationCertificateAuthauth-tls-verify-clientMediumlocationCertificateAuthauth-tls-verify-depthLowlocationClientBodyBufferSizeclient-body-buffer-sizeLowlocationConfigurationSnippetconfiguration-snippetCriticallocationConnectionconnection-proxy-headerLowlocationCorsConfigcors-allow-credentialsLowingressCorsConfigcors-allow-headersMediumingressCorsConfigcors-allow-methodsMediumingressCorsConfigcors-allow-originMediumingressCorsConfigcors-expose-headersMediumingressCorsConfigcors-max-ageLowingressCorsConfigenable-corsLowingressCustomHTTPErrorscustom-http-errorsLowlocationCustomHeaderscustom-headersMediumlocationDefaultBackenddefault-backendLowlocationDenylistdenylist-source-rangeMediumlocationDisableProxyInterceptErrorsdisable-proxy-intercept-errorsLowlocationEnableGlobalAuthenable-global-authLowlocationExternalAuthauth-always-set-cookieLowlocationExternalAuthauth-cache-durationMediumlocationExternalAuthauth-cache-keyMediumlocationExternalAuthauth-keepaliveLowlocationExternalAuthauth-keepalive-requestsLowlocationExternalAuthauth-keepalive-share-varsLowlocationExternalAuthauth-keepalive-timeoutLowlocationExternalAuthauth-methodLowlocationExternalAuthauth-proxy-set-headersMediumlocationExternalAuthauth-request-redirectMediumlocationExternalAuthauth-response-headersMediumlocationExternalAuthauth-signinHighlocationExternalAuthauth-signin-redirect-paramMediumlocationExternalAuthauth-snippetCriticallocationExternalAuthauth-urlHighlocationFastCGIfastcgi-indexMediumlocationFastCGIfastcgi-params-configmapMediumlocationHTTP2PushPreloadhttp2-push-preloadLowlocationLoadBalancingload-balanceLowlocationLogsenable-access-logLowlocationLogsenable-rewrite-logLowlocationMirrormirror-hostHighingressMirrormirror-request-bodyLowingressMirrormirror-targetHighingressModSecurityenable-modsecurityLowingressModSecurityenable-owasp-core-rulesLowingressModSecuritymodsecurity-snippetCriticalingressModSecuritymodsecurity-transaction-idHighingressOpentelemetryenable-opentelemetryLowlocationOpentelemetryopentelemetry-operation-nameMediumlocationOpentelemetryopentelemetry-trust-incoming-spanLowlocationProxyproxy-body-sizeMediumlocationProxyproxy-buffer-sizeLowlocationProxyproxy-bufferingLowlocationProxyproxy-buffers-numberLowlocationProxyproxy-busy-buffers-sizeLowlocationProxyproxy-connect-timeoutLowlocationProxyproxy-cookie-domainMediumlocationProxyproxy-cookie-pathMediumlocationProxyproxy-http-versionLowlocationProxyproxy-max-temp-file-sizeLowlocationProxyproxy-next-upstreamMediumlocationProxyproxy-next-upstream-timeoutLowlocationProxyproxy-next-upstream-triesLowlocationProxyproxy-read-timeoutLowlocationProxyproxy-redirect-fromMediumlocationProxyproxy-redirect-toMediumlocationProxyproxy-request-bufferingLowlocationProxyproxy-send-timeoutLowlocationProxySSLproxy-ssl-ciphersMediumingressProxySSLproxy-ssl-nameHighingressProxySSLproxy-ssl-protocolsLowingressProxySSLproxy-ssl-secretMediumingressProxySSLproxy-ssl-server-nameLowingressProxySSLproxy-ssl-verifyLowingressProxySSLproxy-ssl-verify-depthLowingressRateLimitlimit-allowlistLowlocationRateLimitlimit-burst-multiplierLowlocationRateLimitlimit-connectionsLowlocationRateLimitlimit-rateLowlocationRateLimitlimit-rate-afterLowlocationRateLimitlimit-rpmLowlocationRateLimitlimit-rpsLowlocationRedirectfrom-to-www-redirectLowlocationRedirectpermanent-redirectMediumlocationRedirectpermanent-redirect-codeLowlocationRedirectrelative-redirectsLowlocationRedirecttemporal-redirectMediumlocationRedirecttemporal-redirect-codeLowlocationRewriteapp-rootMediumlocationRewriteforce-ssl-redirectMediumlocationRewritepreserve-trailing-slashMediumlocationRewriterewrite-targetMediumingressRewritessl-redirectLowlocationRewriteuse-regexLowlocationSSLCipherssl-ciphersLowingressSSLCipherssl-prefer-server-ciphersLowingressSSLPassthroughssl-passthroughLowingressSatisfysatisfyLowlocationServerSnippetserver-snippetCriticalingressServiceUpstreamservice-upstreamLowingressSessionAffinityaffinityLowingressSessionAffinityaffinity-canary-behaviorLowingressSessionAffinityaffinity-modeMediumingressSessionAffinitysession-cookie-change-on-failureLowingressSessionAffinitysession-cookie-conditional-samesite-noneLowingressSessionAffinitysession-cookie-domainMediumingressSessionAffinitysession-cookie-expiresMediumingressSessionAffinitysession-cookie-max-ageMediumingressSessionAffinitysession-cookie-nameMediumingressSessionAffinitysession-cookie-pathMediumingressSessionAffinitysession-cookie-samesiteLowingressSessionAffinitysession-cookie-secureLowingressStreamSnippetstream-snippetCriticalingressUpstreamHashByupstream-hash-byHighlocationUpstreamHashByupstream-hash-by-subsetLowlocationUpstreamHashByupstream-hash-by-subset-sizeLowlocationUpstreamVhostupstream-vhostLowlocationUsePortInRedirectsuse-port-in-redirectsLowlocationXForwardedPrefixx-forwarded-prefixMediumlocation风险等级如何在运行时被强制执行风险等级不只是文档标注控制器在每次同步 Ingress 时都会真正执行校验。调用链如下抽取阶段Extractor.Extract遍历所有注解解析器并调用Validate(ing.GetAnnotations())一旦校验失败即返回errors.NewRiskyAnnotations(name)错误见 internal/ingress/annotations/annotations.go。逐解析器校验每个解析器如 canary、authreq、proxy、snippet 等共 40 个在Validate中都会先通过StringRiskToRisk把字符串配置转成AnnotationRisk再调用parser.CheckAnnotationRisk(anns, maxrisk, ...)检查该 Ingress 携带的注解是否超过允许的最大风险。比较逻辑CheckAnnotationRisk见 internal/ingress/annotations/parser/validators.go遍历 Ingress 上的每个注解若注解主键或别名命中配置项、且该项Risk maxrisk则把错误累积起来——这意味着一个 Ingress 可能同时被多个过于危险的注解拒绝。前置校验解析器在读取注解值之前还会先跑checkAnnotationvalidators.go 第 207 行起对值做字符集/格式校验并拦截\r、\n等恶意字符MaliciousRegex防止注入换行构造新的 Nginx 指令。测试佐证风险比较逻辑有完整的单元测试覆盖见 internal/ingress/annotations/parser/validators_test.go其中的用例包括当maxrisk Medium时携带 High 风险的注解会被拒绝当maxrisk Critical时High 与 Critical 注解均可接受maxrisk Low时只接受 Low 注解注解别名AnnotationAliases同样参与风险评估。管理员如何配置允许的风险上限控制器不会对每个注解一律放行或一律拒绝而是由管理员通过 ConfigMap 参数annotations-risk-level统一设定集群允许的最大风险等级apiVersion: v1 kind: ConfigMap metadata: name: ingress-nginx-controller namespace: ingress-nginx data: annotations-risk-level: High含义如果设置为Medium则风险为 High 和 Critical 的注解将不被接受对应 Ingress 配置失败设置Low则只接受 Low。可接受值Critical、High、Medium、Low默认值为High见 configmap.md 与 internal/ingress/controller/config/config.go 中的默认配置。默认High意味着默认情况下Critical 级别的 snippet 注解即被拒绝但 High 及以下的注解含server-alias、auth-url、mirror-*、upstream-hash-by等可用。若你确实需要开放 snippet 能力可额外设置allow-snippet-annotations: true但应仅在可信集群中这样做。配套治理参数风险等级之外ConfigMap 中还有两个直接相关的安全开关annotation-value-word-blocklist逗号分隔的坏词列表命中后整个 Ingress 不会被配置。用于阻断load_module、lua_package、_by_lua、location、root、proxy_pass、serviceaccount等已知被滥用于执行任意代码或读取敏感信息的关键字与 CVE-2021-25742 相关见 configmap.md。注意设置该参数会覆盖默认屏蔽词表因此应把需要屏蔽的词完整列出。allow-cross-namespace-resources控制是否允许注解跨命名空间引用 Secret / ConfigMap如auth-secret、custom-headers关闭时跨命名空间引用会被拒绝见 config.go。常见高风险注解的实战提示结合源码与文档以下是几个容易踩坑的高风险注解1.server-aliasHighingress允许为正则字符源码注释明确指出风险原因在于允许 regex 字符alias/main.go。若开放给不可信用户可能通过正则扩大 server_name 匹配面把本应匹配其他主机的流量引入当前后端。2.auth-snippet/configuration-snippet/server-snippet/stream-snippetCritical直接注入 Nginx 配置片段。多租户集群中开放这类注解等于让低权限用户拥有集群级敏感信息读取能力CVE-2021-25742 即属此类。默认annotations-risk-level: High已将其屏蔽确需使用时建议配合annotation-value-word-blocklist屏蔽危险关键字并只对可信命名空间开放。3.mirror-host/mirror-targetHighingress允许把线上流量镜像到任意主机/目标地址可能造成数据外泄或放大攻击流量。流量镜像的能力本身mirror-request-body等是 Low但目标地址可控性是 High原因在于 URL/主机名不受限。4.upstream-hash-byHighlocation值可以是 Nginx 变量与文本的任意组合如$request_uri可影响后端选择逻辑虽然常用于一致性哈希实现会话粘滞但错误配置可能导致流量倾斜。其合法用法的完整说明见 annotations.md 与 chashsubset 示例。5.auth-tls-error-page/auth-tls-match-cnHighlocation前者可指定任意跳转 URL后者允许正则匹配证书 CNCommonNameAnnotationValidator要求值以CN开头并对剩余部分做正则编译见 validators.go。正则本身是合法功能但也意味着更宽的匹配语义风险分级因此较高。最佳实践建议保持默认annotations-risk-level: High除非确有必要不要放宽到Critical开放任何 snippet 类注解前先评估信任边界。按命名空间分级对不可信的多租户命名空间设置annotations-risk-level: Medium或更低仅允许auth-*、cors-*、proxy-*等受限输入注解对平台自有的基础设施命名空间才考虑放宽。用annotation-value-word-blocklist兜底即使允许 snippet也要屏蔽lua_package、proxy_pass、serviceaccount等关键字阻断常见的提权路径。借助作用域做最小化授权作用域为location的注解只影响单个路径适合逐路径精细控制作用域为ingress的注解影响整个 server/upstream评估风险时按整机对待。校验失败即拒绝一旦 Ingress 携带超等级注解CheckAnnotationRisk会返回错误导致该 Ingress 不被同步——把这一行为视为安全默认值而不是试图绕过它。延伸阅读注解完整清单、取值类型与逐条说明docs/user-guide/nginx-configuration/annotations.md风险等级对应的 ConfigMap 参数docs/user-guide/nginx-configuration/configmap.md#annotations-risk-level风险模型源码AnnotationRisk定义与CheckAnnotationRisk实现见 internal/ingress/annotations/parser/main.go 与 internal/ingress/annotations/parser/validators.go注解抽取与校验入口internal/ingress/annotations/annotations.go风险比较的单元测试internal/ingress/annotations/parser/validators_test.go【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ingress NGINX 注解风险等级与作用域全解：annotations-risk 治理指南
Ingress NGINX 注解风险等级与作用域全解annotations-risk 治理指南【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读Ingress NGINX Controller 通过nginx.ingress.kubernetes.io/*前缀的注解Annotation为用户提供路由重写、认证、限流、金丝雀发布等能力但不同注解对底层 Nginx 配置的控制深度天差地别——有的只接受布尔值或枚举有的却允许注入任意 Nginx 指令甚至 Lua 代码。本文基于仓库中 annotations-risk.md 的官方风险清单系统梳理每个注解的风险等级Low / Medium / High / Critical与作用域ingress / location并结合解析器源码说明风险等级如何在运行时被强制执行、管理员如何通过annotations-risk-level收紧或放宽策略。读完本文你将掌握风险分级的判定依据、整张注解风险对照表的正确解读、以及如何在多租户集群中落地注解安全治理。为什么要为注解标注风险与作用域Ingress NGINX 的注解体系非常庞大完整清单见 annotations.md每个注解都会在控制器生成 Nginx 配置模板时被翻译成具体的指令。从安全治理角度看注解面临两个核心问题注入能力差异巨大部分注解只接受严格枚举值如auth-type只能是basic或digest而configuration-snippet、server-snippet、stream-snippet这类注解允许用户直接写入任意 Nginx 配置片段甚至可能通过 Lua 指令执行任意代码。若多租户集群中的普通用户被允许设置这类注解就可能绕过 RBAC 读取集群内的全部 Secret对应 CVE-2021-25742 一类问题。生效粒度不同注解可能作用于整个 Ingress 资源scope 为ingress影响 server / upstream 级别配置也可能只作用于某个 location 块scope 为location仅影响特定路径的请求处理。annotations-risk.md就是为此而生的官方参考表它为每一个注解声明了风险等级与作用域既是管理员制定准入策略的依据也是控制器内部校验逻辑的说明书——源码中每个注解的解析器都登记了同样的Risk与Scope元数据。风险等级Risk的定义与判定依据风险等级在源码中被定义为四档枚举定义位于 internal/ingress/annotations/parser/validators.goconst ( AnnotationRiskLow AnnotationRisk iota AnnotationRiskMedium AnnotationRiskHigh AnnotationRiskCritical )判定依据在 internal/ingress/annotations/parser/main.go 的注释中有明确说明Risk defines a risk of this annotation being exposed to the user. Annotations with bool fields, or to set timeout are usually low risk. Annotations that allows string input without a limited set of options may represent a high risk.翻译过来即只接受布尔值、数字或超时时间这类受限输入的注解通常是 Low 风险允许不受限字符串输入的注解通常是 High 风险。各等级的实际含义等级含义典型代表Low值域受限bool、枚举、数字、超时无法注入额外指令canary、ssl-redirect、proxy-read-timeoutMedium允许有限字符集的字符串可影响请求行为但注入面可控auth-secret、cors-allow-origin、rewrite-targetHigh允许正则、URL 或可展开的 Nginx 变量可显著改变请求路径server-alias、auth-url、mirror-target、upstream-hash-byCritical直接注入原始 Nginx / Lua 配置片段等于把配置权限交给用户configuration-snippet、auth-snippet、server-snippet、stream-snippet、modsecurity-snippet源码中的风险标注示例每个注解解析器在Validate方法中为其字段登记风险与校验器。例如internal/ingress/annotations/alias/main.go 中server-alias被标记为AnnotationRiskHigh注释写道 High as this allows regex chars——因为服务器别名允许正则字符可能扩大匹配范围甚至与预期主机名之外的流量匹配。internal/ingress/annotations/auth/main.go 中auth-secret被标记为 MediumMedium as it allows a subset of chars。internal/ingress/annotations/authreq/main.go 中auth-snippet被标记为AnnotationRiskCritical与文档表格完全一致。这说明annotations-risk.md表格并非拍脑袋而是与各解析器内AnnotationConfig.Risk字段一一对应的可执行事实。作用域Scope的含义作用域决定注解翻译后的配置注入位置定义于 internal/ingress/annotations/parser/main.goAnnotationScopeLocation AnnotationScope location AnnotationScopeIngress AnnotationScope ingresslocation注解只影响对应 Ingress 规则中某个路径location 块的请求处理。例如proxy-body-size、auth-url、denylist-source-range等。同一主机下不同路径可以各自携带不同的 location 级注解。ingress注解影响整个 Ingress 对象的 server / upstream 配置例如server-alias为该 server 增加别名、canary系列决定金丝雀规则、mirror-host/mirror-target流量镜像目标、session-affinity系列会话粘滞、proxy-ssl-*到后端的 TLS 配置等。值得注意的是同一组内的不同注解作用域可能不同例如 Rewrite 组中rewrite-target的 scope 是ingress而app-root、force-ssl-redirect是locationUpstreamHashBy 组中upstream-hash-by是location可针对特定路径做一致性哈希而其子集相关注解也是location。解读表格时不应按组一概而论而要逐条查看。完整注解风险对照表以下为 annotations-risk.md 中的官方全量表按 Group 分组Risk 为风险等级Scope 为作用域。这是管理员评估哪些注解可以开放给哪些用户的第一手依据GroupAnnotationRiskScopeAliasesserver-aliasHighingressAllowlistallowlist-source-rangeMediumlocationBackendProtocolbackend-protocolLowlocationBasicDigestAuthauth-realmMediumlocationBasicDigestAuthauth-secretMediumlocationBasicDigestAuthauth-secret-typeLowlocationBasicDigestAuthauth-typeLowlocationCanarycanaryLowingressCanarycanary-by-cookieMediumingressCanarycanary-by-headerMediumingressCanarycanary-by-header-patternMediumingressCanarycanary-by-header-valueMediumingressCanarycanary-weightLowingressCanarycanary-weight-totalLowingressCertificateAuthauth-tls-error-pageHighlocationCertificateAuthauth-tls-match-cnHighlocationCertificateAuthauth-tls-pass-certificate-to-upstreamLowlocationCertificateAuthauth-tls-secretMediumlocationCertificateAuthauth-tls-verify-clientMediumlocationCertificateAuthauth-tls-verify-depthLowlocationClientBodyBufferSizeclient-body-buffer-sizeLowlocationConfigurationSnippetconfiguration-snippetCriticallocationConnectionconnection-proxy-headerLowlocationCorsConfigcors-allow-credentialsLowingressCorsConfigcors-allow-headersMediumingressCorsConfigcors-allow-methodsMediumingressCorsConfigcors-allow-originMediumingressCorsConfigcors-expose-headersMediumingressCorsConfigcors-max-ageLowingressCorsConfigenable-corsLowingressCustomHTTPErrorscustom-http-errorsLowlocationCustomHeaderscustom-headersMediumlocationDefaultBackenddefault-backendLowlocationDenylistdenylist-source-rangeMediumlocationDisableProxyInterceptErrorsdisable-proxy-intercept-errorsLowlocationEnableGlobalAuthenable-global-authLowlocationExternalAuthauth-always-set-cookieLowlocationExternalAuthauth-cache-durationMediumlocationExternalAuthauth-cache-keyMediumlocationExternalAuthauth-keepaliveLowlocationExternalAuthauth-keepalive-requestsLowlocationExternalAuthauth-keepalive-share-varsLowlocationExternalAuthauth-keepalive-timeoutLowlocationExternalAuthauth-methodLowlocationExternalAuthauth-proxy-set-headersMediumlocationExternalAuthauth-request-redirectMediumlocationExternalAuthauth-response-headersMediumlocationExternalAuthauth-signinHighlocationExternalAuthauth-signin-redirect-paramMediumlocationExternalAuthauth-snippetCriticallocationExternalAuthauth-urlHighlocationFastCGIfastcgi-indexMediumlocationFastCGIfastcgi-params-configmapMediumlocationHTTP2PushPreloadhttp2-push-preloadLowlocationLoadBalancingload-balanceLowlocationLogsenable-access-logLowlocationLogsenable-rewrite-logLowlocationMirrormirror-hostHighingressMirrormirror-request-bodyLowingressMirrormirror-targetHighingressModSecurityenable-modsecurityLowingressModSecurityenable-owasp-core-rulesLowingressModSecuritymodsecurity-snippetCriticalingressModSecuritymodsecurity-transaction-idHighingressOpentelemetryenable-opentelemetryLowlocationOpentelemetryopentelemetry-operation-nameMediumlocationOpentelemetryopentelemetry-trust-incoming-spanLowlocationProxyproxy-body-sizeMediumlocationProxyproxy-buffer-sizeLowlocationProxyproxy-bufferingLowlocationProxyproxy-buffers-numberLowlocationProxyproxy-busy-buffers-sizeLowlocationProxyproxy-connect-timeoutLowlocationProxyproxy-cookie-domainMediumlocationProxyproxy-cookie-pathMediumlocationProxyproxy-http-versionLowlocationProxyproxy-max-temp-file-sizeLowlocationProxyproxy-next-upstreamMediumlocationProxyproxy-next-upstream-timeoutLowlocationProxyproxy-next-upstream-triesLowlocationProxyproxy-read-timeoutLowlocationProxyproxy-redirect-fromMediumlocationProxyproxy-redirect-toMediumlocationProxyproxy-request-bufferingLowlocationProxyproxy-send-timeoutLowlocationProxySSLproxy-ssl-ciphersMediumingressProxySSLproxy-ssl-nameHighingressProxySSLproxy-ssl-protocolsLowingressProxySSLproxy-ssl-secretMediumingressProxySSLproxy-ssl-server-nameLowingressProxySSLproxy-ssl-verifyLowingressProxySSLproxy-ssl-verify-depthLowingressRateLimitlimit-allowlistLowlocationRateLimitlimit-burst-multiplierLowlocationRateLimitlimit-connectionsLowlocationRateLimitlimit-rateLowlocationRateLimitlimit-rate-afterLowlocationRateLimitlimit-rpmLowlocationRateLimitlimit-rpsLowlocationRedirectfrom-to-www-redirectLowlocationRedirectpermanent-redirectMediumlocationRedirectpermanent-redirect-codeLowlocationRedirectrelative-redirectsLowlocationRedirecttemporal-redirectMediumlocationRedirecttemporal-redirect-codeLowlocationRewriteapp-rootMediumlocationRewriteforce-ssl-redirectMediumlocationRewritepreserve-trailing-slashMediumlocationRewriterewrite-targetMediumingressRewritessl-redirectLowlocationRewriteuse-regexLowlocationSSLCipherssl-ciphersLowingressSSLCipherssl-prefer-server-ciphersLowingressSSLPassthroughssl-passthroughLowingressSatisfysatisfyLowlocationServerSnippetserver-snippetCriticalingressServiceUpstreamservice-upstreamLowingressSessionAffinityaffinityLowingressSessionAffinityaffinity-canary-behaviorLowingressSessionAffinityaffinity-modeMediumingressSessionAffinitysession-cookie-change-on-failureLowingressSessionAffinitysession-cookie-conditional-samesite-noneLowingressSessionAffinitysession-cookie-domainMediumingressSessionAffinitysession-cookie-expiresMediumingressSessionAffinitysession-cookie-max-ageMediumingressSessionAffinitysession-cookie-nameMediumingressSessionAffinitysession-cookie-pathMediumingressSessionAffinitysession-cookie-samesiteLowingressSessionAffinitysession-cookie-secureLowingressStreamSnippetstream-snippetCriticalingressUpstreamHashByupstream-hash-byHighlocationUpstreamHashByupstream-hash-by-subsetLowlocationUpstreamHashByupstream-hash-by-subset-sizeLowlocationUpstreamVhostupstream-vhostLowlocationUsePortInRedirectsuse-port-in-redirectsLowlocationXForwardedPrefixx-forwarded-prefixMediumlocation风险等级如何在运行时被强制执行风险等级不只是文档标注控制器在每次同步 Ingress 时都会真正执行校验。调用链如下抽取阶段Extractor.Extract遍历所有注解解析器并调用Validate(ing.GetAnnotations())一旦校验失败即返回errors.NewRiskyAnnotations(name)错误见 internal/ingress/annotations/annotations.go。逐解析器校验每个解析器如 canary、authreq、proxy、snippet 等共 40 个在Validate中都会先通过StringRiskToRisk把字符串配置转成AnnotationRisk再调用parser.CheckAnnotationRisk(anns, maxrisk, ...)检查该 Ingress 携带的注解是否超过允许的最大风险。比较逻辑CheckAnnotationRisk见 internal/ingress/annotations/parser/validators.go遍历 Ingress 上的每个注解若注解主键或别名命中配置项、且该项Risk maxrisk则把错误累积起来——这意味着一个 Ingress 可能同时被多个过于危险的注解拒绝。前置校验解析器在读取注解值之前还会先跑checkAnnotationvalidators.go 第 207 行起对值做字符集/格式校验并拦截\r、\n等恶意字符MaliciousRegex防止注入换行构造新的 Nginx 指令。测试佐证风险比较逻辑有完整的单元测试覆盖见 internal/ingress/annotations/parser/validators_test.go其中的用例包括当maxrisk Medium时携带 High 风险的注解会被拒绝当maxrisk Critical时High 与 Critical 注解均可接受maxrisk Low时只接受 Low 注解注解别名AnnotationAliases同样参与风险评估。管理员如何配置允许的风险上限控制器不会对每个注解一律放行或一律拒绝而是由管理员通过 ConfigMap 参数annotations-risk-level统一设定集群允许的最大风险等级apiVersion: v1 kind: ConfigMap metadata: name: ingress-nginx-controller namespace: ingress-nginx data: annotations-risk-level: High含义如果设置为Medium则风险为 High 和 Critical 的注解将不被接受对应 Ingress 配置失败设置Low则只接受 Low。可接受值Critical、High、Medium、Low默认值为High见 configmap.md 与 internal/ingress/controller/config/config.go 中的默认配置。默认High意味着默认情况下Critical 级别的 snippet 注解即被拒绝但 High 及以下的注解含server-alias、auth-url、mirror-*、upstream-hash-by等可用。若你确实需要开放 snippet 能力可额外设置allow-snippet-annotations: true但应仅在可信集群中这样做。配套治理参数风险等级之外ConfigMap 中还有两个直接相关的安全开关annotation-value-word-blocklist逗号分隔的坏词列表命中后整个 Ingress 不会被配置。用于阻断load_module、lua_package、_by_lua、location、root、proxy_pass、serviceaccount等已知被滥用于执行任意代码或读取敏感信息的关键字与 CVE-2021-25742 相关见 configmap.md。注意设置该参数会覆盖默认屏蔽词表因此应把需要屏蔽的词完整列出。allow-cross-namespace-resources控制是否允许注解跨命名空间引用 Secret / ConfigMap如auth-secret、custom-headers关闭时跨命名空间引用会被拒绝见 config.go。常见高风险注解的实战提示结合源码与文档以下是几个容易踩坑的高风险注解1.server-aliasHighingress允许为正则字符源码注释明确指出风险原因在于允许 regex 字符alias/main.go。若开放给不可信用户可能通过正则扩大 server_name 匹配面把本应匹配其他主机的流量引入当前后端。2.auth-snippet/configuration-snippet/server-snippet/stream-snippetCritical直接注入 Nginx 配置片段。多租户集群中开放这类注解等于让低权限用户拥有集群级敏感信息读取能力CVE-2021-25742 即属此类。默认annotations-risk-level: High已将其屏蔽确需使用时建议配合annotation-value-word-blocklist屏蔽危险关键字并只对可信命名空间开放。3.mirror-host/mirror-targetHighingress允许把线上流量镜像到任意主机/目标地址可能造成数据外泄或放大攻击流量。流量镜像的能力本身mirror-request-body等是 Low但目标地址可控性是 High原因在于 URL/主机名不受限。4.upstream-hash-byHighlocation值可以是 Nginx 变量与文本的任意组合如$request_uri可影响后端选择逻辑虽然常用于一致性哈希实现会话粘滞但错误配置可能导致流量倾斜。其合法用法的完整说明见 annotations.md 与 chashsubset 示例。5.auth-tls-error-page/auth-tls-match-cnHighlocation前者可指定任意跳转 URL后者允许正则匹配证书 CNCommonNameAnnotationValidator要求值以CN开头并对剩余部分做正则编译见 validators.go。正则本身是合法功能但也意味着更宽的匹配语义风险分级因此较高。最佳实践建议保持默认annotations-risk-level: High除非确有必要不要放宽到Critical开放任何 snippet 类注解前先评估信任边界。按命名空间分级对不可信的多租户命名空间设置annotations-risk-level: Medium或更低仅允许auth-*、cors-*、proxy-*等受限输入注解对平台自有的基础设施命名空间才考虑放宽。用annotation-value-word-blocklist兜底即使允许 snippet也要屏蔽lua_package、proxy_pass、serviceaccount等关键字阻断常见的提权路径。借助作用域做最小化授权作用域为location的注解只影响单个路径适合逐路径精细控制作用域为ingress的注解影响整个 server/upstream评估风险时按整机对待。校验失败即拒绝一旦 Ingress 携带超等级注解CheckAnnotationRisk会返回错误导致该 Ingress 不被同步——把这一行为视为安全默认值而不是试图绕过它。延伸阅读注解完整清单、取值类型与逐条说明docs/user-guide/nginx-configuration/annotations.md风险等级对应的 ConfigMap 参数docs/user-guide/nginx-configuration/configmap.md#annotations-risk-level风险模型源码AnnotationRisk定义与CheckAnnotationRisk实现见 internal/ingress/annotations/parser/main.go 与 internal/ingress/annotations/parser/validators.go注解抽取与校验入口internal/ingress/annotations/annotations.go风险比较的单元测试internal/ingress/annotations/parser/validators_test.go【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考