注意事项

公共注意事项

1.仅支持虚拟机和物理机x86和arm64 UEFI场景。

2.使用kubectl apply通过YAML创建或更新OS的CR时，不建议并发apply，当并发请求过多时，kube-apiserver会无法处理请求导致失败。

3.如用户配置了容器镜像仓的证书或密钥，请用户保证证书或密钥文件的权限最小。

升级注意事项

1. 升级为所有软件包原子升级，默认不提供单包升级能力。

2. 升级为双区升级的方式，不支持更多分区数量。

3. 当前暂不支持跨大版本升级。

4 .单节点的升级过程的日志可在节点的 /var/log/messages 文件查看。

5. 请严格按照提供的升级和回退流程进行操作，异常调用顺序可能会导致系统无法升级或回退。

6. 节点上containerd如需配置ctr使用的私有镜像，请将配置文件host.toml按照ctr指导放在/etc/containerd/certs.d目录下。

7. 使用OCI 镜像升级和mtls双向认证仅支持 openEuler 22.09 及之后的版本。

8. nodeselector、executionmode、timewindow和timeinterval 仅支持openEuler 24.09及之后版本。

9. KubeOS 24.03-LTS-SP1 版本与历史版本不兼容。

10. 使用从http/https服务器下载升级镜像功能需要同步使用对应版本镜像制作工具。

配置注意事项

1. 用户自行指定配置内容，用户需保证配置内容安全可靠 ，尤其是持久化配置（kernel.sysctl.persist、grub.cmdline.current、grub.cmdline.next、kubernetes.kubelet、container.containerd、pam.limits），KubeOS不对参数有效性进行检验。

2. opstype=config时，若osversion与当前集群节点的OS版本不一致，配置不会进行。

3 . 当前仅支持kernel参数临时配置（kernel.sysctl）、持久化配置（kernel.sysctl.persist）和grub cmdline配置（grub.cmdline.current和grub.cmdline.next）、kubelet配置（kubernetes.kubelet）、containerd配置（container.containerd）和pam limits配置（pam.limits）。

4. 持久化配置会写入persist持久化分区，升级重启后配置保留；kernel参数临时配置重启后不保留。

5. 配置grub.cmdline.current或grub.cmdline.next时，如为单个参数（非key=value格式参数），请指定key为该参数，value为空。

6. 进行配置删除（operation=delete）时，key=value形式的配置需保证key、value和实际配置一致。

7. 配置不支持回退，如需回退，请修改配置版本和配置内容，重新下发配置。

8. 配置出现错误，节点状态陷入config时，请将配置版本恢复成上一版本并重新下发配置，从而使节点恢复至idle状态。 但是请注意：出现错误前已经配置完成的参数无法恢复。

9. 在配置grub.cmdline.current或grub.cmdline.next时，若需要将已存在的“key=value”格式的参数更新为只有key无value格式，比如将“rd.info=0”更新成rd.info，需要先删除“key=value”，然后在下一次配置时，添加key。不支持直接更新或者更新删除动作在同一次完成。

OS CR参数说明

在集群中创建类别为OS的定制对象，设置相应字段。类别OS来自于安装和部署章节创建的CRD对象，字段及说明如下：

1. imageurl指定的地址里包含协议，只支持http或https协议。imageurl为https协议时为安全传输，imageurl为http地址时，需指定flagSafe为true，即用户明确该地址为安全时，才会下载镜像。如imageurl为http地址且没有指定flagSafe为true，默认该地址不安全，不会下载镜像并且在升级节点的日志中提示用户该地址不安全。

2. 对于imageurl，推荐使用https协议，使用https协议需要升级的机器已安装相应证书。如果镜像服务器由用户自己维护，需要用户自己进行签名，并保证升级节点已安装对应证书。用户需要将证书放在容器OS/etc/KubeOS/certs目录下。地址由管理员传入，管理员应该保证网址的安全性，推荐采用内网地址。

3. 容器OS镜像的合法性检查需要由容器OS镜像服务提供者做合法性检查，确保下载的容器OS镜像来源可靠。

4. 集群存在多OS版本即存在多个OS的实例时，OS的nodeselector字段需要与其他OS不同，即通过label区分的一类node只能对应一个OS实例：当有OS的nodeselector为all-label时，集群只能存在这一个OS的有效实例（有效实例为存在与这个OS对应的节点）。nodeselector不配置的OS也只能有一个，因为nodeselector不配置时认为是对没有label的节点进行操作。

timewinterval参数说明：

1. 参数不设置时默认为15s。

2. 参数设置为0时，由于k8s controller-runtime的rate limit限制，operator下发任务的时间间隔会逐渐增加直至1000s。

3. 并行时为每批次operator下发升级/配置的时间间隔。

4. 在串行时为每批次节点串行升级完毕后与下次升级/配置下发的时间间隔，批次内部的时间间隔为15s。

