diff --git a/docs/zh/docs/Kmesh/figures/get_kubeconfig_error.png b/docs/zh/docs/Kmesh/figures/get_kubeconfig_error.png deleted file mode 100644 index 99087b68c6fafea1506e5f8bd862c371e93bdc97..0000000000000000000000000000000000000000 Binary files a/docs/zh/docs/Kmesh/figures/get_kubeconfig_error.png and /dev/null differ diff --git a/docs/zh/docs/Kmesh/figures/not_set_cluster_ip.png b/docs/zh/docs/Kmesh/figures/not_set_cluster_ip.png deleted file mode 100644 index 9c879f37fa93c0f4fe0ab0f6220beff174e5f436..0000000000000000000000000000000000000000 Binary files a/docs/zh/docs/Kmesh/figures/not_set_cluster_ip.png and /dev/null differ diff --git "a/docs/zh/docs/Kmesh/\345\270\270\350\247\201\351\227\256\351\242\230\344\270\216\350\247\243\345\206\263\346\226\271\346\263\225.md" "b/docs/zh/docs/Kmesh/\345\270\270\350\247\201\351\227\256\351\242\230\344\270\216\350\247\243\345\206\263\346\226\271\346\263\225.md" deleted file mode 100644 index a8b92c15bb19ee4f0a3226af5b359a1fbab1dd3f..0000000000000000000000000000000000000000 --- "a/docs/zh/docs/Kmesh/\345\270\270\350\247\201\351\227\256\351\242\230\344\270\216\350\247\243\345\206\263\346\226\271\346\263\225.md" +++ /dev/null @@ -1,23 +0,0 @@ -# 常见问题及解决方法 - -## 问题1：在使用集群启动模式时，若没有配置控制面程序ip信息，Kmesh服务启动后会报错退出 - -![](./figures/not_set_cluster_ip.png) - -原因：集群启动模式下，Kmesh服务需要跟控制面程序通信，然后从控制面获取配置信息，因此需要设置正确的控制面程序ip信息。 - -解决方法：参考[安装与部署](./安装与部署.md)章节中集群启动模式，设置正确的控制面程序ip信息。 - -## 问题2：Kmesh服务在启动时,提示"get kube config error!" - -![](./figures/get_kubeconfig_error.png) - -原因：集群启动模式下，Kmesh服务会根据k8s的配置，自动获取控制面程序ip信息，若环境中没有配置k8s的kubeconfig路径，会导致获取kubeconfig失败，然后提示上述信息。（若已经手动修改Kmesh的配置文件，正确配置控制面程序ip信息，该问题可忽略） - -解决方法：按如下方式配置kubeconfig： - -```shell -mkdir -p $HOME/.kube -sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config -sudo chown $(id -u):$(id -g) $HOME/.kube/config -``` diff --git a/docs/zh/docs/cloud/_toc.yaml b/docs/zh/docs/cloud/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..b81cf5d17bb43f175f3a378fcdcc827a19716a17 --- /dev/null +++ b/docs/zh/docs/cloud/_toc.yaml @@ -0,0 +1,32 @@ +label: 云原生 +sections: + - label: 容器引擎 + sections: + - href: ./container_engine/isula_container_engine/_toc.yaml + - href: ./container_engine/docker_engine/_toc.yaml + - label: 容器形态 + sections: + - href: ./container_form/secure_container/_toc.yaml + - href: ./container_form/system_container/_toc.yaml + - label: 容器运行时 + sections: + - href: ./container_runtime/kuasar/_toc.yaml + - label: 容器镜像构建工具 + sections: + - href: ./image_builder/isula_build/_toc.yaml + - label: 云原生操作系统 + sections: + - href: ./kubeos/kubeos/_toc.yaml + - label: 云底座操作系统 + sections: + - href: ./nestos/nestos/_toc.yaml + - label: 混合部署 + sections: + - href: ./hybrid_deployment/rubik/_toc.yaml + - href: ./hybrid_deployment/oncn_bwm/_toc.yaml + - label: 集群部署 + sections: + - href: ./cluster_deployment/kubernetes/_toc.yaml + - label: 服务网格 + sections: + - href: ./kmesh/kmesh/_toc.yaml diff --git a/docs/zh/docs/cloud/container_runtime/.markdownlint.json b/docs/zh/docs/cloud/container_runtime/.markdownlint.json deleted file mode 100644 index 81f0eb7aae8fedbecf92202d0fb0962c6f05c8d3..0000000000000000000000000000000000000000 --- a/docs/zh/docs/cloud/container_runtime/.markdownlint.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "MD003":{"style":"atx"}, - "MD007":{"indent":4}, - "MD029":{"style":"ordered"}, - "MD009":false, - "MD013":false, - "MD014":false, - "MD020":false, - "MD021":false, - "MD024":false, - "MD025":false, - "MD033":false, - "MD036":false, - "MD042":false, - "MD043":false, - "MD044":false, - "MD045":false, - "MD048":false, - "MD049":false, - "MD050":false, - "MD051":false, - "MD052":false, - "MD053":false -} \ No newline at end of file diff --git a/docs/zh/docs/cloud/hybrid_deployment/oncn_bwm/_toc.yaml b/docs/zh/docs/cloud/hybrid_deployment/oncn_bwm/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..99b9aebd47c782de78a20f4496c348a59543dfe9 --- /dev/null +++ b/docs/zh/docs/cloud/hybrid_deployment/oncn_bwm/_toc.yaml @@ -0,0 +1,6 @@ +label: oncn-bwm用户指南 +isManual: true +description: 混合业务场景下的Pod带宽管理方案 +sections: + - label: 概述 + href: ./overview.md diff --git a/docs/zh/docs/oncn-bwm/overview.md b/docs/zh/docs/cloud/hybrid_deployment/oncn_bwm/overview.md similarity index 90% rename from docs/zh/docs/oncn-bwm/overview.md rename to docs/zh/docs/cloud/hybrid_deployment/oncn_bwm/overview.md index 4f4b973a3187385fb9edf680cabf14e2268ede8d..0185ed98963eb37fa6af327e490d1bfab24bbb7c 100644 --- a/docs/zh/docs/oncn-bwm/overview.md +++ b/docs/zh/docs/cloud/hybrid_deployment/oncn_bwm/overview.md @@ -31,7 +31,7 @@ yum install oncn-bwm oncn-bwm工具提供了`bwmcli`命令行工具来使能Pod带宽管理或进行相关配置。`bwmcli`命令的整体格式如下： -**bwmcli** < option(s) > +**bwmcli** \< option(s) > > 说明： > @@ -51,8 +51,8 @@ oncn-bwm工具提供了`bwmcli`命令行工具来使能Pod带宽管理或进行 | 命令格式 | 功能 | | --------------------------- | ------------------------------------------------------------ | -| **bwmcli -e** <网卡名称> | 使能指定网卡的Pod带宽管理。 | -| **bwmcli -d** <网卡名称> | 去除指定网卡的Pod带宽管理。 | +| **bwmcli -e** \<网卡名称> | 使能指定网卡的Pod带宽管理。 | +| **bwmcli -d** \<网卡名称> | 去除指定网卡的Pod带宽管理。 | | **bwmcli -p devs** | 查询节点所有网卡的Pod带宽管理。 | > 说明： @@ -96,7 +96,7 @@ oncn-bwm工具提供了`bwmcli`命令行工具来使能Pod带宽管理或进行 | 命令格式 | 功能 | | ------------------------------------------------------------ | ------------------------------------------------------------ | -| **bwmcli -s** *path* ** | 设置Pod网络优先级。其中*path*为Pod对应的cgroup路径，*prio*为优先级。*path*取相对路径或者绝对路径均可。 *prio*默认值为0，可选值为0和-1，0标识为在线业务，-1标识为离线业务。 | +| **bwmcli -s** path \ | 设置Pod网络优先级。其中*path*为Pod对应的cgroup路径，*prio*为优先级。*path*取相对路径或者绝对路径均可。 *prio*默认值为0，可选值为0和-1，0标识为在线业务，-1标识为离线业务。 | | **bwmcli -p** *path* | 查询Pod网络优先级。 | > 说明： @@ -123,7 +123,7 @@ oncn-bwm工具提供了`bwmcli`命令行工具来使能Pod带宽管理或进行 | 命令格式 | 功能 | | ------------------------------------ | ------------------------------------------------------------ | -| **bwmcli -s bandwidth** ** | 设置一个主机/虚拟机的离线带宽。其中*low*表示最低带宽，*high*表示最高带宽，其单位可取值为kb/mb/gb，有效范围为[1mb, 9999gb]。| +| **bwmcli -s bandwidth** \ | 设置一个主机/虚拟机的离线带宽。其中*low*表示最低带宽，*high*表示最高带宽，其单位可取值为kb/mb/gb，有效范围为[1mb, 9999gb]。| | **bwmcli -p bandwidth** | 查询设置一个主机/虚拟机的离线带宽。 | > 说明： @@ -156,7 +156,7 @@ oncn-bwm工具提供了`bwmcli`命令行工具来使能Pod带宽管理或进行 | 命令格式 | 功能 | | ---------------------------------------------- | ------------------------------------------------------------ | -| **bwmcli -s waterline** ** | 设置一个主机/虚拟机的在线业务水线，其中*val*为水线值，单位可取值为kb/mb/gb ，有效范围为[20mb, 9999gb]。 | +| **bwmcli -s waterline** \ | 设置一个主机/虚拟机的在线业务水线，其中*val*为水线值，单位可取值为kb/mb/gb ，有效范围为[20mb, 9999gb]。 | | **bwmcli -p waterline** | 查询一个主机/虚拟机的在线业务水线。 | > 说明： diff --git a/docs/zh/docs/cloud/hybrid_deployment/rubik/_toc.yaml b/docs/zh/docs/cloud/hybrid_deployment/rubik/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..7a93bd0b000498990717e7607c173f2edc3f7ace --- /dev/null +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/_toc.yaml @@ -0,0 +1,16 @@ +label: 云原生混合部署rubik用户指南 +isManual: true +description: 在业务混合部署的场景下，根据QoS分级，对资源进行合理调度 +sections: + - label: 概述 + href: ./overview.md + - label: 安装与部署 + href: ./installation_and_deployment.md + - label: 特性介绍 + href: ./feature_introduction.md + - label: 配置文档 + href: configuration.md + - label: ./混部隔离示例 + href: ./example_of_isolation_for_hybrid_deployed_services.md + - label: 附录 + href: ./appendix.md diff --git "a/docs/zh/docs/rubik/\351\231\204\345\275\225.md" b/docs/zh/docs/cloud/hybrid_deployment/rubik/appendix.md similarity index 93% rename from "docs/zh/docs/rubik/\351\231\204\345\275\225.md" rename to docs/zh/docs/cloud/hybrid_deployment/rubik/appendix.md index 098554e053449d01472e94a7bbe937594f99e6a2..047c30c0d80464d4c9825b83af27a0089355a845 100644 --- "a/docs/zh/docs/rubik/\351\231\204\345\275\225.md" +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/appendix.md @@ -136,7 +136,7 @@ spec: ## Dockerfile 模板 -```dockefile +```dockerfile FROM scratch COPY ./build/rubik /rubik ENTRYPOINT ["/rubik"] @@ -228,9 +228,9 @@ sed -i "/image:/s/:.*/: ${IMG_NAME_AND_TAG}/" "${YAML_FILE}" - CPU 和 memory 的在线、离线配置需要统一，否则可能导致两个子系统的 QoS 冲突 - 使用混部后，原始的 CPU share 功能存在限制。具体表现为： - - 若当前 CPU 中同时存放在线任务和离线任务，则离线任务的 CPU share 无法生效 - - 若当前 CPU 中只有在线任务或只有离线任务，CPU share 能生效 - - 建议离线业务 Pod 优先级配置为 best effort + - 若当前 CPU 中同时存放在线任务和离线任务，则离线任务的 CPU share 无法生效 + - 若当前 CPU 中只有在线任务或只有离线任务，CPU share 能生效 + - 建议离线业务 Pod 优先级配置为 best effort - 用户态的优先级反转、smt、cache、numa 负载均衡、离线任务的负载均衡，当前不支持 @@ -239,14 +239,14 @@ sed -i "/image:/s/:.*/: ${IMG_NAME_AND_TAG}/" "${YAML_FILE}" 禁止用户直接手动修改 Pod 对应 cgroup 或 resctrl 参数，否则可能出现数据不一致情况。 - CPU cgroup 目录， 如：`/sys/fs/cgroup/cpu/kubepods/burstable//` - - cpu.qos_level - - cpu.cfs_burst_us + - cpu.qos_level + - cpu.cfs_burst_us - memory cgroup 目录，如：`/sys/fs/cgroup/memory/kubepods/burstable//` - - memory.qos_level - - memory.soft_limit_in_bytes - - memory.force_empty - - memory.limit_in_bytes - - memory.high + - memory.qos_level + - memory.soft_limit_in_bytes + - memory.force_empty + - memory.limit_in_bytes + - memory.high - RDT 控制组目录，如：`/sys/fs/resctrl` diff --git "a/docs/zh/docs/rubik/\351\205\215\347\275\256\346\226\207\346\241\243.md" b/docs/zh/docs/cloud/hybrid_deployment/rubik/configuration.md similarity index 95% rename from "docs/zh/docs/rubik/\351\205\215\347\275\256\346\226\207\346\241\243.md" rename to docs/zh/docs/cloud/hybrid_deployment/rubik/configuration.md index 001eb16809e987c4acde180f94285fd99d166766..0ac09bc8bbcecc7d586560b91c5863c922e57ab1 100644 --- "a/docs/zh/docs/rubik/\351\205\215\347\275\256\346\226\207\346\241\243.md" +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/configuration.md @@ -21,10 +21,10 @@ OS/Arch: linux/amd64 执行rubik二进制时，rubik首先会解析配置文件，配置文件的路径固定为`/var/lib/rubik/config.json`。 -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > -> 1. 为避免配置混乱，暂不支持指定其他路径。 -> 2. rubik支持以daemonset形式运行在kubernetes集群中。我们提供了yaml脚本（`hack/rubik-daemonset.yaml`），并定义了`ConfigMap`作为配置。因此，以daemonset形式运行rubik时，应修改`hack/rubik-daemonset.yaml`中的相应配置。 +> - 为避免配置混乱，暂不支持指定其他路径。 +> - ubik支持以daemonset形式运行在kubernetes集群中。我们提供了yaml脚本（`hack/rubik-daemonset.yaml`），并定义了`ConfigMap`作为配置。因此，以daemonset形式运行rubik时，应修改`hack/rubik-daemonset.yaml`中的相应配置。 配置文件采用json格式，字段键采用驼峰命名规则，且首字母小写。 配置文件示例内容如下： @@ -122,6 +122,7 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 ### agent `agent`配置用于记录保存rubik运行的通用配置，例如日志、cgroup挂载点等信息。 + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | ------------------------- | ---------- | -------------------------------------- | --------------------------- | | logDriver=stdio | string | 日志驱动，支持标准输出和文件 | stdio, file | @@ -160,6 +161,7 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 ### quotaTurbo `quotaTurbo`字段用于标识支持弹性限流技术（用户态）配置。 + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | ----------------- | ------ | -------------------------------- | -------------------- | | highWaterMark=60 | int | CPU负载的高水位值 |\[0,警戒水位) | @@ -169,12 +171,14 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 ### ioCost `ioCost`字段用于标识支持iocost对IO权重控制特性配置。其类型为数组，数组中的每一个元素由节点名称`nodeName`和设备参数数组`config`组成。 + | 配置键 | 类型 | 描述 | 可选值 | | ----------------- | ------ | -------------------------------- | -------------------- | | nodeName | string | 节点名称 | kubernetes中节点名称 | | config | 数组 | 单个设备的配置信息 | / | 单个块设备配置`config`参数： + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | --------------- | ------ | --------------------------------------------- | -------------- | | dev | string | 块设备名称，仅支持物理设备 | / | @@ -182,6 +186,7 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 | param | / | 设备参数，根据不同模型有不同参数 | / | 模型为linear时，`param`字段支持如下参数： + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | --------------- | ---- | ---- | ------ | |rbps | int64 | 块设备最大读带宽 | （0, $2^{63}$) | @@ -194,6 +199,7 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 ### psi `psi`字段用于标识基于psi指标的干扰检测特性配置。目前，psi特性支持监测CPU、内存和I/O资源，用户可以按需配置该字段，单独或组合监测资源的PSI取值。 + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | --------------- | ---------- | -------------------------------- | ----------- | | interval=10 |int|psi指标监测间隔（单位：秒）| [10,30]| @@ -203,6 +209,7 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 ### CPU驱逐水位线控制 `cpuevict`字段用于标识CPU驱逐水位线控制特性配置。该特性依照指定采样间隔采集节点CPU利用率，并统计指定窗口内的CPU平均利用率。若CPU平均利用率大于驱逐水位线，则驱逐离线Pod。一旦rubik驱逐离线Pod，则在冷却时间内不再驱逐Pod。 + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | --------------- | ---------- | -------------------------------- | ----------- | | threshold=60 | int | 窗口期内平均CPU利用率的阈值(%)，超过该阈值，则驱逐离线Pod | [1,99]| @@ -213,8 +220,9 @@ Rubik配置分为两类：通用配置和特性配置。通用配置由agent关 ### 内存驱逐水位线控制 `memoryevict`字段用于标识内存驱逐水位线控制特性配置。该特性依照指定采样间隔采集节点内存利用率。若节点内存利用率大于驱逐水位线，则驱逐离线Pod。一旦rubik驱逐离线Pod，则在冷却时间内不再驱逐Pod。 + | 配置键[=默认值] | 类型 | 描述 | 可选值 | | --------------- | ---------- | -------------------------------- | ----------- | | threshold | int | 内存利用率的阈值(%)，超过该阈值，则驱逐离线Pod。若不指定该值，则无法使用本功能。 | [1,99]| | interval=1 | int | 节点CPU利用率采集间隔(s) | [1, 3600] | -| cooldown=4 | int | 冷却时间（s），两次驱逐之间至少需要间隔冷却时间 | [1, 9223372036854775806]| \ No newline at end of file +| cooldown=4 | int | 冷却时间（s），两次驱逐之间至少需要间隔冷却时间 | [1, 9223372036854775806]| diff --git "a/docs/zh/docs/rubik/\346\267\267\351\203\250\351\232\224\347\246\273\347\244\272\344\276\213.md" b/docs/zh/docs/cloud/hybrid_deployment/rubik/example_of_isolation_for_hybrid_deployed_services.md similarity index 99% rename from "docs/zh/docs/rubik/\346\267\267\351\203\250\351\232\224\347\246\273\347\244\272\344\276\213.md" rename to docs/zh/docs/cloud/hybrid_deployment/rubik/example_of_isolation_for_hybrid_deployed_services.md index 46ea8634236abe117cdf476e2727f3f2b077d6e4..531a3a7b03330bf638ae40dee610cd04191232fe 100644 --- "a/docs/zh/docs/rubik/\346\267\267\351\203\250\351\232\224\347\246\273\347\244\272\344\276\213.md" +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/example_of_isolation_for_hybrid_deployed_services.md @@ -84,7 +84,7 @@ function prepare() { yandex/clickhouse-server) sleep 3 - echo "Clickhouse container lauched." + echo "Clickhouse container launched." } function clickhouse() { diff --git a/docs/zh/docs/rubik/modules.md b/docs/zh/docs/cloud/hybrid_deployment/rubik/feature_introduction.md similarity index 89% rename from docs/zh/docs/rubik/modules.md rename to docs/zh/docs/cloud/hybrid_deployment/rubik/feature_introduction.md index a6e651b0b889de33163f25a3bd094832ab4e5bf6..07cc3d6453d0fdcc96b29b39a432b250d0728d0b 100644 --- a/docs/zh/docs/rubik/modules.md +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/feature_introduction.md @@ -22,7 +22,7 @@ rubik支持业务优先级配置，针对在离线业务混合部署的场景， ... ``` -配置参数详见[配置文档](./%E9%85%8D%E7%BD%AE%E6%96%87%E6%A1%A3.md#preemption)。 +配置参数详见[配置文档](./configuration.md#preemption)。 同时，用户需要在pod的yaml注解中增加`volcano.sh/preemptable`字段来指定业务优先级。业务优先级配置示例如下： @@ -31,7 +31,7 @@ annotations: volcano.sh/preemptable: true ``` -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > 在rubik中，所有特性均通过识别`volcano.sh/preemptable`注解作为业务在离线标志。true代表业务为离线业务，false代表业务为在线业务。 @@ -47,8 +47,8 @@ annotations: - /sys/fs/cgroup/cpu 目录下容器的 cgroup 中，如`/sys/fs/cgroup/cpu/kubepods/burstable//`目录。 - cpu.qos_level：开启 CPU 优先级配置，默认值为 0， 有效值为 0 和-1。 - - 0：标识为在线业务。 - - -1：标识为离线业务。 + - 0：标识为在线业务。 + - -1：标识为离线业务。 ### 内存绝对抢占 @@ -62,13 +62,13 @@ annotations: **内核接口** - /proc/sys/vm/memcg_qos_enable：开启内存优先级特性，默认值为 0，有效值为 0 和 1。开启命令为：`echo 1 > /proc/sys/vm/memcg_qos_enable`。 - - 0：表示关闭特性。 - - 1：表示开启特性。 + - 0：表示关闭特性。 + - 1：表示开启特性。 - /sys/fs/cgroup/memory 目录下容器的 cgroup 中，如`/sys/fs/cgroup/memory/kubepods/burstable//`目录 - - memory.qos_level：开启内存优先级配置，默认值为 0，有效值为 0 和-1。 - - 0：标识为在线业务。 - - -1：标识为离线业务。 + - memory.qos_level：开启内存优先级配置，默认值为 0，有效值为 0 和-1。 + - 0：标识为在线业务。 + - -1：标识为离线业务。 ## dynCache 访存带宽和LLC限制 @@ -77,8 +77,8 @@ rubik 支持业务的 Pod 访存带宽(memory bandwidth)和 LLC(Last Level Cache **前置条件**： - cache/访存限制功能仅支持物理机，不支持虚拟机。 - - X86 物理机，需要 OS 支持且开启 intel RDT 的 CAT 和 MBA 功能，内核启动项 cmdline 需要添加`rdt=l3cat,mba` - - ARM 物理机，需要 OS 支持且开启 mpam 功能，内核启动项需要添加`mpam=acpi`。 + - X86 物理机，需要 OS 支持且开启 intel RDT 的 CAT 和 MBA 功能，内核启动项 cmdline 需要添加`rdt=l3cat,mba` + - ARM 物理机，需要 OS 支持且开启 mpam 功能，内核启动项需要添加`mpam=acpi`。 - 由于内核限制，RDT mode 当前不支持 pseudo-locksetup 模式。 - 用户需手动挂载目录`/sys/fs/resctrl`。 rubik 需要读取和设置`/sys/fs/resctrl` 目录下的文件，该目录需在 rubik 启动前挂载，且需保障在 rubik 运行过程中不被卸载。 - rubik运行依赖SYS_ADMIN权限. 设置主机`/sys/fs/resctrl` 目录下的文件需要 rubik 容器被赋有 SYS_ADMIN 权限。 @@ -98,8 +98,8 @@ rubik支持两种方式为业务Pod配置访存带宽和LLC控制组： - 全局方式 用户可在rubik的全局参数中配置`defaultLimitMode`字段，rubik会自动为离线业务Pod（即绝对抢占特性中的注解`volcano.sh/preemptable`）配置控制组。 - - 取值为`static`时，pod将被加入到`rubik_max`控制组。 - - 取值为`dynamic`时，pod将被加入到`rubik_dynamic`控制组。 + - 取值为`static`时，pod将被加入到`rubik_max`控制组。 + - 取值为`dynamic`时，pod将被加入到`rubik_dynamic`控制组。 - 手动指定 用户可手动通过为业务Pod增加注解`volcano.sh/cache-limit`设置其 cache level, 并被加入到指定的控制组中。如下列配置的pod将被加入rubik_low控制组: @@ -109,11 +109,11 @@ rubik支持两种方式为业务Pod配置访存带宽和LLC控制组： volcano.sh/cache-limit: "low" ``` -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > -> 1. cache限制只针对离线业务。 +> - cache限制只针对离线业务。 > -> 2. 手动指定注解优先于全局方式。即，若用户在rubik的全局参数中配置了`defaultLimitMode`字段，并且在业务 Pod yaml 中指定了cache level，则dynCache限制将以Pod yaml中的注解为准。 +> - 手动指定注解优先于全局方式。即，若用户在rubik的全局参数中配置了`defaultLimitMode`字段，并且在业务 Pod yaml 中指定了cache level，则dynCache限制将以Pod yaml中的注解为准。 ### dynCache 内核接口 @@ -278,12 +278,12 @@ quotaBurst通过配置容器的`cpu.cfs_burst_us`内核接口，允许容器在 - cpu.cfs_burst_us -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > 内核态通过内核接口cpu.cfs_burst_us实现。支持内核态配置需要确认cgroup的cpu子系统目录下存在cpu.cfs_burst_us文件，其值约束如下： > -> 1. 当cpu.cfs_quota_us的值不为-1时，需满足cfs_burst_us + cfs_quota_us <= $2^{44}$-1 且 cfs_burst_us <= cfs_quota_us。 -> 2. 当cpu.cfs_quota_us的值为-1时，CPU burst功能不生效，cfs_burst_us默认为0，不支持配置其他任何值。 +> - 当cpu.cfs_quota_us的值不为-1时，需满足cfs_burst_us + cfs_quota_us <= $2^{44}$-1 且 cfs_burst_us <= cfs_quota_us。 +> - 当cpu.cfs_quota_us的值为-1时，CPU burst功能不生效，cfs_burst_us默认为0，不支持配置其他任何值。 #### quotaBurst配置详解 @@ -317,11 +317,11 @@ quotaBurst 功能相关的配置如下： ### 约束限制 - 用户态通过CFS bandwidth control调整cpu.cfs_period_us和cpu.cfs_quota_us参数实现CPU带宽控制。因此用户态约束如下： - - 禁止第三方更改CFS bandwidth control相关参数（包括但不限于cpu.cfs_quota_us、cpu.cfs_period_us等文件），以避免未知错误。 - - 禁止与具有限制CPU资源功能的同类产品同时使用，否则导致用户态功能无法正常使用。 - - 若用户监控CFS bandwidth control相关指标，使用本特性可能会破坏监测指标的一致性。 + - 禁止第三方更改CFS bandwidth control相关参数（包括但不限于cpu.cfs_quota_us、cpu.cfs_period_us等文件），以避免未知错误。 + - 禁止与具有限制CPU资源功能的同类产品同时使用，否则导致用户态功能无法正常使用。 + - 若用户监控CFS bandwidth control相关指标，使用本特性可能会破坏监测指标的一致性。 - 内核态约束如下： - - 用户应使用k8s接口设置pod的busrt值，禁止用户手动直接修改容器的cpu cgroup目录下的cpu.cfs_burst_us文件。 + - 用户应使用k8s接口设置pod的busrt值，禁止用户手动直接修改容器的cpu cgroup目录下的cpu.cfs_burst_us文件。 - 禁止用户同时使能弹性限流用户态和内核态方案。 ## ioCost 支持iocost对IO权重控制 @@ -380,7 +380,7 @@ rubik 支持通过在 cgroup v1 下的 iocost 控制不同 Pod 的 io 权重分 配置参数详见[配置文档](./%E9%85%8D%E7%BD%AE%E6%96%87%E6%A1%A3.md#iocost)。 -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > iocost linear 模型相关参数可以通过 iocost_coef_gen.py 脚本获取，可以从[此链接](https://github.com/torvalds/linux/blob/master/tools/cgroup/iocost_coef_gen.py)获得。 @@ -448,7 +448,7 @@ reboot rubik支持通过根据节点CPU利用率驱逐离线Pod从而避免节点CPU资源过载。用户可以配置CPU驱逐水位线，rubik会统计指定窗口期间节点的平均CPU利用率。若窗口期内平均CPU利用率大于CPU驱逐水位线，则rubik则驱逐资源利用率高且运行时间较短的离线Pod，释放相应资源。 -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > 在离线业务由注解`volcano.sh/preemptable="true"/"false"`标识。 > @@ -481,7 +481,7 @@ rubik支持通过根据节点CPU利用率驱逐离线Pod从而避免节点CPU资 rubik支持通过根据节点内存利用率驱逐离线Pod从而避免节点内存资源过载。用户可以配置内存驱逐水位线。若节点内存利用率大于内存驱逐水位线，则rubik则驱逐资源利用率高且运行时间较短的离线Pod，释放相应资源。 -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > 在离线业务由注解`volcano.sh/preemptable="true"/"false"`标识。 > diff --git a/docs/zh/docs/cloud/hybrid_deployment/rubik/figures/icon-note.gif b/docs/zh/docs/cloud/hybrid_deployment/rubik/figures/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..eebb838c275843dfaf5b402c550e64eb887c1035 Binary files /dev/null and b/docs/zh/docs/cloud/hybrid_deployment/rubik/figures/icon-note.gif differ diff --git a/docs/zh/docs/cloud/hybrid_deployment/rubik/figures/iocost.PNG b/docs/zh/docs/cloud/hybrid_deployment/rubik/figures/iocost.PNG new file mode 100644 index 0000000000000000000000000000000000000000..c3eae863ad15d79d7e36c44799fc4dc946e8ca26 Binary files /dev/null and b/docs/zh/docs/cloud/hybrid_deployment/rubik/figures/iocost.PNG differ diff --git "a/docs/zh/docs/rubik/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" b/docs/zh/docs/cloud/hybrid_deployment/rubik/installation_and_deployment.md similarity index 86% rename from "docs/zh/docs/rubik/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" rename to docs/zh/docs/cloud/hybrid_deployment/rubik/installation_and_deployment.md index a6ceb3f6d06a29b576186a1c66f06516c06aebb4..ca2514fca6af45dc99952068bdab5fddf0e3215c 100644 --- "a/docs/zh/docs/rubik/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/installation_and_deployment.md @@ -29,7 +29,7 @@ rubik 以`DaemonSet`形式部署在 k8s 的每一个节点上，故需要在每 1. 配置 yum 源：rubik组件位于openEuler EPOL源中，以openEuler 24.03-LTS-SP1版本为例，参考如下： - ``` + ```sh # openEuler 24.03-LTS-SP1 官方发布源 name=openEuler24.03-LTS-SP1 baseurl=https://repo.openeuler.org/openEuler-24.03-LTS-SP1/everything/$basearch/ @@ -38,7 +38,7 @@ rubik 以`DaemonSet`形式部署在 k8s 的每一个节点上，故需要在每 gpgkey=https://repo.openeuler.org/openEuler-24.03-LTS-SP1/everything/$basearch/RPM-GPG-KEY-openEuler ``` - ``` + ```sh # openEuler 24.03-LTS-SP1:Epol 官方发布源 name=openEuler24.03-LTS-SP1-Epol baseurl=https://repo.openeuler.org/openEuler-24.03-LTS-SP1/EPOL/$basearch/ @@ -46,14 +46,14 @@ rubik 以`DaemonSet`形式部署在 k8s 的每一个节点上，故需要在每 gpgcheck=1 gpgkey=https://repo.openeuler.org/openEuler-24.03-LTS-SP1/everything/$basearch/RPM-GPG-KEY-openEuler ``` - + 2. 使用 root 权限安装 rubik： ```shell sudo yum install -y rubik ``` -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > rubik 工具相关文件会安装在/var/lib/rubik 目录下。 @@ -69,40 +69,40 @@ sudo echo 1 > /proc/sys/vm/memcg_qos_enable 1. 构建rubik镜像：使用`/var/lib/rubik/build_rubik_image.sh`脚本自动构建或者直接使用 docker容器引擎构建 rubik 镜像。由于 rubik 以 daemonSet 形式部署，故每一个节点都需要 rubik 镜像。用户可以在一个节点构建镜像后使用 docker save/load 功能将 rubik 镜像 load 到 k8s 的每一个节点，也可以在各节点上都构建一遍 rubik 镜像。以 docker 为例，其构建命令如下： -```sh -docker build -f /var/lib/rubik/Dockerfile -t rubik:2.0.1-2 . -``` + ```sh + docker build -f /var/lib/rubik/Dockerfile -t rubik:2.0.1-2 . + ``` 2. 在 k8s master 节点，修改`/var/lib/rubik/rubik-daemonset.yaml`文件中的 rubik 镜像名，与上一步构建出来的镜像名保持一致。 -```yaml -... -containers: -- name: rubik-agent - image: rubik_image_name_and_tag # 此处镜像名需与上一步构建的 rubik 镜像名一致 - imagePullPolicy: IfNotPresent -... -``` + ```yaml + ... + containers: + - name: rubik-agent + image: rubik_image_name_and_tag # 此处镜像名需与上一步构建的 rubik 镜像名一致 + imagePullPolicy: IfNotPresent + ... + ``` 3. 在 k8s master 节点，使用 kubectl 命令部署 rubik daemonset，rubik 会自动被部署在 k8s 的所有节点： -```sh -kubectl apply -f /var/lib/rubik/rubik-daemonset.yaml -``` + ```sh + kubectl apply -f /var/lib/rubik/rubik-daemonset.yaml + ``` 4. 使用`kubectl get pods -A`命令查看 rubik 是否已部署到集群每一个节点上（rubik-agent 数量与节点数量相同且均为 Running 状态）： -```sh -[root@localhost rubik]# kubectl get pods -A | grep rubik -NAMESPACE NAME READY STATUS RESTARTS AGE -... -kube-system rubik-agent-76ft6 1/1 Running 0 4s -... -``` + ```sh + [root@localhost rubik]# kubectl get pods -A | grep rubik + NAMESPACE NAME READY STATUS RESTARTS AGE + ... + kube-system rubik-agent-76ft6 1/1 Running 0 4s + ... + ``` ## 常用配置说明 -通过以上方式部署的 rubik 将以默认配置启动，用户可以根据实际需要修改 rubik 配置，可通过修改 rubik-daemonset.yaml 文件中的 config.json 段落内容后重新部署 rubik daemonset 实现。以下介绍几个常见配置，其他配置详见 [配置文档](./配置文档.md)。 +通过以上方式部署的 rubik 将以默认配置启动，用户可以根据实际需要修改 rubik 配置，可通过修改 rubik-daemonset.yaml 文件中的 config.json 段落内容后重新部署 rubik daemonset 实现。以下介绍几个常见配置，其他配置详见 [配置文档](./configuration.md)。 ### Pod 绝对抢占特性 @@ -124,7 +124,7 @@ kube-system rubik-agent-76ft6 1/1 Running ... ``` -> ![](./figures/icon-note.gif) **说明**： +> [!NOTE]说明 > > 优先级配置仅支持Pod由在线切换为离线，不允许由离线切换为在线。 diff --git a/docs/zh/docs/rubik/overview.md b/docs/zh/docs/cloud/hybrid_deployment/rubik/overview.md similarity index 81% rename from docs/zh/docs/rubik/overview.md rename to docs/zh/docs/cloud/hybrid_deployment/rubik/overview.md index d9fca47da6166509ca7185fcc62a5052919eee7d..54229a3f8380690a9e70fdaccc25281e105ddcdc 100644 --- a/docs/zh/docs/rubik/overview.md +++ b/docs/zh/docs/cloud/hybrid_deployment/rubik/overview.md @@ -9,13 +9,13 @@ rubik 容器调度在业务混合部署的场景下，根据 QoS 分级，对资 rubik 当前支持如下特性： - [preemption 绝对抢占](./modules.md#preemption-绝对抢占) - - [CPU绝对抢占](./modules.md#cpu绝对抢占) - - [内存绝对抢占](./modules.md#内存绝对抢占) + - [CPU绝对抢占](./modules.md#cpu绝对抢占) + - [内存绝对抢占](./modules.md#内存绝对抢占) - [dynCache 访存带宽和LLC限制](./modules.md#dyncache-访存带宽和llc限制) - [dynMemory 内存异步分级回收](./modules.md#dynmemory-内存异步分级回收) - [支持弹性限流](./modules.md#支持弹性限流) - - [quotaBurst 支持弹性限流内核态解决方案](./modules.md#quotaburst-内核态解决方案) - - [quotaTurbo 支持弹性限流用户态解决方案](./modules.md#quotaturbo-用户态解决方案) + - [quotaBurst 支持弹性限流内核态解决方案](./modules.md#quotaburst-内核态解决方案) + - [quotaTurbo 支持弹性限流用户态解决方案](./modules.md#quotaturbo-用户态解决方案) - [ioCost 支持iocost对IO权重控制](./modules.md#iocost-支持iocost对io权重控制) - [PSI 支持基于PSI指标的干扰检测](./modules.md#psi-支持基于psi指标的干扰检测) - [CPU驱逐水位线控制](./modules.md#cpu驱逐水位线控制) diff --git a/docs/zh/docs/cloud/kmesh/kemsh/_toc.yaml b/docs/zh/docs/cloud/kmesh/kemsh/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..7e1623fa8368c32c205689c5e2cb6023fd9ccf3c --- /dev/null +++ b/docs/zh/docs/cloud/kmesh/kemsh/_toc.yaml @@ -0,0 +1,14 @@ +label: Kmesh用户指南 +isManual: true +description: openEuler系统高性能服务网格数据面软件 +sections: + - label: 概述 + href: ./overview.md + - label: 认识Kmesh + href: ./getting_to_know_kmesh.md + - label: 安装与部署 + href: ./installation_and_deployment.md + - label: 使用方法 + href: ./usage.md + - label: 附录 + href: ./appendixes.md diff --git "a/docs/zh/docs/Kmesh/\351\231\204\345\275\225.md" b/docs/zh/docs/cloud/kmesh/kemsh/appendixes.md similarity index 100% rename from "docs/zh/docs/Kmesh/\351\231\204\345\275\225.md" rename to docs/zh/docs/cloud/kmesh/kemsh/appendixes.md diff --git a/docs/zh/docs/Kmesh/figures/kmesh-arch.png b/docs/zh/docs/cloud/kmesh/kemsh/figures/kmesh-arch.png similarity index 100% rename from docs/zh/docs/Kmesh/figures/kmesh-arch.png rename to docs/zh/docs/cloud/kmesh/kemsh/figures/kmesh-arch.png diff --git "a/docs/zh/docs/Kmesh/\350\256\244\350\257\206Kmesh.md" b/docs/zh/docs/cloud/kmesh/kemsh/getting_to_know_kmesh.md similarity index 99% rename from "docs/zh/docs/Kmesh/\350\256\244\350\257\206Kmesh.md" rename to docs/zh/docs/cloud/kmesh/kemsh/getting_to_know_kmesh.md index 0acd0e9a1fb7c268153f13f6855efb73d229ed0f..d82f45f673d721178235b9202323c81f7f59b94f 100644 --- "a/docs/zh/docs/Kmesh/\350\256\244\350\257\206Kmesh.md" +++ b/docs/zh/docs/cloud/kmesh/kemsh/getting_to_know_kmesh.md @@ -12,7 +12,6 @@ * 底噪开销大 istio中，每个sidecar软件占用内存50M+，CPU默认独占2 core，对于大规模集群底噪开销太大，降低了业务容器的部署密度 - Kmesh基于可编程内核，将网格流量治理下沉OS，数据路径3跳->1跳，大幅提升网格数据面的时延性能，帮助业务快速创新。 ## 架构 @@ -37,4 +36,3 @@ Kmesh的主要部件包括： * kmesh-probe： 观测运维探针，提供端到端观测能力 - diff --git "a/docs/zh/docs/Kmesh/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" b/docs/zh/docs/cloud/kmesh/kemsh/installation_and_deployment.md similarity index 94% rename from "docs/zh/docs/Kmesh/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" rename to docs/zh/docs/cloud/kmesh/kemsh/installation_and_deployment.md index 4c74a2488cd8c1499e6afebb84828c0ce63ec853..9f183eaf84d668ea43f85772a465d05e328286f8 100644 --- "a/docs/zh/docs/Kmesh/\345\256\211\350\243\205\344\270\216\351\203\250\347\275\262.md" +++ b/docs/zh/docs/cloud/kmesh/kemsh/installation_and_deployment.md @@ -2,7 +2,7 @@ ## 软件要求 -* 操作系统：openEuler 23.09 +* 操作系统：openEuler 24.03 LTS SP1 ## 硬件要求 @@ -10,7 +10,7 @@ ## 环境准备 -* 安装openEuler系统，安装方法参考 《[安装指南](../Installation/installation.md)》。 +* 安装openEuler系统，安装方法参考 《[安装指南](../../../Installation/installation.md)》。 * 安装Kmesh需要使用root权限。 @@ -33,6 +33,7 @@ ### 集群启动模式 启动前，先进行配置修改，设置集群中控制面程序ip信息（如istiod ip地址），操作如下： + ```json "clusters": [ { @@ -64,6 +65,7 @@ 启动前，修改kmesh.service，选择需要使用的功能选项。 使用流量编排功能，操作如下： + ```shell # 选择-enable-kmesh，禁用ads开关 [root@openEuler ~]# vim /usr/lib/systemd/system/kmesh.service @@ -72,6 +74,7 @@ ExecStart=/usr/bin/kmesh-daemon -enable-kmesh -enable-ads=false ``` 使用网格加速功能，操作如下： + ```shell # 选择-enable-mda选项，禁用ads开关 [root@openEuler ~]# vim /usr/lib/systemd/system/kmesh.service @@ -79,7 +82,7 @@ ExecStart=/usr/bin/kmesh-daemon -enable-mda -enable-ads=false [root@openEuler ~]# systemctl daemon-reload ``` -Kmesh服务启动时会调用kmesh-daemon程序，具体使用方式可以参考[kmesh-daemon使用](./使用方法.md)。 +Kmesh服务启动时会调用kmesh-daemon程序，具体使用方式可以参考[kmesh-daemon使用](./usage.md)。 ### 启动Kmesh @@ -96,4 +99,3 @@ Kmesh服务启动时会调用kmesh-daemon程序，具体使用方式可以参考 # 停止Kmesh服务 [root@openEuler ~]# systemctl stop kmesh.service ``` - diff --git a/docs/zh/docs/Kmesh/Kmesh.md b/docs/zh/docs/cloud/kmesh/kemsh/overview.md similarity index 100% rename from docs/zh/docs/Kmesh/Kmesh.md rename to docs/zh/docs/cloud/kmesh/kemsh/overview.md diff --git "a/docs/zh/docs/Kmesh/\344\275\277\347\224\250\346\226\271\346\263\225.md" b/docs/zh/docs/cloud/kmesh/kemsh/usage.md similarity index 100% rename from "docs/zh/docs/Kmesh/\344\275\277\347\224\250\346\226\271\346\263\225.md" rename to docs/zh/docs/cloud/kmesh/kemsh/usage.md diff --git a/docs/zh/docs/cloud/nestos/nestos/_toc.yaml b/docs/zh/docs/cloud/nestos/nestos/_toc.yaml new file mode 100644 index 0000000000000000000000000000000000000000..76699de8b271ef76f55fca6553f57aef17a831aa --- /dev/null +++ b/docs/zh/docs/cloud/nestos/nestos/_toc.yaml @@ -0,0 +1,10 @@ +label: NestOS用户指南 +isManual: true +description: NestOS是为容器化设计的轻量级操作系统，采用双分区院子更新，确保安全可靠 +sections: + - label: 概述 + href: ./overview.md + - label: NestOS For Container用户指南 + href: ./nestos_for_container.md + - label: 功能特性描述 + href: ./feature_description.md diff --git a/docs/zh/docs/cloud/nestos/nestos/feature_description.md b/docs/zh/docs/cloud/nestos/nestos/feature_description.md new file mode 100644 index 0000000000000000000000000000000000000000..15b8ad381ec9890fb16879e5abb7b8beab4f01f0 --- /dev/null +++ b/docs/zh/docs/cloud/nestos/nestos/feature_description.md @@ -0,0 +1,105 @@ +# 功能特性描述 + +## 容器技术 + +NestOS通过容器化 (containerized) 的运算环境向应用程序提供运算资源，应用程序之间共享系统内核和资源，但是彼此之间又互不可见。这意味着应用程序将不会再被直接安装到操作系统中，而是通过 容器引擎(Docker、Podman、iSulad等) 运行在容器中。大大降低了操作系统、应用程序及运行环境之间的耦合度。相对于传统的应用程序部署部署方式而言，在NestOS 集群中部署应用程序更加灵活便捷，应用程序运行环境之间的干扰更少，而且操作系统自身的维护也更加容易。 + +## rpm-ostree + +### 系统更新 + +rpm-ostree是一种镜像/包混合系统，可以看成是rpm和ostree的合体。一方面它提供了基于rpm的软件包安装管理方式，另一方面它提供了基于ostree的操作系统更新升级。rpm-ostree将这两种操作都视为对操作系统的更新，每次对系统的更新都像rpm-ostree在提交“Transaction-事务”，从而确保更新全部成功或全部失败，并且允许在更新系统后回滚到更新前的状态。 + +rpm-ostree在更新操作系统的时候会有2个bootable区域，分别为主动分区和被动分区，对系统的更新升级在被动分区进行，在重启操作系统主动分区和被动分区转换后才生效。如果软件安装或升级出现问题，通过rpm-ostree会使NestOS回滚到先前的状态。NestOS的“/ostree/”和“/boot/”目录是ostree Repository环境，通过该目录可以查看当前boot使用的哪个ostree。 + +### 只读文件系统 + +在rpm-ostree的文件系统布局中，只有/etc和/var是唯一可写的目录，/var中的任何数据不会被触及，而是在升级过程中共享。在系统升级的过程中采用新的缺省值/etc，并将更改添加到顶部。这意味着升级将会接收/etc中新的默认文件，这是一个非常关键的特性。 + +在通用操作系统中，/var目录下的部分文件采用“/var to tmpfiles.d”的处理策略，即系统通过systemd-tmpfile-setup.service读取/usr/lib/tmpfiles.d/目录下的conf文件，完成/var目录下文件夹和空白文件的创建，/usr/lib/tmpfiles.d/目录下的conf文件全部由相关rpm包提供。在NestOS中，/var目录不涉及rpm-ostree的commit分层，rpm-ostree各个commit 分层都会共享一个/var目录，但是/var目录下的文件会与ostree事务更新模型冲突，在安装软件包时rpm-ostree会将该文件删除。/var目录下的内容完全依赖“/var to tmpfiles.d”来生成，因此NestOS的/usr/lib/tmpfiles.d/目录下，除了部分rpm提供出的conf外，还存在由rpm-ostree在安装XXX软件包时生成的pkg-XXX.conf文件（即使XXX已经提供了conf文件），该文件记录了XXX软件包提供的/var下的文件夹，不涉及文件（文件在rpm-ostree安装包时已经删除）。当用户需要对rpm包提供的/var下的文件夹进行操作时，如删除某文件夹，简单的使用rm命令只能暂时删除，当系统重启后，该文件夹依旧存在，只有修改pkg-XXX.conf文件才能完成永久删除。 + +ostree旨在可以并行安装多个独立操作系统的版本，ostree依赖于一个新的ostree 目录，该目录实际上可以并行安装在现有的操作系统或者是占据物理/root目录的发行版本中。每台客户机和每组部署上都存储在 /ostree/deploy/STATEROOT/CHECKSUM 上，而且还有一个ostree Repository存储在 /ostree/repo 中。每个部署主要由一组指向存储库的硬链接组成，这意味着每个版本都进行了重复数据的删除并且升级过程中只消耗了与新文件成比例的磁盘空间加上一些恒定的开销。 + +ostree模型强调的是OS只读内容保存在 /usr 中，它附带了⽤于创建Linux只读安装以防止无意损坏的代码，对于给定的操作系统，每个部署之间都有一个 /var 共享的可供读写的目录。ostree核心代码不触及该目录的内容，如何管理和升级状态取决于每个操作系统中的代码。 + +### 系统扩展 + +出于安全性和可维护性的考虑，NestOS让基础镜像尽可能保持小巧和精简。但是在某些情况下，需要向基本操作系统本⾝添加软件，例如驱动软件，VPN等等，因为它们比较难容器化。这些包拓展了操作系统的功能，为此，rpm-ostree将这些包视为拓展，而不是仅仅在用户运行时提供。也就是说，目前NestOS对于实际安装哪些包没有限制，默认情况下，软件包是从openEuler仓库下载的。 + +要对软件包进行分层，需要重新编写一个systemd单元来执行rpm-ostree命令安装所需要的包，所做的更改应⽤于新部署，重新启动才能⽣效。 + +## nestos-installer + +nestos-installer是一个帮助安装Nestos的程序，它可以执行以下操作： + +（1）安装操作系统到一个目标磁盘，可使用Ignition和首次引导内核参数对其进行自定义(nestos-installer install) + +（2）下载并验证各种云平台、虚拟化或者裸机平台的操作系统映像(nestos-installer download) + +（3）列出可供下载的nestos镜像(nestos-installer list-stream) + +（4）在ISO中嵌入一个Ignition配置，以自定义地从中启动操作系统(nestos-installer iso ignition) + +（5）将Ignition配置包装在initd映像中，该映像可以被加入到PXE initramfs中以自定义从中启动的操作系统(nestos-installer pxe ignition) + +## zincati + +Zincati是NestOS⾃动更新的代理，它作为Cincinnati服务的客户端，负责监听NestOS版本变化并调用rpm-ostree进行⾃动更新。Zincati有如下特点： + +（1）支持自动更新代理，支持分阶段推出 + +（2）通过toml配置文件支持运行时自定义，用户自定义配置文件可覆盖默认配置 + +（3）多种更新策略 + +（4）通过维护窗口每周在特定时间范围内进行更新的策略 + +（5）收集和导出本地运行的zincati内部指标，可提供给Prometheus以减轻跨大量节点的监控任务 + +（6）具有可配置优先级的日志记录 + +（7）通过Cincinnati协议支持复杂的更新图 + +（8）通过外部锁管理器支持集群范围的重启编排 + +## 系统初始化（Ignition） + +Ignition 是一个与分发无关的配置实用程序，不仅用于安装，还读取配置文件（JSON 格式）并根据该配置初始化NestOS。可配置的组件包括存储和文件系统、systemd单元和用户。 + +Ignition仅在系统第一次引导期间运行一次（在initramfs中）。因为 Ignition 在启动过程的早期运行，所以它可以在用户空间开始启动之前重新分区磁盘、格式化文件系统、创建用户和写入文件。 因此，systemd 服务在 systemd 启动时已经写入磁盘，从而加快了启动速度。 + +（1）Ignition 仅在第一次启动时运行 + +Ignition 旨在用作配置工具，而不是配置管理工具。 Ignition 鼓励不可变的基础设施，其中机器修改要求用户丢弃旧节点并重新配置机器。 + +（2）Ignition不是在任何情况下都可以完成配置 + +Ignition 执行它需要的操作，使系统与 Ignition 配置中描述的状态相匹配。 如果由于任何原因 Ignition 无法提供配置要求的确切机器，Ignition 会阻止机器成功启动。例如，如果用户想要获取托管在[foo.conf](https://example.com/foo.conf)的文档并将其写入磁盘，如果无法解析给定的 URL，Ignition 将阻止机器启动。 + +（3）Ignition只是声明性配置 + +Ignition配置只描述了系统的状态，没有列出 Ignition 应该采取的一系列步骤。 + +Ignition 配置不允许用户提供任意逻辑（包括 Ignition 运行的脚本）。用户只需描述哪些文件系统必须存在、哪些文件必须创建、哪些用户必须存在等等。任何进一步的定制都必须使用由 Ignition 创建的 systemd 服务。 + +（4）Ignition配置不应手写 + +Ignition 配置被设计为人类可读但难以编写，是为了阻止用户尝试手动编写配置。可以使用Butane或类似工具生成或转化生成Ignition 配置。 + +## Afterburn + +Afterburn是类似于云平台一样的一次性代理，可以用于与特定的提供者的元数据端点进行交互，通常和Ignition结合使用。 + +Afterburn包含了很多可以在实例生命周期中不同时间段运行的模块。下面是特定的平台可能在第一次启动时在initramfs中运行的服务： + +（1）设置本地主机名 + +（2）加入网络命令行参数 + +以下的功能是在一定条件下，作为systemd服务单元在一些平台上才能使用的： + +（1）为本地系统用户安装公共SSH密钥 + +（2）从实例元数据中检索属性 + +（3）给提供者登记以便报道成功的启动或实例供应 diff --git a/docs/zh/docs/cloud/nestos/nestos/figures/figure1.png b/docs/zh/docs/cloud/nestos/nestos/figures/figure1.png new file mode 100644 index 0000000000000000000000000000000000000000..388a038273b5bb428c2f961d4241754fc2edc982 Binary files /dev/null and b/docs/zh/docs/cloud/nestos/nestos/figures/figure1.png differ diff --git a/docs/zh/docs/cloud/nestos/nestos/figures/figure2.png b/docs/zh/docs/cloud/nestos/nestos/figures/figure2.png new file mode 100644 index 0000000000000000000000000000000000000000..8e1bbf940a46234f75229611f706cf9ffd54b73a Binary files /dev/null and b/docs/zh/docs/cloud/nestos/nestos/figures/figure2.png differ diff --git a/docs/zh/docs/cloud/nestos/nestos/nestos_for_container.md b/docs/zh/docs/cloud/nestos/nestos/nestos_for_container.md new file mode 100644 index 0000000000000000000000000000000000000000..cf0efac7565442ff3d5294368e2e63439ac42213 --- /dev/null +++ b/docs/zh/docs/cloud/nestos/nestos/nestos_for_container.md @@ -0,0 +1,995 @@ +# NestOS用户使用指南 + +## 1. NestOS介绍 + +### 1.1 前言 + +NestOS是麒麟软件在openEuler社区开源孵化的云底座操作系统，集成了rpm-ostree支持、ignition配置等技术，采用双根文件系统互为主备、原子化更新的设计思路，提供nestos-assembler工具快速集成构建。NestOS针对K8S、OpenStack平台进行适配，优化容器运行底噪，使系统具备十分便捷的集群组建能力，可以更安全的运行大规模的容器化工作负载。 + +本手册将完整阐述从构建、安装部署到使用NestOS的全流程，帮助用户充分利用NestOS的优势，快速高效地完成系统的配置和部署。 + +### 1.2 应用场景与优势 + +NestOS 适合作为以容器化应用为主的云场景基础运行环境，解决了在使用容器技术与容器编排技术实现业务发布、运维时与底层环境高度解耦而带来的运维技术栈不统一，运维平台重复建设等问题，保证了业务与底座操作系统运维的一致性。 + +![figure1](./figures/figure1.png) + +## 2. 环境准备 + +### 2.1 构建环境要求 + +#### 2.1.1 制作构建工具nestos-assembler环境要求 + +- 推荐使用openEuler环境 + +- 剩余可用硬盘空间 > 5G + +#### 2.1.2 构建NestOS环境要求 + +| **类别** | **要求** | +| :------: | :---------------: | +| CPU | 4vcpu | +| 内存 | 4GB | +| 硬盘 | 剩余可用空间>10GB | +| 架构 | x86_64或aarch64 | +| 其他 | 支持kvm | + +### 2.2 部署配置要求 + +| **类别** | **推荐配置** | **最低配置** | +| :------: | :-------------: | :----------: | +| CPU | >4vcpu | 1vcpu | +| 内存 | >4GB | 512M | +| 硬盘 | >20GB | 10GB | +| 架构 | x86_64、aarch64 | / | + +## 3. 快速使用 + +### 3.1 快速构建 + +1）获取nestos-assembler容器镜像 + +推荐使用基于openEuler的base镜像，更多说明请参考6.1 + +```sh +docker pull hub.oepkgs.net/nestos/nestos-assembler:24.03-LTS.20240903.0-aarch64 +``` + +2）编写名为nosa的脚本并存放至/usr/local/bin，并赋予可执行权限 + +```sh +#!/bin/bash + +sudo docker run --rm -it --security-opt label=disable --privileged --user=root \ + -v ${PWD}:/srv/ --device /dev/kvm --device /dev/fuse --network=host \ + --tmpfs /tmp -v /var/tmp:/var/tmp -v /root/.ssh/:/root/.ssh/ -v /etc/pki/ca-trust/:/etc/pki/ca-trust/ \ + ${COREOS_ASSEMBLER_CONFIG_GIT:+-v $COREOS_ASSEMBLER_CONFIG_GIT:/srv/src/config/:ro} \ + ${COREOS_ASSEMBLER_GIT:+-v $COREOS_ASSEMBLER_GIT/src/:/usr/lib/coreos-assembler/:ro} \ + ${COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS} \ + ${COREOS_ASSEMBLER_CONTAINER:-nestos-assembler:your_tag} "$@" +``` + +注意修改COREOS_ASSEMBLER_CONTAINER 的值为本地环境中实际的nestos-assembler容器镜像。 + +3）获取nestos-config + +使用nosa init 初始化构建工作目录，拉取构建配置，创建工作目录nestos-build，在该目录下执行如下命令 + +```sh +nosa init https://gitee.com/openeuler/nestos-config +``` + +4）调整构建配置 + +nestos-config提供默认构建配置，无需额外操作。如需调整，请参考第5章。 + +5）NestOS镜像构建 + +```sh +# 拉取构建配置、更新缓存 +nosa fetch +# 生成根文件系统、qcow2及OCI镜像 +nosa build +# 生成live iso及PXE镜像 +nosa buildextend-metal +nosa buildextend-metal4k +nosa buildextend-live +``` + +详细构建及部署流程请参考第6章。 + +### 3.2 快速部署 + +以NestOS ISO镜像为例，启动进入live环境后，执行如下命令根据向导提示完成安装： + +```sh +sudo installnestos +``` + +其他部署方式请参考第8章。 + +## 4. 系统默认配置 + +| **选项** | **默认配置** | +| :-------------: | :---------------------: | +| docker服务 | 默认disable，需主动开启 | +| ssh服务安全策略 | 默认仅支持密钥登录 | + +## 5. 构建配置nestos-config + +### 5.1 获取配置 + +nestos-config的仓库地址为 + +### 5.2 配置目录结构说明 + +| **目录/****文件** | **说明** | +| :---------------: | :--------------------: | +| live/* | 构建liveiso的引导配置 | +| overlay.d/* | 自定义文件配置 | +| tests/* | 用户自定义测试用例配置 | +| *.repo | repo源配置 | +| .yaml，manifests/ | 主要构建配置 | + +### 5.3 主要文件解释 + +#### 5.3.1 repo文件 + +目录下的repo文件可用来配置用于构建nestos的软件仓库。 + +#### 5.3.2 yaml配置文件 + +目录下的yaml文件主要是提供nestos构建的各种配置，详见5.4章节。 + +### 5.4 主要字段解释 + +| **字段名称** | **作用** | +| :------------------------------------------ | ------------------------------------------------------------ | +| packages-aarch64、packages-x86_64、packages | 软件包集成范围 | +| exclude-packages | 软件包集成黑名单 | +| remove-from-packages | 从指定软件包删除文件(夹) | +| remove-files | 删除特定文件(夹) | +| extra-kargs | 额外内核引导参数 | +| initramfs-args | initramfs构建参数 | +| postprocess | 文件系统构建后置脚本 | +| default-target | 配置default-target，如 multi-user.target | +| rolij.name、releasever | 镜像相关信息(镜像名称、版本) | +| lockfile-repos | 构建可使用的仓库名列表,与5.3.1 介绍的repo文件中的仓库名需要对应 | + +### 5.5 用户可配置项说明 + +#### 5.5.1 repo源配置 + +1）在配置目录编辑repo文件，将内容修改为期望的软件仓库 + +```sh +$ vim nestos-pool.repo +[repo_name_1] +Name=xxx +baseurl = https://ip.address/1 +enabled = 1 + +[repo_name_2] +Name=xxx +baseurl = https://ip.address/2 +enabled = 1 +``` + +2）修改yaml配置文件中的lockfile-repo字段内容为相应的仓库名称列表 + +注：仓库名称为repo文件中[]内的内容，不是name字段内容 + +```sh +$ vim manifests/rpmlist.yaml +修改lockfile-repo字段内容为 +lockfile-repos: +- repo_name_1 +- repo_name_2 +``` + +#### 5.5.2 软件包裁剪 + +修改packages、packages-aarch64、packages-x86_64字段，可在其中添加或删除软件包。 + +如下所示，在package字段中添加了nano，构建安装后系统中会有nano 。 + +```sh +$ vim manifests/rpmlist.yaml +packages: +- bootupd +... +- authselect +- nano +... +packages-aarch64: +- grub2-efi-aa64 +packages-x86_64: +- microcode_ctl +- grub2-efi-x64 +``` + +#### 5.5.3 自定义镜像名称与版本号 + +修改yaml文件中的releasever及rolij.name 字段，这些字段分别控制镜像的版本号及名称。 + +```sh +$ vim manifest.yaml + +releasever: "1.0" +rojig: + license: MIT + name: nestos + summary: NestOS stable +``` + +如上配置，构建出的镜像格式为：nestos-1.0.$(date "+%Y%m%d").$build_num.$type，其中build_num为构建次数，type为类型后缀。 + +#### 5.5.4 自定义镜像中的release信息 + +正常release信息是由我们集成的release包（如openeuler-release）提供的，但是我们也可以通过添加postprocess脚本对/etc/os-release文件进行重写操作。 + +```sh +$ vim manifests/ system-configuration.yaml +在postprocess添加如下内容，若已存在相关内容，则只需修改对应release信息即可 +postprocess: + - | + #!/usr/bin/env bash + set -xeuo pipefail + export OSTREE_VERSION="$(tail -1 /etc/os-release)" + date_now=$(date "+%Y%m%d") + echo -e 'NAME="openEuler NestOS"\nVERSION="24.03-LTS"\nID="openeuler"\nVERSION_ID="24.03-LTS"\nPRETTY_NAME="NestOS"\nANSI_COLOR="0;31"\nBUILDID="'${date_now}'"\nVARIANT="NestOS"\nVARIANT_ID="nestos"\n' > /usr/lib/os-release + echo -e $OSTREE_VERSION >> /usr/lib/os-release + cp -f /usr/lib/os-release /etc/os-release +``` + +#### 5.5.5 成自定义文件 + +在overlay.d目录下每个目录进行自定义文件的添加和修改，这种操作可以实现构建镜像内容的自定义。 + +```sh +mkdir -p overlay.d/15nestos/etc/test/test.txt +echo "This is a test message !" > overlay.d/15nestos/etc/test/test.txt +``` + +使用如上配置进行镜像构建，启动构建出的镜像，查看系统中对应文件内容即为我们上述自定义添加的内容。 + +```sh +[root@nosa-devsh ~]# cat /etc/test/test.txt +This is a test message ! +``` + +## 6.构建流程 + +NestOS采用容器化的方式将构建工具链集成为一个完整的容器镜像，称为NestOS-assembler。 + +NestOS提供构建NestOS-assembler容器镜像能力，方便用户使用。使用该容器镜像，用户可在任意linux发行版环境中构建多种形态NestOS镜像（例如在现有CICD环境中使用），也可对构建发布件进行管理、调试和自动化测试。 + +### 6.1 制作构建工具NestOS-assembler容器镜像 + +#### 6.1.1 前置步骤 + +1）准备容器base镜像 + +NestOS-assembler容器镜像需要基于支持yum/dnf软件包管理器的base镜像制作，理论上可由任意发行版base镜像制作，但为最大程度减少软件包兼容性问题，仍推荐使用基于openEuler的base镜像。 + +2）安装必要软件包 + +安装必备依赖docker + +```sh +dnf install -y docker +``` + +3）克隆nestos-assembler源代码仓库 + +```sh +git clone --depth=1 --single-branch https://gitee.com/openeuler/nestos-assembler.git +``` + +#### 6.1.2 构建NestOS-assembler容器镜像 + +使用openEuler容器镜像作为base镜像，使用以下指令构建： + +```sh +cd nestos-assembler/ +docker build -f Dockerfile . -t nestos-assembler:your_tag +``` + +### 6.2 使用NestOS-assembler容器镜像 + +#### 6.2.1 前置步骤 + +1）准备nestos-assembler容器镜像 + +参考6.1章节构建nestos-assembler容器镜像后，可通过私有化部署容器镜像仓库对该容器镜像进行管理和分发。请确保构建NestOS前，拉取适当版本的nestos-assembler容器镜像至当前环境。 + +2）编写使用脚本nosa + +因NestOS构建过程需多次调用nestos-assembler容器镜像执行不同命令，同时需配置较多参数，为简化用户操作，可编写nosa命令脚本，可参见3.1快速构建部分。 + +#### 6.2.2 使用说明 + +构建工具命令一览 + +| **命令** | **功能说明** | +| :-------------------: | :-------------------------------------------------: | +| init | 初始化构建环境及构建配置，详见6.3 | +| fetch | 根据构建配置获取最新软件包至本地缓存 | +| build | 构建ostree commit，是构建NestOS的核心命令 | +| run | 直接启动一个qemu实例，默认使用最新构建版本 | +| prune | 清理历史构建版本，默认保留最新3个版本 | +| clean | 删除全部构建发布件，添加--all参数时同步清理本地缓存 | +| list | 列出当前构建环境中存在的版本及发布件 | +| build-fast | 基于前次构建记录快速构建新版本 | +| push-container | 推送容器镜像发布件至容器镜像仓库 | +| buildextend-live | 构建支持live环境的ISO发布件及PXE镜像 | +| buildextend-metal | 构建裸金属raw发布件 | +| buildextend-metal4k | 构建原生4K模式的裸金属raw发布件 | +| buildextend-openstack | 构建适用于openstack平台的qcow2发布件 | +| buildextend-qemu | 构建适用于qemu的qcow2发布件 | +| basearch | 获得当前架构信息 | +| compress | 压缩发布件 | +| kola | 自动化测试框架 | +| kola-run | 输出汇总结果的自动化测试封装 | +| runc | 以容器方式挂载当前构建根文件系统 | +| tag | 管理构建工程tag | +| virt-install | 通过virt-install为指定构建版本创建实例 | +| meta | 管理构建工程元数据 | +| shell | 进入nestos-assembler容器镜像 | + +### 6.3 准备构建环境 + +NestOS构建环境需要独立的空文件夹作为工作目录，且支持多次构建，保留、管理历史构建版本。创建构建环境前需首先准备构建配置（参考第5章）。 + +建议一份独立维护的构建配置对应一个独立的构建环境，即如果您希望构建多个不同用途的NestOS，建议同时维护多份构建配置及对应的构建环境目录，这样可以保持不同用途的构建配置独立演进和较为清晰的版本管理。 + +#### 6.3.1 初始化构建环境 + +进入待初始化工作目录，执行如下命令即可初始化构建环境： + +```sh +nosa init https://gitee.com/openeuler/nestos-config +``` + +仅首次构建时需初始化构建环境，后续构建在不对构建配置做出重大更改的前提下，可重复使用该构建环境。 + +#### 6.3.2 构建环境说明 + +初始化完成后，工作目录创建出如下文件夹： + +**builds:**构建发布件及元数据存储目录，latest子目录软链接指向最新构建版本。 + +**cache:**缓存目录，根据构建配置中的软件源及软件包列表拉取至本地，历史构建NestOS的ostree repo均缓存于此目录。 + +**overrides:**构建过程希望附加到最终发布件rootfs中的文件或rpm包可置于此目录。 + +**src:**构建配置目录，存放nestos-config相关内容。 + +**tmp:**临时目录，构建过程、自动化测试等场景均会使用该目录作为临时目录，构建发生异常时可在此处查看虚拟机命令行输出、journal日志等信息。 + +### 6.4 构建步骤 + +NestOS构建主要步骤及参考命令如下： + +![figure2](./figures/figure2.png) + +#### 6.4.1 首次构建 + +首次构建时需初始化构建环境，详见6.3。 + +非首次构建可直接使用原构建环境，可通过nosa list查看当前构建环境已存在版本及对应发布件。 + +#### 6.4.2 更新构建配置及缓存 + +初始化构建环境后，执行如下命令更新构建配置及缓存： + +```sh +nosa fetch +``` + +该步骤初步校验构建配置是否可用，并通过配置的软件源拉取软件包至本地缓存。当构建配置发生变更或单纯希望更新软件源中最新版本软件包，均需要重新执行该步骤，否则可能导致构建失败或不符合预期。 + +当构建配置发生较大变更，希望清空本地缓存重新拉取时，需执行如下命令： + +```sh +nosa clean --all +``` + +#### 6.4.3 构建不可变根文件系统 + +NestOS不可变操作系统的核心是基于ostree技术的不可变根文件系统，执行如下步骤构建ostree文件系统： + +```sh +nosa build +``` + +build命令默认会生成ostree文件系统和OCI归档文件，您也可以在执行命令时同步添加qemu、metal、metal4k中的一个或多个，同步构建发布件，等效于后续继续执行buildextend-qemu、buildextend-metal和buildextend-metal4k命令。 + +```sh +nosa build qemu metal metal4k +``` + +如您希望在构建NestOS时，添加自定义文件或rpm包，请在执行build命令前将相应文件放入构建环境overrides目录下rootfs/或rpm/文件夹。 + +#### 6.4.4 构建各类发布件 + +build命令执行完毕后，可继续执行buildextend-XXX命令用于构建各类型发布件，具体介绍如下： + +- 构建qcow2镜像 + +```sh +nosa buildextend-qemu +``` + +- 构建带live环境的ISO镜像或PXE启动组件 + +```sh +nosa buildextend-metal +nosa buildextend-metal4k +nosa buildextend-live +``` + +- 构建适用于openstack环境的qcow2镜像 + +```sh +nosa buildextend-openstack +``` + +- 构建适用于容器镜像方式更新的容器镜像 + +执行nosa build命令构建ostree文件系统时，会同时生成ociarchive格式镜像，该镜像可直接执行如下命令推送到本地或远程镜像仓库，无需执行其他构建步骤。 + +```sh +nosa push-container [container-image-name] +``` + + 远程镜像仓库地址需附加到推送容器镜像名称中，且除隔离镜像tag外，不得出现":"。如未检测到":"，该命令会自动生成{latest_build}-{arch}格式的tag。示例如下： + +```sh +nosa push-container registry.example.com/nestos:1.0.20240903.0-x86_64 +``` + +该命令支持以下可选参数： + +--authfile ：指定登录远程镜像仓库的鉴权文件 + +--insecure：如远程镜像仓库采用自签名证书等场景，添加该参数可不校验SSL/TLS协议 + +--transport：指定目标镜像推送协议，默认为docker，具体支持项及说明如下： + +​ containers-storage：推送至podman、crio等容器引擎本地存储目录 + +​ dir：推送至指定本地目录 + +​ docker：以docker API推送至私有或远端容器镜像仓库 + +​ docker-archive：等效于docker save导出归档文件，可供docker load使用 + +​ docker-daemon：推送至docker容器引擎本地存储目录 + +### 6.5 获取发布件 + +构建完毕后，发布件均生成于构建环境中如下路径： + +```sh +builds/{version}/{arch}/ +``` + +如您仅关心最新构建版本或通过CI/CD调用，提供latest目录软链接至最新版本目录，即： + +```sh +builds/latest/{arch}/ +``` + +为方便传输，您可以调用如下命令，压缩发布件体积： + +```sh +nosa compress +``` + +压缩后原文件会被移除，会导致部分调试命令无法使用，可以调用解压命令恢复原文件： + +```sh +nosa uncompress +``` + +### 6.6 构建环境维护 + +在构建NestOS环境前后，可能存在如下需求，可使用推荐的命令解决相应问题： + +#### 6.6.1 清理历史或无效构建版本，以释放磁盘空间 + +可以通过以下命令清理历史版本构建： + +```sh +nosa prune +``` + +也可删除当前构建环境中的全部发布件： + +```sh +nosa clean +``` + +如构建配置更换过软件源或历史缓存无保留价值，可彻底清理当前构建环境缓存： + +```sh +nosa clean --all +``` + +#### 6.6.2 临时运行构建版本实例，用于调试或确认构建正确 + +```sh +nosa run +``` + +可通过--qemu-image或--qemu-iso指定启动镜像地址，其余参数请参考nosa run --help说明。 + +实例启动后，构建环境目录会被挂载至/var/mnt/workdir，可通过构建环境目录 + +#### 6.6.3 运行自动化测试 + +```sh +nosa kola run +``` + +该命令会执行预设的测试用例，也可在其后追加测试用例名称，单独执行单条用例。 + +```sh +nosa kola testiso +``` + +该命令会执行iso或pxe live环境安装部署测试，可作为构建工程的冒烟测试。 + +#### 6.6.4 调试验证构建工具（NestOS-assembler） + +```sh +nosa shell +``` + +该命令可启动进入构建工具链容器的shell环境，您可以通过此命令验证构建工具链工作环境是否正常。 + +## 7. 部署配置 + +### 7.1 前言 + +在开始部署NestOS之前，了解和准备必要的配置是至关重要的。NestOS通过点火文件（ignition文件）提供了一系列灵活的配置选项，可以通过Butane工具进行管理，方便用户进行自动化部署和环境设置。 + +在本章节中，将详细的介绍Butane工具的功能和使用方法，并根据不同场景提供配置示例。这些配置将帮助您快速启动和运行NestOS，在满足应用需求的同时，确保系统的安全性和可靠性。此外，还会介绍如何自定义镜像，将点火文件预集成至镜像中，以满足特定应用场景的需求，从而实现高效的配置和部署NestOS。 + +### 7.2 Butane简介 + +Butane是一个用于将人类可读的YAML配置文件转换为NestOS点火文件（Ignition 文件）的工具。Butane工具简化了复杂配置的编写过程，允许用户以更易读的格式编写配置文件，然后将其转换为适合NestOS使用的JSON格式。 + +NestOS对Butane进行了适配修改，新增nestos变体支持和配置规范版本v1.0.0，对应的点火（ignition）配置规范为v3.3.0，确保了配置的稳定性和兼容性。 + +### 7.3 Butane使用 + +安装butane软件包 + +```sh +dnf install butane +``` + +编辑example.yaml并执行以下指令将其转换为点火文件example.ign，其中关于yaml文件的编写，将在后续展开： + +```sh +butane example.yaml -o example.ign -p +``` + +### 7.4 支持的功能场景 + +以下配置示例（example.yaml）简述了NestOS主要支持的功能场景和进阶使用方法。 + +#### 7.4.1 设置用户和组并配置密码/密钥 + +```conf +variant: nestos +version: 1.0.0 +passwd: + users: + - name: nest + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh... + - name: jlebon + groups: + - wheel + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS... + - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW... + - name: miabbott + groups: + - docker + - wheel + password_hash: $y$j9T$aUmgEDoFIDPhGxEe2FUjc/$C5A... + ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R... +``` + +#### 7.4.2 文件操作——以配置网卡为例 + +```conf +variant: nestos +version: 1.0.0 +storage: + files: + - path: /etc/NetworkManager/system-connections/ens2.nmconnection + mode: 0600 + contents: + inline: | + [connection] + id=ens2 + type=ethernet + interface-name=ens2 + [ipv4] + address1=10.10.10.10/24,10.10.10.1 + dns=8.8.8.8; + dns-search= + may-fail=false + method=manual +``` + +#### 7.4.3 创建目录、文件、软连接并配置权限 + +```conf +variant: nestos +version: 1.0.0 +storage: + directories: + - path: /opt/tools + overwrite: true + files: + - path: /var/helloworld + overwrite: true + contents: + inline: Hello, world! + mode: 0644 + user: + name: dnsmasq + group: + name: dnsmasq + - path: /opt/tools/transmogrifier + overwrite: true + contents: + source: https://mytools.example.com/path/to/archive.gz + compression: gzip + verification: + hash: sha512-00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 + mode: 0555 + links: + - path: /usr/local/bin/transmogrifier + overwrite: true + target: /opt/tools/transmogrifier + hard: false +``` + +#### 7.4.4 编写systemd服务——以启停容器为例 + +```conf +variant: nestos +version: 1.0.0 +systemd: + units: + - name: hello.service + enabled: true + contents: | + [Unit] + Description=MyApp + After=network-online.target + Wants=network-online.target + + [Service] + TimeoutStartSec=0 + ExecStartPre=-/bin/podman kill busybox1 + ExecStartPre=-/bin/podman rm busybox1 + ExecStartPre=/bin/podman pull busybox + ExecStart=/bin/podman run --name busybox1 busybox /bin/sh -c ""trap 'exit 0' INT TERM; while true; do echo Hello World; sleep 1; done"" + + [Install] + WantedBy=multi-user.target +``` + +### 7.5 点火文件预集成 + +NestOS构建工具链支持用户根据实际使用场景和需求定制镜像。在镜像制作完成后，nestos-installer还提供了针对镜像部署与应用等方面进行自定义的一系列功能，如嵌入点火文件、预分配安装位置、增删内核参数等功能，以下将针对主要功能进行介绍。 + +#### 7.5.1 点火文件预集成至ISO镜像 + +准备好NestOS的ISO镜像至本地；安装nestos-installer软件包；编辑example.yaml，并使用butane工具将其转换为ign文件，在这里，我们仅配置简单的用户名和密码（密码要求加密，示例中为qwer1234），内容如下： + +```conf +variant: nestos +version: 1.0.0 +passwd: + users: + - name: root + password_hash: "$1$root$CPjzNGH.NqmQ7rh26EeXv1" +``` + +将上述yaml转换为ign文件后，执行如下指令嵌入点火文件并指定目标磁盘位置，其中xxx.iso为准备至本地的NestOS ISO镜像： + +```bash +nestos-installer iso customize --dest-device /dev/sda --dest-ignition example.ign xxx.iso +``` + +使用该集成点火文件的ISO镜像进行安装时，NestOS会自动读取点火文件并安装至目标磁盘，待进度条完成度为100%后，自动进入安装好的NestOS环境，用户可根据ign文件配置的用户名和密码进入系统。 + +#### 7.5.2 点火文件预集成至PXE镜像 + +准备好NestOS的PXE镜像至本地，组件获取方式参考6.5【获取发布件】章节，其他步骤同上。 + +为了方便用户使用，nestos-installer也支持从ISO镜像中提取PXE组件的功能，执行如下指令，其中xxx.iso为保存至本地的NestOS ISO镜像： + +```sh +nestos-installer iso extract pxe xxx.iso +``` + +得到如下输出件： + +```txt +xxx-initrd.img +xxx-rootfs.img +xxx-vmlinuz +``` + +执行如下指令嵌入点火文件并指定目标磁盘位置： + +```conf +nestos-installer pxe customize --dest-device /dev/sda --dest-ignition example.ign xxx-initrd.img --output custom-initrd.img +``` + +根据使用PXE安装NestOS的方式，替换相应的xxx-initrd.img为custom-initrd.img。启动后NestOS会自动读取点火文件并安装至目标磁盘，待进度条完成度为100%后，自动进入安装好的NestOS环境，用户可根据ign文件配置的用户名和密码进入系统。 + +## 8. 部署流程 + +### 8.1 简介 + +NestOS支持多种部署平台及常见部署方式，当前主要支持qcow2、ISO与PXE三种部署方式。与常见通用OS部署相比，主要区别在于如何传入以ign文件为特征的自定义部署配置，以下各部分将会分别介绍。 + +### 8.2 使用qcow2镜像安装 + +#### 8.2.1 使用qemu创建qcow2实例 + +准备NestOS的qcow2镜像及相应点火文件（详见第7章），终端执行如下步骤： + +```sh +IGNITION_CONFIG="/path/to/example.ign" +IMAGE="/path/to/image.qcow2" +IGNITION_DEVICE_ARG="-fw_cfg name=opt/com.coreos/config,file=${IGNITION_CONFIG}" + +qemu-img create -f qcow2 -F qcow2 -b ${IMAGE} my-nestos-vm.qcow2 +``` + +aarch64环境执行如下命令： + +```sh +qemu-kvm -m 2048 -M virt -cpu host -nographic -drive if=virtio,file=my-nestos-vm.qcow2 ${IGNITION_DEVICE_ARG} -nic user,model=virtio,hostfwd=tcp::2222-:22 -bios /usr/share/edk2/aarch64/QEMU_EFI-pflash.raw +``` + +x86_64环境执行如下命令： + +```sh +qemu-kvm -m 2048 -M pc -cpu host -nographic -drive if=virtio,file=my-nestos-vm.qcow2 ${IGNITION_DEVICE_ARG} -nic user,model=virtio,hostfwd=tcp::2222-:22 +``` + +#### 8.2.2 使用virt-install创建qcow2实例 + +假设libvirt服务正常，网络默认采用default子网，绑定virbr0网桥，您可参考以下步骤创建NestOS实例。 + +准备NestOS的qcow2镜像及相应点火文件（详见第7章），终端执行如下步骤： + +```con +IGNITION_CONFIG="/path/to/example.ign" +IMAGE="/path/to/image.qcow2" +VM_NAME="nestos" +VCPUS="4" +RAM_MB="4096" +DISK_GB="10" +IGNITION_DEVICE_ARG=(--qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=${IGNITION_CONFIG}") +``` + +**注意：使用virt-install安装，qcow2镜像及ign文件需指定绝对路径。** + +执行如下命令创建实例： + +```sh +virt-install --connect="qemu:///system" --name="${VM_NAME}" --vcpus="${VCPUS}" --memory="${RAM_MB}" --os-variant="kylin-hostos10.0" --import --graphics=none --disk="size=${DISK_GB},backing_store=${IMAGE}" --network bridge=virbr0 "${IGNITION_DEVICE_ARG[@]} +``` + +### 8.3 使用ISO镜像安装 + +准备NestOS的ISO镜像并启动。首次启动的NestOS ISO镜像会默认进入Live环境，该环境为易失的内存环境。 + +#### 8.3.1 通过nestos-installer安装向导脚本安装OS至目标磁盘 + +1）在NestOS的Live环境中，根据首次进入的打印提示，可输入以下指令，即可自动生成一份简易的点火文件并自动安装重启 + +```sh +sudo installnestos +``` + +2）根据终端提示信息依次输入用户名和密码； + +3）选择目标磁盘安装位置，可直接选择回车设置为默认项/dev/sda； + +4）执行完以上步骤后，nestos-installer开始根据我们提供的配置将NestOS安装至目标磁盘，待进度条100%后，自动重启； + +5）重启后自动进入NestOS，在grub菜单直接回车或者等待5s后启动系统，随后根据此前配置的用户名和密码进入系统。至此，安装完成。 + +#### 8.3.2 通过nestos-installer命令手动安装OS至目标磁盘 + +1）准备好点火文件example.ign（详见第7章）； + +2）根据首次进入NestOS的Live环境打印的提示，输入以下指令开始安装： + +```sh +sudo nestos-installer install /dev/sda --ignition-file example.ign +``` + +如具备网络条件，点火文件也可通过网络获取，如： + +```sh +sudo nestos-installer install /dev/sda --ignition-file http://www.example.com/example.ign +``` + +3）执行完上述指令后，nestos-installer开始根据我们提供的配置将NestOS安装至目标磁盘，待进度条100%后，自动重启； + +4）重启后自动进入NestOS，在gurb菜单直接回车或者等待5s后启动系统，随后根据此前配置的用户名和密码进入系统。至此，安装完成 + +### 8.4 PXE部署 + +NestOS的PXE安装组件包括kernel、initramfs.img和rootfs.img。这些组件以nosa buildextend-live命令生成（详见第6章）。 + +1）使用PXELINUX 的kernel命令行指定内核，简单示例如下： + +```sh +KERNEL nestos-live-kernel-x86_64 +``` + +2）使用PXELINUX 的append命令行指定initrd和rootfs，简单示例如下： + +```sh +APPEND initrd=nestos-live-initramfs.x86_64.img,nestos-live-rootfs.x86_64.img +``` + +**注意：如您采用7.5章节所述，已将点火文件预集成至PXE组件，则仅需在此进行替换，无需执行后续步骤。** + +3）指定安装位置，以/dev/sda为例，在APPEND后追加，示例如下： + +```sh +nestosos.inst.install_dev=/dev/sda +``` + +4）指定点火文件，需通过网络获取，在APPEND后追加相应地址，示例如下： + +```sh +nestos.inst.ignition_url=http://www.example.com/example.ign +``` + +5）启动后NestOS会自动读取点火文件并安装至目标磁盘，待进度条完成度为100%后，自动进入安装好的NestOS环境，用户可根据ign文件配置的用户名和密码进入系统。 + +## 9. 基本使用 + +### 9.1 简介 + +NestOS采用基于ostree和rpm-ostree技术的操作系统封装方案，将关键目录设置为只读状态，核心系统文件和配置不会被意外修改；采用overlay分层思想，允许用户在基础ostree文件系统之上分层管理RPM包，不会破坏初始系统体系结构；同时支持构建OCI格式镜像，实现以镜像为最小粒度进行操作系统版本的切换。 + +### 9.2 SSH连接 + +出于安全考虑，NestOS 默认不支持用户使用密码进行SSH登录，而只能使用密钥认证方式。这一设计旨在增强系统的安全性，防止因密码泄露或弱密码攻击导致的潜在安全风险。 + +NestOS通过密钥进行SSH连接的方法与openEuler一致，如果用户需要临时开启密码登录，可按照以下步骤执行： + +1）编辑ssh服务附加配置文件 + +```sh +vi /etc/ssh/sshd_config.d/40-disable-passwords.conf +``` + +2）修改默认配置PasswordAuthentication为如下内容： + +```sh +PasswordAuthentication yes +``` + +3）重启sshd服务，便可实现临时使用密码进行SSH登录。 + +### 9.3 RPM包安装 + +**注意：不可变操作系统不提倡在运行环境中安装软件包，提供此方法仅供临时调试等场景使用，因业务需求需要变更集成软件包列表请通过更新构建配置重新构建实现。** + +NestOS不支持常规的包管理器dnf/yum，而是通过rpm-ostree来管理系统更新和软件包安装。rpm-ostree结合了镜像和包管理的优势，允许用户在基础系统之上分层安装和管理rpm包，并且不会破环初始系统的结构。使用以下命令安装rpm包： + +```sh +rpm-ostree install +``` + +安装完成后，重新启动操作系统，可以看到引导加载菜单出现了两个分支，默认第一个分支为最新的分支 + +```sh +systemctl reboot +``` + +重启进入系统，查看系统包分层状态，可看到当前版本已安装 + +```sh +rpm-ostree status -v +``` + +### 9.4 版本回退（临时/永久） + +更新/rpm包安装完成后，上一版本的操作系统部署仍会保留在磁盘上。如果更新导致问题，用户可以使用rpm-ostree进行版本回退，这一步操作需要用户手动操作，具体流程如下： + +#### 9.4.1 临时回退 + +要临时回滚到之前的OS部署，在系统启动过程中按住shift键，当引导加载菜单出现时，在菜单中选择相应的分支（默认有两个，选择另外一个即可）。在此之前，可以使用以下指令查看当前环境中已存在的两个版本分支： + +```sh +rpm-ostree status +``` + +#### 9.4.2 永久回退 + +要永久回滚到之前的操作系统部署，用户需在当前版本中运行如下指令，此操作将使用之前版本的系统部署作为默认部署。 + +```sh +rpm-ostree rollback +``` + +重新启动以生效，引导加载菜单的默认部署选项已经改变，无需用户手动切换。 + +```sh +systemctl reboot +``` + +## 10. 容器镜像方式更新 + +### 10.1 应用场景说明 + +NestOS作为基于不可变基础设施思想的容器云底座操作系统，将文件系统作为一个整体进行分发和更新。这一方案在运维与安全方面带来了巨大的便利。然而，在实际生产环境中，官方发布的版本往往难以满足用户的需求。例如，用户可能希望在系统中默认集成自维护的关键基础组件，或者根据特定场景的需求对软件包进行进一步的裁剪，以减少系统的运行负担。因此，与通用操作系统相比，用户对NestOS有着更强烈和更频繁的定制需求。 + + NestOS-assembler 可提供符合OCI标准的容器镜像，且不仅是将根文件系统打包分发，利用ostree native container特性，可使容器云场景用户使用熟悉的技术栈，只需编写一个ContainerFile(Dockerfile)文件，即可轻松构建定制版镜像，用于自定义集成组件或后续的升级维护工作。 + +### 10.2 使用方式 + +#### 10.2.1 定制镜像 + +- 基本步骤 + +（1） 参考第6章构建NestOS容器镜像，可使用nosa push-container命令推送至公共或私有容器镜像仓库。 + +（2） 编写Containerfile(Dockerfile)示例如下： + +```sh +FROM registry.example.com/nestos:1.0.20240603.0-x86_64 + +# 执行自定义构建步骤，例如安装软件或拷贝自构建组件 +# 此处以安装strace软件包为例 +RUN rpm-ostree install strace && rm -rf /var/cache && ostree container commit +``` + +（3）执行docker build或集成于CICD中构建相应镜像 + +- 注意事项 + +（1） NestOS 无yum/dnf包管理器，如需安装软件包可采用rpm-ostree install命令安装本地rpm包或软件源中提供软件 + +（2） 如有需求也可修改/etc/yum.repo.d/目录下软件源配置 + +（3） 每层有意义的构建命令末尾均需添加&& ostree container commit命令，从构建容器镜像最佳实践角度出发，建议尽可能减少RUN层的数量 + +（4） 构建过程中会对非/usr或/etc目录内容进行清理，因此通过容器镜像方式定制主要适用于软件包或组件更新，请勿通过此方式进行系统维护或配置变更（例如添加用户useradd） + +#### 10.2.2 部署/升级镜像 + +假设上述步骤构建容器镜像被推送为registry.example.com/nestos:1.0.20240903.0-x86_64。 + +在已部署NestOS的环境中执行如下命令： + +```sh +sudo rpm-ostree rebase ostree-unverified-registry:registry.example.com/nestos:1.0.20240903.0-x86_64 +``` + +重新引导后完成定制版本部署。 + +当您使用容器镜像方式部署后，rpm-ostree upgrade 默认会将更新源从ostree更新源地址更新为容器镜像地址。之后，您可以在相同的tag下更新容器镜像，使用 rpm-ostree upgrade 可以检测远端镜像是否已经更新，如果有变更，它会拉取最新的镜像并完成部署。 diff --git a/docs/zh/docs/cloud/nestos/nestos/overview.md b/docs/zh/docs/cloud/nestos/nestos/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..c9a7de872d5173cbba6f413b66277b6c884622ac --- /dev/null +++ b/docs/zh/docs/cloud/nestos/nestos/overview.md @@ -0,0 +1,4 @@ +# NestOS云底座操作系统 + +本文介绍云底座操作系统NestOS For Container（下称NestOS）的安装部署与各个特性说明和使用方法，使用户能够快速了解并使用NestOS。NestOS For Virt的使用方法与通用操作系统使用方法一致，可参考欧拉官方文档。 +NestOS搭载了docker、iSulad、podman、cri-o等常见容器引擎，将ignition配置、rpm-ostree、OCI支持、SElinux强化等技术集成在一起，采用基于双系统分区、容器技术和集群架构的设计思路，可以适配云场景下多种基础运行环境。同时NestOS针对Kubernetes进行优化，在IaaS生态构建方面，针对openStack、oVirt等平台提供支持；在PaaS生态构建方面，针对OKD、Rancher等平台提供支持，使系统具备十分便捷的集群组建能力，可以更安全的运行大规模的容器化工作负载。镜像下载地址详见[NestOS官网](https://nestos.openeuler.org/)。 diff --git a/docs/zh/docs/rubik/figures/icon-note.gif b/docs/zh/docs/rubik/figures/icon-note.gif deleted file mode 100644 index 6314297e45c1de184204098efd4814d6dc8b1cda..0000000000000000000000000000000000000000 Binary files a/docs/zh/docs/rubik/figures/icon-note.gif and /dev/null differ diff --git a/docs/zh/docs/rubik/figures/iocost.PNG b/docs/zh/docs/rubik/figures/iocost.PNG deleted file mode 100644 index db9bf8c351e8b7047c5815c5779a98c406a62ccd..0000000000000000000000000000000000000000 Binary files a/docs/zh/docs/rubik/figures/iocost.PNG and /dev/null differ