1.Nginx Ingress簡介
Kubernetes 通過 kube-proxy 服務實現了 Service 的對外發布及負載均衡,它的各種方式都是基於傳輸層實現的。在實際的互聯網應用場景中,不僅要實現單純的轉發,還有更加細致的策略需求,如果使用真正的負載均衡器更會增加操作的靈活性和轉發性能。
基於以上需求,Kubernetes 引入了資源對象 Ingress,Ingress 為 Service 提供了可直接被集群外部訪問的虛擬主機、負載均衡、SSL 代理、HTTP 路由等應用層轉發功能。
Kubernetes 官方發布了基於 GCE 和 Nginx 的 Ingress 控制器,Nginx Ingress 控制器能根據 Service 中 Pod 的變化動態地調整配置,結合 Nginx 的高穩定性、高性能、高並發處理能力等特點,使 Kubernetes 對集群中運行於容器的應用程序具有了更加靈活的應用層管理能力。
Nginx Ingress 因使用 Nginx 的不同版本,分為 Nginx 官方版本和 Kubernetes 社區版。Nginx 官方版本提供其基於Go語言開發的 Ingress 控制器,並與 Nginx 集成分為 Nginx 開源版和 Nginx Plus 版;開源版僅基於 Nginx 的原始功能,提供了 Nginx 原生配置指令的支持,相較於 Nginx Plus 版功能簡單且不支持 Pod 變化的動態變更。
Nginx Plus 版則提供了諸多完善的商業功能,其支持 Nginx 原生配置指令、JWT 驗證、Pod 變化的動態配置及主動健康檢查等功能。Kubernetes 社區版是基於 Nginx 的擴展版 OpenResty 及諸多第三方模塊構建的,其基於 OpenResty 的 Lua 嵌入式編程能力,擴展了 Nginx 的功能,並基於 balancer_by_lua 模塊實現了 Pod 變化的動態變更功能。本節介紹的是基於 Kubernetes 社區版的 Nginx Ingress。
1.1 Nginx Ingress原理
Nginx Ingress 由資源對象 Ingress、Ingress 控制器、Nginx 三部分組成,Ingress 控制器用以將 Ingress 資源實例組裝成 Nginx 配置文件(nginx.conf),並重新加載 Nginx 使變更的配置生效。當它監聽到 Service 中 Pod 變化時通過動態變更的方式實現 Nginx 上游服務器組配置的變更,無須重新加載 Nginx 進程。工作原理如下圖所示。
- Ingress,一組基於域名或 URL 把請求轉發到指定 Service 實例的訪問規則,是 Kubernetes 的一種資源對象,Ingress 實例被存儲在對象存儲服務 etcd 中,通過接口服務被實現增、刪、改、查的操作。
- Ingress 控制器(Ingress controller),用以實時監控資源對象 Ingress、Service、End-point、Secret(主要是 TLS 證書和 Key)、Node、ConfigMap 的變化,自動對 Nginx 進行相應的操作。
- Nginx,實現具體的應用層負載均衡及訪問控制。
圖:Nginx Ingress工作原理
Ingress 控制器通過同步循環機制實時監控接口服務 Ingress 等資源對象的變化,當相關 Service 對應的端點列表有變化時,會通過 HTTP POST 請求將變化信息發送到 Nginx 內部運行的 Lua 程序進行處理,實現對 Nginx Upstream 中后端 Pod IP 變化的動態修改。
每個后端 Pod 的 IP 及 targetPort 信息都存儲在 Nginx 的共享內存區域,Nginx 對每個獲取的請求將使用配置的負載均衡算法進行轉發,Nginx 的配置中應用 Lua 模塊的 balancer_by_lua 功能實現 upstream 指令域的動態操作,Pod IP 變化及資源對象 Ingress 對 upstream 指令域相關注解(annotation)的變化無須執行 Nginx 的 reload 操作。
當 Ingress 控制器監控的其他資源對象變化時,會對當前變化的內容創建 Nginx 配置模型,如果新的配置模型與當前運行的 Nginx 配置模型不一致,則將新的配置模型按照模板生成新的 Nginx 配置,並對 Nginx 執行 reload 操作。
Nginx 配置模型避免了 Nginx 的無效 reload 操作。為避免因 Nginx 配置語法錯誤導致意外中斷,Ingress 控制器為 Nginx 的配置內容提供了沖突檢測及合並機制,Ingress 控制器使用了准入控制插件(Validating Admission Webhook)做驗證 Ingress 配置語法的准入控制,驗證通過的 Ingress 資源對象才會被保存在存儲服務 etcd 中,並被 Ingress 控制器生成確保沒有語法錯誤的 Nginx 配置文件。
1.2 集成的第三方模塊
Kubernetes 的 Nginx Ingress 當前版本是 0.25.1,其集成了 Nginx 的擴展版本 Open-Resty 的 1.15.8.1 版本,OpenResty 的最大特點是集成了 Lua 腳本的嵌入式編程功能,基於 Nginx 的優化,使 Nginx 具有更強的擴展能力。
Nginx Ingress 通過 Lua 腳本編程,利用 OpenResty 的 balancer_by_lua 模塊,可通過 nginx-ingress 控制器動態地修改 Nginx 上游服務器組的配置,無須 Nginx 進程的熱加載,有效地解決了因 Pod 調度帶來的 Pod IP 變化的問題。
Kubernetes 的 Nginx Ingress 在 OpenResty 基礎上還集成了諸多的第三方模塊,模塊功能介紹如下。
1) Ajp協議模塊(nginx_ajp_module)
Ajp 協議模塊是一個使 Nginx 實現 Ajp 協議代理的模塊,該模塊可以使 Nginx 通過 Ajp 協議連接到被代理的 Tomcat 服務。
模塊網址:https://github.com/nginx-modules/nginx_ajp_module
2) InfluxDB輸出模塊(nginx-influxdb-module)
InfluxDB 輸出模塊可以使 Nginx 的每次請求記錄以 InfluxDB 作為后端進行存儲,其以非阻塞的方式對每個請求進行過濾,並使用 UDP 協議將處理后的數據發送到 InfluxDB 服務器。可以通過該模塊實時監控 Nginx 的所有請求,獲得每個請求的連接類型、請求狀態,並通過 InfluxDB 實現相關故障狀態的報警。
模塊網址:https://github.com/influxdata/nginx-influxdb-module
3) GeoIP2數據庫模塊(ngx_http_geoip2)
MaxMind 的 GeoIP 數據庫已經升級到第二代,GeoIP2 數據庫提供了准確的 IP 信息,包括 IP 地址的位置(國家、城市、經緯度)等數據。該模塊增加了 GeoIP2 數據的支持。
模塊網址:https://github.com/nginx-modules/ngx_http_geoip2_module
4) 摘要認證模塊(nginx-http-auth-digest)
摘要認證模塊使 Nginx 的基本認證功能增加了摘要認證(Digest Authentication)的支持,這是一種簡單的身份驗證機制,是對基本認證的一種安全改進,僅通過服務端及客戶端根據用戶名和密碼計算的摘要信息進行驗證,避免了密碼的明文傳遞,增加了認證過程的安全性。
模塊網址:https://github.com/nginx-modules/nginx-http-auth-digest
5) 內容過濾模塊(ngx_http_substitutions_filter_module)
內容過濾模塊是一個內容過濾功能的模塊,其相對於 Nginx 自帶的內容過濾模塊(ngx_http_sub_module)增加了正則匹配的替換方式。
模塊網址:https://github.com/nginx-modules/ngx_http_substitutions_filter_module
6) 分布式跟蹤模塊(nginx-opentracing)
OpenTracing 由 API 規范、實現該規范的框架和庫以及項目文檔組成,是一個輕量級的標准化規范,其位於應用程序和跟蹤分析程序之間,解決了不同分布式追蹤系統API不兼容的問題。OpenTracing 允許開發人員使用 API 向應用程序代碼中添加工具,實現業務應用中的分布式請求跟蹤。
分布式請求跟蹤,也稱分布式跟蹤,是一種用於分析和監視應用程序的方法,特別是那些使用微服務體系結構構建的應用程序。分布式跟蹤有助於查明故障發生的位置以及導致性能低下的原因。該模塊是將 Nginx 的請求提供給 OpenTracing 項目的分布式跟蹤系統用於應用的請求分析和監控。
Nginx Ingress 中集成了 jaeger 和 zipkin 兩種分布式跟蹤系統的 OpenTracing 項目插件,用戶可根據實際情況進行選擇使用。
模塊網址:https://github.com/opentracing-contrib/nginx-opentracing
7) Brotli壓縮模塊(ngx_brotli)
Brotli 是 Google 推出的側重於 HTTP 壓縮的一種開源壓縮算法,它使用 lz77 算法的現代變體、Huffman 編碼和基於上下文的二階建模的組合來壓縮數據。在與 Deflate 相似的壓縮與解壓縮速度下,增加了 20% 的壓縮密度。在與 gzip 的測試下,因壓縮密度高其消耗的壓縮時間要比 gzip 多,但在客戶端解壓的時間則相當。
模塊網址:https://github.com/google/ngx_brotli
8) ModSecurity連接器模塊(ModSecurity-nginx)
ModSecurity 是一個開源的 Web 應用防火牆,其主要作用是增強 Web 應用的安全性並保護 Web 應用免受攻擊。模塊 ModSecurity-nginx 是一個 Nginx 的 ModSecurity 連接器,其提供了 Nginx 和 libmodsecurity(ModSecurity v3)之間的通信通道。Nignx Ingress 中已經集成了 ModSecurity 和 OWASP 規則集,在 Nginx 配置文件目錄可以查看相關配置。
模塊網址:https://github.com/nginx-modules/ModSecurity-nginx
9) lua-resty-waf模塊
lua-resty-waf 是一個基於 OpenResty 的高性能 Web 應用防火牆,它使用 Nginx Lua API 及靈活的規則架構分析和處理 HTTP 請求信息,並不斷開發和測試一些自定義的規則補丁來應對不斷出現的新的安全威脅。lua-resty-waf 提供了 ModSecurity 兼容的規則語法,支持 ModSecurity 現有規則的自動轉換,用戶無須學習新的語法規則就可以擴展 lua-resty-waf 的規則。
模塊網址:https://github.com/p0pr0ck5/lua-resty-waf。
2.Nginx Ingress安裝部署
2.1 HELM方式安裝部署
Helm 是一個非常方便的 Kubernetes 應用部署工具,支持 Nginx Ingress 的快速部署和卸載。通過 Helm 可快速將 Nginx Ingress 部署在 Kubernetes 集群中,Helm 中 Nginx Ingress 的 1.19.1 版本 Chart 部分參數如下表所示。
參數 | 參數值選項 | 默認值 | 功能說明 |
controller.service.type | ClusterIP 或 NodePort 或 LoadBalancer | LoadBalancer | 設置資源對象 Service 的服務類型 |
controller.hostNetwork | true 或 false | false | 設置資源對象 Pod 是否以 hostNet-work方式運行 |
controller.service.externalIPs | -- | -- | 設置資源對象 Service externalIPs 的 IP 地址 |
controller.kind | Deployment 或 Daemon-Set | Deployment | 設置部署方式 |
controller.service.external-TrafficPolicy | Local 或 Cluster | Cluster | 設置 Pod 流量調度方式 |
rbac.create | true 或 false | false | 是否為 nginx-ingress 創建 RBAC 資源 |
controller.autoscaling.enabled | true 或 false | false | 是否啟用多副本支持,啟用后最小副本數為 1,最大值為 11 |
controller.autoscaling.min-Replicas | -- | 1 | 設置創建的最小副本數 |
controller.metrics.enabled | true 或 false | false | 是否啟用 Prometheus Exporter |
controller.containerPort.http | -- | 80 | Nginx Ingress 的默認 HTTP 端口 |
controller.containerPort.https | -- | 443 | Nginx Ingress 的默認 HTTP 端口 |
helm install --name nginx-ingress stable/nginx-ingress --set rbac.create=true
具體說明如下:
-
- Helm 安裝的應用名稱為 nginx-ingress;
- rbac.create 參數用以為 nginx-ingress 創建 RBAC 資源,獲取與接口服務的訪問授權。
Nginx Ingress 以 Pod 形式運行在 Kubernetes 集群中,用戶可根據 Kubernetes 的網絡通信特點以及實際場景選擇靈活的部署方式進行 Nginx Ingress 的部署,此處分別以基於資源對象 Service 的 NodePort 方式和 Pod 的 hostNetwork 方式舉例介紹。
1) Service的NodePort方式
以 NodePort 類型部署 Nginx Ingress,需要使用參數進行指定 controller.service.type 為 NodePort。為便於管理,可以為 Nginx Ingress 創建單獨使用的命名空間 nginx-ingress,部署拓撲如下圖所示。
圖:NodePort方式
部署命令如下:
# 安裝nginx-ingress helm install --name nginx-ingress \ --namespace nginx-ingress \ stable/nginx-ingress \ --set "rbac.create=true,controller.autoscaling.enabled=true,controller. autoscaling.minReplicas=2,controller.service.type=NodePort,con-troller.service.externalTrafficPolicy=Local" # 也可以在創建后調整副本數 kubectl scale --replicas=3 deployment/nginx-ingress
具體說明如下:
-
- Helm 安裝的應用名稱為 nginx-ingress,命名空間為 nginx-ingress;
- 以默認的 Deployment 方式部署,設置 Pod 副本數為 2,並以 Service 的 NodePort 方式對外發布服務,設置流量調度策略為 Local;
- Kubernetes 將為 nginx-ingress Service 隨機創建范圍在 30000~32767 之間的 Node-Port 端口;
- 用戶將 Kubernetes 中節點 IP 和 NodePort 手動添加到傳輸層負載均衡中的虛擬服務器集群中;
- 外部請求發送到傳輸層負載均衡虛擬服務器,傳輸層負載將請求數據轉發到 Kubernetes 集群節點的 NodePort;
- NodePort 類型的 Service 將請求負載到對應的 Nginx Pod;
- Nginx 將用戶請求進行應用層負載轉發到配置的應用 Pod;
- 在該部署方式下,Nginx Pod 需要使用 Local 的流量調度策略,獲取客戶端的真實 IP。
2) Pod的hostNetwork方式
主機網絡(hostNetwork)方式可以使 Pod 與宿主機共享網絡命名空間,外網傳輸效率最高。因 Pod 直接暴露外網,雖然存在一定的安全問題,但不存在客戶端源 IP 隱藏的問題,部署拓撲如下圖所示。
圖:hostNetwork方式
部署命令如下:
# 以Deployment方式部署 helm install --name nginx-ingress \ --namespace nginx-ingress \ stable/nginx-ingress \ --set "rbac.create=true,controller.service.type=ClusterIP,controller. hostNetwork=true"
具體說明如下:
-
- Deployment 方式部署時,Nginx Ingress 的 Service 設置類型為 ClusterIP,僅提供內部服務端口;
- 用戶將 Kubernetes 中節點 IP 及 80、443 端口手動添加到傳輸層負載均衡中的虛擬服務器集群中;
- 用戶請求經傳輸層負載均衡設備轉發到 Nginx,Nginx 將用戶請求負載到 Kubernetes 集群內的 Pod 應用。
也可以使用 DaemonSet 部署方式,在集群中的每個節點自動創建並運行一個 Nginx Ingress Pod,實現 Nginx Ingress 的自動擴展。
# 以DaemonSet方式部署nginx-ingress並成為集群唯一入口 helm install --name nginx-ingress \ --namespace nginx-ingress \ stable/nginx-ingress \ --set "rbac.create=true,controller.kind=DaemonSet,controller.service.type=ClusterIP,controller.hostNetwork=true"
3) SSL終止(SSL Termination)和SSL透傳(SSL Passthrough)
SSL 終止模式下,客戶端的 TLS 數據會在代理服務器 Nginx 中解密,解密的數據由代理服務器直接或再次 TLS 加密后傳遞給被代理服務器,這種模式下,相對增加代理服務器的計算負擔,但方便了 SSL 證書的統一管理。
SSL 透傳模式下,Nginx 不會對客戶端的 HTTPS 請求進行解密,加密的請求會被直接轉發到后端的被代理服務器,這種方式常被應用到后端的 HTTPS 服務器需要對客戶端進行客戶端證書驗證的場景,相對也會降低 Nginx 對 TLS 證書加解密的負擔。由於請求數據是保持加密傳輸的,HTTP 消息頭將無法修改,所以消息頭字段 X-forwarded-* 的客戶端 IP 無法被添加。Nginx Ingress 默認部署方式沒有開啟 SSL 透傳的支持,需要在部署時使用參數 --enable-ssl-passthrough 進行開啟。
# 修改部署資源對象nginx-ingress-controller kubectl edit Deployment/nginx-ingress-controller -n nginx-ingress # 在規范部分添加容器啟動參數--enable-ssl-passthrough spec: containers: - args: - /nginx-ingress-controller - --default-backend-service=nginx-ingress/nginx-ingress-default-backend - --election-id=ingress-controller-leader - --ingress-class=nginx - --configmap=nginx-ingress/nginx-ingress-controller - --enable-ssl-passthrough
4) 卸載Nginx Ingress
Nginx 的配置是以資源對象 ConfigMap 和 Ingress 方式存儲在 etcd 服務中的,所以即便刪除或重新部署 Nginx Ingress 也不會影響之前的配置。
helm delete --purge nginx-ingress
2.2 手動方式安裝部署
手動方式不做過多解釋,簡單來說找到想要安裝的版本,直接應用其中的mandatory.yaml即可,當然,也可以根據自己的需求更改yaml文件
Git地址為以下: https://github.com/kubernetes/ingress-nginx/blob/nginx-0.30.0/deploy/static/mandatory.yaml
3.Nginx Ingress配置映射ConfigMap
通過 Helm 安裝 Nginx Ingress 的默認關聯配置映射實例名稱為 nginx-ingress-controller,用戶可以通過修改資源對象 Deployment/DaemonSet 實例 nginx-ingress-controller 中的參數 --configmap 自定義關聯配置映射實例的名稱。
當然,手動增加configmap,只要寫上對應的ingress的labels也可以。
Nginx Ingress 控制器約定 Nginx Ingress 配置映射實例中的鍵值只能是字符串,即便是數字或布爾值時也要以字符串的形式書寫,比如 "true"、"false"、"100","[]string" 或 "[]int" 的 Slice 類型則表示內部數據是以 "," 分隔的字符串。根據配置涉及的功能可以有如下分類。
3.1 Nginx原生配置指令
用以提供向 Nginx 配置中添加 Nginx 原生配置指令,功能說明如下表所示。
名稱 | 類型 | 默認值 | 功能描述 |
main-snippet | string | "" | 在 main 指令域添加 Nginx 配置指令 |
http-snippet | string | "" | 在 http 指令域添加 Nginx 配置指令 |
server-snippet | string | "" | 在 server 指令域添加 Nginx 配置指令 |
location-snippet | string | "" | 在 location 指令域添加 Nginx 配置指令 |
配置樣例如下:
echo ' apiVersion: v1 kind: ConfigMap data: http-snippet: | ancient_browser "UCWEB"; ancient_browser_value oldweb; server { listen 8080; if ($ancient_browser) { rewrite ^ /${ancient_browser}.html; # 重定向到oldweb.html } } metadata: name: nginx-ingress-controller namespace: nginx-ingress ' | kubectl create -f -
3.2 通用配置
提供 Nginx 核心配置相關配置指令的配置,功能說明如下表所示。
名稱 | 類型 | 默認值 | Nginx 指令 | 功能描述 |
worker-processes | string | auto | worker_processes | 參見《Nginx進程配置指令》一節 |
worker-cpu-affinity | string | "" | worker_cpu_affinity | 參見《Nginx進程配置指令》一節 |
worker-shutdown-timeout | string | 10s | worker_shutdown_timeout | 參見《Nginx進程配置指令》一節 |
max-worker-connections | string | -- | worker_connections | 參見《Nginx進程配置指令》一節 |
max-worker-open-files | string | -- | worker_rlimit_nofile | 參見《Nginx進程配置指令》一節 |
enable-multi-accept | bool | true | multi_accept | 參見《Nginx進程配置指令》一節 |
keep-alive | int | 75 | keepalive_timeout | -- |
keep-alive-requests | int | 100 | keepalive_requests | -- |
variables-hash-bucket-size | int | 128 | variables_hash_bucket_size | -- |
variables-hash-max-size | int | 2048 | variables_hash_max_size | -- |
server-name-hash-max-size | int | 1024 | server_names_hash_max_size | -- |
server-name-hash-bucket-size | int | CPU 緩存行的大小 | server_names_hash_bucket_size | -- |
map-hash-bucket-size | int | 64 | map_hash_bucket_size | -- |
bind-address | []string | "" | listen | 設置虛擬主機綁定的 IP 地址 |
reuse-port | bool | true | listen | 設置監聽端口啟用 reuseport 參數,由 Linux 內核以套接字分片方式實現進程調度 |
disable-ipv6 | bool | false | listen | -- |
disable-ipv6-dns | bool | false | resolver | 設置是否關閉域名解析的 IPv6 地址查找 |
enable-underscores-in-headers | bool | false | underscores_in_headers | 參見《Nginx處理HTTP請求》一節 |
ignore-invalid-headers | bool | true | ignore_invalid_headers | 參見《Nginx處理HTTP請求》一節 |
client-header-buffer-size | string | 1k | client_header_buffer_size | 參見《Nginx處理HTTP請求》一節 |
client-header-timeout | int | 60 | client_header_timeout | 參見《Nginx處理HTTP請求》一節 |
client-body-buffer-size | string | 8k | client_body_buffer_size | 參見《Nginx處理HTTP請求》一節 |
client-body-timeout | int | 69 | client_body_timeout | 參見《Nginx處理HTTP請求》一節 |
large-client-header-buffers | string | 4 8k | large_client_header_buffers | 參見《Nginx處理HTTP請求》一節 |
http-redirect-code | int | 308 | return | 設置 URL 跳轉時的響應碼,可選項為 301,302,307 和 308 |
use-geoip | bool | true | -- | 啟用 geoip 功能 |
use-geoip2 | bool | false | -- | 啟用 geoip2 功能,由第三方模塊實現 |
nginx-status-ipv4-whitelist | []string | 127.0.0.1 | -- | 設置允許訪問路徑 /nginx_status 的 IPv4 地址 |
nginx-status-ipv6-whitelist | []string | ::1 | -- | 設置允許訪問路徑 /nginx_status 的 IPv6 地址 |
server-tokens | bool | true | server_tokens | 參見《Nginx處理HTTP請求》一節 |
lua-shared-dicts | string | "" | -- | 設置 Lua 共享內存字典,Oper_Resty 擴展指令 |
配置樣例如下:
cat>test.yaml<<EOF apiVersion: v1 kind: ConfigMap data: keep-alive: "60" disable-ipv6: "true" metadata: name: nginx-ingress-controller namespace: nginx-ingress EOF kubectl create -f test.yaml
3.3 響應數據配置
提供響應信息頭修改及響應數據壓縮相關功能的配置,功能說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
add-headers | string | "" | add_header | -- |
use-gzip | bool | true | gzip | 啟用 gzip |
gzip-level | int | 5 | gzip_comp_level | 參見《Nginx開啟gzip》一節 |
gzip-types | string | application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/java-script text/plain text/x-component |
gzip_types | 參見《Nginx開啟gzip》一節 |
enable-brotli | bool | false | -- | 設置是否加載 brotli 模塊 |
brotli-level | int | 4 | -- | 設置 brotli 的壓縮級別 |
brotli-types | string | application/xml+rss application/atom+xml application/javascript application/x-javascript application/json applica-tion/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/javascript text/plain text/x-com-ponent |
-- | 設置 brotli 的壓縮類型 |
3.4 訪問控制
提供限制連接數、訪問速度、訪問連接及防火牆的配置,功能說明如下表所示。
名稱 | 類型 | 默認值 | Nginx 指令 | 功能描述 |
limit-conn-zone-variable | string | $binary_remote_addr | limit_conn_zone | 參見《Nginx並發連接數限制模塊》一節 |
limit-conn-status-code | int | 503 | limit_conn_status | 參見《Nginx並發連接數限制模塊》一節 |
limit-rate | int | 0 | limit_rate | -- |
limit-rate-after | int | 0 | limit_rate_after | -- |
limit-req-status-code | int | 503 | limit_req_status | 參見《Nginx並發連接數限制模塊》一節 |
whitelist-source-range | []string []string{} | -- | allow | 設置允許訪問的源 IP 地址 |
block-cidrs | []string | "" | deny | 禁止設置 IP 地址的訪問 |
block-user-agents | []string | "" | map | 禁止設置信息頭字段 User-Agent 匹配值的訪問 |
block-referers | []string | "" | map | 禁止設置信息頭字段 Referer 匹配值的訪問 |
enable-modsecurity | bool | false | -- | 設置是否加載 Mod-Security 連接模塊 |
enable-owasp-modsecurity-crs | bool | false | -- | 設置是否加載 OWASP ModSecurity 核心規則庫 |
3.5 HTTPS配置
提供與 HTTPS 相關的配置,功能說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
ssl-ciphers | string | ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384: ECDHE-ECDSA-CHACHA20-POLY-1305:ECDHE-RSA-CHACHA20-POLY1305: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES256-SHA-384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA -AES-128-SHA256:ECDHE-RSA-AES-128-SHA256 |
ssl-ciphers | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-ecdh-curve | string | auto | ssl_ecdh_curve | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-dhparam | string | "" | ssl_dhparam | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-protocols | string | TLSv1.2 | ssl_protocols | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-early-data | bool | true | ssl_early_data | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-session-cache | bool | true | ssl_session_cache | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-session-cache-size | string | 10m | ssl_session_cache | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-session-tickets | bool | true | ssl_session_tickets | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-session-ticket-key | string | -- | ssl_session_tickets | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-session-timeout | string | 10m | ssl_session_timeout | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-buffer-size | string | 4k | ssl_buffer_size | 參見《Nginx HTTPS服務器搭建》一節 |
ssl-redirect | bool | true | -- | 當被配置的虛擬主機啟用了 TLS 支持,則將虛擬主機的 HTTP 請求跳轉到 HTTPS 請求 |
no-tls-redirect-locations | string | /.well-known/acme-challenge | -- | 一個以“,”分隔的 location 列表,對列表中 location 的 HTTP 請求永遠不會跳轉到 HTTPS 請求 |
3.6 HSTS配置
HSTS(HTTP Strict Transport Security)是一種新的 Web 安全協議,HSTS 配置啟用后,將強制客戶端使用 HTTPS 協議與服務器建立連接,配置映射提供的 HSTS 功能配置功能說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
hsts | bool | true | add_header | 是否運行 SSL 時在消息頭中添加 HSTS 屬性字段 |
hsts-include-subdomains | bool | true | add_header | 是否在當前域名的所有子域中啟用 HSTS |
hsts-max-age | string | 15724800 | add_header | 設置 HSTS Header 的過期時間 |
hsts-preload | bool | false | add_header | 設置是否啟用 HSTS 的預加載支持 |
3.7 認證轉發配置
提供認證轉發功能的全局配置,功能說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
global-auth-url | string | "" | auth_request | 設置外部身份驗證的 URL |
global-auth-method | string | "" | proxy_method | 外部認證 URL 的 HTTP 方法 |
global-auth-signin | string | "" | -- | 當外部認證返回 401 時跳轉的 URL,通常為提示輸人用戶名和密碼的 URL |
global-auth-response-headers | string | "" | -- | 設置認證請求完成后傳遞到真實后端的頭信息 |
global-auth-request-redirect | string | "" | -- | 設置發送給認證服務器請求頭中 X-Auth-Request-Redirect 的值 |
global-auth-snippet | string | "" | -- | 可以自定義在外部認證指令區域添加 Nginx 配置指令 |
global-auth-cache-key | string | "" | -- | 啟用認證緩存,並設置認證緩存的關鍵字 |
global-auth-cache-duration | string | 200 202 401 5m | -- | 基於響應碼設置認證緩存的有效時間 |
no-auth-locations | string | /.well-known/acme-challenge | -- | 一個以“,”分隔的 location 列表,列表中被記錄的請求將不進行身份認證 |
3.8 代理配置
設置 Nginx 的代理功能配置,相關配置說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
retry-non-idempotent | bool | false | proxy_next_upstream | 參見《Nginx HTTP代理服務器》一節 |
proxy-set-header | string | "" | proxy_set_header | 參見《Nginx HTTP代理服務器》一節 |
proxy-headers-hash-max-size | int | 512 | proxy_headers_hash_max_size | 參見《Nginx HTTP代理服務器》一節 |
proxy-headers-hash-bucket-size | int | 64 | proxy_headers_hash_bucket_size | 參見《Nginx HTTP代理服務器》一節 |
hide-headers | string array | empty | proxy_hide_header | 參見《Nginx HTTP代理服務器》一節 |
proxy-body-size | string | 1m | client_max_body_size | -- |
allow-backend-server-header | bool | false | proxy_pass_header | 設置是否允許將被代理服務器的消息頭字段 Server 的值代替 Nginx 的默認值返回給客戶端 |
proxy-connect-timeout | int | 5 | proxy_connect_timeout | 參見《Nginx HTTP代理服務器》一節 |
proxy-read-timeout | int | 60 | proxy_read_timeout | 參見《Nginx HTTP代理服務器》一節 |
proxy-send-timeout | int | 60 | proxy_send_timeout | 參見《Nginx HTTP代理服務器》一節 |
proxy-buffers-number | int | 4 | proxy_buffers | 參見《Nginx HTTP代理服務器》一節 |
proxy-buffer-size | string | 4k | proxy_buffer_size | 參見《Nginx HTTP代理服務器》一節 |
proxy-cookie-path | string | off | proxy_cookie_path | 參見《Nginx HTTP代理服務器》一節 |
proxy-cookie-domain | string | off | proxy_cookie_domain | 參見《Nginx HTTP代理服務器》一節 |
proxy-next-upstream | string | error timeout | proxy_next_upstream | 參見《Nginx HTTP代理服務器》一節 |
proxy-next-upstream-timeout | int | 0 | proxy_next_upstream_timeout | 參見《Nginx HTTP代理服務器》一節 |
proxy-next-upstream-tries | int | 3 | proxy_next_upstream_tries | 參見《Nginx HTTP代理服務器》一節 |
proxy-redirect-from | string | off | proxy_redirect | 此處為添加要替換的源文本 |
proxy-redirect-to | string | off | proxy_redirect | 此處為添加要替換的目標文本 |
proxy-request-buffering | string | on | proxy_request_buffering | 參見《Nginx HTTP代理服務器》一節 |
proxy-buffering | string | off | proxy_buffering | 參見《Nginx HTTP代理服務器》一節 |
proxy-add-original-uri-header | bool | true | proxy_set_header | 為發送到后端的請求頭添加一個頭屬性字段 X-Original-Uri,記錄原始請求 |
use-forwarded-headers | bool | false | proxy_set_header | 設置是否使用傳入的頭屬性字段 X-Forwarded |
forwarded-for-header | string | X-Forwarded-For | proxy_set_header | 設置用於標識客戶端源 IP 的頭屬性字段名稱 X-For-warded |
compute-full-forwarded-for | bool | false | proxy_set_header | 設置是否將遠程地址附加到頭屬性字段 X-For-warded-For 中,而不是替換它 |
custom-http-errors | []int | off | error_page | 該配置會自動啟用 Nginx 配置指令 proxy_intercept_errors,默認是關閉的 |
proxy-stream-timeout | string | 600s | proxy_timeout | 參見《Nginx TCP/UDP代理》一節 |
proxy-stream-responses | int | 1 | proxy_responses | 參見《Nginx TCP/UDP代理》一節 |
use-proxy-protocol | bool | false | listen | 啟用 proxy_protocol 支持 |
proxy-protocol-header-timeout | string | 5d | proxy_protocol_timeout | 設置接收 proxy-protocol 頭的超時時間,可防止 TLS 傳遞處理程序無限期地等待已斷開的連接 |
proxy-real-ip-cidr | []string | 0.0.0.0/0 | set_real_ip_from | 當啟用 proxy-protocol 時設置授信 IP,用於后端獲得真實客戶端 IP |
use-http2 | bool | true | listen | 啟用 HTTP2 監聽 |
http2-max-field-size | string | 4k | http2_max_field_size | 參見《Nginx HTTP2模塊配置》一節 |
http2-max-header-size | string | 16k | http2_max_header_size | 參見《Nginx HTTP2模塊配置》一節 |
http2-max-requests | int | 1000 | http2_max_requests | 參見《Nginx HTTP2模塊配置》一節 |
3.9 負載均衡配置
Nginx Ingress 為方便上游服務器組的動態管理,其基於 Lua 實現了輪詢調度及峰值指數加權移動平均(Peak Exponentially Weighted Moving-Average,Peak EWMA)負載均衡算法。配置映射的配置為全局負載均衡的配置,詳見本節的注解負載均衡說明。配置映射還提供了被代理服務器長連接的配置支持,配置說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
load-balance | string | round_robin | -- | 設置負載均衡算法,支持輪詢 round_robin 和 Peak EWMA 兩種模式, 基於 OpenResty 的 balancer_by_lua 模塊實現 |
upstream-keepalive-connections | int | 32 | keepalive | 參見《Nginx負載均衡模塊》一節 |
upstream-keepalive-timeout | int | 60 | keepalive_timeout | 參見《Nginx負載均衡模塊》一節 |
upstream-keepalive-requests | int | 100 | keepalive_requests | 參見《Nginx負載均衡模塊》一節 |
3.10 日志配置
設置 Nginx 的日志功能配置,相關配置說明如下表所示。
名稱 | 類型 | 默認值 | Nginx指令 | 功能描述 |
disable-access-log | bool | false | access-log | 設置 HTTP 指令域 access-log 的指令值為 off |
access-log-params | string | "" | access-log | 設置訪問日志的參數 |
access-log-path | string | /var/log/nginx/access.log | access-log | 設置訪問日志路徑 |
log-format-escape-json | bool | false | log_format | 設置日志格式為 JSON |
log-format-upstream | string | %v-[$the_real_ip]-$remote_user[$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_up-stream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id |
log_format | HTTP 日志模板 |
skip-access-log-urls | []string | []string{} | access-log | 設置不進行訪問日志記錄的 URL,access-log 的 if 參數 |
enable-access-log-for-default-backend | bool | false | access-log | 是否開啟默認后端的訪問日志記錄 |
log-format-stream | string | [$time_local] $protocol $status $bytes_sent $bytes_received $session_time | log_format | TCP/UDP 日志模板 |
error-log-path | string | /var/log/nginx/error.log | error_log | 錯誤日志路徑 |
error-log-level | string | notice | error_log | 錯誤日志級別 |
3.11 分布式跟蹤配置
設置分布式跟蹤功能的配置,配置鍵及功能描述如下表所示。
名稱 | 類型 | 默認值 | 功能描述 |
generate-request-id | bool | true | 如果請求頭中沒有屬性字段 X-Request-ID,則為該請求隨機創建一個,用於分布式鏈路跟蹤 |
enable-opentracing | bool | false | 設置是否加載 opentracing 模塊,啟用分布式跟蹤支持 |
zipkin-collector-host | string | "" | 設置用於上傳跟蹤信息的 zipkin 主機地址 |
zipkin-collector-port | int | 9411 | 設置用於上傳跟蹤信息的 zipkin 主機端口 |
zipkin-service-name | string | nginx | 設置用於在 zipkin 中創建跟蹤的服務名稱 |
zipkin-sample-rate | float | 1.0 | 設置 zipkin 跟蹤的采樣率 |
jaeger-collector-host | string | "" | 設置用於上傳跟蹤信息的 jaeger 主機地址 |
jaeger-collector-port | int | 6831 | 設置用於上傳跟蹤信息的 jaeger 主機端口 |
jaeger-service-name | string | nginx | 設置用於在 jaeger 中創建跟蹤的服務名稱 |
jaeger-sampler-type | string | const | 設置 jaeger 的采樣器名稱,可選項為 const、probabilistic、ratelimiting、remote |
jaeger-sampler-param | string | 1 | 設置 jaeger 采樣器的參數 |
jaeger-sampler-host | string | http://127.0.0.1 | 設置 jaeger 采樣器為 remote 時的主機地址 |
jaeger-sampler-port | int | 5778 | 設置 jaeger 采樣器為 remote 時的主機端口 |
4.Nginx Ingress注解Annotations
Nginx Ingress 注解使用在 Ingress 資源實例中,用以設置當前 Ingress 資源實例中 Nginx 虛擬主機的相關配置,對應配置的是 Nginx 當前虛擬主機的 server 指令域內容。在與 Nginx Ingress 配置映射具有相同功能配置時,將按照所在指令域層級遵循 Nginx 配置規則覆蓋。
Nginx Ingress注解按照配置功能有如下分類。
4.1 Nginx原生配置指令
支持在注解中添加 Nginx 原生配置指令。配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/server-snippet | string | 在 server 指令域添加 Nginx 配置指令 |
nginx.ingress.kubernetes.io/configuration-snippet | string | 在 location 指令域添加 Nginx 配置指令 |
配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org annotations: nginx.ingress.kubernetes.io/server-snippet: | location / { return 302 /coffee; } spec: rules: - host: web.nginxbar.org http: paths: - path: /tea backend: serviceName: tea-svc servicePort: 80 - path: /coffee backend: serviceName: coffee-svc servicePort: 80
4.2 通用配置
Nginx 虛擬主機中的通用配置。通用配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/enable-access-log | true 或 false | 對當前虛擬主機設置是否啟用訪問日志,默認為真 |
nginx.ingress.kubernetes.io/server-alias | string | 為 Nginx 添加更多的主機名,同 Nginx 配置指令 server name |
nginx.ingress.kubernetes.io/app-root | string | 將當前虛擬主機根目錄的訪問 302 跳轉到當前指定的路徑 |
nginx.ingress.kubernetes.io/client-body-buffer-size | string | 同 Nginx 配置指令 client_body_buffer_size |
nginx.ingress.kubernetes.io/use-regex | true 或 false | 是否對當前虛擬主機的 Nginx 指令 location 使用正則方式進行路徑匹配,默認值為 false |
nginx.ingress.kubernetes.io/custom-http-errors | []int | 根據響應碼狀態定義為錯誤狀態並跳轉到設置的默認后端 |
nginx.ingress.kubernetes.io/default-backend | string | 自定義默認后端的資源對象 Service 名稱,當客戶端的請求沒有匹配的 Nginx 規則或響應錯誤時,將被轉發到默認后端 |
nginx.ingress.kubernetes.io/whitelist-source-range | CIDR | 功能同 ConfigMap 配置鍵 whitelist-source-range |
nginx.ingress.kubernetes.io/permanent-redirect | string | 設置永久重定向的目標地址 |
nginx.ingress.kubernetes.io/permanent-redirect-code | number | 自定義永久重定向的響應碼,默認為 301 |
nginx.ingress.kubernetes.io/temporal-redirect | string | 設置臨時重定向的目標地址 |
nginx.ingress.kubernetes.io/from-to-www-redirect | true 或 false | 設置是否將當前虛擬主機子域名為 www 的請求跳轉到當前主機域名 |
nginx.ingress.kubernetes.io/rewrite-target | URI | 同 Nginx 配置指令 rewrite |
nginx.ingress.kubernetes.io/enable-rewrite-log | true 或 false | 同 Nginx 配置指令 rewrite log,默認為 false |
nginx.ingress.kubernetes.io/mirror-uri | string | 同 Nginx 配置指令 mirro |
nginx.ingress.kubernetes.io/mirror-request-body | true 或 false | 同 Nginx 配置指令 mirror_request_body,默認為 true |
配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org namespace: default annotations: nginx.ingress.kubernetes.io/rewrite-target: /tea/$1 nginx.ingress.kubernetes.io/enable-rewrite-log: "true" spec: rules: - host: web.nginxbar.org # 此service的訪問域名 http: paths: - backend: serviceName: nginx-web servicePort: 8080 path: /coffee/(.+)
4.3 訪問控制
用以設置基於流量、請求連接數、請求頻率的訪問控制。訪問控制配置說明如下表所示。
注解 | 類型/選項 | 功能描述 |
nginx.ingress.kubernetes.io/limit-rate | number | 訪問流量速度限制,同 Nginx 配置指令 limit_rate |
nginx.ingress.kubernetes.io/limit-rate-after | number | 啟用訪問流量速度限制的最大值,同 Nginx 配置指令 limit_rate_after |
nginx.ingress.kubernetes.io/limit-connections | number | 節並發連接數限制,同 Nginx 配置指令 limit_conn |
nginx.ingress.kubernetes.io/limit-rps | number | 每秒請求頻率限制,burst 參數為給定值的 5 倍,響應狀態碼由 ConfigMap 的 limit-req-status-code 設定 |
nginx.ingress.kubernetes.io/limit-rpm | number | 每分鍾請求頻率限制,burst 參數為給定值的 5 倍,響應狀態碼由 ConfigMap 的 limit-req-status-code 設定 |
nginx.ingress.kubernetes.io/limit-whitelist | CIDR | 對以上限制設置基於 IP 的白名單 |
4.4 認證管理
Nginx Ingress 提供了基本認證、摘要認證和外部認證 3 種方式,為被代理服務器提供認證支持。認證管理配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/enable-global-auth | true 或 false | 如果 ConfigMap 的 global-auth-url 被設置,Nginx 會將所有的請求重定向到提供身份驗證的 URL,默認為 true |
nginx.ingress.kubernetes.io/satisfy | string | 同 Nginx 配置指令 satisfy |
nginx.ingress.kubernetes.io/auth-type | basic 或 digest | 設置 HTTP 認證類型,支持基本和摘要兩種類型 |
nginx.ingress.kubernetes.io/auth-secret | string | 指定關聯資源對象 secret 的名稱 |
nginx.ingress.kubernetes.io/auth-realm | string | 設置基本認證的提示信息 auth_basic |
nginx.ingress.kubernetes.io/auth-url | string | 設置提供外部身份認證的 URL,由 Nginx 配置指令 auth_request 提供該功能 |
nginx.ingress.kubernetes.io/auth-signin | string | 設置當外部認證返回 401 時跳轉的 URL,通常為提示輸入用戶名和密碼的 URL |
nginx.ingress.kubernetes.io/auth-method | string | 指定訪問外部認證 URL 的 HTTP 方法,由 Nginx 配置指令 proxy_method 提供該功能 |
nginx.ingress.kubernetes.io/auth-request-redirect | string | 設置發送給認證服務器請求頭中 X-Auth-Request-Redirect 的值 |
nginx.ingress.kubernetes.io/auth-cache-key | string | 啟用認證緩存,並設置認證緩存的關鍵字 |
nginx.ingress.kubernetes.io/auth-cache-duration | string | 基於響應碼設置認證緩存的有效時間 |
nginx.ingress.kubernetes.io/auth-response-headers | string | 設置認證請求完成后傳遞到真實后端的頭信息 |
nginx.ingress.kubernetes.io/auth-snippet | string | 可以自定義在外部認證指令區域添加 Nginx 配置指令 |
基本認證配置如下:
# 創建基本認證用戶名nginxbar、密碼123456,輸出文件名必須是auth htpasswd -bc auth nginxbar 123456 # 創建資源對象secret保存賬號和密碼 kubectl create secret generic basic-auth --from-file=auth # 查看創建的basic-auth kubectl get secret basic-auth -o yaml # 創建基本認證的Ingress實例 cat>auth-nginxbar-org.yaml<<EOF apiVersion: extensions/v1beta1 kind: Ingress metadata: name: auth-nginxbar-org namespace: default annotations: # 設置認證類型 nginx.ingress.kubernetes.io/auth-type: basic # 關聯賬號和密碼 nginx.ingress.kubernetes.io/auth-secret: basic-auth # 顯示認證提示信息 nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required for web.nginxbar.org' spec: rules: - host: auth.nginxbar.org # 此service的訪問域名 http: paths: - backend: serviceName: nginx-web servicePort: 8080 EOF kubectl create -f auth-nginxbar-org.yaml
認證轉發配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: auth-nginxbar-org namespace: default annotations: nginx.ingress.kubernetes.io/auth-url: "http://$host/auth2" nginx.ingress.kubernetes.io/auth-signin: "http://$host/auth/start" nginx.ingress.kubernetes.io/auth-method: "POST" nginx.ingress.kubernetes.io/auth-cache-key: "foo", nginx.ingress.kubernetes.io/auth-cache-duration": "200 202 401 30m" nginx.ingress.kubernetes.io/auth-snippet: | proxy_set_header Foo-Header 42; spec: rules: - host: auth.nginxbar.org # 此service的訪問域名 http: paths: - backend: serviceName: nginx-web servicePort: 8080
4.5 跨域訪問
跨域訪問功能配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/enable-cors | true 或 false | 是否啟用跨域訪問支持,默認為 false |
nginx.ingress.kubernetes.io/cors-allow-origin | string | 允許跨域訪問的域名,默認為 *,表示接受任意域名的訪問 |
nginx.ingress.kubernetes.io/cors-allow-methods | string | 允許跨域訪問方法,默認為 GET、PUT、POST、DELETE、PATCH、OPTIONS |
nginx.ingress.kubernetes.io/cors-allow-headers | string | 允許跨域訪問的請求頭,默認為 DNT,X-CustomHeader、Keep-Alive、User-Agent、X-Requested-With、 If-Modified-Since、Cache-Control、Content-Type、Authorization |
nginx.ingress.kubernetes.io/cors-allow-credentials | true 或 false | 設置在響應頭中 Access-Control-Allow-Credentials 的值,設置是否允許客戶端攜帶驗證信息,如 cookie 等,默認為 true |
nginx.ingress.kubernetes.io/cors-max-age | number | 設置響應頭中 Access-Control-Max-Age 的值,設置返回結果可以用於緩存的最長時間,默認為 1728000 秒 |
配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org namespace: default annotations: nginx.ingress.kubernetes.io/cors-allow-headers: >- DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With, If-Modified-Since,Cache-Control,Content-Type,Authorization nginx.ingress.kubernetes.io/cors-allow-methods: 'PUT, GET, POST, OPTIONS' nginx.ingress.kubernetes.io/cors-allow-origin: '*' nginx.ingress.kubernetes.io/enable-cors: "true" nginx.ingress.kubernetes.io/cors-max-age: 600 spec: rules: - host: web.nginxbar.org http: paths: - backend: serviceName: nginx-web servicePort: 8080 path: /
4.6 代理配置
Nginx 代理相關功能配置說明如下表所示。
注解 | 類型/選項 | 功能描述 |
nginx.ingress.kubernetes.io/service-upstream | true 或 false | 默認 Nginx 以 Service 中 Pod 的 IP 和端口為 Upstream 中的成員列表,該參數為 true 時,將以 Service 的 ClusterIP 和端口為被代理入口, 該功能避免了因 Pod 漂移帶來的 Upstream 的配置變化 |
nginx.ingress.kubernetes.io/backend-protocol | http 或 HTTPS 或 GRPC 或 GRPCS 或 AJP 或 FCGI |
設置代理后端服務器的代理協議類型,默認為 HTTP |
nginx.ingress.kubernetes.io/proxy-body-size | string | 同 Nginx 配置指令 client_max_body-size,默認為 1m |
nginx.ingress.kubernetes.io/proxy-cookie-do-main | string | 同 Nginx 配置指令 proxy_cookie_domain |
nginx.ingress.kubernetes.io/proxy-cookie-path | string | 同 Nginx 配置指令 proxy_cookie_path |
nginx.ingress.kubernetes.io/proxy-connect-timeout | number | 同 Nginx 配置指令 proxy_connect_timeout |
nginx.ingress.kubernetes.io/proxy-send-time-out | number | 同 Nginx 配置指令 proxy_send_timeout |
nginx.ingress.kubernetes.io/proxy-read-time-out | number | 同 Nginx 配置指令 proxy_read_timeout |
nginx.ingress.kubernetes.io/proxy-next-up-stream | string | 同 Nginx 配置指令 proxy_next_upstream |
nginx.ingress.kubernetes.io/proxy-next-up-stream-timeout | number | 同 Nginx 配置指令 proxy_next_upstream_timeout |
nginx.ingress.kubernetes.io/proxy-next-up-stream-tries | number | 同 Nginx 配置指令 proxy_next_upstream_tries |
nginx.ingress.kubernetes.io/proxy-buffering | string | 同 Nginx 配置指令 proxy_buffering |
nginx.ingress.kubernetes.io/proxy-buffers-number | number | 同 Nginx 配置指令 proxy_buffers |
nginx.ingress.kubernetes.io/proxy-buffer-size | string | 同 Nginx 配置指令 proxy_buffer_size |
nginx.ingress.kubernetes.io/proxy-request-buffering | string | 同 Nginx 配置指令 proxy_request_buffering |
nginx.ingress.kubernetes.io/proxy-http-ver-sion | 1.0 或 1.1 | 同 Nginx 配置指令 proxy_http_version,默認為 1.1 |
nginx.ingress.kubernetes.io/upstream-vhost | string | 自定義發送到上游服務器的信息頭字段中 Host 的內容,相當於 Nginx 配置指令 proxy_set_header Host $host 的設置 |
nginx.ingress.kubernetes.io/proxy-redirect-from | string | 設置要替換的源文本,同 Nginx 配置指令 proxy_redirect |
nginx.ingress.kubernetes.io/proxy-redirect-to | string | 設置要替換的目標文本,同 Nginx 配置指 proxy redirect |
nginx.ingress.kubernetes.io/connection-proxy-header | string | 設置發送到被代理服務器請求頭中字段屬性 connection 的值,相當於 Nginx 配置指令 proxy_set_header Connection 的狀態為 Keep-Alive |
nginx.ingress.kubernetes.io/x-forwarded-prefix | string | 創建並設置代理請求頭屬性字段 X-Forwarded-Prefix 屬性,用以向后端傳遞請求路徑 |
nginx.ingress.kubernetes.io/http2-push-pre-load | true 或 false | 同 Nginx 配置指令 http2-push-preload,默認值為 false |
4.7 負載均衡
為方便上游服務器組的動態管理,Nginx Ingress 基於 Lua 實現了一致性哈希、基於子集的一致性哈希、輪詢調度及峰值指數加權移動平均(Peak Exponentially Weighted Moving-Average,Peak EWMA)負載均衡算法。負載均衡配置說明如下表所示。
注解 | 類型/選項 | 功能描述 |
nginx.ingress.kubernetes.io/upstream-hash-by | string | 同 Nginx 配置指令 hash,此處默認為一致性哈希負載算法, 允許除了客戶端 IP 或 cookie 之外的會話粘連 |
nginx.ingress.kubernetes.io/upstream-hash-by-subset | true 或 false | 設置是否使用子集模式的一致性哈希負載算法,默認為 false |
nginx.ingress.kubernetes.io/upstream-hash-by-subset-size | int | 設置子集模式中上游服務器分組的大小,默認為 3 |
nginx.ingress.kubernetes.io/load-balance | round_robin 或 ewma | 設置負載均衡算法,基於 balancer_by_lua 模塊實現, 支持輪詢和 Peak EWMA 兩種負載算法 |
子集模式的一致性哈希負載算法是將上游服務器組中的被代理服務器分成固定數量的分組,然后把每個分組當作一致性哈希計算的虛擬節點。默認一致性哈希是按照每個被代理服務器為虛擬節點進行計算的。
Peak EWMA 負載均衡算法,是對每個 Pod 請求的往返延時(Round-Trip Time,RTT)計算移動平均值,並用該 Pod 的未完成請求數對這個平均值加權計算,計算值最小的 Pod 端點將被分配新的請求。
4.8 會話保持配置
設置基於 cookie 的會話親緣關系,也就是會話保持功能。啟用基於 cookie 的會話保持功能時,可以使同一客戶端的請求始終轉發給同一后端服務器。Nginx Ingress 對啟用會話保持功能的 Service 集群使用一致性哈希負載算法,即使后端 Pod 數量變化,也不會對會話保持功能產生太大的影響。會話保持配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/affinity | cookie | 設置會話保持類型,目前只有 cookie 類型 |
nginx.ingress.kubernetes.io/session-cookie-name | string | 設置 cookie 名稱,默認為 INGRESSCOOKIE |
nginx.ingress.kubernetes.io/session-cookie-path | string | 設置 cookie 字段 path 的值,默認值為當前資源實例 path 的設置。如果啟用 use-regex 功能, 使用正則匹配時,必須單獨指定,不能使用默認值 |
nginx.ingress.kubernetes.io/session-cookie-max-age | -- | 設置 cookie 字段 max-age 的值,表示 cookie 過期時間 |
nginx.ingress.kubernetes.io/session-cookie-expires | -- | 為兼容舊的瀏覽器,設置 cookie 字段 expires 的值,表示 cookie 過期時間 |
nginx.ingress.kubernetes.io/session-cookie-change-on-failure | true 或 false | 當會話保持的被代理服務器請求失敗時,如果設置值為 true,則將下次請求更改為向另一台被代理服務器轉發, 否則繼續向當前被代理服務器轉發請求 |
配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org annotations: nginx.ingress.kubernetes.io/affinity: "cookie" nginx.ingress.kubernetes.io/session-cookie-name: "route" nginx.ingress.kubernetes.io/session-cookie-expires: "172800" nginx.ingress.kubernetes.io/session-cookie-max-age: "172800" spec: rules: - host: web.nginxbar.org http: paths: - backend: serviceName: nginx-web servicePort: 8080 path: /
4.9 HTTPS配置
HTTPS 功能的配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/force-ssl-redirect | true 或 false | 當客戶端的 HTTPS 被外部集群進行 SSL 卸載(SSL offloading)時,仍將 HTTP 的請求強制跳轉到 HTTPS 端口 |
nginx.ingress.kubernetes.io/ssl-redirect | true 或 false | 設置當前虛擬主機支持 HTTPS 請求時,是否將 HTTP 的請求強制跳轉到 HTTPS 端口,全局默認為 true |
nginx.ingress.kubernetes.io/ssl-passthrough | true 或 false | 設置是否啟用 SSL 透傳 |
nginx.ingress.kubernetes.io/auth-tls-secret | string | 設置客戶端證書的資源對象名稱 |
nginx.ingress.kubernetes.io/ssl-ciphers | string | 設置 TLS 用於協商使用的加密算法組合,同 Nginx 配置指令 ssl_ciphers |
nginx.ingress.kubernetes.io/auth-tls-verify-client | string | 是否啟用客戶端證書驗證,同 Nginx 配置指令 ssl_verify_client |
nginx.ingress.kubernetes.io/auth-tls-verify-depth | number | 客戶端證書鏈的驗證深度同 Nginx 配置指令 ssl_verify_depth |
nginx.ingress.kubernetes.io/auth-tls-error-page | string | 設置客戶端證書驗證錯誤時的跳轉頁面 |
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream | true 或 false | 指定證書是否傳遞到上游服務器 |
nginx.ingress.kubernetes.io/secure-verify-ca-secret | string | 設置是否啟用對被代理服務器的 SSL 證書驗證功能 |
HTTPS 配置樣例如下:
# 創建TLS證書 openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /data/apps/certs/dashboard.key -out /data/apps/certs/dashboard.crt -subj "/CN=dashboard.nginxbar.org/O=dashboard.nginxbar.org" kubectl -n kube-system create secret tls ingress-secret --key /data/apps/certs/dashboard.key --cert /data/apps/certs/dashboard.crt # 創建HTTPS服務 cat>dashboard-ingress.yaml<<EOF apiVersion: extensions/v1beta1 kind: Ingress metadata: name: dashboard-ingress namespace: kube-system annotations: nginx.ingress.kubernetes.io/ingress.class: nginx # 使用HTTPS協議代理后端服務器 nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" # 啟用SSL透傳 nginx.ingress.kubernetes.io/ssl-passthrough: "true" spec: tls: - hosts: - dashboard.nginxbar.org secretName: ingress-secret rules: - host: dashboard.nginxbar.org http: paths: - path: / backend: serviceName: kubernetes-dashboard servicePort: 443 EOF kubectl create -f dashboard-ingress.yaml curl -k -H "Host:dashboard.nginxbar.org" https://10.103.196.209
Nginx-ingress 在用戶沒有提供證書的情況下會提供一個內置的默認 TLS 證書,如果 secretName 參數沒有配置或配置錯誤,Nginx 會使用系統默認的證書,所以配置后仍需檢查確認。
HTTPS 客戶端證書身份認證配置樣例如下:
# 創建客戶端證書資源對象default/ca-secret apiVersion: extensions/v1beta1 kind: Ingress metadata: annotations: # 啟用客戶端證書驗證 nginx.ingress.kubernetes.io/auth-tls-verify-client: "on" # 綁定客戶端證書的資源對象名稱,是命名空間default的ca-secret nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret" # 客戶端證書鏈的驗證深度為1 nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1" # 設置客戶端證書驗證錯誤時的跳轉頁面 nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html" # 指定證書傳遞到上游服務器 nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true" name: nginx-test namespace: default spec: rules: - host: mydomain.com http: paths: - backend: serviceName: http-svc servicePort: 80 path: / tls: - hosts: - mydomain.com secretName: tls-secret
4.10 “金絲雀”發布
“金絲雀”發布又稱為灰度發布,灰度發布功能可以將用戶請求按照指定的策略進行分割,並轉發到不同的代理服務器組,通過不同的代理服務器部署應用不同版本可進行對照比較,因該方式對於新版本而言類似於使用“金絲雀”的方式進行測試,所以也叫“金絲雀”發布。
Nginx Ingress 支持 Header、cookie 和權重 3 種方式,可單獨使用,也可以組合使用。“金絲雀”發布配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/canary | true 或 false | 啟用“金絲雀”發布功能 |
nginx.ingress.kubernetes.io/canary-by-header | string | 設置請求頭屬性字段的名稱,用於根據該字段的值判斷是否將請求路由到“金絲雀”服務器組,該字段值為 always 時則該請求被路由到“金絲雀”服務器組; 該字段值為 never 時則不路由到“金絲雀”服務器組 |
nginx.ingress.kubernetes.io/canary-by-header-value | string | 自定義用於判斷是否路由到“金絲雀”服務器組的請求頭字段值,默認為 always,必須與 canary-by-header同時使用 |
nginx.ingress.kubernetes.io/canary-by-cookie | string | 設置 cookie 的字段名稱,用於根據該字段的值判斷是否將請求路由到“金絲雀”服務器組。always 則路由到“金絲雀”服務器組; never 則永遠不路由到“金絲雀”服務器組 |
nginx.ingress.kubernetes.io/canary-weight | number | 將請求基於整數(0~100)的請求百分比隨機路由到“金絲雀”服務器組;100 表示所有請求都路由到“金絲雀”服務器組; 0 表示不路由任何請求到“金絲雀”服務器組 |
“金絲雀”路由規則同時存在時的優先順序是 canary-by-header、canary-by-cookie、canary-weight。
配置樣例如下:
# 創建主機web.nginxbar.org的Ingress資源配置 apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org namespace: default annotations: nginx.ingress.kubernetes.io/ingress.class: "nginx" spec: rules: - host: web.nginxbar.org # 此service的訪問域名 http: paths: - backend: serviceName: nginx-web servicePort: 8080 # 創建主機web.nginxbar.org金絲雀組的Ingress資源配置 apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org-canary namespace: default annotations: nginx.ingress.kubernetes.io/ingress.class: "nginx" nginx.ingress.kubernetes.io/canary: "true", # 根據請求頭字段CanaryByHeader的值進行判斷 nginx.ingress.kubernetes.io/canary-by-header: "CanaryByHeader", # 請求頭字段CanaryByHeader的值為DoCanary時,路由到“金絲雀”服務器組 nginx.ingress.kubernetes.io/canary-by-header-value: "DoCanary", # 根據Cookie字段CanaryByCookie的值進行判斷 nginx.ingress.kubernetes.io/canary-by-cookie: "CanaryByCookie", # 隨機10%的請求路由到“金絲雀”服務器組 nginx.ingress.kubernetes.io/canary-weight: "10", spec: rules: - host: web.nginxbar.org # 此service的訪問域名 http: paths: - backend: serviceName: nginx-web-canary servicePort: 8080
4.11 lua-resty-waf模塊
lua-resty-waf 是一個基於 OpenResty 的高性能 Web 應用防火牆,對當前虛擬主機的訪問可以按照相關防火牆規則進行訪問過濾。模塊配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/lua-resty-waf | string | 設置 WAF 防火牆的工作模式,inactive 表示不執行任何操作;active 表示啟用:simulate 模式下, 如果給定請求有匹配的規則,它將記錄一條警告消息而不進行處理。這有助於在完全部署規則之前調試規則並消除可能的誤報 |
nginx.ingress.kubernetes.io/lua-resty-waf-debug | true 或 false | 設置是否啟用調試功能,默認值為 false |
nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets | string | 設置忽略規則集的名稱,當某些規則集(如 sqli 或 xss crs 規則集)太容易誤報或不適用時,可通過該設置進行忽略處理 |
nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules | string | 設置自定義的規則 |
nginx.ingress.kubernetes.io/lua-resty-waf-allow-unknown-content-types | true 或 false | 設置在發送了不在允許內容類型表中的內容類型頭時是否繼續處理請求。默認允許的為 text/html、text/json、 application/json 的文檔類型,默認值為 false |
nginx.ingress.kubernetes.io/lua-resty-waf-score-threshold | number | 設置請求異常評分的閾值,如果超過這個閾值,則拒絕該請求,默認值為 5 |
nginx.ingress.kubernetes.io/lua-resty-waf-process-multipart-body | true 或 false | 設置是否使用 lua-resty-upload 模塊對 multipart/form-data 類型請求體的處理,默認為 true |
4.12 ModSecurity模塊配置
ModSecurity 是一個開源的 Web 應用防火牆。必須首先通過在 ConfigMap 中啟用 Mod-Security 來加載 ModSecurity 模塊。這將為所有路徑啟用 ModSecurity 過濾,可以手動在 Ingress 資源實例中禁用此功能。ModSecurity 模塊配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/enable-mod-security | bool | 設置是否啟用 ModSecurity 過濾,啟用時應用推薦的規則以僅檢測(Detection-Only)模式運行 |
nginx.ingress.kubernetes.io/enable-owasp-core-rules | bool | 設置是否使用 OWASP 核心規則進行請求檢測 |
nginx.ingress.kubernetes.io/modsecurity-transaction-id | string | 設置從 Nginx 傳遞事務 ID,而不是在庫中自動生成,有利於在 ModSecurity 中跟蹤查看檢測的請求, 對應模塊配置指令為 modsecurity_transaction_id |
nginx.ingress.kubernetes.io/modsecurity-snippet | string | 添加模塊配置指令 modsecurity_rules 的內容 |
配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org annotations: nginx.ingress.kubernetes.io/enable-modsecurity: "true" nginx.ingress.kubernetes.io/enable-owasp-core-rules: "true" nginx.ingress.kubernetes.io/modsecurity-transaction-id: "$request_id" nginx.ingress.kubernetes.io/modsecurity-snippet: | SecRuleEngine On SecDebugLog /tmp/modsec_debug.log spec: rules: - host: web.nginxbar.org http: paths: - backend: serviceName: nginx-web servicePort: 8080 path: /
4.13 Influxdb模塊配置
通過使用 Nginx Influxdb 模塊,可以用 UDP 協議將請求記錄實時發送到后端的 Influxdb 服務器。Influxdb 模塊配置說明如下表所示。
注解 | 類型 | 功能描述 |
nginx.ingress.kubernetes.io/enable-influxdb | true 或 false | 是否啟用 Influxdb 輸出功能 |
nginx.ingress.kubernetes.io/influxdb-measurement | string | 指定 Influxdb 中的 measurement 名稱 |
nginx.ingress.kubernetes.io/influxdb-port | string | 指定 Influxdb 的端口 |
nginx.ingress.kubernetes.io/influxdb-host | string | 指定 Influxdb 的 IP 地址 |
nginx.ingress.kubernetes.io/influxdb-server-name | string | 設置自己的應用標識 |
配置樣例如下:
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: web-nginxbar-org annotations: nginx.ingress.kubernetes.io/enable-influxdb: "true" nginx.ingress.kubernetes.io/influxdb-measurement: "nginxbar-reqs" nginx.ingress.kubernetes.io/influxdb-port: "8089" nginx.ingress.kubernetes.io/influxdb-host: "192.168.2.110" nginx.ingress.kubernetes.io/influxdb-server-name: "nginxbar-com" spec: rules: - host: web.nginxbar.org http: paths: - backend: serviceName: nginx-web servicePort: 8080 path: /
5.參考
Ingress配置參考:https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md
Ingress注釋參考https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/annotations.md