前置檢查表

升級兼容性說明

在組件的開發(fā)和維護(hù)過程中，Nginx Ingress Controller組件的新版本可能會引入新的功能、改進(jìn)現(xiàn)有功能或者修復(fù)安全問題，但同時也可能因為內(nèi)部架構(gòu)的調(diào)整、依賴庫的變化等原因，導(dǎo)致與之前版本存在兼容性差異。關(guān)于Nginx Ingress Controller的變更記錄，請參見Nginx Ingress Controller。

snippet注解默認(rèn)禁用

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

由于安全原因，自v1.9.3-aliyun.1版本起，Nginx Ingress Controller將默認(rèn)禁用所有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

出于安全和穩(wěn)定性風(fēng)險的考慮，建議您優(yōu)先使用相關(guān)注解或者設(shè)置項來實現(xiàn)所需功能。

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

不支持較低版本的TLS

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

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

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

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

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

ssl-protocols: TLSv1.2 TLSv1.3

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

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:
    # 引用匹配的內(nèi)容。
    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

驗證階段說明

驗證組件及業(yè)務(wù)狀態(tài)

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

升級注意事項

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

已知問題

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

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

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

影響范圍

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

示例配置

您可以根據(jù)以下的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）中，對應(yīng)的Nginx配置：

  Location /api/resource   ## 沒有結(jié)尾的 "/"

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

  說明

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

• 高版本行為

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

  Location /api/resource/  # 增加了結(jié)尾的 "/"
  {
  }
  ...
  Location = /api/resource  # 增加了一個 Location 進(jìn)行精確匹配
  {
  }

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

常見問題

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

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

驗證和發(fā)布階段Pod擴(kuò)容失敗怎么辦？

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

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

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

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

   

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

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

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

   

4. 修改差異字段。

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

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

   說明

   修改集群內(nèi)Deployment過程中，Nginx Ingress Controller Pod會重啟，建議您在業(yè)務(wù)低峰期進(jìn)行相關(guān)操作。