Design and Usage of Clusterfile in Sealer for Cluster Configuration and Plugins

In the previous article we introduced Sealer's overall system architecture; this piece focuses on the design philosophy and usage patterns of the Clusterfile, which defines how a cluster instance is created.

Design principles : While the Kubefile determines how a cluster image is built, the Clusterfile controls the creation of cluster instances. Sealer's Cluster API exposes only the most common parameters, hiding low‑frequency options that can be handled via Kubefile overrides. Example Dockerfile snippet:

FROM kubernetes:1.19.9

COPY my-kubeadm.yaml.tmp kubeadm.yaml.tmp

The Clusterfile hides parameters that most users do not need to care about, placing implementation‑specific fields in annotations and other convention‑based files, making the experience simpler while still allowing extensive extensibility.

Clusterfile parameter details (excerpt):

apiVersion: sealer.aliyun.com/v1alpha1
# Kind can be Cluster, Config, or Plugin
kind: Cluster
metadata:
  name: my-cluster
  annotation:
    trident.aliyun-inc.com/etcd: "/data/etcd"
    trident.aliyun-inc.com/docker: "/var/lib/docker"
    sea.aliyun.com/cloudrootfs/dir: "/var/lib/seadent/data/my-cluster"
spec:
  image: registry.cn-qingdao.aliyuncs.com/sealer-io/kubernetes:v1.19.9
  env:
    - DOMAIN="sealer.alibaba.com"
  provider: BAREMETAL
  ssh:
    passwd: 
    pk: xxx
    pkPasswd: xxx
    user: root
  network:
    interface: eth0
    cniName: calico
    podCIDR: 100.64.0.0/10
    svcCIDR: 10.96.0.0/22
    withoutCNI: false
  certSANS:
    - aliyun-inc.com
    - 10.0.0.2
  masters:
    cpu: 6
    memory: 6
    count: 4
    systemDisk: 200
    dataDisks:
      - 200
  nodes:
    cpu: 3
    memory: 6
    count: 2
    systemDisk: 200
    dataDisks:
      - 200

Adding configuration via Clusterfile : To modify application parameters without rebuilding the cluster image, Sealer leverages an overwrite mechanism. Users can append additional Config objects to the same Clusterfile, separated by --- . Example of injecting MySQL and Redis configurations:

apiVersion: sealer.aliyun.com/v1alpha1
kind: Cluster
metadata:
  name: my-cluster
spec:
  image: registry.cn-qingdao.aliyuncs.com/sealer-app/my-SAAS-all-inone:latest
  provider: BAREMETAL
---
apiVersion: sealer.aliyun.com/v1alpha1
kind: Config
metadata:
  name: mysql-config
spec:
  path: etc/mysql-valus.yaml
  data: |
    mysql-user: root
    mysql-passwd: xxx
---
apiVersion: sealer.aliyun.com/v1alpha1
kind: Config
metadata:
  name: redis-config
spec:
  path: etc/redis-valus.yaml
  data: |
    redis-user: root
    redis-passwd: xxx

After appending these sections, running sealer apply applies the new settings. The accompanying Kubefile should include the necessary commands to install the applications, e.g.:

FROM kuberentes:v1.19.9
...
CMD helm install mysql -f etc/mysql-config.yaml
CMD helm install redis -f etc/redis-config.yaml

Injecting environment variables : Small configuration values can be injected via cluster environment variables. For example, to set a service port dynamically:

kind: Service
apiVersion: v1
metadata:
  labels:
    k8s-app: kubernetes-app
  name: kubernetes-app
  namespace: kubernetes-app
spec:
  ports:
    - port: 8080
      targetPort: {{ AppPort }}
  selector:
    k8s-app: kubernetes-app

The corresponding Kubefile might look like:

FROM kubernetes:1.16.9
COPY app.yaml manifests/
CMD kubectl apply -f manifests/app.yaml

When running the image, pass the variable with sealer run -e AppPort=8089 myApp:latest , or set it via the env field in the Clusterfile.

Cluster plugins : For special scenarios such as changing hostnames, upgrading kernels, or synchronizing time, Sealer supports plugins defined in the Clusterfile. Examples include:

HOSTNAME plugin :

---
apiVersion: sealer.aliyun.com/v1alpha1
kind: Plugin
metadata:
  name: HOSTNAME
spec:
  data: |
    10.10.0.2 master-0
    10.10.0.3 master-1
    10.10.0.4 master-2
    10.10.0.5 node-0
    10.10.0.6 node-1
    10.10.0.7 node-2

SHELL plugin (post‑install action on a range of nodes):

apiVersion: sealer.aliyun.com/v1alpha1
kind: Plugin
metadata:
  name: SHELL
spec:
  action: PostInstall
  on: 10.10.0.1-10.10.0.3
  data: |
    kubectl taint nodes node-role.kubernetes.io/master=:NoSchedule

LABEL plugin (assigning labels to nodes):

apiVersion: sealer.aliyun.com/v1alpha1
kind: Plugin
metadata:
  name: LABEL
spec:
  data: |
    10.10.0.2 ssd=true
    10.10.0.3 ssd=true
    10.10.0.4 ssd=true
    10.10.0.5 ssd=false,hdd=true
    10.10.0.6 ssd=false,hdd=true
    10.10.0.7 ssd=false,hdd=true

After configuring the desired plugins, applying the Clusterfile with sealer apply activates them.

Conclusion : The article provides a comprehensive overview of Clusterfile's capabilities in Sealer, covering basic cluster configuration, dynamic parameter injection, environment variable handling, and plugin extensions, encouraging readers to explore the official Sealer repository for further details.