diff --git a/translation-projects/README-optimization/translated-README/embedded-en.md b/translation-projects/README-optimization/translated-README/embedded-en.md new file mode 100644 index 0000000000000000000000000000000000000000..ac8d567498aa126bd9687eb8edc6bf0d97424353 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/embedded-en.md @@ -0,0 +1,116 @@ +# embedded + +#### 1 Introduction + +Support the openEuler version of embedded devices, currently supports two CPU architectures [aarch64|x86_64]. + +#### 2 Compilation Instructions + +build.sh is the compilation entry, used as follows: + +```Usage: +Usage: + +./build.sh -a [aarch64|x86_64] -r [repo] -d [work dir] -p [live|virtual|disk|docker] -t [rpm|image|all] +``` + +The function description of each parameter is as follows: + +1)\- r, specify the repo file in the configuration file format of dnf/yum, please refer to [document1](https://docs.openeuler.org/zh/docs/20.03_LTS/docs/Administration/%E4%BD%BF%E7%94%A8DNF%E7%AE%A1%E7%90%86%E8%BD%AF%E4%BB%B6%E5%8C%85.html "使用DNF管理软件包"). + +2) -d, specify the working directory used in the compilation process, where all intermediate files and results are stored. Since the compilation process requires large disk space, the directory should be located in a disk with **≥20G** free space. + +3) -p, specify the type of image to be compiled. Currently, docker image is stably supported. + +4) -t, specify the compilation type. rpm refers to the rpm repository compiled according to the source code and patch; image refers to the specified image compiled according to the given repo; all will execute the compilation process specified by rpm and image in order. + +5) a, no need to specify. Parameters supporting cross-compilation are reserved. + +The structure of the working directory during normal compilation (- specified by the d parameter) is as follows: + +``` +allsrcpath.list // List of packages to be compiled according to package_conf.xml +image/ // Storage location of the image and its description file +kiwiconfig/ +logs_1.tar.gz // Compilation log of each package in round 1/2 +logs_2.tar.gz // Compilation log of each package in round 2/2 +openeuler.repo +rpms/ // The directory where the rpm package of each package is compiled, which can be referenced as a repo source +src/ // Download and patch the source code files of each software package according to the configuration file +``` + +**Attention: if the compiled session (login terminal) is prone to disconnection, please use something like ```nohup sh build.sh -r ... > log.txt 2>&1 &```to execute the compilation**, avoiding compilation interruption caused by disconnection. + +#### 3 Configuration File Description + +The configuration files are located in the config directory: + +``` +kiwiconf/ +openeuler.repo +package_conf.xml +``` + +1) ```kiwiconf/```, storing the configuration files required by the kiwicompat command. Generally, no changes are required. + +The format of the config.xml refers to [document 2](https://documentation.suse.com/kiwi/9/single-html/kiwi/index.html#image-description-elements "image-description-elements")，[document 3](https://documentation.suse.com/kiwi/9/html/kiwi/image-description.html "image-description")。 + +Kiwi calls images.sh after creating the system directory. This script can be used to cut unnecessary files in the root directory or make some system settings. See [document 4](https://documentation.suse.com/kiwi/9/single-html/kiwi/index.html#script-template-for-config-sh-images-sh "script-template-for-config-sh-images-sh") for some predefined functions and variables available in this script. + +2) ```openeuler.repo```, reserved repo file, generally used in the -r parameter of build.sh. + +3) ```package_conf.xml```, you need to patch the source code repository with git format-patch and configure the software package for source code compilation. An example is given to illustrate the role of each tag. + +``` + + + argon2 + https://gitee.com/openeuler-embedded/argon2 + openEuler-20.03-LTS + ../src/patch/argon2.patch + 1 + + + attr + https://gitee.com/openeuler-embedded/attr + openEuler-20.03-LTS + ../src/patch/attr.patch + 1 + + ...... +``` + +#### 4 Example of Using the Image + +Take the docker image as an example. The image is located in the image path of the working directory and the name is openEuler-embedded.xxx-xxx.docker.tar.xz. + +```shell +docker load -i openEuler-embedded.xxx-xxx.docker.tar.xz +docker run --rm --privileged --name embedded-test -v `pwd`:/data -itd openeuler-embedded init +docker exec -it embedded-test bash +``` + +#### 5 Environmental Dependence + +1）kiwi >= 9.21 + +2）docker/chroot/createrepo/xmllint/openssl + +#### 6 TODO + +Up to now, rpm software package compilation and docker image production can be used stably. + +To be improved in the next stage: + +1) Image diversification support, such as virtual machine image and embedded device image. + +2) Scheduling module for rpm building, which can build all software packages based on the automatically identified dependencies. + +3) Support cross-compilation + +#### 7 Contribution + +1. Fork the repository. +2. Create Feat_xxx branch. +3. Commit local code. +4. Create Pull Request. diff --git a/translation-projects/README-optimization/translated-README/etmem-en.md b/translation-projects/README-optimization/translated-README/etmem-en.md new file mode 100644 index 0000000000000000000000000000000000000000..c5d8605a79464555e53f78bdf326f34efd16bad0 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/etmem-en.md @@ -0,0 +1,494 @@ +# etmem + +## Introduction + +With the development of CPU computing power, especially the reduction of ARM core cost, memory cost and memory capacity have become the core pain point that constrains business cost and performance. Therefore, how to save memory cost and how to expand memory capacity has become an urgent problem for storage. + +`etmem` memory grading expansion technology, through DRAM + memory compression/high-performance storage new media to form multi-level memory storage, grading the memory data, and migrating the tiered cold memory data from the memory medium to the high-performance storage medium to achieve memory capacity expansion, to achieve memory cost reduction. + +## Compilation Tutorial + +1. Download `etmem` source code + + $ git clone https://gitee.com/openeuler/etmem.git + +2. Compile and run dependencies + + The compilation and running of `etmem` depends on the `libboundscheck` component + +3. Compile + + $ cd etmem + + $ mkdir build + + $ cd build + + $ cmake .. + + $ make + + +## Instructions + +### Start the etmemd process + +#### How to use + +Run the server process by running etmemd binary, for example: + +$ etmemd -l 0 -s etmemd_socket + +#### Help information + +options： + +-l|\-\-log-level Log level + +-s|\-\-socket Socket name to listen to + +-h|\-\-help Show this message + +-m|\-\-mode-systemctl mode used to start(systemctl) + +#### Command-line parameter description + +| Parameter | Meaning | Required | Available parameter | Range | Description | +| ---------------------- | ------------------------------------------------------------ | -------- | ------------------- | ---------------------------- | ------------------------------------------------------------ | +| -l / -\-log-level | etmemd log level | NO | YES | 0~3 | 0: debug level 1: info level 2: warning level 3: error level Only the level greater than or equal to the configured level will be printed to the **/var/log/message** file | +| -s / -\-socket | Name of the etmemd listener, used to interact with the client | YES | YES | String within 107 characters | Specify the name of the server listener | +| -h / -\-help | Help information | NO | NO | NA | Execution with this parameter will print and then exit | +| -m / -\-mode-systemctl | When etmemd is pulled up as a service, this parameter can be used in the command to support fork mode startup | NO | NO | NA | NA | +### etmem configuration file + +Before running `etmem` processes, the administrator needs to plan which processes require memory expansion, configure the process information into the `etmem` configuration file, and configure the period of memory scan, number of scans, memory hot and cold thresholds, and other information. + +The sample configuration file is in the source package, placed in **conf/example_conf.yaml** in the root directory of the source code. It is recommended to be placed in the **/etc/etmem/** directory when in use. The sample content is: + +``` +[project] +name=test +loop=1 +interval=1 +sleep=1 + +#slide engine example +[engine] +name=slide +project=test + +[task] +project=test +engine=slide +name=background_slide +type=name +value=mysql +T=1 +max_threads=1 + +#cslide engine example +[engine] +name=cslide +project=test +node_pair=2,0;3,1 +hot_threshold=1 +node_mig_quota=1024 +node_hot_reserve=1024 + +[task] +project=test +engine=cslide +name=background_cslide +type=pid +name=23456 +vm_flags=ht +anon_only=no +ign_host=no + +#thirdparty engine example +[engine] +name=thirdparty +project=test +eng_name=my_engine +libname=/usr/lib/etmem_fetch/my_engine.so +ops_name=my_engine_ops +engine_private_key=engine_private_value + +[task] +project=test +engine=my_engine +name=backgroud_third +type=pid +value=12345 +task_private_key=task_private_value +``` + +Description of each field of the configuration file: + +| Configuration item | Meaning | Required | Available parameter | Range | Description | +| ------------------ | ------------------------------------------------------------ | ------------------------------------------------ | ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| [project] | Project common configuration segment start ID | NO | NO | NA | The beginning identification of the project parameter, which indicates that the following parameters are parameters of the project section until another [XXX] or the end of the file | +| name | Name of the project | YES | YES | String within 64 characters | Used to identify the project. Engine and task need to specify the project to be mounted when configuring | +| loop | Number of cycles of memory scan | YES | YES | 1~10 | loop=3 // Scan 3 times | +| interval | Time interval between each memory scan | YES | YES | 1~1200 | interval=5 // 5s between each scan | +| sleep | Time interval between major cycles of each memory scan and operation | YES | YES | 1~1200 | sleep=10 // 10s between each major cycle | +| [engine] | engine common configuration segment start ID | NO | NO | NA | The beginning identification of the engine parameter, which indicates that the following parameters are parameters of the engine section until another [XXX] or the end of the file | +| project | Declare the project | YES | YES | String within 64 characters | If a project named test already exists, it can be written as project=test | +| engine | Declare the engine | YES | YES | slide/cslide/thridparty | Declare that the slide or cslide or thirdparty strategy is used | +| node_pair | Configuration item of cslide engine, declares the node pair of AEP and DRAM in the system | Must be configured when engine is **cslide** | YES | Configure the node numbers of AEP and DRAM in pairs. AEP and DRAM are separated by commas and each pair is separated by semicolons | node_pair=2,0;3,1 | +| hot_threshold | Configuration item of cslide engine, declare the threshold of memory cold and hot threads | Must be configured when engine is **cslide** | YES | Integer >= 0 | hot_threshold=3 // Memory accessed less than 3 times is recognized as cold memory | +| node_mig_quota | Configuration item of cslide engine, flow control, declares the maximum one-way flow rate each time DRAM and AEP migrate to each other | Must be configured when engine is **cslide** | YES | Integer >= 0 | node_mig_quota=1024 // In MB, AEP to DRAM or DRAM to AEP relocation up to 1024M at a time | +| node_hot_reserve | Configuration item of cslide engine, declares the reserved space size of the hot memory in DRAM | Must be configured when engine is **cslide** | YES | Integer >= 0 | node_hot_reserve=1024 // In MB, when the hot memory of all virtual machines is greater than this configuration value, the hot memory will also be migrated to AEP | +| eng_name | Configuration item of thirdparty engine, declares the name of the engine for task mounting | Must be configured when engine is **thirdparty** | YES | String within 64 characters | eng_name=my_engine // When mounting a task on this third-party strategy engine, write engine=my_engine in the task | +| libname | Configuration item of thirdparty engine, declares the address(absolute address) of the dynamic library of the third-party strategy | Must be configured when engine is **thirdparty** | YES | String within 64 characters | libname=/user/lib/etmem_fetch/code_test/my_engine.so | +| ops_name | Configuration item of thirdparty engine, declares the name of the operation symbol in the dynamic library of the third-party strategy | Must be configured when engine is **thirdparty** | YES | String within 64 characters | ops_name=my_engine_ops // Name of the structure of the third-party strategy implementation interface | +| engine_private_key | Configuration item of thirdparty engine, which is reserved for third-party strategy task parsing private parameter configuration items, optional | NO | NO | Self-restriction according to third-party strategy private parameters | Self-configuration according to the third-party strategy private engine parameters | +| [task] | task common configuration segment start ID | NO | NO | NA | The beginning identification of the task parameter, which indicates that the following parameters are parameters of the task section until another [XXX] or the end of the file | +| project | Declare the project to be mounted | YES | YES | String within 64 characters | If a project named test already exists, it can be written as project=test | +| engine | Declare the engine to be mounted | YES | YES | String within 64 characters | Name of the engine to be mounted | +| name | Name of the task | YES | YES | String within 64 characters | name=background1 // Declare the name of the task as backgound1 | +| type | Type for target process identification | YES | YES | pid/name | pid means identified by process number, name means identified by process name | +| value | Specific fields for target process identification | YES | YES | Actual process number/process name | Used in conjunction with the type field to specify the process number or process name of the target process. The user ensures the correctness and uniqueness of the configuration. | +| T | Task configuration item when engine is slide, declare the threshold of memory cold and hot threads | Must be configured when engine is **slide** | YES | 0~loop * 3 | T=3 //Memory accessed less than 3 times is recognized as cold memory | +| max_threads | Task configuration item when engine is slide, the maximum number of threads in the etmemd internal thread pool, each thread handles the memory scanning and operation tasks of a process/sub process | NO | YES | 1~2 * (number of cores) + 1, default is 1 | No external appearance, control the number of internal processing threads on the etmemd server. When the target process has multiple sub-processes, the larger the configuration, the more concurrent executions, but also the more resources are occupied. | +| vm_flags | Task configuration item when engine is cslide, specifying the flag to scan vma, the scan will not be distinguished if this item is not configured | Must be configured when engine is **cslide** | YES | Only ht is currently supported | vm_flags=ht // Scan vma memory whose flags are ht (large pages) | +| anon_only | Task configuration item when engine is cslide, which identifies whether to scan only anonymous pages | NO | YES | yes/no | anon_only=no // When configured as yes, only anonymous pages will be scanned, and when configured as no, non-anonymous pages will also be scanned | +| ign_host | Task configuration item when engine is cslide, which identifies whether to ignore the page table scan information on the host | NO | YES | yes/no | ign_host=no // yes to ignore, no to not ignore | +| task_private_key | Task configuration item when engine is thirdparty, which is reserved for third-party strategy task parsing private parameter configuration items, optional | NO | NO | Self-restriction according to third-party strategy private parameters | Self-configuration according to the third-party strategy private task parameters | + + + +### Creation and deletion of etmem project/engine/task objects + +#### Use case + +1）The administrator creates the project/engine/task of etmem (a project can contain more than one etmem engine, and an engine can contain more than one task) + +2）The administrator deletes the existing etmem project/engine/task (all tasks in the project will be stopped automatically before deleting the project) + +#### How to use + +Run the `etmem` binary and specify the second parameter as obj to create or delete. For **project/engine/task**, it is identified and distinguished by the content configured in the configuration file. The prerequisite is that the `etmem` configuration file has been configured correctly and the `etmemd` process has been started. + +Add object: + +etmem obj add -f /etc/example_config.yaml -s etmemd_socket + +Delete object: + +etmem obj del -f /etc/example_config.yaml -s etmemd_socket + +Print help information: + +etmem obj help + +#### Help information + +Usage: + +etmem obj add [options] + +etmem obj del [options] + +etmem obj help + +Options: + +-f|\-\-file Add configuration file + +-s|\-\-socket Socket name to connect + +**Notes:** + +1. Configuration file must be given. + +#### Command-line parameter description + + +| Parameter | Meaning | Required | Available parameter | Description | +| --------------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------- | ------------------------------------------------------------ | +| -f / -\-file | Specify the configuration file | Must contain subcommand **add**, **del** | YES | Path name needs to be specified | +| -s / \-\-socket | The socket name to communicate with the etmemd server. Must be the same as that specified when etmemd is started | Must contain subcommand **add**, **del** | YES | Must be configured. When there is more than one etmemd, the administrator chooses which etmemd to communicate with | + +### etmem task start/stop/query + +#### Use case + +After the project has been added via `etmem obj add`, you can start and stop the project of `etmem` before calling `etmem obj del` to delete the project. + +1）The administrator starts the added project + +2）The administrator stops the started project + +When the administrator calls `obj del` to delete the project, if the project has been started, it will stop automatically. + +#### How to use + +For projects that have been successfully added, you can control the start and stop of the project by using the `etmem project` command. Examples are as follows: + +Start project + +etmem project start -n test -s etmemd_socket + +Stop project + +etmem project stop -n test -s etmemd_socket + +Query project + +etmem project show -n test -s etmemd_socket + +Print help + +etmem project help + +#### Help information + +Usage: + +etmem project start [options] + +etmem project stop [options] + +etmem project show [options] + +etmem project help + +Options: + +-n|\-\-name Add project name + +-s|\-\-socket Socket name to connect + +Notes: + +1. Project name and socket name must be given when executing add or del option. + +2. Socket name must be given when executing show option. + +#### Command-line parameter description + +| Parameter | Meaning | Required | Available parameter | Description | +| -------------- | ------------------------------------------------------------ | ----------------------------------------------------- | ------------------- | ------------------------------------------------------------ | +| -n / -\-name | Specify the name of the project | Must contain subcommand **start**, **stop**, **show** | YES | Project name, corresponding to the configuration file | +| -s / -\-socket | The socket name to communicate with the etmemd server. Must be the same as that specified when etmemd is started | Must contain subcommand **start**, **stop**, **show** | YES | Must be configured. When there is more than one etmemd, the administrator chooses which etmemd to communicate with | + +### etmem supports self-starting with the system + +#### Use case + +`etmemd` supports being pulled up in fork mode as a `systemd` service after the `systemd` configuration file is configured by the user. + +#### How to use + +Write a service configuration file to start `etmemd`, you must use the -m parameter to specify this mode, for example: + +etmemd -l 0 -s etmemd_socket -m + +#### Help information + +options: + +-l|\-\-log-level Log level + +-s|\-\-socket Socket name to listen to + +-m|\-\-mode-systemctl mode used to start(systemctl) + +-h|\-\-help Show this message + +#### Command-line parameter description +| Parameter | Meaning | Required | Available parameter | Range | Description | +| ----------------------- | ------------------------------------------------------------ | -------- | ------------------- | ---------------------------- | ------------------------------------------------------------ | +| -l / \-\-log-level | etmemd log level | NO | YES | 0~3 | 0: debug level 1: info level 2: warning level 3: error level Only the level greater than or equal to the configured level will be printed to the **/var/log/message** file | +| -s / \-\-socket | Name of the etmemd listener, used to interact with the client | YES | YES | String within 107 characters | Specify the name of the server listener | +| -m / \-\-mode-systemctl | When etmemd is pulled up as a service, this parameter can be used in the command to support fork mode startup | NO | NO | NA | NA | +| -h / \-\-help | Help information | NO | NO | NA | Execution with this parameter will print and then exit | + + + + +### etmem supports third-party memory expansion strategies + +#### Use case + +`etmem` supports users to register third-party memory expansion strategies, and provides a dynamic library of scanning modules. At runtime, memory is eliminated through the third-party strategy elimination algorithm. + +Users use the dynamic library of scan modules provided by `etmem` and implement the interfaces in the structures required by `etmem` + +#### How to use + +Users use their own third-party extension elimination strategy, which mainly needs to be implemented and operated according to the following steps: + +1. Call the scanning interface provided by the scanning module as needed; + +2. Implement each interface according to the function template provided in the etmem header file, and finally package it into a structure; + +3. Compile the dynamic library of the third-party extension elimination strategy; + +4. Declare the engine of `thirdparty` type in the configuration file as required; + +5. Fill the name of the dynamic library and the name of the interface structure into the fields corresponding to the task in the configuration file as required. + +Other steps are similar to other engines using `etmem` + +Interface structure template: + +struct engine_ops { + +/* Parsing for engine private parameters, if there is, needs to be implemented, otherwise set to NULL */ + +int (*fill_eng_params)(GKeyFile *config, struct engine *eng); + +/* Cleanup for engine private parameters, if there is, needs to be implemented, otherwise set to NULL */ + +void (*clear_eng_params)(struct engine *eng); + +/* Parsing of task private parameters, if there is, need to be implemented, otherwise set to NULL */ + +int (*fill_task_params)(GKeyFile *config, struct task *task); + +/* Cleanup for task private parameters, if there is, need to be implemented, otherwise set to NULL */ + +void (*clear_task_params)(struct task *tk); + +/* Interface to start the task */ + +int (*start_task)(struct engine *eng, struct task *tk); + +/* Interface to stop the task */ + +void (*stop_task)(struct engine *eng, struct task *tk); + +/* Fill in PID related private parameters */ + +int (*alloc_pid_params)(struct engine *eng, struct task_pid **tk_pid); + +/* Destroy PID related private parameters */ + +void (*free_pid_params)(struct engine *eng, struct task_pid **tk_pid); + +/* Private command support required by the third party strategy, if not, set to NUL */ + +int (*eng_mgt_func)(struct engine *eng, struct task *tk, char *cmd, int fd); + +}; + +A sample configuration file is shown below, please refer to the configuration file description section for details: + +#thirdparty + +[engine] + +name=thirdparty + +project=test + +eng_name=my_engine + +libname=/user/lib/etmem_fetch/code_test/my_engine.so + +ops_name=my_engine_ops + +engine_private_key=engine_private_value + +[task] + +project=test + +engine=my_engine + +name=background1 + +type=pid + +value=1798245 + +task_private_key=task_private_value + +**NOTE** ： + +Users need to use the dynamic library of the scan module provided by `etmem` and implement the interface in the structure required by `etmem` + +The fd in `eng_mgt_func` interface cannot write 0xff and 0xfe words + +Support adding multiple different third-party strategy dynamic libraries in a project, distinguished by `eng_name` in the configuration file + +### etmem supports memory expansion using AEP + +#### Use case + +Use the `etmem` component package to enable memory hierarchical expansion to the path of AEP. + +Scan large pages of VMs within the node and perform strategy elimination through the `cslide` engine to move the cold memory to the AEP. + +#### How to use + +Use the `cslide` engine for memory expansion, the following parameter examples are available, please refer to the configuration file description chapter for specific parameter meanings. + +#cslide + +[engine] + +name=cslide + +project=test + +node_pair=2,0;3,1 + +hot_threshold=1 + +node_mig_quota=1024 + +node_hot_reserve=1024 + +[task] + +project=test + +engine=cslide + +name=background1 + +type=pid + +value=1823197 + +vm_flags=ht + +anon_only=no + +ign_host=no + + **WARNING** : Prohibit concurrent scanning of the same process + +Meanwhile, this `cslide` strategy supports private commands. + + +- showtaskpages +- showhostpages + +For the engine and all tasks that use this strategy engine, you can use these two commands to view task-related page access and the use of system large pages on the host of the virtual machine. + +Example commands are as follows: + +etmem engine showtaskpages <-t task_name> -n proj_name -e cslide -s etmemd_socket + +etmem engine showhostpages -n proj_name -e cslide -s etmemd_socket + +**Note**: showtaskpages and showhostpages are only supported when the engine uses `cslide`. + +#### Command-line parameter description +| Parameter | Meaning | Required | Available parameter | Description | +| ----------------- | ------------------------------------------------------------ | -------- | ------------------- | ------------------------------------------------------------ | +| -n / -\-proj_name | Specify the name of the project | YES | YES | Specify the name of the project that already exists and needs to be executed | +| -s / -\-socket | The socket name to communicate with the etmemd server. Must be the same as that specified when etmemd is started | YES | YES | Must be configured. When there is more than one etmemd, the administrator chooses which etmemd to communicate with | +| -e / -\-engine | Specify the name of the engine to be executed | YES | YES | Specify the name of the engine that already exists and needs to be executed | +| -t / -\-task_name | Specify the name of the task to be performed | NO | YES | Specify the name of the task that already exists and needs to be executed | + +## Contribution + +1. Fork the repository. +2. Create Feat_xxx branch. +3. Commit local code. +4. Create Pull Request. diff --git a/translation-projects/README-optimization/translated-README/geo-coding-en.rst b/translation-projects/README-optimization/translated-README/geo-coding-en.rst new file mode 100644 index 0000000000000000000000000000000000000000..39cb79d8f4f745d5844bf7251f58fdeacdbc7a3c --- /dev/null +++ b/translation-projects/README-optimization/translated-README/geo-coding-en.rst @@ -0,0 +1,80 @@ +1. ========== + geo-coding + ========== + geo-coding is a Python client for geo-coordinate-related services, including common and popular features such as geocoder, coordinate calculation, and coordinate system conversion. + + Use Cases + ------------ + + * Used for businesses and projects that require latitude and longitude geographic coordinate positioning and calculation, such as various geographic coordinate big data projects. + * Used as the underlying toolkit for similar map projects, providing tools for many businesses that need to calculate latitude and longitude to determine orientation. + + Features + ------------ + 1. Geocoder: Enable developers to easily locate coordinates of addresses, cities, countries, and landmarks around the world using third-party geocoding programs and other data sources. + Plan development sequence: Baidu, Gaode... + + 2. Coordinate system conversion: Convert latitude and longitude coordinates using the standard of Baidu, Gaode, Geodetic Coordinate System, and Ordnance Survey... + + 3. Distance: calculate the actual distance between coordinates and other practical functions. + + 4. Unit conversion. + + 5. Data: Longitude and Latitude Coordinates of China's Border + + Advantages + ------------ + At present, most of the software with geographic functions is very bloated, and there are only few coordinate software adapted to Map of China. The library is a lightweight tool based on only Python, which aimed to enrich the functions and provide low-level and fast services for actual business. + + Development Plan Sequence + ------------ + * 2,5,3,4,1 + + Version Support + ------------ + * Python 3.x + * Linux: build/passing + * Windows: build/passing + + Usage examples + ------------ + * + + + Start Contributing + ------------ + Ready to contribute or use? Here's how to set up "geo-coding" for local development. + + 1. Fork `geo-coding` repository on Gitee. + 2. Clone your repository locally::: + + $ git clone https://gitee.com/weihaitong/geo-coding.git + + 3. Here is how to use this tool::: + + $ cd geo-coding/ + $ python setup.py install + + 4.If you want to contribute to the project, you can create a branch for local development.:: + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make changes locally. + + 5. Submit your changes and push your branch to Gitee::: + + $ git add . + $ git commit -m "Your detailed description of the changes" + $ git push origin name-of-your-bugfix-or-feature + + 6. Submit a pull request on Gitee. + + + Pull Request Guide + ----------------------- + + Please check that it meets the following guidelines before submitting a pull request: + + 1. The pull request should include tests. + 2. Update the document if the pull request adds a feature. Put your new feature into a function with a document string and add it to the list in README.rst. + 3. The pull request should work with Python 3.x. And make sure the tests pass all supported Python versions. diff --git a/translation-projects/README-optimization/translated-README/integration-test-en.md b/translation-projects/README-optimization/translated-README/integration-test-en.md new file mode 100644 index 0000000000000000000000000000000000000000..97e2a6873298323c97fe825d0afcbf23677d8fb3 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/integration-test-en.md @@ -0,0 +1,39 @@ +# integration-test + +## Introduction +This repository provides source code for openEuler OS integration and smoke test. + +## Software Architecture +Software architecture description: + +├── README.md +├── License +│ └── LICENSE +├── suite2cases +└── testcases + +## Instructions +The test code provided by this repository is written based on the [mugen](https://gitee.com/openeuler/test-tools.git) framework. Use the test code by steps: + +- Download [mugen](https://gitee.com/openeuler/test-tools.git) test framework. +- Download the test code from this repository and archive it to the corresponding directory of the test framework. +- Follow the [mugen usage guide](https://gitee.com/openeuler/test-tools/blob/master/mugen/README.md) for test execution. + +## Contributing Guide +1. Fork the repository. +2. Define the correspondence between test suites and test cases in the specified files in the suite2cases directory. +3. Write test code in testcases directory with reference to [test case naming and code programming specification](https://gitee.com/openeuler/package-reinforce-test/blob/master/测试用例命名及代码编程规范.md). +4. Download the mugen test framework and complete code debugging. +5. Submit local code. +6. Create a new Pull Request on Gitee. + + +#### Gitee Feature + +1. Use Readme_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md. +2. Visit Gitee blog on [blog.gitee.com](https://blog.gitee.com). +3. Explore outstanding open-source projects on [https://gitee.com/explore](https://gitee.com/explore). +4. Learn from [GVP](https://gitee.com/gvp) (Gitee Most Valuable Project, overall rating by Gitee). +5. Read the manual of Gitee on [https://gitee.com/help](https://gitee.com/help). +6. Take a look at Gitee Cover Character (a column used to show the style of Gitee members) on [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/). + diff --git a/translation-projects/README-optimization/translated-README/kata_integration-en.md b/translation-projects/README-optimization/translated-README/kata_integration-en.md new file mode 100644 index 0000000000000000000000000000000000000000..75ed5a451c73a328e845376d857883a9db949e4f --- /dev/null +++ b/translation-projects/README-optimization/translated-README/kata_integration-en.md @@ -0,0 +1,17 @@ +# kata_integration + +#### Introduction +Build Kata containers related component integration tools. + +#### Instructions + +1. Download kata containers related component codes to the root directory of the tool. +2. Execute make all to compile all kata components. +3. Use make xxx to compile a single component. + +#### Contributing Guide + +1. Fork the repository. +2. Submit local code. +3. Create a new Pull Request on Gitee. + diff --git a/translation-projects/README-optimization/translated-README/nvwa-en.md b/translation-projects/README-optimization/translated-README/nvwa-en.md new file mode 100644 index 0000000000000000000000000000000000000000..664df4893865e889ac51203ebdeddef6e17d2095 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/nvwa-en.md @@ -0,0 +1,63 @@ +# nvwa + +#### Introduction + +nvwa is a tool used for automated hot upgrades of openEuler. + +#### Construction Method + +``` +cd src +go get nvwa +go build +``` + +#### About Configuration + +The configuration file is placed in the **config** directory. When running, the binary system will search for the configuration file in three places, in the following order: + +1. Running directory +2. **config** subdirectory of the running directory +3. **/etc/nvwa** + +The configuration files include: + +1. **nvwa-restore.yaml** + +Processes and services that need to be restored on-site. For each service, nvwa will modify the the configuration of systemd and restore the running state through systemd. + +2. **nvwa-server.yaml** + +Directories, logs, binary directory configurations, etc. required for hot upgrades. + + +#### Supported Commands + +- **nvwa update** -- Hot upgrade to the corresponding kernel version (relevant files must be placed under **/boot**) + + nvwa will search for the required kernel and rootfs in the **/boot** directory. The kernel must be named in the **vmlinuz**- format and the rootfs must be named in **initramfs**-**.img** format. + ++ **nvwa help** + + Display helpful information about the client. + ++ **nvwa init** + + Delete the image generated by nvwa and modify the service. + +## Restrictions on Restoring the Service + +The standard output and error output of the service must be set to files. +The pid occupation error may occur during service restoration. + +## Check nvwa Run Log + +> service nvwa status + +## Development Plan + ++ Manage the logs of **criu/kexec/nvwa** in a centralized manner. ++ Print timestamps and automatically calculate the delay. + +## Kernel Boot Acceleration Patch ++ The patch is stored in the patches directory. Different kernel versions have different patch sets. diff --git a/translation-projects/README-optimization/translated-README/oec-hardware-en.md b/translation-projects/README-optimization/translated-README/oec-hardware-en.md new file mode 100644 index 0000000000000000000000000000000000000000..c175645dde177d1d3d4150e5b7ac317ac0d51684 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/oec-hardware-en.md @@ -0,0 +1,334 @@ + + +- [Overview](#Overview) + - [Background](#Background) + - [Principle](#Principle) + - [Framework](#Framework) + - [Test process](#Test process) + - [Use process](#Use process) + - [User flow](#User flow) + - [Network diagram](#Network diagram) +- [Install test frame](#Install test frame) + - [Prerequisites](#Prerequisites) + - [Get installation package](#Get installation package) + - [Installation process](#Installation process) + - [Client](#Client) + - [Server](#Server) + - [Verify installation correctness](#Verify installation correctness) +- [User guide](#User guide) + - [Prerequisites](#Prerequisites-1) + - [Use steps](#Use steps) +- [View Results](#View Results) + - [How to view](#How to view) + - [Results Description & Suggestion](#Results Description & Suggestion) +- [Appendix: Test item descriptions](#Appendix: Test item descriptions) + - [Existing test items](#Existing test items) + - [New test items](#New test items) + + + +# Overview + +## Background + +To expand the compatibility range of their products, OS manufacturers often seek cooperation with hardware manufacturers for compatibility testing. The OS manufacturer formulates a test standard and provides test cases for the hardware manufacturer to carry out the actual test. After the test is passed, OS manufacturers and hardware manufacturers will jointly publish compatibility information on the corresponding official website. + +The purpose of verification is to ensure the compatibility between OS and hardware platforms. Verification is limited to basic function verification, not including performance test and other tests. + +The openEuler hardware compatibility verification test framework has the following features: + +1. To meet the trustworthy requirements, you must use the openEuler OS, and the kernel module cannot be reprogrammed/inserted at will. +2. Discover the hardware list adaptively through the scanning mechanism to determine the set of test cases to run. +3. Object-oriented abstraction of various hardware types and test case classes for extended development. + +## Principle + +### Framework + +``` +. +├── hwcompatible Framework main function +│ ├── compatibility.py Framework main function +│ ├── client.py Upload test results to the server +│ ├── command.py bash command execution package +│ ├── commandUI.py Command line interactive tool +│ ├── device.py Scan device information +│ ├── document.py Collect configuration information +│ ├── env.py Global variables, mainly paths of each configuration file or directory +│ ├── job.py Test task management +│ ├── log.py Log module +│ ├── reboot.py Dedicated to restart tasks, so that the machine can continue to execute tests even after reboot +│ ├── sysinfo.py Collect system information +│ └── test.py Test suite template +├── scripts Tool scripts +│ ├── oech Framework command line tool +│ ├── oech-server.service Framework server service file, used to start the web server +│ ├── oech.service Framework client service file, used to take over reboot instances +│ └── kernelrelease.json Specification of the system and kernel version that can be used for certification +├── server Server +│ ├── oech-server-pre.sh Service pre-execution script +│ ├── results/ Test result storage directory +│ ├── server.py Server main program +│ ├── static/ Picture storage directory +│ ├── templates/ Webpage template storage directory +│ ├── uwsgi.conf nginx service configuration +│ └── uwsgi.ini uwsgi service configuration +└── tests Test suite +``` + + + +### Test process + +![test-flow](docs/test-flow.png) + +## Use process + +### User flow + +![user-flow](docs/user-flow.png) + +### Network diagram + +![test-network](docs/test-network.png) + +# Install test frame + +## Prerequisites + +Openeuler 20.03 (LTS) or later is installed. + +## Get installation package + +https://gitee.com/src-openeuler/oec-hardware/releases + +## Installation process + +### Client + +1. Configure the corresponding version of everything source in [the official repo of openEuler](https://repo.openeuler.org/) and install the client oec-hardware using `dnf`. + + ``` + dnf install oec-hardware-XXX.rpm + ``` + +### Server + + 1. Configure the corresponding version of everything source in [the official repo of openEuler](https://repo.openeuler.org/) and install the server oec-hardware-server using `dnf`. + + ``` + dnf install oec-hardware-server-XXX.rpm + ``` + + 2. Some components required by the web display page are not provided by the system itself and need to be installed using pip3 (please configure the available pip source by yourself). + + ``` + pip3 install Flask Flask-bootstrap uwsgi + ``` + + 3. Start the service. This service uses port 8080 by default and provides Web services with nginx (default port 80). Please ensure that these ports are not occupied. + + ``` + systemctl start oech-server.service + systemctl start nginx.service + ``` + + 4. Turn off the firewall and SElinux. + + ``` + systemctl stop firewalld + iptables -F + setenforce 0 + ``` + + ## Verify installation correctness + + If the client enters the `oech` command and it runs, the installation is successful. If you have any problems with the installation, please send your feedback to oecompatibility@openeuler.org. + + # User guide + + ## Prerequisites + + * `/usr/share/oech/kernelrelease.json` file lists all currently supported system versions. Use `uname -a` command to confirm whether the framework supports the current system kernel version. + * The framework will scan all NICs by default. Before testing the NIC, please filter the NIC under test and assignit an IP that can `ping` the server. If the client is testing the InfiniBand NIC, the server must also have an InfiniBand NIC and configure the IP in advance. + + ## Use stepsassign it + + 1. Start the test framework on the client. Start `oech` on the client, where `ID` and `URL` can be filled in as needed. `ID` is recommended to fill in the issue ID on gitee. `Server` must be filled in as the server domain name or ip that the client can access directly, which is used to display test reports and serve for network testing. + + ``` + # oech + The openEuler Hardware Compatibility Test Suite + Please provide your Compatibility Test ID: + Please provide your Product URL: + Please provide the Compatibility Test Server (Hostname or Ipaddr): + ``` + + 2. Enter the test suite selection interface. In the case selection interface, the framework will automatically scan the hardware and select the test suite available for testing in the current environment. Enter `edit` to enter the test suite selection interface. + + ``` + These tests are recommended to complete the compatibility test: + No. Run-Now? Status Class Device + 1 yes NotRun acpi + 2 yes NotRun clock + 3 yes NotRun cpufreq + 4 yes NotRun disk + 5 yes NotRun ethernet enp3s0 + 6 yes NotRun ethernet enp4s0 + 7 yes NotRun ethernet enp5s0 + 8 yes NotRun kdump + 9 yes NotRun memory + 10 yes NotRun perf + 11 yes NotRun system + 12 yes NotRun usb + 13 yes NotRun watchdog + Ready to begin testing? (run|edit|quit) + ``` + + 3. Select the test suite. `all|none` is used to `select all|cancel all` respectively (the required test item`system` cannot be cancelled); the number can select the test suite, and only one number can be selected each time. After pressing the enter character, `no` changes to `yes`, indicating that the test set has been selected. + + ``` + Select tests to run: + No. Run-Now? Status Class Device + 1 no NotRun acpi + 2 no NotRun clock + 3 no NotRun cpufreq + 4 no NotRun disk + 5 yes NotRun ethernet enp3s0 + 6 no NotRun ethernet enp4s0 + 7 no NotRun ethernet enp5s0 + 8 no NotRun kdump + 9 no NotRun memory + 10 no NotRun perf + 11 yes NotRun system + 12 no NotRun usb + 13 no NotRun watchdog + Selection (|all|none|quit|run): + ``` + + 4. Start the test. Enter `run` to start the test after the selection is completed. + + 5. Upload test results. After the test is completed, you can upload the test results to the server for displaying the results and log analysis. If the upload fails, please check the network configuration and then re-upload the test results. + + ``` + ... + ------------- Summary ------------- + ethernet-enp3s0 PASS + system FAIL + Log saved to /usr/share/oech/logs/oech-20200228210118-TnvUJxFb50.tar succ. + Do you want to submit last result? (y|n) y + Uploading... + Successfully uploaded result to server X.X.X.X. + ``` + + + + # View Results + + ## How to view + + 1. Open the server IP address in the browser, click the `Results` interface in the navigation bar, and find the corresponding test id to enter. + + ![results](docs/results.png) + + 2. Enter a single task page to see the specific test results, including environment information and execution results. + + - `Submit` Submit means Upload the results to the official certification server of openEuler (**not yet open**). + + - `Devices` view all test device information. + + - `Runtime` View the test run log. + + - `Attachment` Download test attachments. + + ![result-qemu](docs/result-qemu.png) + + + + ## Results Description & Suggestion + +The test results are displayed in the **Result** column. There are two types of results: **PASS** or **FAIL**. If the result is **FAIL**, you can directly click on the result to view the execution log, and check according to the error report and use case code. + + # Appendix: Test item descriptions + + ## Existing test items + + 1. **system** + + - Check whether the tool has been modified. + - Check whether the OS version and kernel version match. + - Check whether the kernel has been modified/infected. + - Check whether selinux is enabled properly. + - Use `dmidecode` tool to read the hardware information. + + 2. **cpufreq** + + - Test whether the cpu runs at the same frequency as expected with different tuning strategies. + - Test whether the time required for a cpu to perform exactly the same amount of computation at different frequencies is inversely correlated with the frequency value. + + 3. **clock** + + - Test time vectoriality without backwards. + - Test the basic stability of the RTC hardware clock. + + 4. **memory** + + - Use `memtester` tool for memory read-write test. + - mmap all available system memory, trigger swap, and perform 120s read and write tests. + - Test hugetlb。 + - Memory hot-swap test. + + 5. **network** + + - Use `ethtool` to get NIC information and `ifconfig` to perform down/up tests on the NIC. + - Use `qperf` to test tcp/udp latency and bandwidth, as well as http upload and download rates of Ethernet card. + - Use `perftest` to test InfiniBand or RoCE NIC latency and bandwidth. + - **NOTE** During the network bandwidth test, please confirm in advance that the server NIC rate is not less than that of the client, and ensure that there is no other traffic interference in the test network. + + 6. **disk** + + Use `fio` tool to perform sequential/random read and write tests on bare disks/file systems. + + 7. **kdump** + + Trigger `kdump` to test whether the vmcore file can be generated and parsed properly. + + 8. **watchdog** + + Trigger `watchdog` to test whether the system can be reset properly. + + 9. **perf** + + Test whether the `perf` tool works properly. + + 10. **cdrom** + + Use `mkisofs` and `cdrecord` to record and read the optical drive. + + 11. **ipmi** + + Use `ipmitool` to query IPMI information. + + 12. **nvme** + + Use `nvme-cli` tool to format, read and write, and query the disk. + + 13. **usb** + + Plug and unplug the usb device to test whether the usb interface can be recognized properly. + + 14. **acpi** + + Use `acpidump` tool to read data. + + ## New test items + + 1. Add your own test templates in `tests/` to implement your own test class inheritance framework `Test`. + + 2. Important member variables or functions. + + - Function `test` - **Required**, the main process of the test. + - Function `setup` - Environment preparation before testing. It is mainly used to initialize the related information of the tested device, see the `network test`. + - Function `teardown` - Clean up the environment after the test is completed. It is mainly used to ensure that the environment can be restored correctly regardless of the success or failure of the test, see the `network test`. + - Variable `requirements` - An array that stores the names of the rpm packages that the test depends on, and the framework will be installed automatically before the test starts. + - Variable `reboot` and `rebootup` - If `reboot = True`, the test suite/test case will reboot the system and continue to execute the functions specified by `rebootup` after the reboot, see the `kdump test`. diff --git a/translation-projects/README-optimization/translated-README/openeuler-wiki-bot-en.md b/translation-projects/README-optimization/translated-README/openeuler-wiki-bot-en.md new file mode 100644 index 0000000000000000000000000000000000000000..395fad3272080366cd6442ab3f45085754ccf345 --- /dev/null +++ b/translation-projects/README-optimization/translated-README/openeuler-wiki-bot-en.md @@ -0,0 +1,29 @@ +openeuler-wiki-bot +============== + +## Usage + +```bash +usage: openeuler-wiki-bot.py [-h] [-l] [-r] [-s SIG] [-a] + +openEuler wiki bot. + +optional arguments: + -h, --help show this help message and exit + -l, --list List all sig info. + -r, --report Generate information report. + -s SIG, --sig SIG Specify sig group. + -a, --all Report information for all sig. +``` + +#### Example1: Get the sig list + +```bash +./openeuler-wiki-bot.py -l +``` + +#### Example2: Get all issues and prs of sig-ai-big data + +```bash +./openeuler-wiki-bot.py -r -s sig-ai-bigdata +``` diff --git a/translation-projects/README-optimization/translated-README/operator-manager-en.md b/translation-projects/README-optimization/translated-README/operator-manager-en.md new file mode 100644 index 0000000000000000000000000000000000000000..0f570e9f6d6b0341b1d4f811d31f43dfd89a2c7b --- /dev/null +++ b/translation-projects/README-optimization/translated-README/operator-manager-en.md @@ -0,0 +1,162 @@ +# Operator-manager +[![](https://img.shields.io/badge/language-Go-brightgreen.svg)](https://github.com/golang/go) +[![](https://img.shields.io/badge/Dependence-Kubebuilder-blue.svg)](https://book.kubebuilder.io/) +[![](https://img.shields.io/badge/Reference-OLM-important.svg)](https://operatorframework.io) + +## Overview + +`Operator-Manager` is a lightweight Operator management framework designed based on [kubebuilder](https://book.kubebuilder.io/) architecture. The framework is mainly based on [kubenetes](https://kubernetes.io/) custom resources, deploying the required version of `Operator` through stateful operation management mode, and can support `Operator` uninstallation, version update, and other operations to achieve convenient cloud-native application management. + +## Architecture + +Architecture + +The design principle of `Operator-Manager` is to use `operator` to manage `operator`, which is based on Kubernetes secondary development and can help operations and maintenance staff to manage stateful applications efficiently. The `operator-manager` regards the `operator` to be managed as a kind of stateful application and manages the `crd`, `service account`, `webhook`, and other dependencies of the `operator`. + +`Operator-Manager` is mainly based on the following three types of `crd` and `controller`. + +| Resource | Controller | Version | Description | +| --------------------- | -------------------------------- | -------- | ------------------------------------------------------------ | +| ClusterServiceVersion | ClusterServiceVersion_Controller | v1alpha1 | Including Operator's application metadata, name, version, logo, required resources, installation strategy, etc... | +| BluePrint | BluePrint_Controller | v1 | Resolve and deploy the crd resources that csv and operator depend on, and implement version management based on BluePrint in the cluster | +| Subscription | Subscription_controller | v1 | Connect with the user, and the user initiates a request by modifying the relevant instance of the subscription deployed in the cluster | + +| controller | Creatable Resources | +| -------------------------------- | -------------------------- | +| ClusterServiceVersion_Controller | Deployment | +| ClusterServiceVersion_Controller | Service Account | +| ClusterServiceVersion_Controller | (Cluster)Roles | +| ClusterServiceVersion_Controller | (Cluster)RoleBindings | +| BluePrint_Controller | Custom Resource Definition | +| BluePrint_Controller | ClusterServiceVersion | +| Subscription_Controller | BluePrint | + +## Design + +Compared with the [OLM](https://operatorframework.io) architecture designed by `CoreOS`, our lightweight `operator` management architecture eliminates directory management and reduces resource overhead. `Operator Manager` consists of three Controllers: `Subscription Controller`, `BluePrint Controller` and `ClusterServiceVersion Controller`. The `Subscription Controller` is responsible for processing the subscription request initiated by the user, interacting with the [operatorhub](https://operatorhub.io/), completing the operator verification, downloading the required dependent resources from the cloud server, and resolving the user subscription to create the corresponding `BluePrint CRD`. `BluePrint Controller` is responsible for resolving dependencies and creating CRDs for operators to be created/upgraded/rolled back/deleted. The `ClusterServiceVersion Controller` is responsible for deploying the operators to be created/upgraded/rolled back/deleted to the cluster through the `deployment` controller. After checking the dependent resources and dependent permissions, deploy the `service account` and `RBAC rules`. + +## Features + +| Feature | Completion Status | +| ----------------------------------- | ------------------ | +| User initiated subscription request | :heavy_check_mark: | +| Operator dependency resolution | :heavy_check_mark: | +| Install and deploy operator | :heavy_check_mark: | +| Version management | :heavy_check_mark: | +| Bind service account | :heavy_check_mark: | +| Authority management | :heavy_check_mark: | +| Status check | :heavy_check_mark: | +| Uninstall and remove operator | :heavy_check_mark: | +| Docking operatorhub.io | :heavy_check_mark: | +| Web Dashboard | :x: | + + +## Prerequisites +- [git][git_tool] +- [go][go_tool] version v1.13+. +- [docker][docker_tool] version 17.03+. +- [kubectl][kubectl_tool] version v1.11.3+. +- [kubebuilder][kubebuilder_tool] +- Access to a Kubernetes v1.16.3+ cluster. + +The `MakeFile` exists in the root directory of the project. After the file is executed, the following tools will be installed during the process of creating the project: +- [kustomize](https://kubernetes-sigs.github.io/kustomize/) +- [controller-gen](https://github.com/kubernetes-sigs/controller-tools) + + +## Quick Start + +### Install + +1. Execute `cd $GOPATH/src/github.com && mkdir -p buptGophers && cd buptGophers` +2. Download the project source code to the local repository, execute `git clone https://gitee.com/openeuler2020/team-1924513571.git` +3. Change the project name, make sure the project path is correct, execute `mv team-1924513571 operator-manager && cd operator-manager` +4. Install the `operator-manager` project dependencies according to `MAKEFILE`, execute `make install` + +**NOTE:** The project now supports ARM/AMD architecture deployment. You may encounter installation errors after executing the `make install` command. Please make sure the following operations: `ENV GOPROXY="https://goproxy.io`/`ENV GO111MODULE=onGOPROXY`.If you encounter other problems, please contact us. + +## Use loaclly + +1. Start Project + + Excute `make run ` locally + +2. Subscription Request + + Once the project starts normally, users can initiate operator management by deploying a `cr` instance of `subscription` and deploying that `cr` instance to the cluster manually. + + For `cr` instances, see the project directory `/config/samples`. + + ```yaml + apiVersion: operators.coreos.com.operator-manager.domain/v1 + kind: Subscription + metadata: + name: subscription-sample + spec: + # Add fields here + startingCSV: prometheus.0.22.2 + option: create + foo: bar + status: + opstatus: not operate + ``` + **NOTE:** To delete, change the `spec.option` field to `delete`. + +3. Monitor the running status of the cluster + + Users can check the running status of `operator-manager` according to the log information printed by the cluster, or obtain the running status of `subscription`, `blueprint`, `clusterserviceversion`, `crd`, `deployment`, ` pod`, `serviceaccount`, `RBAC rules` and other related resources through the `kubect` command to check whether the user subscription content is completed. + +4. Other operations + + The user can also directly design the `cr` instance of `BluePrint` to complete the management operation of `operator`. However, the `cr` instance of `BluePrint` requires a lot of manual modification information. It is recommended that the user complete the `operator` management operation by the `cr` of `Subscription`. + +5. Start the file server + + Users can access the `community-operators` directory and execute `go mod download` operation to configure the `Gin` environment. Execute `go run main.go` to start the local file server. + +# Key Concepts + +## Subscription + +Connect with the user. The user initiates a request by modifying the relevant instance of the subscription deployed in the cluster. + +## BluePrint + +Resolve and deploy `crd` resources that `csv` and `operator` depend on, and implement version management based on `BluePrint` inside the cluster. + +## ClusterServiceVersion + +Include: + +- Application metadata. (name, description, version definition, links, icons, labels, etc.) +- Installation strategies, including the set of deployments required during the `Operator` installation and the set of permissions such as `service accounts`, RBAC roles, and bindings. +- CRDs: Including the type of `CRD`, the service it belongs to, other k8s native resources interacted by `operator` and `spec`, `status` field descriptors that contain semantic information about the model. + +## CRD + +To simplify the cost of running applications in `Kubernetes`, OLM can discover and resolve dependencies between running applications by defining additional metadata on the application. + +Each `Operator` must define the following: + +- The `CRD` that it is responsible for managing, for example, `Operator Etcd` is used to manage `EtcdCluster`; +- The `CRD` it depends on, for example, `Operator Valut` depends on `EtcdCluster` because Valut is supported by etcd. + The basic dependency resolution is then achieved by finding the corresponding `Operator` to manage and install the `CRD`s required by the application. The way users interact with the directory may further limit dependency resolution. + +### Controller + +Controller is the core concept of `Kubernetes`. The job of the controller is to ensure that the actual state (including the cluster state, as well as the external state) matches the desired state of any given object. This process is called reconciling. In `controller-runtime`, the logic that implements reconciling for a specific type is called `Reconciler`, which is the key logic of the controller. + +## Acknowledgement + +- [OpenEuler](https://openeuler.org/): `Operator-manager` project uses the OpenEuler operating system for development; +- [OSCHINA](https://www.oschina.net/): `Operator-manager` project comes from the OSCHINA open-source competition; +- [PENG CHENG LABORATORY](https://www.pcl.ac.cn/): `Operator-manager` project developed and tested on the Kunpeng server of Pengcheng laboratory； + +[architecture]: /doc/design/architecture.md +[philosophy]: /doc/design/philosophy.md +[installation guide]: /doc/install/install.md +[git_tool]:https://git-scm.com/downloads +[go_tool]:https://golang.org/dl/ +[docker_tool]:https://docs.docker.com/install/ +[kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ +[kubebuilder_tool]:https://book.kubebuilder.io/quick-start.html