5. OS的实例字段进行更新会立刻触发operator。

升级指导

1. 编写YAML文件，在集群中部署 OS 的cr实例，用于部署cr实例的YAML示例如下，假定将上面的YAML保存到upgrade_v1alpha1_os.yaml;

使用磁盘镜像进行升级

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
  name: os-sample
spec:
  imagetype: disk
  opstype: upgrade
  osversion: edit.os.version
  maxunavailable: edit.node.upgrade.number
  containerimage: ""
  evictpodforce: true/false
  imageurl: edit.image.url
  checksum: image.checksum
  flagSafe: imageurl.safety
  mtls: imageurl use mtls or not
  cacert:  ca certificate 
  clientcert:  client certificate 
  clientkey:  client certificate key

使用容器镜像进行升级使用容器镜像进行升级前请先制作升级所需的容器镜像，制作方式请见《容器OS镜像制作指导》中 KubeOS OCI 镜像制作。节点容器引擎为docker

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
  name: os-sample
spec:
  imagetype: docker
  opstype: upgrade
  osversion: edit.os.version
  maxunavailable: edit.node.upgrade.number
  containerimage: container image like repository/name:tag
  evictpodforce: true/false
  imageurl: ""
  checksum: container image digests
  flagSafe: false
  mtls: true

节点容器引擎为containerd

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
  name: os-sample
spec:
  imagetype: containerd
  opstype: upgrade
  osversion: edit.os.version
  maxunavailable: edit.node.upgrade.number
  containerimage: container image like repository/name:tag
  evictpodforce: true/false
  imageurl: ""
  checksum: container image digests
  flagSafe: false
  mtls: true

升级并且进行配置的示例如下：

• 以节点容器引擎为containerd为例，升级方式对配置无影响，upgradeconfigs在升级前起效，sysconfigs在升级后起效，配置参数说明请见配置（Settings）指导。
• 升级并且配置时opstype字段需为upgrade。
• upgradeconfig为升级之前执行的配置，sysconfigs为升级机器重启后执行的配置，用户可按需进行配置。

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
    name: os-sample
spec:
    imagetype: ""
    opstype: upgrade
    osversion: edit.os.version
    maxunavailable: edit.node.upgrade.number
    containerimage: ""
    evictpodforce: true/false
    imageurl: ""
    checksum: container image digests
    flagSafe: false
    mtls: false
    sysconfigs:
        version: edit.os.version
        configs:
            - model: kernel.sysctl
            contents:
                - key: kernel param key1
                  value: kernel param value1
                - key: kernel param key2
                  value: kernel param value2
            - model: kernel.sysctl.persist
              configpath: persist file path
              contents:
                - key: kernel param key3
                  value: kernel param value3
                - key: ""
                  value: ""
    upgradeconfigs:
        version: 1.0.0
        configs:
            - model: kernel.sysctl
            contents:
                - key: kernel param key4
                  value: kernel param value4

设置nodeselector、timewindow、timeinterval、executionmode升级部分节点示例如下：

• 以节点容器引擎为containerd为例，升级方式对节点筛选无影响。
• 需要进行升级的节点需包含key为upgrade.openeuler.org/node-selector的label，nodeselector的值为该label的value，即假定nodeselector值为kubeos，则只对包含upgrade.openeuler.org/node-selector=kubeos的label的worker节点进行升级。
• nodeselector、timewindow、timeinterval、executionmode对配置和回滚同样有效。
• 节点添加label、修改label、删除label和查看label命令示例如下：

# 为节点kubeos-node1增加label
kubectl label nodes kubeos-node1 upgrade.openeuler.org/node-selector=kubeos-v1
# 修改节点kubeos-node1的label
kubectl label --overwrite nodes kubeos-node1 upgrade.openeuler.org/node-selector=kubeos-v2
# 删除节点kubeos-node1的label
kubectl label nodes kubeos-node1 upgrade.openeuler.org/node-selector-
# 查看节点的label
kubectl get nodes --show-labels

• yaml示例如下：

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
  name: os-sample
spec:
  imagetype: containerd
  opstype: upgrade
  osversion: edit.os.version
  maxunavailable: edit.node.upgrade.number
  containerimage: container image like repository/name:tag
  evictpodforce: true/false
  imageurl: ""
  checksum: container image digests
  flagSafe: false
  mtls: true
  nodeselector: edit.node.label.key
  timewindow:
    starttime: "HH::MM::SS/YYYY-MM-DD HH::MM::SS"
    endtime: "HH::MM::SS/YYYY-MM-DD HH::MM::SS"
  timeinterval: time intervel like 30
  executionmode: serial/parallel

查看未升级的节点的 OS 版本。

kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage'

执行命令，在集群中部署cr实例后，节点会根据配置的参数信息进行升级。

kubectl apply -f upgrade_v1alpha1_os.yaml

