升级指南

这个指南描述了如何来升级开放边缘服务网格 (osm-edge) 控制平面。

升级如何工作

osm-edge 的控制平面生命周期被 Helm 来管理，并且通过 Helm 升级功能能够被升级，该功能将基于修改的值和资源模板，按照需要，来给控制平面组件打补丁或者做替换。

升级期间的资源可用性

既然升级可能会包含重新部署新版本的 osm-edge 控制器，那么这就会造成控制器的停机。当 osm-edge 控制器不可用时，处理新的 SMI 资源就会有延时，创建新的 Pod 用来注入代理 sidecar 容器将会失败，并且 mTLS 证书将不能被轮换。

已经存在的 SMI 资源将不被影响，这就意味着数据平面(包含 Pipy sidecar 配置)也将不受升级的影响。

如果升级包括了 CRD 修改，那么数据平面的暂停是预期中的。精简的数据平面升级在问题 #512 里面被追踪。

策略

只有某些升级方法被测试并被支持。

注意：这些计划是暂时的，很容易被改变。

破坏性修改，在本章节中，指的是对如下面向用户的组件的不兼容修改：

  • osm CLI 命令，标志和行为
  • SMI CRD 和控制器

这意味着以下内容不是面向用户的，只要不兼容由面向用户的组件处理，不兼容的更改就不会被视为“破坏”：

  • chart values.yaml
  • osm-mesh-config MeshConfig
  • 内部使用的标签和标注 (被谁监视、注入、矩阵等等)

只能支持在那些不包含破坏性修改的版本间的升级，如下所述：

对于 osm-edge 版本 0.y.z：

  • 在 0.y.z 和 0.y.z+1 之间，不会引入破坏性修改
  • 在 0.y.z 和 0.y+1.0 之间，可能引入破坏性修改

对于 osm-edge 版本 x.y.z，这里 x >= 1 的：

  • 在 x.y.z 和 x.y+1.0 之间或者 x.y.z 和 x.y.z+1 之间的，破坏性改变将不被引入
  • 在 x.y.z 和 x+1.0.0 之间的，破坏性改变将被引入

如何升级 osm-edge

升级一个网格，被推荐的方式是利用 osm CLI。对于高级用例，helm 或许被使用。

CRD 升级

因为 Helm 不管理在初始化安装之外的 CRD，osm-edge 利用一个在 osm-bootstrap Pod 上的初始容器来在升级期间更新现有的和添加新的 CRD。如果一个新的发布包含对现有 CRD 的更新或者添加新的 CRD，在 osm-bootstrap Pod 上的 init-osm-bootstrap 将更新 CRD。相关联的定制资源将被保留，在升级之前和之后都不需要额外的行动。

请检查发布事项里面的 CRD Updates，来查阅被 osm-edge 使用的 CRD 是否存在任何的更新。如果定制资源的版本在被更新的 CRD 支持版本里面，不需要即刻的行动。osm-edge 为它的 CRD 实现了一个转换网络钩子 (webhook)，确保对更老版本的支持，并提供在以后的一个时间节点更新定制资源的灵活性。

用 osm-edge CLI 来更新

先决条件

  • Kubernetes 集群并已安装 osm-edge控制平面
    • 确保 Kubernetes 集群有被新的 osm-edge chart所需要的最小 Kubernetes 版本。这点能够在安装先决条件里被找到。
  • 已经安装 osm CLI
    • 默认的，osm CLI 将升级到同它安装相同的 chart 版本。例如，v1.1.0 的 osm CLI 将升级 osm-edge Helm chart 到 v1.1.0。升级到任何其他版本的 Helm chart，而不是匹配于 CLI 的，或许可以工作，但是这些场景没有被测试过，而且即便被报告了问题，也不会被修复。

osm mesh upgrade 命令对一个网格的现有 Helm 发布版做 helm upgrade。

基础用法不需要额外的参数或者标志：

$ osm mesh upgrade
osm-edge successfully upgraded mesh osm

这个命令将升级网格，其在默认的 osm-edge 命名空间里面使用默认的网格名称。来自先前发布版的值默认情况下不会被保留到这个新的发布版，但是可以通过在 osm mesh upgrade 上独立地使用 --set 标志来传递旧值。

查阅 osm mesh upgrade --help 来获取更多细节。

用 Helm 来升级

先决条件

  • 已经安装 osm-edge 控制平面的 Kubernetes 集群
  • helm 3 CLI

osm-edge 配置

当升级时，任何被用来安装或者运行 osm-edge 的自定义设置都可能被恢复到默认值，这只包含任何矩阵部署。请确保仔细地遵守了指南来阻止这些值被覆盖。

要阻止任何已经做出的对 osm-edge 配置的修改，使用 helm --values 标志。创建一个values.yaml的副本（确认使用了针对升级的 chart 的版本），改变任何希望定制的值。可以省去所有其他的值。

