diff --git a/docs/en/docs/Administration/faqs.md b/docs/en/docs/Administration/faqs.md index 5fc145d13b938d547d649182d524a22e2eb9c73d..002ad18fc10d69a1612da43f6cb090fcdeb46f1f 100644 --- a/docs/en/docs/Administration/faqs.md +++ b/docs/en/docs/Administration/faqs.md @@ -7,6 +7,12 @@ - [Failed to Compile MariaDB Using rpmbuild](#failed-to-compile-mariadb-using-rpmbuild) - [Failed to Start the SNTP Service Using the Default Configuration](#failed-to-start-the-sntp-service-using-the-default-configuration) - [Installation Failure Caused by Software Package Conflict, File Conflict, or Missing Software Package](#installation-failure-caused-by-software-package-conflict-file-conflict-or-missing-software-package) + - [Failed to Downgrade libiscsi](#failed-to-downgrade-libiscsi) + - [Failed to Downgrade xfsprogs](#failed-to-downgrade-xfsprogs) + - [CPython/Lib Detects CVE-2019-9674: Zip Bomb](#cpython/lib-detects-cve-2019-9674:-zip-bomb) + - [ReDoS Attack Occurs Due to Improper Use of glibc Regular Expressions](#redos-attack-occurs-due-to-improper-use-of-glibc-regular-expressions) + - [An Error Is Reported When gdbm-devel Is Installed or Uninstalled During the Installation and Uninstallation of httpd-devel and apr-util-devel](#an-error-is-reported-when-gdbm-devel-is-installed-or-uninstalled-during-the-installation-and-uninstallation-of-httpd-devel-and-apr-util-devel) + ## Why Is the Memory Usage of the libvirtd Service Queried by Running the systemctl and top Commands Different? @@ -162,3 +168,145 @@ If a software package is missing, perform the following steps \(the missed softw ``` 3. Perform the upgrade again. + +### Installing Conflicting Instances +* A file conflict occurs. + + The **python3-edk2-devel.noarch** file conflicts with the **build.noarch** file due to duplicate file names. + + ```shell + # yum install python3-edk2-devel.noarch build.noarch + ... + Error: Transaction test error: + file /usr/bin/build conflicts between attempted installs of python3-edk2-devel-202002-3.oe1.noarch and build-20191114-324.4.oe1.noarch + ``` + +## Failed to Downgrade libiscsi + +### Symptom + +libiscsi-1.19.4 or later fails to be downgraded to libiscsi-1.19.3 or earlier. + +``` +Error: +Problem: problem with installed package libiscsi-utils-1.19.0-4.oe1.x86_64 +- package libiscsi-utils-1.19.0-4.oe1.x86_64 requires libiscsi(x86-64) = 1.19.0-4.oe1, but none of the providers can be installed +- cannot install both libiscsi-1.19.0-3.oe1.x86_64 and libiscsi-1.19.0-4.oe1.x86_64 +- cannot install both libiscsi-1.19.0-4.oe1.x86_64 and libiscsi-1.19.0-3.oe1.x86_64 +- conflicting requests +(try to add '--allowerasing' to command line to replace conflicting packages or '--skip-broken' to skip uninstallable packages or '--nobest' to use not only best candidate packages) +``` + +### Possible Cause + +In libiscsi-1.19.3 or earlier, binary files named **iscsi-xxx** are packed into the main package **libiscsi**. However, these binary files introduce improper dependency CUnit. To solve this problem, in libiscsi-1.19.4, these binary files are separated into the **libiscsi-utils** subpackage. The main package is weakly dependent on the subpackage. You can integrate or uninstall the subpackage during image building based on product requirements. If the subpackage is not integrated or is uninstalled, the functions of the **libiscsi** main package are not affected. +When libiscsi-1.19.4 or later is downgraded to libiscsi-1.19.3 or earlier and the **libiscsi-utils** subpackage is installed in the system, because libiscsi-1.19.3 or earlier does not contain **libiscsi-utils**, **libiscsi-utils** will fail to be downgraded. Due to the fact that **libiscsi-utils** depends on the **libiscsi** main package before the downgrade, a dependency problem occurs and the libiscsi downgrade fails. + +### Solution + +Run the following command to uninstall the **libiscsi-utils** subpackage and then perform the downgrade: + +``` +yum remove libiscsi-utils +``` + +## Failed to Downgrade xfsprogs + +### Symptom + +xfsprogs-5.6.0-2 or later fails to be downgraded to xfsprogs-5.6.0-1 or earlier. + +``` +Error: +Problem: problem with installed package xfsprogs-xfs_scrub-5.6.0-2.oe1.x86_64 +- package xfsprogs-xfs_scrub-5.6.0-2.oe1.x86_64 requires xfsprogs = 5.6.0-2.oe1, but none of the providers can be installed +- cannot install both xfsprogs-5.6.0-1.oe1.x86_64 and xfsprogs-5.6.0-2.oe1.x86_64 +- cannot install both xfsprogs-5.6.0-2.oe1.x86_64 and xfsprogs-5.6.0-1.oe1.x86_64 +- conflicting requests +``` + +### Possible Cause + +In xfsprogs-5.6.0-2, to reduce improper dependencies of the **xfsprogs** main package and separate experimental commands from the main package, the `xfs_scrub*` commands are separated into the **xfsprogs-xfs_scrub** subpackage. The **xfsprogs** main package is weakly dependent on the **xfsprogs-xfs_scrub** sub-package. You can integrate or uninstall the subpackage during image creation based on product requirements. If the subpackage is not integrated or is uninstalled, the functions of the **xfsprogs** main package are not affected. + +When xfsprogs-5.6.0-2 or later is downgraded to xfsprogs-5.6.0-1 or earlier and the **xfsprogs-xfs_scrub** subpackage is installed in the system, because xfsprogs-5.6.0-1 or earlier does not contain **xfsprogs-xfs_scrub**, **xfsprogs-xfs_scrub** will fail to be downgraded. Due to the fact that **xfsprogs-xfs_scrub** depends on the **xfsprogs** main package before the downgrade, a dependency problem occurs and the xfsprogs downgrade fails. + +### Solution + +Run the following command to uninstall the **xfsprogs-xfs_scrub** subpackage and then perform the downgrade: + +``` +yum remove xfsprogs-xfs_scrub +``` + +## CPython/Lib Detects CVE-2019-9674: Zip Bomb + +### Symptom + +**Lib/zipfile.py** in Python 3.7.2 or earlier allows remote attackers to create DoS requests using zip bombs, resulting in high resource consumption. + +### Possible Cause + +Remote attackers use zip bombs to cause denial of service, affecting target system services or even crashing the system. A zip bomb is a zip file with a high compression ratio. It may be several MB or dozens of MB in size. However, after decompression, a large amount of data is generated, consuming a large amount of resources. + +### Solution + +Add the alarm information to **zipfile** at https://github.com/python/cpython/blob/3.7/Doc/library/zipfile.rst. + +## ReDoS Attack Occurs Due to Improper Use of glibc Regular Expressions + +### Symptom + +The regcomp/regexec interface of glibc is used for programming, or the glibc regular expressions, such as grep/sed, are used in shell commands. Improper regular expressions or inputs cause ReDoS attacks (CVE-2019-9192/CVE-2018-28796). +The typical regular expression pattern is the combination of the"reverse reference (\1)" with the "asterisk (*)" (zero match or multiple matches), "plus sign (+)" (one match or multiple matches), or "{m,n}" (minimum match: m; maximum match: n); or the combination of ultra-long character strings with regular expressions. The following is an example: + +``` +# echo D | grep -E "$(printf '(\0|)(\\1\\1)*')"Segmentation fault (core dumped) +# grep -E "$(printf '(|)(\\1\\1)*')" +Segmentation fault (core dumped) +# echo A | sed '/\(\)\(\1\1\)*/p' +Segmentation fault (core dumped) +# time python -c 'print "a"*40000' | grep -E "a{1,32767}" +Segmentation fault (core dumped) +# time python -c 'print "a"*40900' | grep -E "(a)\\1" +Segmentation fault (core dumped) +``` + +### Possible Cause + +A core dump occurs on the process that uses the regular expression. The glibc regular expression is implemented using the NFA/DFA hybrid algorithm. The internal principle is to use a greedy algorithm for recursive query to match as many character strings as possible. The greedy algorithm causes the ReDoS attack when processing the recursive regular expression. + +### Solution + +1. Strict permission control is required to reduce the attack surface. + +2. Ensure that the regular expression is correct. Do not enter an invalid regular expression or a combination of ultra-long character strings with regular expressions (references or asterisks) that may trigger infinite recursion. + + ``` + # ()(\1\1)* + # "a"*400000 + ``` + +3. After a user program detects a process exception, the user program can restart the process to restore services, improving program reliability. + +## An Error Is Reported When gdbm-devel Is Installed or Uninstalled During the Installation and Uninstallation of httpd-devel and apr-util-devel + +### Symptom + +1. An error is reported when gdbm-devel-1.18.1-1 is installed or uninstalled. +2. After the error is rectified, gdbm and gdbm-devel are upgraded to the 1.18.1-2 version. However, the default version of gdbm-devel is still 1.18.1-1 when httpd-devel and apr-util-devel (dependent on gdbm-devel) are installed. As a result, the error persists. + +### Possible Cause + +1. The gdbm-devel-1.18.1-1 package does not contain the help package that provides `info`. As a result, the help package cannot be introduced when gdbm-devel is installed independently, and the following alarm information is displayed: + + ``` + install-info: No such file or directory for /usr/share/info/gdbm.info.gz + ``` + +2. By default, the gdbm-1.18.1-1 main package is installed in the system, but the gdbm-devel package is not installed. The software packages depending on gdbm-devel still match the version of the gdbm main package and install gdbm-devel-1.18.1-1. As a result, the error persists. + +### Solution + +1. Install gdbm-1.18.1-2 to upgrade gdbm. The error is rectified. +2. Upgrade gdbm, and then install gdbm-devel to make it depend on the gdbm of the later version. The error is rectified. \ No newline at end of file diff --git a/docs/en/docs/Container/figures/isula-build_arch.png b/docs/en/docs/Container/figures/isula-build_arch.png index 911a9ae6f46988586ab49f15de282948f5470c37..f92f15085820ce824bc2ca60ff7d6d25e95f1402 100644 Binary files a/docs/en/docs/Container/figures/isula-build_arch.png and b/docs/en/docs/Container/figures/isula-build_arch.png differ diff --git a/docs/en/docs/KubeOS/about-kubeos.md b/docs/en/docs/KubeOS/about-kubeos.md new file mode 100644 index 0000000000000000000000000000000000000000..0793503e800b357dd197021a5726f13fb9e992b8 --- /dev/null +++ b/docs/en/docs/KubeOS/about-kubeos.md @@ -0,0 +1,42 @@ +# About KubeOS + +## Introduction + +Containers and Kubernetes are widely used in cloud scenarios. However, a current manner of managing the containers and the OSs separately usually faces problems of function redundancy and difficult collaboration between scheduling systems. In addition, it is difficult to manage OS versions. Software packages are installed, updated, and deleted separately in OSs of the same version. After a period of time, the OS versions become inconsistent, causing version fragmentation. Besides, the OSs may be tightly coupled with services, making it difficult to upgrade major versions. To solve the preceding problems, openEuler provides KubeOS, a container OS upgrade tool based on openEuler. + +Container OSs are lightweight OSs designed for scenarios where services run in containers. KubeOS connects container OSs as components to Kubernetes, so that the container OSs are in the same position as services. The Kubernetes cluster manages containers and container OSs in a unified system. + +KubeOS is a Kubernetes operator for controlling the container OS upgrade process and upgrading the container OSs as a whole to implement collaboration between the OS manager and services. Before the container OSs are upgraded, services are migrated to other nodes to reduce the impact on services during OS upgrade and configuration. In this upgrade pattern, the container OSs are upgraded atomically so that the OSs remain synchronized with the expected status. This ensures that the OS versions in the cluster are consistent, preventing version fragmentation. + +## Architecture + +### KubeOS Architecture + +**Figure 1** KubeOS architecture + +![](./figures/kubeos-architecture.png) + +As shown in the preceding figure, KubeOS consists of three components: os-operator, os-proxy, and os-agent. The os-operator and os-proxy components run in containers and are deployed in the Kubernetes cluster. The os-agent component does not belong to the cluster and runs on worker nodes as processes. + +- os-operator: global container OS manager, which continuously checks the container OS versions of all nodes, controls the number of nodes to be upgraded concurrently based on the configured information, and marks the nodes to be upgraded. + +- os-proxy: OS manager of a single node, which continuously checks the container OS version of the node. If a node is marked as the node to be upgraded by os-operator, the node is locked, the pod is evicted, and the upgrade information is forwarded to os-agent. + +- os-agent: receives information from the proxy, downloads the container OS image used for upgrade from the OS image server, upgrades the container OS, and restarts the node. + + +### File System of a Container OS + +**Figure 2** File system layout of a container OS + +![](./figures/file-system-layout-of-a-container-os.png) + + + +As shown in the figure, a container OS comprises four partitions: + +- boot partition: GRUB2 file partition. +- Persist partition: stores persistent user data. When the container OS is upgraded, the data in this partition is retained. +- Two root partitions: A container OS uses the dual-partition mode with two root partitions, rootA and rootB. Assume that the system runs on the rootA partition after initialization. When the system is upgraded, the new system is downloaded to the rootB partition. GRUB has two boot options: A and B. The default boot option of GRUB is set to B and the node is restarted. After the node is started, the container OS runs on the updated rootB partition. + +The root file system of the container OS is read-only. Users' persistent data is stored in the Persist partition. diff --git a/docs/en/docs/KubeOS/figures/file-system-layout-of-a-container-os.png b/docs/en/docs/KubeOS/figures/file-system-layout-of-a-container-os.png new file mode 100644 index 0000000000000000000000000000000000000000..b4a3af27b6dd7f23dc6f45ec4601bfceabbf5e9a Binary files /dev/null and b/docs/en/docs/KubeOS/figures/file-system-layout-of-a-container-os.png differ diff --git a/docs/en/docs/KubeOS/figures/kubeos-architecture.png b/docs/en/docs/KubeOS/figures/kubeos-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..7d32855d3167706975c2323109005af3ffb1b4f5 Binary files /dev/null and b/docs/en/docs/KubeOS/figures/kubeos-architecture.png differ diff --git a/docs/en/docs/KubeOS/installation-and-deployment.md b/docs/en/docs/KubeOS/installation-and-deployment.md new file mode 100644 index 0000000000000000000000000000000000000000..bf566091ae0656e15dfe2019205b494da9695b16 --- /dev/null +++ b/docs/en/docs/KubeOS/installation-and-deployment.md @@ -0,0 +1,227 @@ +# Installation and Deployment + +This chapter describes how to install and deploy the KubeOS tool. + + + + + +- [Installation and Deployment](#installation-and-deployment) + + - [Software and Hardware Requirements](#software-and-hardware-requirements) + + - [Hardware Requirements](#hardware-requirements) + - [Software Requirements](#software-requirements) + - [Environment Preparation](#environment-preparation) + + - [KubeOS Installation](#kubeos-installation) + + - [KubeOS Deployment](#kubeos-deployment) + + - [Building the os-operator and os-proxy Images](#building-the-os-operator-and-os-proxy-images) + - [Building a Container OS Image](#building-a-container-os-image) + - [Deploying CRD, os-operator, and os-roxy](#deploying-crd-os-operator-and-os-proxy) + + + + + +## Software and Hardware Requirements + +### Hardware Requirements + +* Currently, only the x86 architecture is supported. + +### Software Requirements + +* OS: openEuler 21.09 + +### Environment Preparation + +* Install the openEuler system. For details, see the _openEuler 21.09 Installation Guide_. +* Install qemu-img, bc, Parted, tar, Yum, and Docker. + +## KubeOS Installation + +To install KubeOS, perform the following steps: + +1. Configure the Yum sources: openEuler 21.09 and openEuler 21.09:EPOL: + + ``` + [openEuler21.09] # openEuler 21.09 official source + name=openEuler21.09 + baseurl=http://repo.openeuler.org/openEuler-21.09/everything/$basearch/ + enabled=1 + gpgcheck=1 + gpgkey=http://repo.openeuler.org/openEuler-21.09/everything/$basearch/RPM-GPG-KEY-openEuler + ``` + + ``` + [Epol] # openEuler 21.09:EPOL official source + name=Epol + baseurl=http://repo.openeuler.org/openEuler-21.09/EPOL/main/$basearch/ + enabled=1 + gpgcheck=1 + gpgkey=http://repo.openeuler.org/openEuler-21.09/OS/$basearch/RPM-GPG-KEY-openEuler + ``` + +2. Install KubeOS as the **root** user. + + ```shell + # yum install KubeOS KubeOS-scripts -y + ``` + + +> ![](./public_sys-resources/icon-note.gif)**NOTE**: +> +> KubeOS is installed in the **/opt/kubeOS** directory, including the os-operator, os-proxy, os-agent binary files, container OS image build tools, and corresponding configuration files. + +## KubeOS Deployment + +After KubeOS is installed, you need to configure and deploy it. This section describes how to configure and deploy KubeOS. + +### Building the os-operator and os-proxy Images + +#### Environment Preparation + +Before using Docker to create a container image, ensure that Docker has been installed and configured. + +#### Procedure + +1. Go to the working directory. + + ```shell + cd /opt/kubeOS + ``` + +2. Specify the image repository, name, and version for os-proxy. + + ```shell + export IMG_PROXY=your_imageRepository/os-proxy_imageName:version + ``` + +3. Specify the image repository, name, and version for os-operator. + + ```shell + export IMG_OPERATOR=your_imageRepository/os-operator_imageName:version + ``` + +4. Compile a Dockerfile to build an image. Pay attention to the following points when compiling a Dockerfile: + + * The os-operator and os-proxy images must be built based on the base image. Ensure the security of the base image. + * Copy the os-operator and os-proxy binary files to the corresponding images. + * Ensure that the **root** owner and owner group are assigned for the os-proxy binary file in the os-proxy image, and the file permission is **500**. + * Ensure that the owner and owner group of the os-operator binary file in the os-operator image are the user who runs the os-operator process in the container, and the file permission is **500**. + * The locations of the os-operator and os-proxy binary files in the image and the commands run during container startup must correspond to the parameters specified in the YAML file used for deployment. + + An example Dockerfile is as follows: + + ``` + FROM your_baseimage + COPY ./bin/proxy /proxy + ENTRYPOINT ["/proxy"] + ``` + + ``` + FROM your_baseimage + COPY --chown=6552:6552 ./bin/operator /operator + ENTRYPOINT ["/operator"] + ``` + + You can build the Dockerfile in multiple phases. + +5. Build the images to be deployed in containers (os-operator and os-proxy images). + + ```shell + # Specify the Dockerfile path of os-proxy. + export DOCKERFILE_PROXY=your_dockerfile_proxy + # Specify the Dockerfile path of os-operator. + export DOCKERFILE_OPERATOR=your_dockerfile_operator + # Build images. + docker build -t ${IMG_OPERATOR} -f ${DOCKERFILE_OPERATOR} . + docker build -t ${IMG_PROXY} -f ${DOCKERFILE_PROXY} . + ``` + +6. Push the container images to the image repository. + + ```shell + docker push ${IMG_OPERATOR} + docker push ${IMG_PROXY} + ``` + + +### Building a Container OS Image + +#### Precautions + +* The **root** permissions are required for creating a container OS image. +* The RPM package source of the container OS image build tool is the full ISO file of openEuler, for example, **openEuler-21.09-everything-x86_64-dvd.iso**. +* By default, the container OS image built using the default RPM list is stored in the same path as the build tool. This partition must have at least 25 GiB free disk space. +* When creating a container OS image, you cannot customize the file system to be mounted. + +#### Procedure + +The command for creating a container OS is as follows: + +**generate.sh** *ISO_PATH VERSION AGENT_PATH ENCRYPTED_PASSWD* + +The parameters are described as follows: + +- `ISO_PATH`: full ISO file path +- `AGENT_PATH`: os-agent binary file path + +* `VERSION`: version of the created container OS image + +* `ENCRYPTED_PASSWD`: password of the **root** user of the container OS image. The password is encrypted with a salt value and can be generated using OpenSSL or KIWI commands. + + +To create a container OS, perform the following steps: + +1. Go to the execution directory. + + ```shell + cd /opt/kubeOS/scripts + ``` + +2. Run **generate.sh** to create the container OS. The following is a command example: + + ```shell + bash generate.sh openEuler-21.09-everything-x86_64-dvd.iso v1 ../bin/os-agent '''$1$xyz$RdLyKTL32WEvK3lg8CXID0''' + ``` + + After the container OS image is created, the following files are generated in the **/opt/kubeOS/scripts** directory: + + - **system.qcow2**: system image. The default size of **system.qcow2** is 20 GiB. The size of the root file system partition is less than 2020 MiB, and the size of the Persist partition is less than 16 GiB. + - **update.img**: partition image of the root file system that is used for upgrade. + + The created container OS image can be used only in the VM of the x86 architecture. + + +### Deploying CRD, os-operator, and os-proxy + +#### Precautions + +* Deploy the Kubernetes cluster first. For details, see the _openEuler 21.09 Kubernetes Cluster Deployment Guide_. + +- The OS of the worker nodes to be upgraded in the cluster must be the container OS built using the method described in the previous section. If it is not, use **system.qcow2** to deploy the VM again. For details about how to deploy a VM, see the _openEuler 21.09 Virtualization User Guide_. Currently, the master nodes do not support container OS upgrade. Use openEuler 21.09 to deploy the upgrade on the master nodes. +- Compile the YAML files for deploying CustomResourceDefinition (CRD), os-operator, os-proxy, and role-based access control (RBAC) of the OS. +- The os-operator and os-proxy components are deployed in the Kubernetes cluster. os-operator must be deployed as a Deployment, and os-proxy as a DaemonSet. +- Deploy Kubernetes security mechanisms, such as the RBAC, pod service account, and security policy. + +#### Procedure + +1. Prepare YAML files, including those used for deploying CRD, RBAC, os-operator, and os-proxy of the OS. For details, see [YAML examples](https://gitee.com/openeuler/KubeOS/tree/master/docs/example/config). The following uses **crd.yaml**, **rbac.yaml**, and **manager.yaml** as examples. + +2. Deploy CRD, RBAC, os-operator, and os-proxy. Assume that the **crd.yaml**, **rbac.yaml**, and **manager.yaml** files are stored in the **config/crd**, **config/rbac**, and **config/manager** directories, respectively. Run the following commands: + + ```shell + kubectl apply -f confg/crd + kubectl apply -f config/rbac + kubectl apply -f config/manager + ``` + +3. After the deployment is complete, run the following command to check whether each component is started properly. If **STATUS** of all components is **Running**, the components are started properly. + + ```shell + kubectl get pods -A + ``` diff --git a/docs/en/docs/KubeOS/kubeos-user-guide.md b/docs/en/docs/KubeOS/kubeos-user-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..aa615c852e059d2ea061ea75ee0cd9d5264ebfa7 --- /dev/null +++ b/docs/en/docs/KubeOS/kubeos-user-guide.md @@ -0,0 +1,8 @@ +# KubeOS User Guide + +This document describes how to install, deploy, and use KubeOS in the openEuler system. KubeOS connects the container OS to the scheduling system in standard extension pattern and manages the OS upgrade of nodes in the cluster through the scheduling system. + +This document is intended for community developers, open source enthusiasts, and partners who use the openEuler system and want to learn and use the container OSs. Users must: + +* Know basic Linux operations. +* Understand Kubernetes and Docker. diff --git a/docs/en/docs/KubeOS/public_sys-resources/icon-note.gif b/docs/en/docs/KubeOS/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/docs/en/docs/KubeOS/public_sys-resources/icon-note.gif differ diff --git a/docs/en/docs/KubeOS/usage-instructions.md b/docs/en/docs/KubeOS/usage-instructions.md new file mode 100644 index 0000000000000000000000000000000000000000..9e54dda2e383171544da46e559b944f0e9e7fafa --- /dev/null +++ b/docs/en/docs/KubeOS/usage-instructions.md @@ -0,0 +1,114 @@ +# Usage Instructions + + + + + +- [Usage Instructions](#usage-instructions) + + - [Precautions](#precautions) + + - [Upgrade](#upgrade) + + - [Rollback](#rollback) + + - [Application Scenarios](#application-scenarios) + + - [Manual Rollback](#manual-rollback) + + - [KubeOS-based Rollback](#kubeos-based-rollback) + + + + + +## Precautions + +1. KubeOS provides atomic upgrade for all software packages. By default, single-package upgrade is not supported. +2. KubeOS supports container OSs with two partitions. Partitions more than two are not supported. +3. You can view the upgrade logs of a single node in the **/var/log/messages** file on the node. +4. Strictly follow the upgrade and rollback processes described in this document. If the processes are invoked in an abnormal sequence, the system may fail to be upgraded or rolled back. + +## Upgrade + +Compile the YAML file to deploy the instance of the OS custom resource (CR) in the cluster. The following is an example YAML file for deploying the CR instance: + +``` +apiVersion: upgrade.openeuler.org/v1alpha1 +kind: OS +metadata: + name: os-sample +spec: + osversion: KubeOS 1.0.0 + imageurl: edit.image.url + maxunavailable: 1 + checksum: image checksum + flagsafe: imageurl is safe or not +``` + +Parameter description: + +| Parameter | Description | Mandatory (Yes/No)| +| -------------- | ----------------------------------- | -------- | +| osversion | Address of the image used for the upgrade | Yes | +| imageurl | Version of the OS image used for the upgrade | Yes | +| maxunavailable | Number of nodes that are upgraded concurrently | Yes | +| checksum | Checksum (SHA-256) value of the image used for the upgrade| Yes | +| flagsafe | Whether `imageurl` specifies a secure address| Yes | + +The address specified by `imageurl` contains the protocol. Only the HTTP or HTTPS protocol is supported. If `imageurl` is set to an HTTPS address, secure transmission is used. If `imageurl` is set to an HTTP address, set `flagsafe` to `true`, because the image can be downloaded only when the address is secure. If `imageurl` is set to an HTTP address but `flagsafe` is not set to `true`, the address is insecure by default. The image will not be downloaded, and a message is written to the log of the node to be upgraded indicating that the address is insecure. + +You are advised to set `imageurl` to an HTTPS address. In this case, ensure that the required certificate has been installed on the node to be upgraded. If the image server is maintained by yourself, you need to sign the certificate and ensure that the certificate has been installed on the node to be upgraded. Place the certificate in the **/etc/pki/ca-trust/source/anchors** directory of the container OS and run the `update-ca-trust extract` command to install the certificate. The administrator specifies the address and must ensure the security of the address. The intranet address is recommended. + +Assume that the YAML file is **upgrade_v1alpha1_os.yaml**. + +Check the OS version of the node that is not upgraded. + +``` +kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' +``` + +Run the following command to deploy the CR instance in the cluster. The node is upgraded based on the configured parameters. + +``` +kubectl apply -f upgrade_v1alpha1_os.yaml +``` + +Check the node OS version again to determine whether the node upgrade is complete. + +``` +kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' +``` + +> ![](./public_sys-resources/icon-note.gif)**NOTE**: +> +> If the upgrade needs to be performed again, modify the `imageurl`, `osversion`, `checksum`, `maxunavailable`, or `flagsafe` parameter in the **upgrade_v1alpha1_os.yaml** file. + +## Rollback + +### Application Scenarios + +- If a node cannot be started, you can only manually roll back the container OS to the previous version that can be properly started. +- If a node can be started and run the system, you can manually or use KubeOS (similar to the upgrade) to roll back the container OS. You are advised to use KubeOS. + +### Manual Rollback + +Manually restart the node and select the second boot option to roll back the container OS. Manual rollback can only roll back the container OS to the version before the upgrade. + +### KubeOS-based Rollback + +1. Modify the YAML configuration file (for example, **upgrade_v1alpha1_os.yaml**) of the OS CR instance. Set the `imageurl`, `osversion`, `checksum`, and `flagsafe` parameters to the information about the target version to be rolled back to. + +2. Update the CR instance in the cluster. + + ``` + kubectl apply -f upgrade_v1alpha1_os.yaml + ``` + + After the update is complete, the node rolls back the container OS based on the configuration information. + +3. Check the OS version of the container on the node to determine whether the rollback is successful. + + ``` + kubectl get nodes -o custom-columns='NAME:.metadata.name,OS:.status.nodeInfo.osImage' + ``` diff --git a/docs/en/docs/Releasenotes/acknowledgement.md b/docs/en/docs/Releasenotes/acknowledgment.md similarity index 80% rename from docs/en/docs/Releasenotes/acknowledgement.md rename to docs/en/docs/Releasenotes/acknowledgment.md index 47c049cdd996b1d7f590a023e095661e90599b30..ac610fdf054e041e13d6b45bf2f9670d2c394f62 100644 --- a/docs/en/docs/Releasenotes/acknowledgement.md +++ b/docs/en/docs/Releasenotes/acknowledgment.md @@ -1,4 +1,4 @@ -# Acknowledgement +# Acknowledgment We sincerely thank all the members who participated in and assisted in the openEuler project. It is your hard work to make the version released successfully and provide the possibility for the better development of openEuler. diff --git a/docs/en/docs/desktop/DDE-User-Manual.md b/docs/en/docs/desktop/DDE-User-Manual.md index 1472942cbcd2445a4731108094f6dadd8304db8d..7956aab42a70b08f991e964196d84d2b6a2893a3 100755 --- a/docs/en/docs/desktop/DDE-User-Manual.md +++ b/docs/en/docs/desktop/DDE-User-Manual.md @@ -1,6 +1,6 @@ -# DDE Desktop Environment User Manual +# DDE Desktop Environment ## Overview DDE desktop environment is an elegant, secure, reliable and easy to use GUI comprised of the desktop, dock, launcher and control center. Acting as the key basis for our operating system, its main interface is shown as below. diff --git a/docs/en/docs/desktop/Install_XFCE.md b/docs/en/docs/desktop/Install_XFCE.md index a1cc296893e10ff28b794a74fcc8505866b6bea7..68676948c9f5149ca73da5412296dc689cda7eb1 100644 --- a/docs/en/docs/desktop/Install_XFCE.md +++ b/docs/en/docs/desktop/Install_XFCE.md @@ -1,4 +1,4 @@ -# Xfce Installation Guide +# Xfce Installation Xfce is a lightweight Linux desktop. In the current version, all components have been updated from GTK2 to GTK3 and from D-Dbus Glib to GDBus. Most components support GObject Introspection (GI), which is used to generate and parse the API meta information of the C program library, so that the dynamic language (or managed language) can be bound to the program library based on C + GObject. In the current version, user experience is optimized, new features are added, and a large number of bugs are fixed. Xfce occupies fewer memory and CPU resources than other UIs (GNOME and KDE), providing smoother and more efficient user experience. @@ -61,4 +61,9 @@ You are advised to create an administrator during the installation. ``` sudo reboot - ``` \ No newline at end of file + ``` + + 9. FAQs +**Why Is the Background Color of the LightDM Login Page Black?** +The login page is black because `background` is not set in the default configuration file **/etc/lightdm/lightdm-gtk-greeter.conf** of lghtdm-gtk. +Set `background=/usr/share/backgrounds/xfce/xfce-blue.jpg` in the `greeter` section at the end of the configuration file, and then run the `systemctl restart lightdm` command. \ No newline at end of file diff --git a/docs/en/docs/desktop/Xfce_userguide.md b/docs/en/docs/desktop/Xfce_userguide.md index ea6396320d845f3c7f44ac8d2bdfb95a7ff6d4a0..10cee1e6cdd25d94e4ad2df6d0e875ff28e79424 100644 --- a/docs/en/docs/desktop/Xfce_userguide.md +++ b/docs/en/docs/desktop/Xfce_userguide.md @@ -1,40 +1,49 @@ # Table of Contents -* [Xfce User Guide](#Xfce User Guide) - * [1. Overview](#1. Overview) - * [2. Desktop](#2. Desktop) - * [2.1 Desktop Icons](#2.1 Desktop Icons) - * [2.2 Shortcut Menu](#2.2 Shortcut Menu) - * [3. Taskbar](#3. Taskbar) - * [3.1 Basic Functions](#3.1 Basic Functions) - * [3.1.1 Applications](#3.1.1 Applications) - * [3.1.2 Window Display Area](#3.1.2 Window Display Area) - * [3.1.3 Multi-View Switching](#3.1.3 Multi-View Switching) - * [3.1.4 Tray](#3.1.4 Tray) - * [3.1.4.1 Network](#3.1.4.1 Network) - * [3.1.4.2 Volume](#3.1.4.2 Volume) - * [3.1.4.3 Power Supply](#3.1.4.3 Power Supply) - * [3.1.4.4 Notification Center](#3.1.4.4 Notification Center) - * [3.1.4.5 Calendar](#3.1.4.5 Calendar) - * [3.1.4.6 Advanced Settings](#3.1.4.6 Advanced Settings) - * [3.1.4.7 Login User Actions](#3.1.4.7 Login User Actions) - * [3.1.4.7.1 Lock Screen](#3.1.4.7.1 Lock Screen) - * [3.1.4.7.2 Switch User](#3.1.4.7.2 Switch User) - * [3.1.4.7.3 Suspend](#3.1.4.7.3 Suspend) - * [3.1.4.7.3 Shut Down](#3.1.4.7.3 Shut Down) - * [3.1.4.7.3 Log Out](#3.1.4.7.3 Log Out) - * [4. Shortcut Operation Bar](#4. Shortcut Operation Bar) - * [4.1 Basic Functions](#4.1 [Basic Functions]) - * [4.1.1 Show Desktop](#4.1.1 Show Desktop) - * [4.1.2 Terminal](#4.1.2 Terminal) - * [4.1.3 File Manager](#4.1.3 File Manager) - * [4.1.4 Web Browser](#4.1.4 Web Browser) - * [4.1.5 Application Finder](#4.1.5 Application Finder) - * [4.1.6 User Home Directory](#4.1. 6 User Home Directory) - -# Xfce User Guide - -## 1\. Overview + + + + +- [Table of Contents](#table-of-contents) +- [Xfce Desktop Environment](#xfce-desktop-environment) + - [1. Overview](#1-overview) + - [2. Desktop](#2-desktop) + - [2.1 Desktop Icons](#21-desktop-icons) + - [2.2 Shortcut Menu](#22-shortcut-menu) + - [3. Taskbar](#3-taskbar) + - [3.1 Basic Functions](#31-basic-functions) + - [3.1.1 Applications](#311-applications) + - [3.1.2 Window Display Area](#312-window-display-area) + - [3.1.3 Multi-View Switching](#313-multi-view-switching) + - [3.1.4 Tray](#314-tray) + - [3.1.4.1 Network](#3141-network) + - [3.1.4.2 Volume](#3142-volume) + - [3.1.4.3 Power supply](#3143-power-supply) + - [3.1.4.4 Notification Center](#3144-notification-center) + - [3.1.4.5 Calendar](#3145-calendar) + - [3.1.4.6 Advanced Settings](#3146-advanced-settings) + - [3.1.4.7 Login User Actions](#3147-login-user-actions) + - [3.1.4.7.1 Lock Screen](#31471-lock-screen) + - [3.1.4.7.2 Switch User](#31472-switch-user) + - [3.1.4.7.3 Suspend](#31473-suspend) + - [3.1.4.7.3 Shut Down](#31473-shut-down) + - [3.1.4.7.3 Log Out](#31473-log-out) + - [4. Shortcut Operation Bar](#4-shortcut-operation-bar) + - [4.1 Basic Functions](#41-basic-functions) + - [4.1.1 Show Desktop](#411-show-desktop) + - [4.1.2 Terminal](#412-terminal) + - [4.1.3 File Manager](#413-file-manager) + - [4.1.4 Web Browser](#414-web-browser) + - [4.1.5 Application Finder](#415-application-finder) + - [4.1.6 User Home Directory](#416-user-home-directory) + + + + + +# Xfce Desktop Environment + +## 1. Overview Xfce is a lightweight desktop environment running on Unix-like operating systems. Xfce provides multiple functional components, including all applications. This document describes how to use Xfce. @@ -43,7 +52,8 @@ The following figure shows the WebUI. ![Figure 1 Main screen of the desktop - big](./figures/xfce-1.png)
-## 2\. Desktop + +## 2. Desktop ### 2.1 Desktop Icons @@ -73,7 +83,8 @@ The following table describes some options. | Applications| Applications|
-## 3\. Taskbar + +## 3. Taskbar ### 3.1 Basic Functions @@ -217,7 +228,8 @@ To log out of the GUI, click **Log Out**. Then, the system closes all running applications. Therefore, before performing this operation, save the current work.
-## 4\. Shortcut Operation Bar + +## 4. Shortcut Operation Bar ### 4.1 Basic Functions @@ -264,7 +276,7 @@ You can click the ![](./figures/xfce-95.png) icon on the shortcut operation bar ![Figure 28 Searching for an application - big](./figures/xfce-951.png) -#### 4.1. 6 User Home Directory +#### 4.1.6 User Home Directory Click ![](./figures/xfce-96.png) on the shortcut operation bar and click **Open File**. The user home directory page is displayed. diff --git a/docs/en/docs/desktop/install-DDE.md b/docs/en/docs/desktop/install-DDE.md index 05a05125a3867f2b12897901f08bcddad9a24274..533c6715a7ef084ccc40125f297cb1b6ade46d8a 100644 --- a/docs/en/docs/desktop/install-DDE.md +++ b/docs/en/docs/desktop/install-DDE.md @@ -1,31 +1,31 @@ -# DDE installation +# DDE Installation #### Introduction -DDE is a powerful desktop environment developed by UnionTech Team. Contains dozens of powerful desktop applications, which are truly self-developed desktop products. +DDE is a powerful desktop environment developed by UnionTech. It contains dozens of self-developed desktop applications. -#### installation method +#### Procedure -1. [download](https://openeuler.org/zh/download/) openEuler ISO and install the OS. -2. update the software source +1. [Download](https://openeuler.org/zh/download/) the openEuler ISO file and install the OS. +2. Update the software source. ```bash sudo dnf update ``` -3. install DDE +3. Install DDE. ```bash sudo dnf install dde ``` -4. set to start with a graphical interface +4. Set the system to start with the graphical interface. ```bash sudo systemctl set-default graphical.target ``` -5. reboot +5. Reboot the system. ```bash sudo reboot ``` -6. After the restart is complete, use the user created during the installation process or the openeuler user to log in to the desktop. +6. After the reboot is complete, use the user created during the installation process or the **openeuler** user to log in to the desktop. - > dde cannot log in with root account - > dde has built-in openeuler user, the password of this user is openeuler + > DDE does not allow login as the root user. + > DDE has a built-in openeuler user whose password is openeuler. -Now you can use dde. +Now you can use DDE. diff --git a/docs/en/docs/desktop/install-UKUI.md b/docs/en/docs/desktop/install-UKUI.md index 6fcb824248c13f0811e04664f5ff905e55640521..49376c728575d37ed59d771a6abeebe5979c88a1 100755 --- a/docs/en/docs/desktop/install-UKUI.md +++ b/docs/en/docs/desktop/install-UKUI.md @@ -1,21 +1,21 @@ -# UKUI installation +# UKUI Installation UKUI is a Linux desktop built by the KylinSoft software team over the years, primarily based on GTK and QT. Compared to other UI interfaces, UKUI is easy to use. The components of UKUI are small and low coupling, can run alone without relying on other suites. It can provide user a friendly and efficient experience. UKUI supports both x86_64 and aarch64 architectures. -We recommend you create a new administrator user before install UKUI. +You are advised to create an administrator user before installing UKUI. -1.download openEuler 21.09 and update the software source. +1. Download openEuler 21.09 and update the software source. ``` sudo dnf update ``` -2.install UKUI. +2. Install UKUI. ``` sudo dnf install ukui ``` -3.If you want to start with graphical interface after confirming the installation, please run this code and reboot(`reboot`). +3. If you want to set the system to start with the graphical interface after confirming the installation, run the following command and reboot the system (`reboot`). ``` systemctl set-default graphical.target ``` -At present, UKUI version is still constantly updated. Please check the latest installation method : +UKUI is constantly updated. Please check the latest installation method: [https://gitee.com/openkylin/ukui-issues](https://gitee.com/openkylin/ukui-issues) diff --git a/docs/en/menu/index.md b/docs/en/menu/index.md index 2171b9ce9b2790f596ce499f2861e6160fb46364..c903dd0b419c1132453bfd19ffa2d95e4c06dd7d 100644 --- a/docs/en/menu/index.md +++ b/docs/en/menu/index.md @@ -12,7 +12,7 @@ headless: true - [Common Vulnerabilities and Exposures (CVE)]({{< relref "./docs/Releasenotes/common-vulnerabilities-and-exposures-(cve).md" >}}) - [Source Code]({{< relref "./docs/Releasenotes/source-code.md" >}}) - [Contribution]({{< relref "./docs/Releasenotes/contribution.md" >}}) - - [Acknowledgement]({{< relref "./docs/Releasenotes/acknowledgement.md" >}}) + - [Acknowledgment]({{< relref "./docs/Releasenotes/acknowledgment.md" >}}) - [Quick Start]({{< relref "./docs/Quickstart/quick-start.md" >}}) - [Installation Guide]({{< relref "./docs/Installation/Installation.md" >}}) - [Installation on Servers]({{< relref "./docs/Installation/install-server.md" >}}) @@ -166,14 +166,25 @@ headless: true - [Installing and Deploying an HA Cluster]({{< relref "./docs/thirdparty_migration/installha.md" >}}) - [Desktop Environment User Guide]({{< relref "./docs/desktop/desktop.md" >}}) - [UKUI]({{< relref "./docs/desktop/ukui.md" >}}) - - [Installation UKUI]({{< relref "./docs/desktop/install-UKUI.md" >}}) + - [UKUI Installation]({{< relref "./docs/desktop/install-UKUI.md" >}}) - [UKUI User Guide]({{< relref "./docs/desktop/UKUI-user-guide.md" >}}) - [DDE]({{< relref "./docs/desktop/dde.md" >}}) - - [install-DDE]({{< relref "./docs/desktop/install-DDE.md" >}}) + - [DDE Installation]({{< relref "./docs/desktop/install-DDE.md" >}}) - [DDE User Guide]({{< relref "./docs/desktop/DDE-User-Manual.md" >}}) - - [XFCE]({{< relref "./docs/desktop/xfce.md" >}}) - - [Xfce Installation Guide]({{< relref "./docs/desktop/Install_XFCE.md" >}}) + - [Xfce]({{< relref "./docs/desktop/xfce.md" >}}) + - [Xfce Installation]({{< relref "./docs/desktop/Install_XFCE.md" >}}) - [Xfce User Guide]({{< relref "./docs/desktop/Xfce_userguide.md" >}}) - [Toolset User Guide]({{< relref "./docs/userguide/overview.md" >}}) - - [patch-tracking]({{< relref "./docs/userguide/patch-tracking.md" >}}) - - [pkgship]({{< relref "./docs/userguide/pkgship.md" >}}) \ No newline at end of file + - [Patch Tracking]({{< relref "./docs/userguide/patch-tracking.md" >}}) + - [pkgship]({{< relref "./docs/userguide/pkgship.md" >}}) +- [A-Ops User Guide]({{< relref "./docs/A-Ops/overview.md" >}}) + - [Anomaly Detection]({{< relref "./docs/A-Ops/anomaly-detection-service-manual.md" >}}) + - [Fault Diagnosis]({{< relref "./docs/A-Ops/fault-diagnosis-manual.md" >}}) + - [Service Deployment]({{< relref "./docs/A-Ops/service-deployment-manual.md" >}}) + - [Host Management]({{< relref "./docs/A-Ops/host-management-manual.md" >}}) + - [Auto Service Deployment]({{< relref "./docs/A-Ops/auto-service-deployment-manual.md" >}}) + - [Configuration Source Tracing]({{< relref "./docs/A-Ops/configuration-source-tracing-usage-guide.md" >}}) +- [KubeOS User Guide]({{< relref "./docs/KubeOS/kubeos-user-guide.md" >}}) + - [About KubeOS]({{< relref "./docs/KubeOS/about-kubeos.md" >}}) + - [Installation and Deployment]({{< relref "./docs/KubeOS/installation-and-deployment.md" >}}) + - [Usage Instructions]({{< relref "./docs/KubeOS/usage-instructions.md" >}}) \ No newline at end of file