#Cluster Plugin

#Overview

A cluster plugin is a tool for extending the platform's functionality. Each plugin is managed through three cluster-level CRDs: ModulePlugin, ModuleConfig, and ModuleInfo.

• ModulePlugin: Defines the basic information of the cluster plugin.
• ModuleConfig: Defines the version information of the plugin. Each ModulePlugin can correspond to one or more ModuleConfigs.
• ModuleInfo: Records the installed plugin's version and status information.

Cluster plugins support dynamic form configuration. Dynamic forms are simple UI forms that provide customizable configuration options or parameter combinations for plugins. For example, when installing the Log Collector, you can select the log storage plugin as ElasticSearch or ClickHouse via the dynamic form. The dynamic form definition is located in the .spec.config field of the ModuleConfig; if the plugin does not require a dynamic form, this field is empty.

Plugins are published via the violet tool. Note:

• Plugins can only be published to the global cluster, but can be installed on either the global or workload cluster depending on the configuration.
• In the same cluster, a plugin can only be installed once.
• Once published successfully, the platform will automatically create the corresponding ModulePlugin and ModuleConfig in the global cluster—no manual modifications are required.
• Creating a ModuleInfo resource installs the plugin and allows selecting the version, target cluster, and dynamic form parameters. Refer to the ModuleConfig of the selected version for the dynamic form definition. For more usage instructions, refer to the plugin-specific documentation.

#Viewing Available Plugins

To view all plugins provided by the platform:

1. Navigate to the platform management view.
2. Click the left navigation menu: Administrator > Marketplace > Cluster Plugin

This page lists all available plugins along with their current status.

#Installing via Web Console

If a plugin shows an "absent" status, follow these steps to install it:

1. Download the plugin package:

   • Visit the Customer Portal to download the corresponding plugin package.
   • If you don't have access to the Customer Portal, contact technical support.

2. Upload the package to the platform:

   • Use the violet tool to publish the package to the platform.
   • For detailed instructions on using this tool, refer to the CLI.

3. Verify the upload:

   • Navigate to Administrator > Marketplace > Upload Packages
   • Switch to the Cluster Plugin tab
   • Locate the uploaded plugin name
   • The plugin details will show the version(s) of the uploaded package

4. Install the plugin:

   • If the plugin shows a "ready" status, click Install
   • Some plugins require installation parameters; refer to the plugin-specific documentation
   • Plugins without installation parameters will start installation immediately after clicking Install

#Installing via YAML

The installation method differs by plugin type:

• Non-config plugin: No additional parameters required; installation is straightforward.
• Config plugin: Requires filling in configuration parameters; refer to the plugin documentation for details.

The following examples demonstrate YAML-based installation.

#non-config

Example: Web Terminal

#1. Check available versions

Ensure the plugin has been published by checking for ModulePlugin and ModuleConfig resources in the global cluster:

# kubectl get moduleplugins web-cli
NAME      AGE
web-cli   4d20h

# kubectl get moduleconfigs -l cpaas.io/module-name=web-cli
NAME             AGE
web-cli-v4.0.4   4d21h

This indicates that the ModulePlugin web-cli exists in the global cluster and version v4.0.4 is published.

Check the ModuleConfig for version v4.0.4:

# kubectl get moduleconfigs web-cli-v4.0.4 -oyaml
apiVersion: cluster.alauda.io/v1alpha1
kind: ModuleConfig
metadata:
  ...
  name: web-cli-v4.0.4
spec:
  affinity:
    clusterAffinity:
      matchLabels:
        is-global: "true"
  version: v4.0.4
  config: {}
  ...

The .spec.affinity defines cluster affinity, indicating that web-cli can only be installed on the global cluster. .spec.config is empty, meaning the plugin requires no configuration and can be installed directly.

#2. Create a ModuleInfo

Create a ModuleInfo resource in the global cluster to install the plugin without any configuration parameters:

apiVersion: cluster.alauda.io/v1alpha1
kind: ModuleInfo
metadata:
  labels:
    cpaas.io/cluster-name: global
    cpaas.io/module-name: web-cli
    cpaas.io/module-type: plugin
  name: global-temporary-name
spec:
  config: {}
  version: v4.0.4

Field explanations:

• name: Temporary name for the cluster plugin. The platform will rename it after creation based on the content, in the format <cluster-name>-<hash of content>, e.g., global-ee98c9991ea1464aaa8054bdacbab313.

• label cpaas.io/cluster-name: Specifies the target cluster where the plugin should be installed. If it conflicts with the ModuleConfig's affinity, installation will fail.

  Note: This label does not change where the YAML is applied—the YAML must still be applied in the global cluster.

