升级Nginx Ingress Controller组件

前置检查表

升级兼容性说明

在组件的开发和维护过程中，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会重启，建议您在业务低峰期进行相关操作。