Container Service for Kubernetes：Nginx Ingress配置詞典

索引

ConfigMap預設配置說明

您可以通過kubectl edit cm -n kube-system nginx-configuration命令，對ConfigMap進行編輯。以下是ConfigMap預設配置和說明。更多配置資訊請參見官方文檔。

apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-configuration
 namespace: <Namespace>  # 預設為kube-system
 labels:
   app: ingress-nginx
data:
   log-format-upstream: '$remote_addr - [$remote_addr] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id $host [$proxy_alternative_upstream_name]'
   proxy-body-size: 20m
   proxy-connect-timeout: "10"
   max-worker-connections: "65536"
   enable-underscores-in-headers: "true"
   reuse-port: "true"
   worker-cpu-affinity: "auto"
   server-tokens: "false"
   ssl-redirect: "false"
   allow-backend-server-header: "true"
   ignore-invalid-headers: "true"
   generate-request-id: "true"
   upstream-keepalive-timeout: "900"

以下是配置項說明。

Ingress支援Annotation

在使用Nginx Ingress Controller時，可以根據應用的具體需求來調整其配置。您可以通過添加註釋（Annotations）來改變 Nginx的行為。以下是常用的注釋配置。如需瞭解更多注釋請參見Nginx Ingress Annotation。

負載平衡演算法

Nginx Ingress提供多種負載平衡演算法來最佳化後端服務的流量分發。根據應用程式的特點和需求，您可以選擇不同的負載平衡策略。

以下是一致性Hash負載平衡配置YAML樣本。

apiVersion: networking.k8s.io/v1
kind: Ingress 
metadata: 
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # 根據請求的URI進行hash。
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              service:
                name: <YOUR_SERVICE_NAME>  #替換為您的目標服務名稱
                port:
                  number: <YOUR_SERVICE_PORT>  #替換為您的目標服務連接埠
            property:
              ingress.beta.kubernetes.io/url-match-mode: STARTS_WITH
            pathType: ImplementationSpecific
  ingressClassName: nginx

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # 根據請求的URI進行hash。
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              serviceName: <YOUR_SERVICE_NAME>  #替換為您的目標服務名稱
              servicePort: <YOUR_SERVICE_PORT>  #替換為您的目標服務連接埠

Cookie親和性

以下是基於Cookie的會話親和性的注釋和說明。

以下是配置Cookie親和性注釋YAML樣本。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
  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:
  ingressClassName: nginx
  rules:
  - host: stickyingress.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port: 
              number: 80

重新導向

以下是Nginx Ingress重新導向注釋。

以下是永久重新導向的目標URL配置樣本，展示如何通過Ingress規則將訪問foo.com的請求重新導向至bar.com。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/permanent-redirect: "https://bar.com"
spec:
  ingressClassName: nginx
  rules:
  - host: foo.com
    http:
      paths:
      - path: "/"
        pathType: ImplementationSpecific
        backend:
         service:
            name: httpbin
            port:
              number: 8000

Rewrite重寫

以下是Nginx Ingress重寫Rewrite注釋。

以下是Rewrite重寫Host配置樣本，將請求example.com/test在轉寄至後端服務之前，重寫為test.com/test。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
  name: demo
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: ImplementationSpecific

限流

為了確保服務的穩定性，可以通過配置限流策略來控制每個用戶端IP的請求頻率和並發串連數。以下是相關的註解及其說明：

以下是限流配置樣本。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/limit-rate: "100K"
    nginx.ingress.kubernetes.io/limit-whitelist: "10.1.10.100"
    nginx.ingress.kubernetes.io/limit-rps: "1"
    nginx.ingress.kubernetes.io/limit-rpm: "30"
spec:
  rules:
  - host: iphone.example.com 
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: iphone-backend-svc
            port:
              number: 80

容災

為了確保服務的高可用性和穩定性，Nginx Ingress提供了容災（Fallback）機制，以處理服務節點不可用或特定錯誤響應的情況。以下是關於相關註解的說明：

灰階發布

灰階發布和藍綠髮布是廣泛採用的策略，以確保應用的平滑升級和高可用性。通過以下注釋配置可以實現靈活的流量管理，從而滿足不同發布需求。更多詳情請參見通過Nginx Ingress實現灰階發布和藍綠髮布。

