Skip to content

update readme and add plugin example #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kakaZhou719 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update readme and add plugin example #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/workflows/.mlc_config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"ignorePatterns": [
{
"pattern": "^http://127.0.0.1"
},
{
"pattern": "^http://localhost"
}
]
}
16 changes: 16 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
124 changes: 104 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 |
25 changes: 25 additions & 0 deletions plugins/example/example.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Copyright © 2021 Alibaba Group Holding Ltd.
Copy link

@starnop starnop Apr 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use plugin.yaml as the file name

Copy link
Member Author

@kakaZhou719 kakaZhou719 Apr 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plugin file name should be unique at the same image on overlay filesystem. its under example dir , so i kept its name to guide other contributors to name a different plugin file.

#
# 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"