From af7bde9a7577c335b6b1fb1efd2f2920b6b487d6 Mon Sep 17 00:00:00 2001 From: wangyueliang Date: Sun, 14 Apr 2024 00:04:34 +0800 Subject: [PATCH 1/2] Improve some documents && Release for v0.13.0.4 --- README.en.md | 96 +++++++++++++++++++----- README.md | 89 ++++++++++++++++++---- docs/README.en.md | 9 +++ docs/README.md | 9 +++ docs/changelog-compared-with-upstream.md | 54 +++++++++++++ 5 files changed, 226 insertions(+), 31 deletions(-) create mode 100644 docs/README.en.md create mode 100644 docs/README.md create mode 100644 docs/changelog-compared-with-upstream.md diff --git a/README.en.md b/README.en.md index 289e832b..13fefab5 100644 --- a/README.en.md +++ b/README.en.md @@ -1,29 +1,89 @@ -# nestos-assembler +# Nestos-Assembler -#### Description -nestos-installer is a build environment used to build NestOS systems. +### Description +`nestos-assembler` is a build environment used to build NestOS systems. -#### Summary +### Summary -nestos-assembler is a build environment that contains a series of tools that can be used to build NestOS. nestos-assembler implements that the process of building and testing the operating system is encapsulated in a container. +`nestos-assembler` is a build environment that contains a series of tools that can be used to build NestOS. `nestos-assembler` implements that the process of building and testing the operating system is encapsulated in a container. -nestos-assembler can be simply understood as a container environment that can build nestos. This environment integrates some scripts, RPM packages and tools required to build NestOS. +`nestos-assembler` can be simply understood as a container environment that can build nestos. This environment integrates some scripts, RPM packages and tools required to build NestOS. -#### Common commands +### Usage -| name | Description | +#### Build Container image +``` +git clone https://gitee.com/openeuler/nestos-assembler.git +cd nestos-assembler/ +docker build -f Dockerfile . -t nestos-assembler:your_tag +``` +#### nosa shell script +The role of nosa shell script is to encapsulate the `nestos-assembler` call process and simplify command execution complexity. Due to differences in user usage of container runtime and building container image names, the nosa shell script is currently not provided by `nestos-assembler`. Please follow the following steps to modify and implement it in the environment where `nestos-assembler` will running: +- Write the content as shown in the following example. Please modify the container image name according to the actual situation: +``` +#!/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} "$@" +``` +- Save or move the script to the dir /usr/local/bin/ +- Granting executable permissions: +``` +sudo chmod +x /usr/local/bin/nosa +``` + +### Common commands +#### Basic build process +| Command | Description | +| --- | --- | +| nosa init | Initialize the build working directory and pull the build configuration | +| nosa fetch | Update the latest build configuration and download the required rpm package for caching | +| nosa build | Building a new commit of the OSTree file system | + +#### Build manage +| Command | Description | +| --- | --- | +| nosa list | List historical builds and built releases under the current working directory | +| nosa clean | Delete all historical builds(builds/、tmp/) | +| nosa prune | Delete specific build versions | +| nosa compress | Compress build artifacts | +| nosa decompress | Decompression build artifacts | +| nosa uncompress | Decompression build artifacts | +| nosa tag | Manage build tags | + +#### Build for specified platform +| Command | Description | +| --- | --- | +| nosa buildextend-qemu| Build qemu platform qcow2 format image, also can be completed by the `build` command | +| nosa buildextend-metal| Build a raw format disk image, also can be completed by the `build` command | +| nosa buildextend-metal4k| Build a native 4k mode raw format disk image, also can be completed by the `build` command | +| nosa buildextend-live| To build an ISO image with a live environment, the metal and metal4k format images must have already been built | +| nosa buildextend-openstack| Building a qcow2 image for the openstack | + +#### Others +| Command | Description | | --- | --- | -| nosa clean | Delete all build artifacts | -| nosa fetch | Fetch and import the latest packages | -| nosa build | Generate qemu artifacts for the given platforms | -| nosa buildextend-metal | Generate metal artifacts for the given platforms | -| nosa buildextend-metal4k | Generate metal4k artifacts for the given platforms | -| nosa buildextend-live | Generate the Live ISO | +| nosa kola run | Automated functional testing of specified version builds using the Kola testing framework | +| nosa kola testiso |Automated scenario testing of building different platform artifacts for specified versions using the Kola testing framework(e.g. iso, PXE)| +| nosa kola-run | Equivalent to `kola run`, this command can eliminate interference from invalid logs during the testing process, obtain test statistics results, and extract valid logs| +| nosa push-container | Push OCI format OSTree to registry | +| nosa run | Run the NestOS qemu instance of the specified build, usually used for debugging and validation | +| nosa runc | Run the command using the NestOS container image of the specified build, default to bash, usually used for debugging and validation | +| nosa shell | Enter the `nestos-assembler` container image environment bash, usually used for debugging and verification | + +### LICENSE + +`nestos-assembler` complies with the Apache 2.0 copyright agreement. -#### LICENSE +### Notice -nestos-assembler complies with the Apache 2.0 copyright agreement. +`nestos-assembler` is a fork of coreos-assembler(https://github.com/coreos/coreos-assembler), It will be adapted and maintained in the openEuler ecosystem, and independent evolution will be considered in the later stage.Thanks for the coreos-assembler project from Fedora coreos team. -#### Notice +### The main differences with coreos-assembler -nestos-assembler is a fork of coreos-assembler(https://github.com/coreos/coreos-assembler), It will be adapted and maintained in the openEuler ecosystem, and independent evolution will be considered in the later stage.Thanks for the coreos-assembler project from Fedora coreos team. +Refer to [changelog-compared-with-upstream.md](./docs/changelog-compared-with-upstream.md)。 diff --git a/README.md b/README.md index 6cfa09e5..7fbb7880 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,90 @@ # nestos-assembler -#### 介绍 +### 介绍 nestos-assembler是用于构建NestOS系统的构建环境. -#### 概述 +### 概述 nestos-assembler是一个构建环境，该环境包含一系列工具，可用来构建NestOS，nestos-assembler实现了在构建和测试操作系统的过程都是封装在一个容器中。 nestos-assembler可以简单理解为是一个可以构建NestOS的容器环境，该环境集成了构建NestOS所需的一些脚本、rpm包和工具。 -#### 常用命令 -| name | Description | +### 使用方法 + +#### 容器镜像构建 +``` +git clone https://gitee.com/openeuler/nestos-assembler.git +cd nestos-assembler/ +docker build -f Dockerfile . -t nestos-assembler:your_tag +``` +#### nosa脚本 +nosa 脚本的作用是封装nestos-assembler调用过程，简化命令执行复杂度。受限于用户使用容器引擎及构建容器镜像名称的不同，当前nestos-assembler暂未提供nosa脚本，请按照以下步骤在nestos-assembler运行环境中自行修改实现： +- 编写nosa脚本内容，参考示例如下，注意根据实际容器镜像名称修改： +``` +#!/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} "$@" +``` +- 将该脚本保存或移动至 /usr/local/bin/ 目录 +- 赋予可执行权限： +``` +sudo chmod +x /usr/local/bin/nosa +``` + +### 常用命令 +#### 基本构建流程 +| 命令 | 描述 | +| --- | --- | +| nosa init | 初始化构建工作目录，拉取构建配置 | +| nosa fetch | 更新最新构建配置，下载缓存所需rpm包 | +| nosa build | 构建新版ostree文件系统 | + +#### 构建管理 +| 命令 | 描述 | +| --- | --- | +| nosa list | 列出当前工作目录下历史构建及已构建发布件 | +| nosa clean | 删除全部历史构建(builds、tmp) | +| nosa prune | 删除特定构建版本 | +| nosa compress | 压缩构建发布件 | +| nosa decompress | 解压缩构建发布件 | +| nosa uncompress | 解压缩构建发布件 | +| nosa tag | 管理构建版本标识 | + +#### 特定平台发布件构建 +| 命令 | 描述 | +| --- | --- | +| nosa buildextend-qemu| 构建qemu平台qcow2格式镜像，可由`build`命令添加目标同步完成 | +| nosa buildextend-metal| 构建raw格式磁盘镜像，可由`build`命令添加目标同步完成 | +| nosa buildextend-metal4k| 构建原生4k模式raw格式磁盘镜像，可由`build`命令添加目标同步完成 | +| nosa buildextend-live| 构建带有live环境的ISO镜像，必须已构建完毕metal和metal4k格式镜像 | +| nosa buildextend-openstack| 构建适用于openstack环境的qcow2镜像 | + +#### 其他 +| 命令 | 描述 | | --- | --- | -| nosa clean | 删除历史构建(builds、tmp) | -| nosa fetch | 下载所需rpm包 | -| nosa build | 通过下载的rpm包构建ostree和qemu镜像 | -| nosa buildextend-metal | 构建metal镜像 | -| nosa buildextend-metal4k | 构建metal4k镜像 | -| nosa buildextend-live | 构建iso镜像 | +| nosa kola run | 使用kola测试框架对指定版本构建进行自动化功能测试 | +| nosa kola testiso |使用kola测试框架对指定版本构建不同平台发布件进行自动化场景测试(e.g. iso, PXE)| +| nosa kola-run | 等效于`kola run`，通过此命令可排除测试过程无效日志干扰，获取测试统计结果及有效日志摘录| +| nosa push-container | 推送OCI格式ostree文件系统至容器镜像仓库 | +| nosa run | 运行指定构建版本的NestOS qemu实例，一般用于调试验证 | +| nosa runc | 以指定构建版本的NestOS 容器镜像运行命令，默认为bash，一般用于调试验证 | +| nosa shell | 进入nestos-assembler容器镜像环境bash，一般用于调试验证 | -#### LICENSE +### LICENSE nestos-assembler 遵从 Apache 2.0 版权协议 -#### 说明 +### 声明 + +nestos-assembler 为 [coreos-assembler](https://github.com/coreos/coreos-assembler) 衍生版本，将在openEuler生态内适配维护，后期考虑独立演进。 + +感谢Fedora CoreOS团队对 coreos-assembler 的精彩付出。 + +### 与coreos-assembler主要差异 -nestos-assembler 基于 coreos-assembler(https://github.com/coreos/coreos-assembler) 分叉，将在openEuler生态内适配维护，后期考虑独立演进。 +参见 [对比上游项目主要改动](./docs/changelog-compared-to-upstream.md)。 diff --git a/docs/README.en.md b/docs/README.en.md new file mode 100644 index 00000000..7ade45dd --- /dev/null +++ b/docs/README.en.md @@ -0,0 +1,9 @@ +# Document Notes + +- nestos-assembler is forked from [coreos-assembler](https://github.com/coreos/coreos-assembler),most of the content in the original document can be referenced normally, and some keywords need to be replaced, such as replacing 'cosa' with 'nosa' and 'core' with 'nest'. + +- The differences with the upstream version can be referred to in [changelog-compared-with-upstream.md](./changelog-compared-with-upstream.md)。 + +- Some interfaces are not available for NestOS, please refer to [Readme](../README.en.md) for details. + +- We will gradually provide Chinese translations of some key documents in the future. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..86242ca4 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# 文档说明 + +- nestos-assembler由上游[coreos-assembler](https://github.com/coreos/coreos-assembler)衍生而来，原始文档绝大多数内容均可正常参考，部分关键词需替换,如cosa替换为nosa，core替换为nest等。 + +- 与上游版本差异可参考 [对比上游项目主要改动](./changelog-compared-with-upstream.md)。 + +- 部分功能接口不适用于NestOS，详情参考[Readme](../README.md)。 + +- 后续将会逐步提供部分关键文档中文翻译版本。 \ No newline at end of file diff --git a/docs/changelog-compared-with-upstream.md b/docs/changelog-compared-with-upstream.md new file mode 100644 index 00000000..09a90e63 --- /dev/null +++ b/docs/changelog-compared-with-upstream.md @@ -0,0 +1,54 @@ +# 对比上游项目主要改动 + +## 功能接口变化 + +### `nestos-assembler`不支持下列命令： +- nosa aliyun-replicate +- nosa aws-replicate +- nosa buildextend-aliyun +- nosa buildextend-aws +- nosa buildextend-azure +- nosa buildextend-azurestack +- nosa buildextend-dasd +- nosa buildextend-digitalocean +- nosa buildextend-exoscale +- nosa buildextend-gcp +- nosa buildextend-ibmcloud +- nosa buildextend-nutanix +- nosa buildextend-powervs +- nosa buildextend-vmware +- nosa buildextend-vultr +- nosa buildfetch +- nosa buildinitramfs-fast +- nosa buildupload +- nosa dev-overlay +- nosa dev-synthesize-osupdate +- nosa dev-synthesize-osupdatecontainer +- nosa generate-hashlist +- nosa koji-upload +- nosa oc-adm-release +- nosa remote-prune +- nosa sign +- nosa test-coreos-installer +- nosa upload-oscontainer + +### `nestos-assembler`添加下列命令： +- nosa kola-run + +## 代码变化 + +#### 新增构建变种NestOS，并设为默认 +#### 默认构建base镜像及软件源修改为openEuler +#### 新增iSula容器引擎测试用例 +#### push-container命令增强 +支持添加“--insecure”参数，忽略目标镜像仓库的SSL/TLS验证 + + +## 目录结构变化 + +### 移除与上游CICD相关代码目录及构建内容： +- ci/ +- gangplank/ +- docs/gangplank/ + +### 修改和新增部分文档说明 -- Gitee From 0d5ec716657f41662d4e378eba69790648e30590 Mon Sep 17 00:00:00 2001 From: lijian Date: Mon, 15 Apr 2024 02:28:04 +0000 Subject: [PATCH 2/2] Modify error link Signed-off-by: lijian --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7fbb7880..efb89770 100644 --- a/README.md +++ b/README.md @@ -87,4 +87,4 @@ nestos-assembler 为 [coreos-assembler](https://github.com/coreos/coreos-assembl ### 与coreos-assembler主要差异 -参见 [对比上游项目主要改动](./docs/changelog-compared-to-upstream.md)。 +参见 [对比上游项目主要改动](./docs/changelog-compared-with-upstream.md)。 -- Gitee