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
Yuhang Wei f2256bb8f5 sync branch to openEuler-22.03-LTS-SP1 
Signed-off-by: Yuhang Wei <weiyuhang3@huawei.com>
(cherry picked from commit 9186039f774168dfbacef04dac8ee56356149736)
2024-03-13 17:11:26 +08:00

618 lines
39 KiB
Diff
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 View Git Blame Copy Permalink