前置檢查表

升級兼容性說明

在組件的開發和維護過程中，Nginx Ingress Controller組件的新版本可能會引入新的功能、改進現有功能或者修復安全問題，但同時也可能因為內部架構的調整、依賴庫的變化等原因，導致與之前版本存在兼容性差異。關于Nginx Ingress Controller的變更記錄，請參見Nginx Ingress Controller。

snippet注解默認禁用

影響版本：v1.9.3-aliyun.1以下（不包括v1.9.3-aliyun.1）。

由于安全原因，自v1.9.3-aliyun.1版本起，Nginx Ingress Controller將默認禁用所有snippet注解，可能包括：

• nginx.ingress.kubernetes.io/configuration-snippet

• nginx.ingress.kubernetes.io/server-snippet

• nginx.ingress.kubernetes.io/stream-snippet

• nginx.ingress.kubernetes.io/auth-snippet

• nginx.ingress.kubernetes.io/modsecurity-snippet

出于安全和穩定性風險的考慮，建議您優先使用相關注解或者設置項來實現所需功能。

如您仍需要使用snippet注解能力，請在充分評估風險后，通過在ConfigMapkube-system/nginx-configuration中添加allow-snippet-annotations: "true"手動開啟注解功能。

不支持較低版本的TLS

影響版本：v1.7.0-aliyun.1以下（不包括v1.7.0-aliyun.1）。

由于TLS1.1及以下版本存在安全問題，Nginx Ingress Controller新版本不再默認支持TLS v1.1和TLS v1.0的加密方式。因此，在升級前，請確保您的業務不依賴v1.1及以下版本的TLS，并且在配置中將其移除。修改ConfigMap后會立即生效。

例如，若Nginx Ingress Controller組件的ConfigMap（kube-system/nginx-configuration）配置如下所示：

ssl-protocols: SSLv3 SSLv2 TLSv1 TLSv1.1 TLSv1.2 TLSv1.3

您需要在確認業務不受影響后，可直接將該行設置移除，使用默認選項；或者選擇移除SSLv3、SSLv2、TLSv1、TLSv1.1四項，改為：

ssl-protocols: TLSv1.2 TLSv1.3

若您需要強制使用舊版本的TLS加密方式，請參見Ingress支持哪些SSL/TLS版本？進行配置。

nginx.ingress.kubernetes.io/rewrite-target用法不兼容

影響版本：0.22.0以下（不包括0.22.0）。

• 0.22.0版本對nginx.ingress.kubernetes.io/rewrite-target注解的用法做了修改。在0.22.0及以上版本，使用rewrite-target時，需要顯式指定捕獲組的使用。

