github.com/sealerio/sealer@v0.11.1-0.20240507115618-f4f89c5853ae/docs/design/plugin.md (about)

     1  # Plugin Usage
     2  
     3  ## Plugin type list
     4  
     5  ### hostname plugin
     6  
     7  HOSTNAME plugin will help you to change all the hostnames
     8  
     9  ```yaml
    10  ---
    11  apiVersion: sealer.io/v1
    12  kind: Plugin
    13  metadata:
    14    name: MyHostname # Specify this plugin name,will dump in $rootfs/plugins dir.
    15  spec:
    16    type: HOSTNAME # fixed string,should not change this name.
    17    action: PreInit # Specify which phase to run.
    18    data: |
    19      192.168.0.2 master-0
    20      192.168.0.3 master-1
    21      192.168.0.4 master-2
    22      192.168.0.5 node-0
    23      192.168.0.6 node-1
    24      192.168.0.7 node-2
    25  ```
    26  
    27  ### shell plugin
    28  
    29  You can exec any shell command on specify node in any phase.
    30  
    31  ```yaml
    32  apiVersion: sealer.io/v1
    33  kind: Plugin
    34  metadata:
    35    name: MyShell # Specify this plugin name,will dump in $rootfs/plugins dir.
    36  spec:
    37    type: SHELL
    38    action: PostInstall # PreInit PostInstall
    39    data: |
    40      kubectl get nodes
    41  ```
    42  
    43  ```shell
    44  action : [PreInit| PostInstall] # Specify phases to execute the shell
    45    Pre-initialization phase            |   action: PreInit
    46    Pre-join phase                      |   action: PreJoin
    47    Post-join phase                     |   action: PostJoin
    48    before exec Kubefile CMD phase      |   action: PreGuest
    49    after  installing the cluster phase |   action: PostInstall
    50    before clean cluster phase          |   action: PreClean
    51    after clean cluster phase           |   action: PostClean
    52    combined use phase                  |   action: PreInit|PreJoin
    53  on     : #Specifies the machine to execute the command
    54    If null, it is executed on all nodes by default
    55    on all master nodes                 |  'on': master
    56    on all work nodes                   |  'on': node
    57    on the specified IP address         |  'on': 192.168.56.113,192.168.56.114,192.168.56.115,192.168.56.116
    58    on a machine with continuous IP     |  'on': 192.168.56.113-192.168.56.116
    59    on the specified label node (action must be PostInstall or PreClean)  |  'on': node-role.kubernetes.io/master=
    60  data   : #Specifies the shell command to execute
    61  ```
    62  
    63  ### label plugin
    64  
    65  Help you set label after install kubernetes cluster
    66  
    67  ```yaml
    68  apiVersion: sealer.io/v1
    69  kind: Plugin
    70  metadata:
    71    name: MyLabel
    72  spec:
    73    type: LABEL
    74    action: PreGuest
    75    data: |
    76      192.168.0.2 ssd=true
    77      192.168.0.3 ssd=true
    78      192.168.0.4 ssd=true
    79      192.168.0.5 ssd=false,hdd=true
    80      192.168.0.6 ssd=false,hdd=true
    81      192.168.0.7 ssd=false,hdd=true
    82  ```
    83  
    84  ## clusterCheck plugin
    85  
    86  Server and environmental factors (poor server disk performance) may cause Sealer to deploy the application services immediately after installing the Kubernetes cluster, causing deployment failures.
    87  The Cluster Check plugin waits for the Kubernetes cluster to stabilize before deploying the application service.
    88  
    89  ```yaml
    90  apiVersion: sealer.io/v1
    91  kind: Plugin
    92  metadata:
    93    name: checkCluster
    94  spec:
    95    type: CLUSTERCHECK
    96    action: PreGuest
    97  ```
    98  
    99  ### Etcd backup plugin
   100  
   101  ```yaml
   102  apiVersion: sealer.io/v1
   103  kind: Plugin
   104  metadata:
   105    name: MyBackup
   106  spec:
   107    type: ETCD
   108    action: PostInstall
   109  ```
   110  
   111  Etcd backup plugin is triggered manually: `sealer plugin -f etcd_backup.yaml`
   112  
   113  ### taint plugin
   114  
   115  Add or remove taint by adding the taint plugin for the PreGuest phase:
   116  
   117  ```yaml
   118  apiVersion: sealer.io/v1
   119  kind: Plugin
   120  metadata:
   121    name: taint
   122  spec:
   123    type: TAINT
   124    action: PreGuest
   125    data: |
   126      192.168.56.3 key1=value1:NoSchedule
   127      192.168.56.4 key2=value2:NoSchedule-
   128      192.168.56.3-192.168.56.7 key3:NoSchedule
   129      192.168.56.3,192.168.56.4,192.168.56.5,192.168.56.6,192.168.56.7 key4:NoSchedule
   130      192.168.56.3 key5=:NoSchedule
   131      192.168.56.3 key6:NoSchedule-
   132      192.168.56.4 key7:NoSchedule-
   133  ```
   134  
   135  > The value of data is `ips taint_argument`,
   136  > ips: Multiple IP addresses are connected through ',', and consecutive IP addresses are written as the first IP address and the last IP address;
   137  > taint_argument: Same as kubernetes add or remove taints writing (key=value:effect #The effect must be NoSchedule, PreferNoSchedule or NoExecute)。
   138  
   139  ### Out of tree plugin
   140  
   141  at present, we only support the golang so file as out of tree plugin. More description about golang plugin
   142  see [golang plugin website](https://pkg.go.dev/plugin).
   143  
   144  copy the so file and the plugin config to your ClusterImage at build stage use `Kubefile`,sealer will parse and execute
   145  it.
   146  
   147  plugin config:
   148  
   149  ```yaml
   150  apiVersion: sealer.io/v1
   151  kind: Plugin
   152  metadata:
   153    name: label_nodes.so # out of tree plugin name
   154  spec:
   155    type: LABEL_TEST_SO # define your own plugin type.
   156    action: PostInstall # which stage will this plugin be applied.
   157    data: |
   158      192.168.0.2 ssd=true
   159  ```
   160  
   161  Kubefile:
   162  
   163  ```shell script
   164  FROM kubernetes:v1.19.8
   165  COPY label_nodes.so plugin
   166  COPY label_nodes.yaml plugin
   167  ```
   168  
   169  Build a ClusterImage that contains the golang plugin (or more plugins):
   170  
   171  ```shell script
   172  sealer build -m lite -t kubernetes-post-install:v1.19.8 .
   173  ```
   174  
   175  ## How to use plugin
   176  
   177  ### use it via Clusterfile
   178  
   179  For example, set node label after install kubernetes cluster:
   180  
   181  ```yaml
   182  apiVersion: sealer.io/v2
   183  kind: Cluster
   184  metadata:
   185    name: default-kubernetes-cluster
   186  spec:
   187    image: kubernetes:v1.19.8
   188    ssh:
   189      passwd: xxx
   190    hosts:
   191      - ips: [ 192.168.0.2,192.168.0.3,192.168.0.4 ]
   192        roles: [ master ]
   193      - ips: [ 192.168.0.5 ]
   194        roles: [ node ]
   195  ---
   196  apiVersion: sealer.io/v1
   197  kind: Plugin
   198  metadata:
   199    name: LABEL
   200  spec:
   201    type: LABEL
   202    action: PostInstall
   203    data: |
   204      172.20.126.8 ssd=false,hdd=true
   205  ```
   206  
   207  ```shell script
   208  sealer apply -f Clusterfile
   209  ```
   210  
   211  ### use it via Kubefile
   212  
   213  Define the default plugin in Kubefile to build the image and run it.
   214  
   215  In many cases it is possible to use plugins without using Clusterfile, essentially sealer stores the Clusterfile plugin
   216  configuration in the Rootfs/Plugins directory before using it, so we can define the default plugin when we build the
   217  image.
   218  
   219  Plugin configuration shell.yaml:
   220  
   221  ```yaml
   222  apiVersion: sealer.io/v1
   223  kind: Plugin
   224  metadata:
   225    name: SHELL
   226  spec:
   227    action: PostInstall
   228    data: |
   229      if type yum >/dev/null 2>&1;then
   230      yum -y install iscsi-initiator-utils
   231      systemctl enable iscsid
   232      systemctl start iscsid
   233      elif type apt-get >/dev/null 2>&1;then
   234      apt-get update
   235      apt-get -y install open-iscsi
   236      systemctl enable iscsid
   237      systemctl start iscsid
   238      fi
   239  ```
   240  
   241  Kubefile:
   242  
   243  ```shell script
   244  FROM kubernetes:v1.19.8
   245  COPY shell.yaml plugin
   246  ```
   247  
   248  Build a ClusterImage that contains an installation iscsi plugin (or more plugins):
   249  
   250  ```shell script
   251  sealer build -m lite -t kubernetes-iscsi:v1.19.8 .
   252  ```
   253  
   254  Run the image and the plugin will also be executed without having to define the plugin in the Clusterfile:
   255  `sealer run kubernetes-iscsi:v1.19.8 -m x.x.x.x -p xxx`