逾時相關配置

以下是Ingress Nginx的逾時配置選項，包括全域逾時配置和特定資源的自訂逾時設定。使用合適的配置可以最佳化串連效能和可靠性。

• 全域逾時配置

  通過kubectl edit cm -n kube-system nginx-configuration命令，編輯以下配置項配置全域逾時。

  配置項	描述	取實值型別	預設值
  nginx.ingress.kubernetes.io/proxy-connect-timeout	設定與Proxy 伺服器建立串連的逾時時間，單位為秒（s）。	int	nginx.ingress.kubernetes.io/proxy-connect-timeout: "5" 建議不超過75
  nginx.ingress.kubernetes.io/proxy-read-timeout	設定從Proxy 伺服器讀取響應的逾時。該逾時僅在兩個連續的讀取操作之間設定，而不是為整個響應的傳輸設定，單位為秒（s）。	int	nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-send-timeout	設定向Proxy 伺服器傳輸請求的逾時。該逾時只在兩個連續的寫操作之間設定，而不是為整個請求的傳輸設定，單位為秒（s）。	int	nginx.ingress.kubernetes.io/proxy-send-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-stream-next-upstream-timeout	限制允許將串連傳遞到下一個伺服器的時間，設定為0s則關閉此限制。	string	nginx.ingress.kubernetes.io/proxy-stream-next-upstream-timeout: "600s"
  nginx.ingress.kubernetes.io/proxy-stream-timeout	設定用戶端或Proxy 伺服器串連上兩個連續的讀或寫操作之間的逾時時間。如果在這個時間內沒有資料轉送，串連就會關閉。	string	nginx.ingress.kubernetes.io/proxy-stream-timeout: "600s"
  nginx.ingress.kubernetes.io/upstream-keepalive-timeout	設定一個逾時時間，在這個時間內，與上遊伺服器的空閑串連將保持開放，單位為秒（s）。	int	nginx.ingress.kubernetes.io/upstream-keepalive-timeout: "900"
  nginx.ingress.kubernetes.io/worker-shutdown-timeout	設定優雅停機的逾時時間。	string	nginx.ingress.kubernetes.io/worker-shutdown-timeout: "240s"
  nginx.ingress.kubernetes.io/proxy-protocol-header-timeout	設定接收代理協議標頭檔的逾時值。預設的5秒可以防止TLS直通處理常式無限期地等待一個中斷的串連。	string	nginx.ingress.kubernetes.io/proxy-protocol-header-timeout: "5s"
  nginx.ingress.kubernetes.io/ssl-session-timeout	設定 SSL 會話緩衝中的會話參數的有效時間。會話到期時間是相對於建立時間而言的。每個會話緩衝會佔用大約0.25MB的空間。	string	nginx.ingress.kubernetes.io/ssl-session-timeout: "10m"
  nginx.ingress.kubernetes.io/client-body-timeout	定義讀取用戶端請求本文的逾時，單位為秒（s）。	int	nginx.ingress.kubernetes.io/client-body-timeout: "60"
  nginx.ingress.kubernetes.io/client-header-timeout	定義讀取用戶端要求標頭的逾時，單位為秒（s）。	int	nginx.ingress.kubernetes.io/client-header-timeout: "60"

• 特定資源自訂逾時配置

  以下是特定資源自訂逾時配置注釋，以及相關的參數配置。

  配置項	描述
  nginx.ingress.kubernetes.io/proxy-connect-timeout	設定代理連線逾時時間。
  nginx.ingress.kubernetes.io/proxy-send-timeout	設定代理髮送逾時時間。
  nginx.ingress.kubernetes.io/proxy-read-timeout	設定代理讀取逾時時間。
  nginx.ingress.kubernetes.io/proxy-request-buffering	是否啟用請求緩衝功能。 on啟用請求緩衝。如果啟用了請求緩衝功能，則會在接收到完整的請求資料之後才將其轉寄到後端工作負載，否則可能會在接收到部分請求資料時就開始轉寄請求。HTTP/1.1 Chunked編碼的請求不受此參數限制，始終會進行緩衝。 off則禁用請求緩衝。如果禁用，發送過程中出現發送錯誤，就不會選擇下一個工作負載進行重試。