• 0.22.0版本以下的rewrite-target特性和最新版本的rewrite-target特性不兼容，在組件升級前，可以使用configuration-snippet代替rewrite-target注解。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      - path: /something/
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      - path: /something123/
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # 使用rewrite指令，/something為path中路徑（不包含尾部的斜杠）。
    # Ingress中包含多個路徑，需要添加多條rewrite指令。
    nginx.ingress.kubernetes.io/configuration-snippet: |
      rewrite "(?i)/something(/|$)(.*)" /$2 break;
      rewrite "(?i)/something123(/|$)(.*)" /$2 break;
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      - path: /something/ # 和舊版本Ingress資源的路徑保持一致。
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      - path: /something123/ # 和舊版本Ingress資源的路徑保持一致。
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # 引用匹配的內容。
    nginx.ingress.kubernetes.io/rewrite-target: /$2
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      # 使用捕獲組。
      - path: /something(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port:
              number: 80
      # 使用捕獲組。
      - path: /something123(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: http-svc-1
            port:
              number: 80

驗證階段說明

驗證組件及業務狀態

除自身所擁有的業務監控能力外，ACK也提供了SLS日志、阿里云Prometheus大盤和容器自身的日志來觀測Nginx Ingress Controller的運行狀態。開啟上述服務，請參見Nginx Ingress訪問日志分析與監控和使用阿里云Prometheus監控。

升級注意事項

在低版本的Nginx Ingress Controller升級到高版本時，由于高版本在前綴匹配邏輯上有所變化，需要關注路徑path配置與實際請求URL的是否一致，否則可能會導致原本正常的請求出現404錯誤。

已知問題

在Nginx Ingress Controller的不同版本中，前綴匹配邏輯可能存在差異，這可能導致服務訪問問題。

• 在低版本（v0.44之前）的Nginx Ingress Controller中，前綴匹配的規則較為寬松，允許如/aaa/bbb的配置，可以匹配請求的URL/aaa/bbbbb。

• 升級到高版本后，前綴匹配的邏輯可能會變得更加嚴格，只匹配精確的請求路徑，這可能導致原本應匹配的路徑/aaa/bbbbb不再匹配，從而引發404錯誤。

影響范圍

受影響的版本為Nginx Ingress版本低于v0.44。關于Nginx Ingress Controller版本記錄，請參見Nginx Ingress Controller。相關PR信息請參見kubernetes/ingress-nginx #6443。

示例配置

您可以根據以下的YAML配置比較低版本（如v0.22.0.5-552e0db-aliyun）和高版本（如v1.2.1-aliyun.1+）渲染出Nginx配置之間的差異。

  apiVersion: extensions/v1beta1
  kind: Ingress
  metadata:
    labels:
      ingress-controller: nginx
    name: test
    namespace: default
  spec:
    ingressClassName: nginx
    rules:
    - host: www.example.com
      http:
        paths:
        - backend:
            service:
              name: api-resources-svc
              port:
                number: 8080
          path: /api/resource

• 低版本行為

  在低版本Nginx Ingress（如v0.22.0.5-552e0db-aliyun）中，對應的Nginx配置：

  Location /api/resource   ## 沒有結尾的 "/"

  在上面的配置中，使用的路徑/api/resource在低版本Nginx中允許通過http://www.example.com/api/resources進行訪問。

  說明

  實際訪問路徑是resources而不是resource。

• 高版本行為

  若將Nginx Ingress Controller升級到高版本（如v1.2.1-aliyun.1+），對應的Nginx配置：

  Location /api/resource/  # 增加了結尾的 "/"
  {
  }
  ...
  Location = /api/resource  # 增加了一個 Location 進行精確匹配
  {
  }

  訪問http://www.example.com/api/resources將返回404錯誤。

常見問題

Nginx Ingress Controller是否支持升級至指定的版本？升級成功后，還能回退到之前的某個版本嗎？

Nginx Ingress Controller組件不支持升級到指定版本，采用分階段的形式進行升級，直至將組件升級到最新的版本。升級成功后無法回退。

驗證和發布階段Pod擴容失敗怎么辦？

Deployment模板檢查不通過怎么辦？

如果在前置檢查過程中，您的Deployment模板檢查不通過，請單擊異常原因右側的鏈接，進入組件差異展示頁面，查看檢查不通過的字段。

1. 在Nginx Ingress Controller 組件升級頁面的前置檢查下方，單擊查看詳情。

2. 在檢查報告頁面的集群組件檢查結果區域，單擊①處的紅色方框查看檢查結果，然后在檢查結果頁面單擊Deployment 模板，最后單擊②處異常原因右側的鏈接。

   

3. 進入組件差異展示頁面，查看檢查不通過的字段。

   在組件差異頁面，會展示出該版本組件的標準模板（左側）和當前集群中的組件模板（右側）的對比展示。組件差異頁面會標出兩者之間的全部差異，包括兼容和不兼容的字段，并在差異展示的下方標出集群中組件是否通過差異檢查，以及不兼容的差異字段的具體路徑。

   如下圖所示，下方提示存在一處差異，差異字段為.spec.template.spec.containers.(nginx-ingress-controller).args（括號中的內容為數組中元素的name字段）。通過組件差異對比，發現args中--v=2被修改為了--v=3，需要在升級前進行修正。

   

4. 修改差異字段。

   選擇工作負載>無狀態，找到Nginx Ingress Controller組件，單擊更多>查看YAML，在編輯YAML頁面中將args字段中的--v=3修改為--v=2。

5. 將差異字段修改后，您也可以重新進入或刷新組件差異展示頁面，查看最新的對比結果。當頁面底部提示組件可通過差異檢測時，即可通過Deployment模板檢查點。

   說明

   修改集群內Deployment過程中，Nginx Ingress Controller Pod會重啟，建議您在業務低峰期進行相關操作。