升级Nginx Ingress Controller组件

功能原理

分阶段升级

Nginx Ingress Controller作为数据面的关键组件，对稳定性有较高要求。

由于新版本对Nginx Ingress Controller所做的自定义修改较多以及升级版本跨度较大，可能会导致部分配置不兼容。而且版本跨度大引起的配置不兼容，可能不会在升级后立即暴露出来，因此，一次性将组件升级到最新版本的风险较高。

为了确保升级Nginx Ingress Controller后组件以及业务的正常运行，升级将采用分阶段的形式进行。升级期间，可以对业务状况进行检查，有问题也能够及时回滚。

升级流程

第一部分：前置检查

前置检查将会在组件升级开始之前自动进行，以检查组件当前状态是否满足升级条件。如果组件存在不满足升级条件的设置，或者处于不健康状态时，将无法通过健康检查，在完成问题手动修复之前，无法继续进行升级。

组件前置检查，请参见常见问题中的“前置检查说明”。

第二部分：验证阶段

验证阶段会扩容出1个新版本组件的Pod，用于对新版本组件运行状态以及Ingress规则是否符合预期做验证。扩容成功后，一部分流量将会进入该Pod，此时可以通过容器日志、SLS日志服务或阿里云Prometheus监控服务来查看流量是否有异常。

验证Pod扩容成功后，升级流程会被暂停。在确认组件和业务无异常后，即可手动确认继续进行下一阶段。若此时出现问题，也可以选择回滚，删除新版本Pod，终止升级流程。

该步是通过修改Deployment中的spec.minReadySeconds和spec.strategy字段实现的。

第三部分：发布阶段

发布阶段将会进行完整的滚动升级流程，将旧版本组件完全替换为新版本。在所有Pod更新完成后，升级流程会暂停，此时可以对组件和业务做最终的确认。当确认无误后，升级结束。若此时出现问题，也可以选择回滚，将所有Pod重置回旧版本，并结束升级流程。

第四部分：回滚

在验证阶段或者发布阶段后的暂停过程中，如果发现组件或业务出现异常，可以通过回滚来将组件恢复到升级前的初始阶段。

升级前注意事项

• 在组件升级过程中，请勿对组件以及Ingress规则进行任何修改和操作，以免影响到升级的正常进行。
• 在组件升级前，请确保拥有对业务流量的监控手段，以便能够在出现问题时及时发现。可以通过SLS日志服务或阿里云Prometheus服务来查看业务流量状况。以上两种观测手段的配置，请参见Nginx Ingress访问日志分析与监控和阿里云Prometheus监控。
• 请确认目前组件健康状态正常，Pod均为Ready状态，没有错误日志。
• 请确认没有使用HPA等自动扩缩容规则。
• 请确认LoadBalancer Service状态正常，没有异常事件透出。

操作步骤

1. 登录容器服务管理控制台，在左侧导航栏选择集群。
2. 在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择运维管理 > 组件管理。
3. 在组件管理页面，找到Nginx Ingress Controller组件，单击组件右下方的升级。
4. 在弹出的升级界面中，单击开始并确认，开始升级流程。
   说明 您可以在升级过程中的任何时候退出该页面，然后通过单击组件管理中的升级进度重新回到流程中。
5. 流程第一阶段需要进行前置检查。在完成前置检查后，流程会自动进入下一阶段。
   若前置检查不通过，可以通过前置检查下的查看详情跳转到检查报告页面。然后根据未通过的检查点排查问题，详细信息，请参见前置检查说明。问题解决后，可以单击重试以重新开始升级流程。
6. 验证阶段完成后，升级流程进入暂停状态。此时，需要对组件运行状态和业务状态进行验证。关于验证方法，请参见常见问题中的“验证组件及业务状态”。
   • 若出现扩容不成功的情况，请参见常见问题中的“验证和发布阶段Pod扩容失败常见原因”。也可以在集群中查看Pod启动失败的具体原因，并在解决之后单击重试，重试该阶段。
   • 若验证业务出现问题，可以通过单击回滚进行回滚操作。回滚完成后，该升级流程将会结束，可以从组件管理中单击升级重新开始。
7. 验证阶段确认一切正常后，单击继续进入发布阶段。发布阶段滚动更新完成后，升级流程进入暂停状态。此时，需要对组件和业务状态进行最后一次确认。确认没有问题后，单击继续完成升级流程。
   若业务验证出现问题，可以通过单击回滚进行回滚操作。回滚完成后，该升级流程将会结束，可以从组件管理中单击升级重新开始。

   说明 建议整个升级流程的总时间不超过一周。

   

