packages/KubeOS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
KubeOS/0002-docs-Add-the-content-of-the-user-guide.patch

618 lines
39 KiB
Diff
Raw Normal View History

sync branch to openEuler-22.03-LTS-SP1 Signed-off-by: Yuhang Wei <weiyuhang3@huawei.com> (cherry picked from commit 9186039f774168dfbacef04dac8ee56356149736)
2024-03-13 14:26:44 +08:00
From f34fe043179aec4bd2a9270fc25cef3f4377c152 Mon Sep 17 00:00:00 2001
From: liyuanr <liyuanrong1@huawei.com>
Date: Thu, 11 Jan 2024 20:25:05 +0800
Subject: [PATCH 02/13] docs:Add the content of the user guide.
Modify the format of the user guide,
add precautions, and add configuration information.
Signed-off-by: liyuanr <liyuanrong1@huawei.com>
---
docs/quick-start.md | 399 +++++++++++++++++++++++++++-----------------
1 file changed, 243 insertions(+), 156 deletions(-)
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 0d4dc4b..9656fb9 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -1,18 +1,22 @@
# 快速使用指导
-## 编译及部署
+[TOC]
-### 编译指导
+## 编译指导
* 编译环境：openEuler Linux x86/AArch64
+
* 进行编译需要以下包：
* golang(大于等于1.15版本)
* make
* git
+ * rust(大于等于1.57版本)
+ * cargo(大于等于1.57版本)
+ * openssl-devel
``` shell
- sudo yum install golang make git
- ```
+ sudo yum install golang make git rust cargo openssl-devel
+ ```
* 使用git获取本项目的源码
@@ -27,76 +31,101 @@
```shell
cd KubeOS
- sudo make
- ```
-
- * proxy及operator容器镜像构建
- * proxy及operator容器镜像构建使用docker，请先确保docker已经安装和配置完毕
- * 请用户自行编写Dockerfile来构建镜像，请注意
- * operator和proxy需要基于baseimage进行构建，用户保证baseimage的安全性
- * 需将operator和proxy拷贝到baseimage上
- * 请确保proxy属主和属组为root，文件权限为500
- * 请确保operator属主和属组为在容器内运行operator的用户，文件权限为500
- * operator和proxy的在容器内的位置和容器启动时运行的命令需与部署operator的yaml中指定的字段相对应
- * 首先指定镜像仓库地址、镜像名及版本，Dockerfile路径，然后构建并推送镜像到镜像仓库
- * Dockerfile参考如下, Dockerfile也可以使用多阶段构建:
-
- ``` dockerfile
- FROM your_baseimage
- COPY ./bin/proxy /proxy
- ENTRYPOINT ["/proxy"]
- FROM your_baseimage
- COPY --chown=6552:6552 ./bin/operator /operator
- ENTRYPOINT ["/operator"]
- ```
+ sudo make
+ # 编译生成的二进制在bin目录下，查看二进制
+ tree bin
+ bin
+ ├── operator
+ ├── os-agent
+ ├── proxy
+ ├── rust
+ │   ├── ...
+ │   └── release
+ │   ├── ...
+ │   ├── os-agent
+ │   └── proxy
+ ```
- ```shell
- # 指定proxy的镜像仓库，镜像名及版本
- export IMG_PROXY=your_imageRepository/proxy_imageName:version
- # 指定proxy的Dockerfile地址
- export DOCKERFILE_PROXY=your_dockerfile_proxy
- # 指定operator的镜像仓库，镜像名及版本
- export IMG_OPERATOR=your_imageRepository/operator_imageName:version
- # 指定operator的Dockerfile路径
- export DOCKERFILE_OPERATOR=your_dockerfile_operator
-
- # 镜像构建
- docker build -t ${IMG_OPERATOR} -f ${DOCKERFILE_OPERATOR} .
- docker build -t ${IMG_PROXY} -f ${DOCKERFILE_PROXY} .
- # 推送镜像到镜像仓库
- docker push ${IMG_OPERATOR}
- docker push ${IMG_PROXY}
- ```
+ * ```bin/proxy```、```bin/os-agent```为go语言编写的proxy和os-agent，```bin/rust/release/proxy```、```bin/rust/release/os-agent```为rust语言编写的proxy和os-agent，二者功能一致。
+
+## 镜像构建指导
+
+### proxy及operator镜像构建指导
+
+* proxy及operator容器镜像构建使用docker，请先确保docker已经安装和配置完毕
+
+* 请用户自行编写Dockerfile来构建镜像，请注意
+ * operator和proxy需要基于baseimage进行构建，用户保证baseimage的安全性
+ * 需将operator和proxy拷贝到baseimage上
+ * 请确保proxy属主和属组为root，文件权限为500
+ * 请确保operator属主和属组为在容器内运行operator的用户，文件权限为500
+ * operator和proxy的在容器内的位置和容器启动时运行的命令需与部署operator的yaml中指定的字段相对应
+
+* 首先指定镜像仓库地址、镜像名及版本，Dockerfile路径，然后构建并推送镜像到镜像仓库
+
+* Dockerfile参考如下, Dockerfile也可以使用多阶段构建:
+
+ ``` dockerfile
+ FROM your_baseimage
+ COPY ./bin/proxy /proxy
+ ENTRYPOINT ["/proxy"]
+ FROM your_baseimage
+ COPY --chown=6552:6552 ./bin/operator /operator
+ ENTRYPOINT ["/operator"]
+ ```
-* OS虚拟机镜像制作
- * 制作注意事项
- * 请确保已安装qemu-img，bc，parted，tar，yum，docker
- * 容器OS镜像制作需要使用root权限
- * 容器OS 镜像制作工具的 rpm 包源为 openEuler 具体版本的 everything 仓库和 EPOL 仓库。制作镜像时提供的 repo 文件中，yum 源建议同时配置 openEuler 具体版本的 everything 仓库和 EPOL 仓库
- * 容器OS镜像制作之前需要先将当前机器上的selinux关闭或者设为允许模式
- * 使用默认rpmlist进行容器OS镜像制作出来的镜像默认和制作工具保存在相同路径，该分区至少有25G的剩余空间
- * 容器镜像制作时不支持用户自定义配置挂载文件
- * 容器OS镜像制作工具执行异常中断，可能会残留文件、目录或挂载，需用户手动清理，对于可能残留的rootfs目录，该目录虽然权限为555，但容器OS镜像制作在开发环境进行，不会对生产环境产生影响。
- * 请确保os-agent属主和属组为root，建议os-agent文件权限为500
- * 容器OS虚拟机镜像制作
- 进入scripts目录，执行脚本
-
- ```shell
- cd scripts
- bash kbimg.sh create vm-image -p xxx.repo -v v1 -b ../bin/os-agent -e '''$1$xyz$RdLyKTL32WEvK3lg8CXID0'''
- ```
-
- * 其中 xx.repo 为制作镜像所需要的 yum 源，yum 源建议配置为 openEuler 具体版本的 everything 仓库和 EPOL 仓库。
- * 容器 OS 镜像制作完成后，会在 scripts 目录下生成：
- * raw格式的系统镜像system.img，system.img大小默认为20G，支持的根文件系统分区大小<2020MiB，持久化分区<16GB。
- * qcow2 格式的系统镜像 system.qcow2。
- * 可用于升级的根文件系统分区镜像 update.img 。
- * 制作出来的容器 OS 虚拟机镜像目前只能用于 CPU 架构为 x86 和 AArch64 的虚拟机场景，x86 架构的虚拟机使用 legacy 启动模式启动需制作镜像时指定-l参数
- * 容器OS运行底噪<150M (不包含k8s组件及相关依赖kubernetes-kubeadm，kubernetes-kubelet， containernetworking-plugins，socat，conntrack-tools，ebtables，ethtool)
- * 本项目不提供容器OS镜像，仅提供裁剪工具，裁剪出来的容器OS内部的安全性由OS发行商保证。
- * 声明： os-agent使用本地unix socket进行通信，因此不会新增端口。下载镜像的时候会新增一个客户端的随机端口，1024~65535使用完后关闭。proxy和operator与api-server通信时作为客户端也会有一个随机端口，基于kubernetes的operator框架，必须使用端口。他们部署在容器里。
-
-### 部署指导
+ ```shell
+ # 指定proxy的镜像仓库，镜像名及版本
+ export IMG_PROXY=your_imageRepository/proxy_imageName:version
+ # 指定proxy的Dockerfile地址
+ export DOCKERFILE_PROXY=your_dockerfile_proxy
+ # 指定operator的镜像仓库，镜像名及版本
+ export IMG_OPERATOR=your_imageRepository/operator_imageName:version
+ # 指定operator的Dockerfile路径
+ export DOCKERFILE_OPERATOR=your_dockerfile_operator
+
+ # 镜像构建
+ docker build -t ${IMG_OPERATOR} -f ${DOCKERFILE_OPERATOR} .
+ docker build -t ${IMG_PROXY} -f ${DOCKERFILE_PROXY} .
+ # 推送镜像到镜像仓库
+ docker push ${IMG_OPERATOR}
+ docker push ${IMG_PROXY}
+ ```
+
+### KubeOS虚拟机镜像制作指导
+
+* 制作注意事项
+ * 请确保已安装qemu-img，bc，parted，tar，yum，docker
+ * 容器OS镜像制作需要使用root权限
+ * 容器OS 镜像制作工具的 rpm 包源为 openEuler 具体版本的 everything 仓库和 EPOL 仓库。制作镜像时提供的 repo 文件中，yum 源建议同时配置 openEuler 具体版本的 everything 仓库和 EPOL 仓库
+ * 容器OS镜像制作之前需要先将当前机器上的selinux关闭或者设为允许模式
+ * 使用默认rpmlist进行容器OS镜像制作出来的镜像默认和制作工具保存在相同路径，该分区至少有25G的剩余空间
+ * 容器镜像制作时不支持用户自定义配置挂载文件
+ * 容器OS镜像制作工具执行异常中断，可能会残留文件、目录或挂载，需用户手动清理，对于可能残留的rootfs目录，该目录虽然权限为555，但容器OS镜像制作在开发环境进行，不会对生产环境产生影响。
+ * 请确保os-agent属主和属组为root，建议os-agent文件权限为500
+
+* 容器OS虚拟机镜像制作
+ 进入scripts目录，执行脚本
+
+ ```shell
+ cd scripts
+ bash kbimg.sh create vm-image -p xxx.repo -v v1 -b ../bin/os-agent -e '''$1$xyz$RdLyKTL32WEvK3lg8CXID0'''
+ ```
+
+ * 其中 xx.repo 为制作镜像所需要的 yum 源，yum 源建议配置为 openEuler 具体版本的 everything 仓库和 EPOL 仓库。
+ * 容器 OS 镜像制作完成后，会在 scripts 目录下生成：
+ * raw格式的系统镜像system.img，system.img大小默认为20G，支持的根文件系统分区大小<2020MiB，持久化分区<16GB。
+ * qcow2 格式的系统镜像 system.qcow2。
+ * 可用于升级的根文件系统分区镜像 update.img 。
+ * 制作出来的容器 OS 虚拟机镜像目前只能用于 CPU 架构为 x86 和 AArch64 的虚拟机场景，x86 架构的虚拟机使用 legacy 启动模式启动需制作镜像时指定-l参数
+ * 容器OS运行底噪<150M (不包含k8s组件及相关依赖kubernetes-kubeadm，kubernetes-kubelet， containernetworking-plugins，socat，conntrack-tools，ebtables，ethtool)
+ * 本项目不提供容器OS镜像，仅提供裁剪工具，裁剪出来的容器OS内部的安全性由OS发行商保证。
+
+* 声明： os-agent使用本地unix socket进行通信，因此不会新增端口。下载镜像的时候会新增一个客户端的随机端口，1024~65535使用完后关闭。proxy和operator与api-server通信时作为客户端也会有一个随机端口，基于kubernetes的operator框架，必须使用端口。他们部署在容器里。
+
+## 部署指导
+
+### os-operator和os-proxy部署指导
* 环境要求
* openEuler Linux x86/AArch64系统
@@ -142,18 +171,35 @@
kubectl get pods -A
```
-### 使用指导
+## 使用指导
#### 注意事项
-* 容器OS升级为所有软件包原子升级，默认不在容器OS内提供单包升级能力。
-* 容器OS升级为双区升级的方式，不支持更多分区数量。
-* 单节点的升级过程的日志可在节点的/var/log/message文件查看。
-* 请严格按照提供的升级和回退流程进行操作，异常调用顺序可能会导致系统无法升级或回退。
-* 使用docker镜像升级和mtls双向认证仅支持 openEuler 22.09 及之后的版本
-* 不支持跨大版本升级
-
-#### 参数说明
+* 公共注意事项
+ * 仅支持虚拟机x86和arm64 UEFI场景。
+ * 当前不支持集群节点OS多版本管理，即集群中OS的CR只能为一个。
+ * 使用kubectl apply通过YAML创建或更新OS的CR时，不建议并发apply，当并发请求过多时，kube-apiserver会无法处理请求导致失败。
+ * 如用户配置了容器镜像仓的证书或密钥，请用户保证证书或密钥文件的权限最小。
+* 升级注意事项
+ * 升级为所有软件包原子升级，默认不提供单包升级能力。
+ * 升级为双区升级的方式，不支持更多分区数量。
+ * 当前暂不支持跨大版本升级。
+ * 单节点的升级过程的日志可在节点的 /var/log/messages 文件查看。
+ * 请严格按照提供的升级和回退流程进行操作，异常调用顺序可能会导致系统无法升级或回退。
+ * 节点上containerd如需配置ctr使用的私有镜像，请将配置文件host.toml按照ctr指导放在/etc/containerd/certs.d目录下。
+
+* 配置注意事项
+ * 用户自行指定配置内容，用户需保证配置内容安全可靠 ，尤其是持久化配置（kernel.sysctl.persist、grub.cmdline.current、grub.cmdline.next），KubeOS不对参数有效性进行检验。
+ * opstype=config时，若osversion与当前集群节点的OS版本不一致，配置不会进行。
+ * 当前仅支持kernel参数临时配置（kernel.sysctl）、持久化配置（kernel.sysctl.persist）和grub cmdline配置（grub.cmdline.current和grub.cmdline.next）。
+ * 持久化配置会写入persist持久化分区，升级重启后配置保留；kernel参数临时配置重启后不保留。
+ * 配置grub.cmdline.current或grub.cmdline.next时，如为单个参数（非key=value格式参数），请指定key为该参数，value为空。
+ * 进行配置删除（operation=delete）时，key=value形式的配置需保证key、value和实际配置一致。
+ * 配置不支持回退，如需回退，请修改配置版本和配置内容，重新下发配置。
+ * 配置出现错误，节点状态陷入config时，请将配置版本恢复成上一版本并重新下发配置，从而使节点恢复至idel状态。 但是请注意：出现错误前已经配置完成的参数无法恢复。
+ * 在配置grub.cmdline.current或grub.cmdline.next时，若需要将已存在的“key=value”格式的参数更新为只有key无value格式，比如将“rd.info=0”更新成rd.info，需要先删除“key=value”，然后在下一次配置时，添加key。不支持直接更新或者更新删除动作在同一次完成。
+
+#### OS CR参数说明
在集群中创建类别为OS的定制对象，设置相应字段。类别OS来自于安装和部署章节创建的CRD对象，字段及说明如下：
@@ -163,21 +209,21 @@
| 参数 |参数类型 | 参数说明 | 使用说明 | 是否必选 |
| -------------- | ------ | ------------------------------------------------------------ | ----- | ---------------- |
- | imagetype | string | 使用的升级镜像的类型 | 需为 docker ，containerd ，或者是 disk，其他值无效，且该参数仅在升级场景有效。<br> **注意**：若使用containerd，agent优先使用crictl工具拉取镜像，没有crictl时才会使用ctr命令拉取镜像。使用ctr拉取镜像时，镜像如果在私有仓内，需按照[官方文档](https://github.com/containerd/containerd/blob/main/docs/hosts.md)在/etc/containerd/certs.d目录下配置私有仓主机信息，才能成功拉取镜像。|是 |
- | opstype | string | 进行的操作，升级,回退或者配置 | 需为 upgrade ，config 或者 rollback ，其他值无效 |是 |
- | osversion | string | 用于升级或回退的镜像的OS版本 | 需为 KubeOS version , 例如: KubeOS 1.0.0|是 |
- | maxunavailable | int | 同时进行升级或回退的节点数 | maxunavailable值设置为大于实际集群的节点数时也可正常部署，升级或回退时会按照集群内实际节点数进行|是 |
- | containerimage | string | 用于升级的容器镜像 | 需要为容器镜像格式：[REPOSITORY/NAME[:TAG@DIGEST]](https://docs.docker.com/engine/reference/commandline/tag/#extended-description)，仅在使用容器镜像升级场景下有效|是 |
- | imageurl | string | 用于升级的磁盘镜像的地址 | imageurl中包含协议，只支持http或https协议，例如：<https://192.168.122.15/update.img> 仅在使用磁盘镜像升级场景下有效|是 |
+ | imagetype | string | 升级镜像的类型 | 仅支持docker ，containerd ，或者是 disk，仅在升级场景有效。<br> **注意**：若使用containerd，agent优先使用crictl工具拉取镜像，没有crictl时才会使用ctr命令拉取镜像。使用ctr拉取镜像时，镜像如果在私有仓内，需按照[官方文档](https://github.com/containerd/containerd/blob/main/docs/hosts.md)在/etc/containerd/certs.d目录下配置私有仓主机信息，才能成功拉取镜像。 |是 |
+ | opstype | string | 操作类型：升级,回退或者配置 | 仅支持upgrade ，config 或者 rollback |是 |
+ | osversion | string | 升级/回退的目标版本 | osversion需与节点的目标os版本对应（节点上/etc/os-release中PRETTY_NAME字段或k8s检查到的节点os版本） 例如：KubeOS 1.0.0。 |是 |
+ | maxunavailable | int | 每批同时进行升级/回退/配置的节点数。 | maxunavailable值大于实际节点数时，取实际节点数进行升级/回退/配置。 |是 |
+ | containerimage | string | 用于升级的容器镜像 | 仅在imagetype是容器类型时生效，仅支持以下3种格式的容器镜像地址： repository/name repository/name@sha256:xxxx repository/name:tag |是 |
+ | imageurl | string | 用于升级的磁盘镜像的地址 | imageurl中包含协议，只支持http或https协议，例如：<https://192.168.122.15/update.img> ，仅在使用磁盘镜像升级场景下有效 |是 |
| checksum | string | 用于升级的磁盘镜像校验的checksum(SHA-256)值或者是用于升级的容器镜像的digests值 | 仅在升级场景下有效 |是 |
| flagSafe | bool | 当imageurl的地址使用http协议表示是否是安全的 | 需为 true 或者 false ，仅在imageurl使用http协议时有效 |是 |
| mtls | bool | 用于表示与imageurl连接是否采用https双向认证 | 需为 true 或者 false ，仅在imageurl使用https协议时有效|是 |
| cacert | string | https或者https双向认证时使用的根证书文件 | 仅在imageurl使用https协议时有效| imageurl使用https协议时必选 |
| clientcert | string | https双向认证时使用的客户端证书文件 | 仅在使用https双向认证时有效|mtls为true时必选 |
| clientkey | string | https双向认证时使用的客户端公钥 | 仅在使用https双向认证时有效|mtls为true时必选 |
- | evictpodforce | bool | 用于表示升级/回退时是否强制驱逐pod | 需为 true 或者 false ，仅在升级或者回退时有效| 必选 |
- | sysconfigs | / | 需要进行配置的参数值 | 在配置或者升级或者回退机器时有效，在升级或者回退操作之后即机器重启之后起效，详细字段说明请见```配置（Settings）指导```| 可选 |
- | upgradeconfigs | / | 需要升级前进行的配置的参数值 | 在升级或者回退时有效，在升级或者回退操作之前起效，详细字段说明请见```配置（Settings）指导```| 可选 |
+ | evictpodforce | bool | 升级/回退时是否强制驱逐pod | 需为 true 或者 false ，仅在升级或者回退时有效| 必选 |
+ | sysconfigs | / | 配置设置 | 1. “opstype=config”时只进行配置。 2.“opstype=upgrade/rollback”时，代表升级/回退后配置，即在升级/回退重启后进行配置。```配置（Settings）指导``` | “opstype=config”时必选 |
+ | upgradeconfigs | / | 升级前配置设置 | 在升级或者回退时有效，在升级或者回退操作之前起效，详细字段说明请见```配置（Settings）指导```| 可选 |
#### 升级指导
@@ -271,13 +317,13 @@
sysconfigs:
version: edit.os.version
configs:
- - model: kernel.systcl
+ - model: kernel.sysctl
contents:
- key: kernel param key1
value: kernel param value1
- key: kernel param key2
value: kernel param value2
- - model: kernel.systcl.persist
+ - model: kernel.sysctl.persist
configpath: persist file path
contents:
- key: kernel param key3
@@ -287,7 +333,7 @@
upgradeconfigs:
version: 1.0.0
configs:
- - model: kernel.systcl
+ - model: kernel.sysctl
contents:
- key: kernel param key4
value: kernel param value4
@@ -311,12 +357,13 @@
kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage'
```
-* 如果后续需要再次升级，与上面相同对 upgrade_v1alpha1_os.yaml 的 imageurl, osversion, checksum, maxunavailable, flagSafe 或者containerimage字段进行相应修改。
+* 如果后续需要再次升级，与上面相同，对upgrade_v1alpha1_os.yaml的相应字段进行修改
#### 配置（Settings）指导
* Settings参数说明:
- 以进行配置时的示例yaml为例对配置的参数进行说明，示例yaml如下：
+
+ 基于示例YAML对配置的参数进行说明，示例YAML如下，配置的格式（缩进）需和示例保持一致：
```yaml
apiVersion: upgrade.openeuler.org/v1alpha1
@@ -330,72 +377,97 @@
maxunavailable: edit.node.config.number
containerimage: ""
evictpodforce: false
- imageurl: ""
checksum: ""
- flagSafe: false
- mtls: false
sysconfigs:
- version: 1.0.0
+ version: edit.sysconfigs.version
configs:
- - model: kernel.systcl
- contents:
+ - model: kernel.sysctl
+ contents:
- key: kernel param key1
value: kernel param value1
- key: kernel param key2
value: kernel param value2
operation: delete
- - model: kernel.systcl.persist
+ - model: kernel.sysctl.persist
configpath: persist file path
contents:
- key: kernel param key3
- value: kernel param value3
+ 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
```
- * 配置的参数说明如下：
- * version: 配置的版本,通过版本差异触发配置，请修改配置后更新 version
- * configs: 具体配置内容
- * model: 进行的配置的类型，支持的配置类型请看[Settings 列表](#setting-列表)
- * configpath: 如为持久化配置，配置文件路径
- * contents: 配置参数的 key / value 和对参数的操作。
- * key / value: 请看[Settings 列表](#setting-列表)对支持的配置的 key / value的说明。
- * operation: 若不指定operation，则默认为添加或更新。若指定为delete，代表删除目前OS中已配置的参数。
- **注意：** 当operation为delete时，yaml中的key/value必须和OS上想删除参数的key/value**一致**，否则删除失败。
- * upgradeconfigs与sysconfig参数相同，upgradeconfig为升级前进行的配置，仅在升级/回滚场景起效，在升级/回滚操作执行前进行配置，只进行配置或者需要升级/回滚重启后执行配置，使用sysconfigs
+ 配置的参数说明如下：
+
+ | 参数 | 参数类型 | 参数说明 | 使用说明 | 配置中是否必选 |
+ | ---------- | -------- | --------------------------- | ------------------------------------------------------------ | ----------------------- |
+ | version | string | 配置的版本 | 通过version是否相等来判断配置是否触发，version为空（为""或者没有值）时同样进行判断，所以不配置sysconfigs/upgradeconfigs时，继存的version值会被清空并触发配置。 | 是 |
+ | configs | / | 具体配置内容 | 包含具体配置项列表。 | 是 |
+ | model | string | 配置的类型 | 支持的配置类型请看附录下的```Settings列表``` | 是 |
+ | configpath | string | 配置文件路径 | 仅在kernel.sysctl.persist配置类型中生效，请看附录下的```Settings列表```对配置文件路径的说明。 | 否 |
+ | contents | / | 具体key/value的值及操作类型 | 包含具体配置参数列表。 | 是 |
+ | key | string | 参数名称 | key不能为空，不能包含"="，不建议配置含空格、tab键的字符串，具体请看附录下的```Settings列表```中每种配置类型对key的说明。 | 是 |
+ | value | string | 参数值 | key=value形式的参数中，value不能为空，不建议配置含空格、tab键的字符串，具体请看附录下的```Settings列表```中对每种配置类型对value的说明。 | key=value形式的参数必选 |
+ | operation | string | 对参数进行的操作 | 仅对kernel.sysctl.persist、grub.cmdline.current、grub.cmdline.next类型的参数生效。默认为添加或更新。仅支持配置为delete，代表删除已存在的参数（key=value需完全一致才能删除）。 | 否 |
+
+
+
+ * upgradeconfigs与sysconfigs参数相同，upgradeconfigs为升级/回退前进行的配置，仅在upgrade/rollback场景起效，sysconfigs既支持只进行配置，也支持在升级/回退重启后进行配置
+
* 使用说明
+
* 编写YAML文件，在集群中部署 OS 的cr实例，用于部署cr实例的YAML示例如上，假定将上面的YAML保存到upgrade_v1alpha1_os.yaml
+
* 查看配置之前的节点的配置的版本和节点状态（NODESTATUS状态为idle）
```shell
- kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADESYSCONFIG:status.upgradesysconfigs.version'
+ kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'
```
* 执行命令，在集群中部署cr实例后，节点会根据配置的参数信息进行配置，再次查看节点状态(NODESTATUS变成config)
```shell
kubectl apply -f upgrade_v1alpha1_os.yaml
- kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADESYSCONFIG:status.upgradesysconfigs.version'
+ kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'
```
* 再次查看节点的配置的版本确认节点是否配置完成(NODESTATUS恢复为idle)
```shell
- kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADESYSCONFIG:status.upgradesysconfigs.version'
+ kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'
```
-* 如果后续需要再次升级，与上面相同对 upgrade_v1alpha1_os.yaml 的相应字段进行相应修改。
+* 如果后续需要再次配置，与上面相同对 upgrade_v1alpha1_os.yaml 的相应字段进行相应修改。
#### 回退指导
* 回退场景
- * 虚拟机无法正常启动时，需要退回到上一可以启动的版本时进行回退操作，仅支持手动回退容器 OS 。
- * 虚拟机能够正常启动并且进入系统，需要将当前版本退回到老版本时进行回退操作，支持工具回退（类似升级方式）和手动回退，建议使用工具回退。
- * 配置出现错误，节点状态陷入config时，可以回退至上一个配置版本以恢复节点至idle状态。
- **注意**：在配置新版本时，出现错误前已经配置的参数无法回退。
+ * 虚拟机无法正常启动时，可在grub启动项页面手动切换启动项，使系统回退至上一版本（即手动回退）。
+ * 虚拟机能够正常启动并且进入系统时，支持工具回退和手动回退，建议使用工具回退。
+ * 工具回退有两种方式：
+ 1. rollback模式直接回退至上一版本。
+ 2. upgrade模式重新升级至上一版本
* 手动回退指导
- * 手动重启虚拟机，选择第二启动项进行回退，手动回退仅支持回退到本次升级之前的版本。
+
+ * 手动重启虚拟机，进入启动项页面后，选择第二启动项进行回退，手动回退仅支持回退到上一个版本。
* 工具回退指导
* 回退至任意版本
- * 修改 OS 的cr实例的YAML 配置文件（例如 upgrade_v1alpha1_os.yaml），设置相应字段为期望回退的老版本镜像信息。类别OS来自于安装和部署章节创建的CRD对象，字段说明及示例请见上一节升级指导。
+ * 修改 OS 的cr实例的YAML 配置文件（例如 upgrade_v1alpha1_os.yaml），设置相应字段为期望回退的老版本镜像信息。类别OS来自于安装和部署章节创建的CRD对象，字段说明及示例请见上一节升级指导。
+
* YAML修改完成后执行更新命令，在集群中更新定制对象后，节点会根据配置的字段信息进行回退
```shell
@@ -444,13 +516,13 @@
sysconfigs:
version: previous config version
configs:
- - model: kernel.systcl
+ - model: kernel.sysctl
contents:
- key: kernel param key1
value: kernel param value1
- key: kernel param key2
value: kernel param value2
- - model: kernel.systcl.persist
+ - model: kernel.sysctl.persist
configpath: persist file path
contents:
- key: kernel param key3
@@ -467,23 +539,21 @@
* 查看节点容器 OS 版本(回退OS版本)或节点config版本&节点状态为idle(回退config版本)，确认回退是否成功。
```shell
- kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage'
-
- kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADESYSCONFIG:status.upgradesysconfigs.version'
+ kubectl get osinstances -o custom-columns='NAME:.metadata.name,NODESTATUS:.spec.nodestatus,SYSCONFIG:status.sysconfigs.version,UPGRADECONFIG:status.upgradeconfigs.version'
```
-#### Admin容器
+## Admin容器镜像制作、部署和使用
KubeOS提供一个分离的包含sshd服务和hostshell工具的Admin容器，来帮助管理员在必要情况下登录KubeOS，其中的sshd服务由[sysmaster](https://gitee.com/openeuler/sysmaster)/systemd拉起。Admin容器部署后用户可通过ssh连接到节点的Admin容器，进入Admin容器后执行hostshell命令获取host的root shell。
-##### 部署方法
+### admin容器镜像制作
-以sysmaster为例，根据系统版本和架构，获取对应的sysmaster RPM包，如获取openEuler-22.03-LTS-aarch64版本的[sysmaster](https://repo.openeuler.org/openEuler-22.03-LTS-SP2/everything/aarch64/Packages/)到scripts/admin-container目录下。
+以sysmaster为例，根据系统版本和架构，获取对应的sysmaster RPM包，如获取openEuler-22.03-LTS-SP1-aarch64版本的[sysmaster](https://repo.openeuler.org/openEuler-22.03-LTS-SP1/update/aarch64/Packages/)到scripts/admin-container目录下。
-**修改**admin-container目录下的Dockerfile，指定sysmaster RPM包的路径，其中的openeuler-22.03-lts可在[openEuler Repo](https://repo.openeuler.org/openEuler-22.03-LTS-SP2/docker_img)下载。
+修改admin-container目录下的Dockerfile，指定sysmaster RPM包的路径，其中的openeuler-22.03-lts-sp1可在[openEuler Repo](https://repo.openeuler.org/openEuler-22.03-LTS-SP1/docker_img)下载。
```Dockerfile
-FROM openeuler-22.03-lts
+FROM openeuler-22.03-lts-sp1
RUN yum -y install openssh-clients util-linux
@@ -514,7 +584,9 @@ bash -x kbimg.sh create admin-image -f admin-container/Dockerfile -d your_imageR
docker push your_imageRepository/admin_imageName:version
```
-在master节点上部署Admin容器，需要提供ssh公钥来免密登录，**修改**并应用如下示例yaml文件:
+### admin容器部署
+
+在master节点上部署Admin容器，需要提供ssh公钥来免密登录，修改并应用如下示例yaml文件:
```yaml
apiVersion: v1
@@ -583,6 +655,8 @@ spec:
control-plane: admin-container-sysmaster
```
+### admin容器使用
+
ssh到Admin容器，然后执行hostshell命令进入host root shell, 如：
```shell
@@ -590,7 +664,7 @@ ssh -p your-exposed-port root@your.worker.node.ip
hostshell
```
-##### hostshell
+#### hostshell说明
为了保证KubeOS的轻便性，许多工具或命令没有安装在KubeOS内。因此，用户可以在制作Admin容器时，将期望使用的二进制文件放在容器内的如/usr/bin目录下。hostshell工具在执行时会将容器下的/usr/bin, /usr/sbin, /usr/local/bin, /usr/local/sbin路径添加到host root shell的环境变量。
@@ -605,11 +679,10 @@ hostshell
#### kernel Settings
-* kenerl.sysctl: 设置内核参数，key/value 表示内核参数的 key/value, 示例如下:
-
+* kenerl.sysctl：临时设置内核参数，重启后无效，key/value 表示内核参数的 key/value， key与value均不能为空且key不能包含“=”，该参数不支持删除操作（operation=delete）示例如下:
```yaml
configs:
- - model: kernel.systcl
+ - model: kernel.sysctl
contents:
- key: user.max_user_namespaces
value: 16384
@@ -617,12 +690,10 @@ hostshell
value: 0
operation: delete
```
-
-* kernel.sysctl.persist: 设置持久化内核参数，key/value 表示内核参数的 key/value, configpath为配置修改/新建的文件路径，如不指定configpath默认修改/etc/sysctl.conf
-
+* kenerl.sysctl：临时设置内核参数，重启后无效，key/value 表示内核参数的 key/value， key与value均不能为空且key不能包含“=”，该参数不支持删除操作（operation=delete）示例如下:
```yaml
configs:
- - model: kernel.systcl.persist
+ - model: kernel.sysctl.persist
configpath : /etc/persist.conf
contents:
- key: user.max_user_namespaces
@@ -637,22 +708,38 @@ hostshell
* grub.cmdline: 设置grub.cfg文件中的内核引导参数，该行参数在grub.cfg文件中类似如下示例：
```shell
- linux /boot/vmlinuz root=UUID=5b1aaf5d-5b25-4e4b-a0d3-3d4c8d2e6a6e ro consoleblank=600 console=tty0 console=ttyS0,115200n8 selinux=1 panic=3
- ```
+ linux /boot/vmlinuz root=/dev/sda2 ro rootfstype=ext4 nomodeset quiet oops=panic softlockup_panic=1 nmi_watchdog=1 rd.shell=0 selinux=0 crashkernel=256M panic=3
+ ```
- key/value 表示如上示例中内核引导参数的 key=value。
- **注意：** 当该参数有多个等号，如root=UUID=some-uuid时，配置时的key为第一个等号前的所有字符，value为第一个等号后的所有字符。
- 配置方法示例如下：
+* KubeOS使用双分区，grub.cmdline支持对当前分区或下一分区进行配置：
+
+ - grub.cmdline.current：对当前分区的启动项参数进行配置。
+ - grub.cmdline.next：对下一分区的启动项参数进行配置。
+
+* 注意：升级/回退前后的配置，始终基于升级/回退操作下发时的分区位置进行current/next的区分。假设当前分区为A分区，下发升级操作并在sysconfigs（升级重启后配置）中配置grub.cmdline.current，重启后进行配置时仍修改A分区对应的grub cmdline。
+
+* grub.cmdline.current/next支持“key=value”（value不能为空），也支持单key。若value中有“=”，例如“root=UUID=some-uuid”，key应设置为第一个“=”前的所有字符，value为第一个“=”后的所有字符。 配置方法示例如下：
```yaml
configs:
- - model: grub.cmdline
- contents:
- - key: selinux
- value: 0
- - key: root
- value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94
- - key: panic
- value: 3
- operation: delete
+ - model: grub.cmdline.current
+ contents:
+ - key: selinux
+ value: "0"
+ - key: root
+ value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94
+ - key: panic
+ value: "3"
+ operation: delete
+ - key: crash_kexec_post_notifiers
+ - model: grub.cmdline.next
+ contents:
+ - key: selinux
+ value: "0"
+ - key: root
+ value: UUID=e4f1b0a0-590e-4c5f-9d8a-3a2c7b8e2d94
+ - key: panic
+ value: "3"
+ operation: delete
+ - key: crash_kexec_post_notifiers
```
--
2.34.1
Reference in New Issue Copy Permalink