跨域

在Nginx Ingress 控制器中設定跨域資源共用（CORS）可以協助你控制何種資源可以被跨域訪問。更多詳情請參見Nginx Ingress跨網域設定

重試邏輯

以下用於配置請求重試邏輯的註解。配置這些註解可以協助提升服務的高可用性和容錯能力。

IP存取控制

通過以下註解配置Nginx Ingress中的IP黑白名單。

以下是配置IP白名單注釋樣本。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/whitelist-source-range: "10.1.10.2"
spec:
  rules:
  - host: iphone.exmaple.com 
    http:
      paths:
      - path: /
        pathType: Prefix 
        backend:backend:
          service:
            name: iphone-example-svc
            port:
              number: 80

您還可以使用命令kubectl edit cm -n kube-system nginx-configuration通過編輯配置中的whitelist-source-range 來進行全域設定。

流量鏡像

通過配置以下注釋，您可以實現對應用的流量複製。可以在不影響生產環境的情況下協助您識別潛在的問題，提高應用的穩定性。配置詳情參見通過Nginx Ingress實現應用流量複製。

安全防護

為了在用戶端與網關之間的通訊中提供更高的安全性，以下註解可以加強通訊加密。更多詳情請參見Nginx Ingress Controller安全加密。

• 用戶端與網關之間的通訊加密

  通過以下註解來加強用戶端與網關之間的通訊安全性。

  註解	範圍	描述
  nginx.ingress.kubernetes.io/ssl-cipher	網域名稱	指定TLS的加密套件，可以指定多個（TLS的加密套件之間使用英文冒號分隔），僅當TLS握手時採用TLSv1.0-1.2生效。預設加密套件如下： ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES128-SHA AES128-GCM-SHA256 AES128-SHA ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-RSA-AES256-SHA AES256-GCM-SHA384 AES256-SHA
  nginx.ingress.kubernetes.io/auth-tls-secret	網域名稱	網關使用的CA認證，用於驗證mTLS握手期間，用戶端提供的認證。該註解主要應用於網關需要驗證用戶端身份的情境。 對應的Secret中必須包含一個名為ca.crt的檔案。ca.crt檔案應包含完整的憑證授權單位鏈。

• 網關與後端服務之間通訊加密

  通過以下註解來加強網關與後端服務之間的通訊安全性。

  註解	範圍	描述
  nginx.ingress.kubernetes.io/proxy-ssl-secret	服務	網關使用的用戶端認證，用於後端服務對網關進行身份認證。 該配置必須使用PEM格式的認證。 Secret中必須包含以下檔案： tls.crt: 用戶端認證。 tls.key: 用戶端認證的密鑰。 ca.crt: 信任的CA認證，用於驗證代理HTTPS伺服器的認證。 注釋的取值格式必須為"namespace/secretName"。
  nginx.ingress.kubernetes.io/proxy-ssl-name	服務	TLS握手期間使用的SNI。
  nginx.ingress.kubernetes.io/proxy-ssl-server-name	服務	開啟或關閉在TLS握手期間使用SNI。

安全認證

以下是有關Basic認證的注釋，確保只有授權使用者才能訪問應用程式介面。

配置樣本：

1. 使用htpasswd命令列工具產生密碼檔案。

   htpasswd -c auth joker

   查看產生的密碼檔案。

   cat auth 
   # 輸出樣本： joker:$apr1$R.G4krs/$hh0mX8xe4A3lYKMjvlVs1/

2. 將產生的密碼檔案建立為Secret：

   kubectl create secret generic basic-auth --from-file=auth 

3. 在Ingress資源中應用Basic認證，配置樣本如下：

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-nginx
     annotations:
       kubernetes.io/ingress.class: "nginx"
       nginx.ingress.kubernetes.io/auth-type: basic
       nginx.ingress.kubernetes.io/auth-secret: basic-auth      
   spec:
     rules:
     - host: iphone.exmaple.com 
       http:
         paths:
         - path: /
           pathType: Prefix 
           backend:backend:
             service:
               name: iphone-backend-svc
               port:
                 number: 80