常见问题

前置检查说明

升级兼容性说明

如果Ingress规则存在不兼容的配置，由低版本升级到高版本后，可能会导致组件出现业务流量不符合预期的情况。nginx.ingress.kubernetes.io/rewrite-target存在不兼容问题，影响版本：0.22.0以下（不包括0.22.0）。

0.22.0版本对nginx.ingress.kubernetes.io/rewrite-target annotation的用法做了修改。在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 Contoroller的运行状态。开启上述服务，请参见Nginx Ingress访问日志分析与监控和阿里云Prometheus监控。

SLS日志服务

阿里云Prometheus大盘

您可以通过阿里云Prometheus服务提供的大盘，来观测组件整体的请求情况。

1. 登录容器服务管理控制台，在左侧导航栏单击集群。
2. 在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择运维管理 > Prometheus监控。
3. 单击网络监控页签，然后单击集群ingress流量监控。
   说明 若监控中没有集群ingress流量监控，请确认是否配置了组件的Prometheus Metrics收集功能。详细信息，请参见阿里云Prometheus监控。
4. 在大盘中可以看到Ingress的各项运行指标，也可以通过选择对应Pod，来只查看该Pod的指标。同样，需要注意的是新的Pod请求成功率有无异常，以及请求数对比旧Pod是否一致。若数据差距较大，可选择回滚操作。
   说明 Ingress规则中没有指定Host（默认为通配符“*”）的规则默认不会记录Metrics。

Pod日志

您可以通过kubectl，以命令行的形式访问Pod日志，来查看是否存在错误。

• 执行以下命令，查看Pod中Nginx的错误日志，包括warn、error和crit这三个级别的：

  kubectl logs -n kube-system <Pod名称> | grep -e warn -e error -e crit

• 执行以下命令，查看Pod中Controller的错误或警告日志：

  kubectl logs -n kube-system <Pod名称> | grep "^[EWF]"

验证和发布阶段Pod扩容失败常见问题及解决方案

Deployment模板检查不通过

如果您的Deployment模板检查不通过，同时无法确定Nginx Ingress Controller组件具体哪个位置发生了不兼容，您可以下载与集群内组件同一版本的组件标准模板，与集群内的组件的YAML进行比对，然后通过手动还原模板的方式修复该问题。

1. 获取集群内Nginx Ingress Controller组件的版本。
   1. 登录容器服务管理控制台，在左侧导航栏选择集群。
   2. 在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择运维管理 > 组件管理。
   3. 在组件管理页面单击网络，找到Nginx Ingress Controller，查看Nginx Ingress Controller版本。
2. 执行以下命令，获取集群内Nginx Ingress Controller组件的YAML内容。
   仅需要获取Nginx Ingress Controller组件Deployment资源的spec字段下的内容。

   kubectl get deploy -n kube-system nginx-ingress-controller -oyaml | sed -n -e '/^spec:$/,/^status:$/{/^status:$/d; p;}'

3. 获取组件标准模板。

   以下罗列了Nginx Ingress Controller组件支持升级的各个版本的标准模板，根据步骤1获取的Nginx Ingress Controller版本，获取对应版本的组件标准模板。

   • 0.15.0-3
   • v0.20.0.1-4597ce2-aliyun
   • v0.22.0.5-552e0db-aliyun
   • v0.30.0.1-5f89cb606-aliyun
   • v0.30.0.2-9597b3685-aliyun
   • v0.44.0.1-5e842447b-aliyun
   • v0.44.0.2-abf1c6fe4-aliyun
   • v0.44.0.3-8e83e7dc6-aliyun
   • v0.44.0.5-e66e17ee3-aliyun
   • v0.44.0.9-7b9e93e7e-aliyun
   • v0.44.0.12-27ae67262-aliyun
   • v1.1.0-aliyun.1
   • v1.1.0-aliyun.2
   • v1.1.2-aliyun.2
   • v1.2.0-aliyun.1
   • v1.2.1-aliyun.1
   • v1.5.1-aliyun.1
   • v1.6.4-aliyun.1
4. 使用YAML Diff比对集群内Nginx Ingress Controller组件的YAML与组件标准模板差异点，修改集群内Nginx Ingress Controller组件的YAML，除了前置检查说明中所提到的兼容字段外，其他内容需要与组件标准模板保持一致。
   说明 修改集群内Deployment过程中，Nginx Ingress Controller Pod会重启，建议您在业务低峰期进行相关操作。