add more plugin description

Author: kakzhou719

.github/workflows/.mlc_config.json

@@ -0,0 +1,10 @@
+{
+    "ignorePatterns": [
+        {
+            "pattern": "^http://127.0.0.1"
+        },
+        {
+            "pattern": "^http://localhost"
+        }
+    ]
+}

.gitignore

@@ -0,0 +1,16 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+_output
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+.idea
+seautil/seautil
+sealer/sealer
+*.swp

README.md

@@ -1,5 +1,17 @@
 # plugins
 
+## What is plugin
+
+Sealer provide plugin mechanism that allows users to run sealer image according to different plugin configurations.
+
+This will bring the possibility of flexible configuration of any image default setting, any cluster node, any cluster
+startup stage, such as host disk initialization, cluster preflight ,status checker before or after cluster installation
+and so on.
+
+At present, sealer only support the `shell` type plugins. it provides a shell operation entry that means user could
+execute any shell scripts on any node at any cluster launch stage. user only need to do is writing a yaml file which
+defined shell data and its scope to experience sealer plugin feature.
+
 ## Plugin Spec
 
 PluginSpec defines the desired state of Plugin
@@ -13,27 +25,99 @@ type PluginSpec struct {
 }
 ```
 
-1. for `PluginSpec.Type`: plugin type,currently only supported "SHELL".
-2. for `PluginSpec.Data`: plugin`s real data, sealer will use it to do actual action.
-3. for `PluginSpec.Scope`: plugin`s scope, it is usually the role name, support use '|' to specify multiple scopes.
-4. for `PluginSpec.Action`: phase of this plugin will run. below is the phase list we currently supported.
+* for `PluginSpec.Type`: plugin type,currently only supported "SHELL".
+* for `PluginSpec.Data`: plugin`s real data, sealer will use it to do actual action.
+* for `PluginSpec.Scope`: plugin scope, it is usually the role name, support use '|' to specify multiple scopes.
+* for `PluginSpec.Action`: phase of this plugin will run. if action is `host type`,will execute on `PluginSpec.Scope`
+  specified, if it is `cluster type`, only execute plugin at master0. below is the phase list we currently supported.
 
 plugin will be executed by `PluginSpec.Name` in alphabetical order at the same stage.
 
-The following is a detailed introduction for plugin action.
-
-| action name | action scope | explanation |
-| :-----| ----: | :----: |
-| pre-init-host | cluster host | will run before init cluster host |
-| post-init-host | cluster host | will run after init cluster host  |
-| pre-clean-host | cluster host | will run before clean cluster host  |
-| post-clean-host | cluster host | will run after clean cluster host  |
-| pre-install | master0 | will run before install cluster |
-| post-install | master0 | will run after install cluster  |
-| pre-uninstall | master0 | will run before uninstall cluster |
-| post-uninstall | master0 | will run after uninstall cluster  |
-| pre-scaleup | master0 | will run before scaleup cluster |
-| post-scaleup | master0 | will run after scaleup cluster  |
-| upgrade-host | cluster host | will run before upgrade cluster  |
-| upgrade | master0 | will run for upgrading cluster  |
+The following is a detailed introduction for plugin action.it is divided into 2 categories, one is the `host type`
+plugin and the other is the `cluster type` plugin.
+
+| action name | action scope | category| explanation |
+| :-----| ----: | ----: |----: |
+| pre-init-host | all host |host type | will run before init cluster host |
+| post-init-host | all host | host type| will run after init cluster host  |
+| pre-clean-host | all host | host type| will run before clean cluster host  |
+| post-clean-host | all host | host type| will run after clean cluster host  |
+| pre-install | master0 | cluster type| will run before install cluster |
+| post-install | master0 |cluster type | will run after install cluster  |
+| pre-uninstall | master0 |cluster type | will run before uninstall cluster |
+| post-uninstall | master0 | cluster type| will run after uninstall cluster  |
+| pre-scaleup | master0 | cluster type| will run before scaleup cluster |
+| post-scaleup | master0 | cluster type| will run after scaleup cluster  |
+| upgrade-host | all host | host type| will run before upgrade cluster  |
+| upgrade | master0 | cluster type| will run for upgrading cluster  |
+
+## How to use
+
+### use plugin though Kubefile
+
+Define the default plugin in Kubefile to build the image and run it.
+
+In many cases it is possible to use plugins without using Clusterfile, essentially sealer stores the Clusterfile plugin
+configuration in the Rootfs/Plugins directory before using it, so we can define the default plugin when we build the
+image.
+
+For example, build a new sealer image with plugins/example/example.yaml, only need to do is coping your plugin file
+to `plugins/` directory.
+
+Kubefile:
+
+```shell script
+FROM docker.io/sealerio/kubernetes:v1-22-15-sealerio-2
+COPY example.yaml plugins/
+```
+
+Build a Sealer Image that contains a plugin (or more plugins):
+
+```shell script
+sealer build -t kubernetes-with-plugin:v1 .
+```
+
+Run the image and the plugin will also be executed without having to define the plugin in the Clusterfile:
+`sealer run kubernetes-with-plugin:v1 -m x.x.x.x -p xxx`
+
+### use plugin though Clusterfile
+
+For example, set plugins/example/example.yaml content at clusterfile:
+
+```yaml
+apiVersion: sealer.io/v2
+kind: Cluster
+metadata:
+  name: default-kubernetes-cluster
+spec:
+  image: docker.io/sealerio/kubernetes:v1.22.15
+  ssh:
+    passwd: xxx
+  hosts:
+    - ips: [ 192.168.0.2,192.168.0.3,192.168.0.4 ]
+      roles: [ master ]
+    - ips: [ 192.168.0.5 ]
+      roles: [ node ]
+---
+apiVersion: sealer.io/v2
+kind: Plugin
+metadata:
+  name: pre_init_host
+spec:
+  type: SHELL
+  action: pre-init-host
+  scope: master
+  data: |
+    set -e;set -x
+    echo "i am pre init host plugin"
+```
+
+```shell script
+sealer apply -f Clusterfile
+```
+
+## Available plugin list
 
+| name | owner | category| link | description |
+| :-----| ----: | ----: |----: |----: |
+| example | sealer community | host type | plugins/example/example.yaml| just a little plugin example for user to quickly experience |

plugins/example/example.yaml

@@ -0,0 +1,25 @@
+# Copyright © 2021 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: sealer.io/v2
+kind: Plugin
+metadata:
+  name: pre_init_host # Specify this plugin name,will dump in $rootfs/plugin dir.
+spec:
+  type: SHELL
+  action: pre-init-host
+  scope: master
+  data: |
+    set -e;set -x
+    echo "i am pre init host plugin"