• label cpaas.io/module-name: Plugin name, must match the ModulePlugin resource.

• label cpaas.io/module-type: Fixed field, must be plugin; missing this field causes installation failure.

• .spec.config: If the corresponding ModuleConfig is empty, this field can be left empty.

• .spec.version: Specifies the plugin version to install, must match .spec.version in ModuleConfig.

#3. Verify installation

Since the ModuleInfo name changes upon creation, locate the resource via label in the global cluster to check the plugin status and version:

kubectl get moduleinfo -l cpaas.io/module-name=web-cli
NAME                                      CLUSTER   MODULE    DISPLAY_NAME   STATUS    TARGET_VERSION   CURRENT_VERSION   NEW_VERSION
global-ee98c9991ea1464aaa8054bdacbab313   global    web-cli   web-cli        Running   v4.0.4           v4.0.4            v4.0.4

Field explanations:

• NAME: ModuleInfo resource name
• CLUSTER: Cluster where the plugin is installed
• MODULE: Plugin name
• DISPLAY_NAME: Display name of the plugin
• STATUS: Installation status; Running means successfully installed and running
• TARGET_VERSION: Intended installation version
• CURRENT_VERSION: Version before installation
• NEW_VERSION: Latest available version for installation

#with-config

Example: GPU Device Plugin

#1. Check available versions

Ensure the plugin has been published by checking ModulePlugin and ModuleConfig resources in the global cluster:

# kubectl get moduleplugins gpu-device-plugin
NAME                AGE
gpu-device-plugin   4d23h

# kubectl get moduleconfigs -l cpaas.io/module-name=gpu-device-plugin
NAME                        AGE
gpu-device-plugin-v4.0.15   4d23h

This indicates that ModulePlugin gpu-device-plugin in the global cluster exists and version v4.0.15 is published.

Check the ModuleConfig for v4.0.15:

# kubectl get moduleconfigs gpu-device-plugin-v4.0.15 -oyaml
apiVersion: cluster.alauda.io/v1alpha1
kind: ModuleConfig
metadata:
  ...
  name: gpu-device-plugin-v4.0.15
spec:
  affinity:
    clusterAffinity:
      matchExpressions:
      - key: cpaas.io/os-linux
        operator: Exists
      matchLabels:
        cpaas.io/arch-amd64: "true"
  config:
    custom:
      mps_enable: false
      pgpu_enable: false
      vgpu_enable: false
  version: v4.0.15
  ...

Notes:

• This plugin can only be installed on clusters with Linux OS and amd64 architecture.
• The dynamic form includes three device driver switches: custom.mps_enable, custom.pgpu_enable, and custom.vgpu_enable. Only when set to true will the corresponding driver be installed.

#2. Create a ModuleInfo

Create a ModuleInfo resource in the global cluster to install the plugin, filling in dynamic form parameters as needed (e.g., enabling pgpu and vgpu drivers):

apiVersion: cluster.alauda.io/v1alpha1
kind: ModuleInfo
metadata:
  labels:
    cpaas.io/cluster-name: business
    cpaas.io/module-name: gpu-device-plugin
    cpaas.io/module-type: plugin
  name: business-temporary-name
spec:
  config:
    custom:
      mps_enable: false
      pgpu_enable: true
      vgpu_enable: true
  version: v4.0.15

Field explanations are the same as non-config. Refer to the plugin documentation for config details.

#3. Verify installation

Locate the ModuleInfo via label in the global cluster to check status and version:

# kubectl get moduleinfo -l cpaas.io/module-name=gpu-device-plugin
NAME                                      CLUSTER   MODULE              DISPLAY_NAME        STATUS    TARGET_VERSION   CURRENT_VERSION   NEW_VERSION
business-7ebb241b4f77471235e57dd1ec7fbd0d business  gpu-device-plugin   gpu-device-plugin   Running   v4.0.15          v4.0.15           v4.0.15

Field explanations are the same as non-config.

#Upgrade Process

To upgrade an existing plugin to a newer version:

1. Upload the new version:

   • Follow the same process to upload the new version to the platform.
   • After the upload is completed, wait approximately 10–15 minutes for the platform to synchronize the new version information.

2. Verify the new version:

   • Navigate to Administrator > Marketplace > Upload Packages
   • Switch to the Cluster Plugin tab
   • The plugin details will show the newly uploaded version

3. Perform the upgrade:

   • Navigate to Administrator > Clusters > Clusters
   • Clusters with upgradable plugins will display an upgrade icon
   • Enter the cluster details and switch to the Features tab
   • The upgrade button will be enabled under the features component
   • Click Upgrade to complete the plugin upgrade