再次查看节点的 OS 版本来确认节点是否升级完成。

kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage'

说明：如果后续需要再次升级，与上面相同对 upgrade_v1alpha1_os.yaml 的 相应字段进行相应修改。

配置（Settings）指导

• Settings参数说明:基于示例YAML对配置的参数进行说明，示例YAML如下，配置的格式（缩进）需和示例保持一致：

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
  name: os-sample
spec:
  imagetype: ""
  opstype: config
  osversion: edit.os.version
  maxunavailable: edit.node.config.number
  containerimage: ""
  evictpodforce: false
  checksum: ""
  sysconfigs:
      version: edit.sysconfigs.version
      configs:
          - model: kernel.sysctl
            contents: 
              - key: kernel param key1
                value: kernel param value1
              - key: kernel param key2
                value: kernel param value2
                operation: delete
          - model: kernel.sysctl.persist
            configpath: persist file path
            contents:
              - key: kernel param key3
                value: kernel param value3
          - model: grub.cmdline.current
            contents:
              - key: boot param key1
              - key: boot param key2
                value: boot param value2
              - key: boot param key3
                value: boot param value3
                operation: delete
          - model: grub.cmdline.next
            contents:
              - key: boot param key4
              - key: boot param key5
                value: boot param value5
              - key: boot param key6
                value: boot param value6
                operation: delete

• 配置的参数说明如下：

• upgradeconfigs与sysconfigs参数相同，upgradeconfigs为升级/回退前进行的配置，仅在upgrade/rollback场景起效，sysconfigs既支持只进行配置，也支持在升级/回退重启后进行配置。
• 编写YAML文件，在集群中部署 OS 的cr实例，用于部署cr实例的YAML示例如上，假定将上面的YAML保存到upgrade_v1alpha1_os.yaml。查看配置之前的节点的配置的版本和节点状态（NODESTATUS状态为idle）。

kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'

• 执行命令，在集群中部署cr实例后，节点会根据配置的参数信息进行配置，再次查看节点状态(NODESTATUS变成config)。

kubectl apply -f upgrade_v1alpha1_os.yaml
kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'

• 再次查看节点的配置的版本确认节点是否配置完成(NODESTATUS恢复为idle)。

kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'

• 如果后续需要再次配置，与上面相同对 upgrade_v1alpha1_os.yaml 的相应字段进行相应修改。

回退指导

使用场景 ​

• 虚拟机无法正常启动时，可在grub启动项页面手动切换启动项，使系统回退至上一版本（即手动回退）。
• 虚拟机能够正常启动并且进入系统时，支持工具回退和手动回退，建议使用工具回退。
• 工具回退有两种方式：

手动回退指导 ​

• 手动重启虚拟机，进入启动项页面后，选择第二启动项进行回退，手动回退仅支持回退到上一个版本。

工具回退指导 ​

• 回退至任意版本修改 OS 的cr实例的YAML 配置文件（例如 upgrade_v1alpha1_os.yaml），设置相应字段为期望回退的老版本镜像信息。类别OS来自于安装和部署章节创建的CRD对象，字段说明及示例请见上一节升级指导。YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退

kubectl apply -f upgrade_v1alpha1_os.yaml

• 回退至上一版本OS回退至上一版本：修改upgrade_v1alpha1_os.yaml，设置osversion为上一版本，opstype为rollback，回退至上一版本（即切换至上一分区）。YAML示例如下：

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
name: os-sample
spec:
    imagetype: ""
    opstype: rollback
    osversion: KubeOS previous version
    maxunavailable: 2
    containerimage: ""
    evictpodforce: true/false
    imageurl: ""
    checksum: ""
    flagSafe: false
    mtls: true

• 配置回退至上一版本：修改upgrade_v1alpha1_os.yaml，设置sysconfigs/upgradeconfigs的version为上一版本，回退至上一版本（已配置的参数无法回退）。

apiVersion: upgrade.openeuler.org/v1alpha1
kind: OS
metadata:
  name: os-sample
spec:
  imagetype: ""
  opstype: config
  osversion: edit.os.version
  maxunavailable: edit.node.config.number
  containerimage: ""
  evictpodforce: true/false
  imageurl: ""
  checksum: ""
  flagSafe: false
  mtls: false
  sysconfigs:
      version: previous config version
      configs:
          - model: kernel.sysctl
            contents:
              - key: kernel param key1
                value: kernel param value1
              - key: kernel param key2
                value: kernel param value2
          - model: kernel.sysctl.persist
            configpath: persist file path
            contents:
              - key: kernel param key3
                value: kernel param value3

• YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退。

kubectl apply -f upgrade_v1alpha1_os.yaml

更新完成后，节点会根据配置信息回退容器 OS。

• 查看节点容器 OS 版本(回退OS版本)或节点config版本&节点状态为idle(回退config版本)，确认回退是否成功

kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'