注意：任何进入到 MeshConfig 的配置修改在升级期间将不会被应用，这个值将保留升级之前的。如果希望更新在 MeshConfig 里面的任何值，可以通过在升级之后给资源打补丁来完成。

例如，如果 MeshConfig 中的 logLevel 域在升级前被设置为 info，在升级期间在 override.yaml 里更新这个值将不会造成任何改变。

警告: 不要修改 osm.meshName 或者 osm.osmNamespace

Helm 升级

然后运行下面的 helm upgrade 命令。

$ helm upgrade <mesh name> osm --repo https://openservicemesh.github.io/osm --version <chart version> --namespace <osm namespace> --values override.yaml

如果优先使用默认设置，省略 --values 标志。

运行 helm upgrade --help 了解更多选项。

升级第三方依赖

Pipy

Pipy 版本能够通过修改在 osm-mesh-config 里面的 sidecarImage 变量值来更新。当如此做时，推荐指定和 Pipy 版本相关联的镜像摘要来避免供应链攻击。例如，要更新 Pipy镜像到 latest（此处仅作为例子，不建议使用 latest 镜像），接下来的命令应该被运行：

export osm_namespace=osm-system # Replace osm-system with the namespace where osm-edge is installed
kubectl patch meshconfig osm-mesh-config -n $osm_namespace -p '{"spec":{"sidecar":{"sidecarImage":"flomesh/pipy:latest"}}}' --type=merge

在已经被更新 MeshConfig 资源之后，所有的作为网格一部分的 Pod 和部署必须被重启，这样更新版本的 Pipy sidecar 能够被注入到 Pod 上以作为 osm-edge 执行的自动化 sidecar 注入的一部分。这个可以通过 kubectl rollout restart deploy 命令来完成。

Prometheus、Grafana 和 Jaeger

如果启用，osm-edge 的 Prometheus，Grafana 和 Jaeger 服务会与其他 osm-edge 控制组件组件一起部署。虽然这些第三方的依赖不能够通过像 Pipy 这样的 MeshConfig 来更新，它们的版本仍旧能够在部署中被直接更新。例如，要更新 Prometheus 到 v2.19.1，用户能够运行：

export osm_namespace=osm-system # Replace osm-system with the namespace where osm-edge is installed
kubectl set image deployment/osm-prometheus -n $osm_namespace prometheus="prom/prometheus:v2.19.1"

要更新 Grafana 8.1.0，命令如下：

kubectl set image deployment/osm-grafana -n $osm_namespace grafana="grafana/grafana:8.1.0"

对 Jaeger，应该运行下面的命令来更新到 1.26.0：

kubectl set image deployment/jaeger -n $osm_namespace jaeger="jaegertracing/all-in-one:1.26.0"

osm-edge 升级问题解决指南

osm-edge 网格升级超时

CPU 不足

如果 osm mesh upgrade 命令超时了，很可能是由于 CPU 不足造成的。

  1. 检查 Pod 来看看是否它们中有不是充分运行的
# Replace osm-system with osm-controller's namespace if using a non-default namespace
kubectl get pods -n osm-system
  1. 如果有任何的 Pod 在待定状态，使用 kubectl describe 来检查 Events 部分
# Replace osm-system with osm-controller's namespace if using a non-default namespace
kubectl describe pod <pod-name> -n osm-system

如果看到如下的错误，那么请增加 Docker 能够使用的 CPU 数量。

`Warning  FailedScheduling  4s (x15 over 19m)  default-scheduler  0/1 nodes are available: 1 Insufficient cpu.`

错误确认 CLI 参数

如果 osm mesh upgrade 命令仍旧超时，很可能是 CLI/镜像 版本不匹配。

  1. 检查 Pod 来看看是否它们中有没有启动和运行的
# Replace osm-system with osm-controller's namespace if using a non-default namespace
kubectl get pods -n osm-system
  1. 如果有任何的 Pod 在 Pending 状态，使用 kubectl describe 来检查 Events 部分的 Error Validating CLI parameters
# Replace osm-system with osm-controller's namespace if using a non-default namespace
kubectl describe pod <pod-name> -n osm-system
  1. 如果发现了错误，请检查 Pod 的 log 来排查错误
kubectl logs -n osm-system <pod-name> | grep -i error

如果看到了如下的错误，那么它就是由于 CLI/镜像 版本不匹配造成的。

`"error":"Please specify the init container image using --init-container-image","reason":"FatalInvalidCLIParameters"`

绕开的方法是在运行 osm mesh upgrade 时设置 container-registry 和 osm-image-tag 标志。

osm mesh upgrade --container-registry $CTR_REGISTRY --osm-image-tag $CTR_TAG --enable-egress=true

其他问题

如果运行中遇到的问题不在上述解决方案之列，请开一个 GitHub Issue。