#Cluster Plugin

#Overview

集群插件是用于扩展平台功能的工具。每个插件通过三个集群级别的 CRD 进行管理：ModulePlugin、ModuleConfig 和 ModuleInfo。

• ModulePlugin：定义集群插件的基本信息。
• ModuleConfig：定义插件的版本信息。每个 ModulePlugin 可以对应一个或多个 ModuleConfig。
• ModuleInfo：记录已安装插件的版本和状态信息。

集群插件支持动态表单配置。动态表单是简单的 UI 表单，提供插件的可定制配置选项或参数组合。例如，安装 Log Collector 时，可以通过动态表单选择日志存储插件为 ElasticSearch 或 ClickHouse。动态表单定义位于 ModuleConfig 的 .spec.config 字段；如果插件不需要动态表单，则该字段为空。

插件通过 violet 工具发布。注意：

• 插件只能发布到 global cluster，但可根据配置安装到 global cluster 或 workload cluster。
• 同一集群中，插件只能安装一次。
• 发布成功后，平台会自动在 global cluster 创建对应的 ModulePlugin 和 ModuleConfig，无需手动修改。
• 创建 ModuleInfo 资源即可安装插件，并可选择版本、目标集群及动态表单参数。动态表单定义参考所选版本的 ModuleConfig。更多使用说明请参考插件相关文档。

#查看可用插件

查看平台提供的所有插件：

1. 进入平台管理视图。
2. 点击左侧导航菜单：Administrator > Marketplace > Cluster Plugins

此页面列出所有可用插件及其当前状态。

#通过 Web 控制台安装

如果插件显示“absent”状态，按以下步骤安装：

1. 下载插件包：

   • 访问 Customer Portal 下载对应插件包。
   • 若无访问权限，请联系技术支持。

2. 上传包到平台：

   • 使用 violet 工具将包发布到平台。
   • 详细使用说明请参考 CLI。

3. 验证上传：

   • 进入 Administrator > Marketplace > Upload Packages
   • 切换到 Cluster Plugin 标签页
   • 找到已上传的插件名称
   • 插件详情会显示上传包的版本信息

4. 安装插件：

   • 若插件显示“ready”状态，点击 Install
   • 部分插件需填写安装参数，详见插件文档
   • 无安装参数的插件点击 Install 后即开始安装

#通过 YAML 安装

安装方式根据插件类型不同：

• 非配置插件：无需额外参数，安装简单。
• 配置插件：需填写配置参数，详见插件文档。

以下示例演示基于 YAML 的安装。

#non-config

示例： Web Terminal

#1. 检查可用版本

确认插件已发布，检查 global cluster 中是否存在 ModulePlugin 和 ModuleConfig 资源：

# 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

表示 global cluster 中存在 ModulePlugin web-cli，且已发布版本 v4.0.4。

查看版本 v4.0.4 的 ModuleConfig：

# 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: {}
  ...

.spec.affinity 定义集群亲和性，表示 web-cli 只能安装在 global cluster。.spec.config 为空，说明插件无需配置，可直接安装。

#2. 创建 ModuleInfo

在 global cluster 创建 ModuleInfo 资源，安装插件且无配置参数：

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

字段说明：

• name：集群插件临时名称，平台创建后会根据内容重命名，格式为 <cluster-name>-<内容哈希>，例如 global-ee98c9991ea1464aaa8054bdacbab313。

• label cpaas.io/cluster-name：指定插件安装的目标集群。若与 ModuleConfig 的亲和性冲突，安装会失败。

  注意： 此标签不改变 YAML 应用的集群，YAML 仍必须应用于 global cluster。

• label cpaas.io/module-name：插件名称，必须与 ModulePlugin 资源匹配。

• label cpaas.io/module-type：固定字段，必须为 plugin，缺失此字段会导致安装失败。

• .spec.config：对应 ModuleConfig 为空时，此字段可留空。

• .spec.version：指定安装的插件版本，必须与 ModuleConfig 中的 .spec.version 匹配。

#3. 验证安装

由于 ModuleInfo 名称创建后会变更，可通过标签在 global cluster 查找资源，查看插件状态和版本：

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

字段说明：

• NAME：ModuleInfo 资源名称
• CLUSTER：插件安装的集群
• MODULE：插件名称
• DISPLAY_NAME：插件显示名称
• STATUS：安装状态，Running 表示安装成功且运行中
• TARGET_VERSION：目标安装版本
• CURRENT_VERSION：安装前版本
• NEW_VERSION：可升级的最新版本

#with-config

示例： GPU Device Plugin

#1. 检查可用版本

确认插件已发布，检查 global cluster 中 ModulePlugin 和 ModuleConfig 资源：

# 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

表示 global cluster 中存在 ModulePlugin gpu-device-plugin，且已发布版本 v4.0.15。

查看版本 v4.0.15 的 ModuleConfig：

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

说明：

• 该插件仅能安装在操作系统为 Linux 且架构为 amd64 的集群。
• 动态表单包含三个设备驱动开关：custom.mps_enable、custom.pgpu_enable 和 custom.vgpu_enable，仅设置为 true 时才会安装对应驱动。

#2. 创建 ModuleInfo

在 global cluster 创建 ModuleInfo 资源，安装插件并填写动态表单参数（例如启用 pgpu 和 vgpu 驱动）：

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

字段说明同 non-config，配置详情请参考插件文档。

#3. 验证安装

通过标签在 global cluster 查找 ModuleInfo，查看状态和版本：

# 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

字段说明同 non-config。

#集群插件生命周期值

Cluster Plugins 页面使用 cpaas.io/lifecycle-type 标签指示集群插件的维护和升级方式。若标签缺失，则插件视为 Agnostic。

其中，Core 表示插件随 ACP Core 版本及集群 Distribution Version 一起发布和升级。

Cluster Plugins 列表页显示 Life cycle 列，并提供 Life cycle 过滤器，方便快速识别各插件类型。

#升级流程

升级已安装插件到新版本：

1. 上传新版本：

   • 按照相同步骤将新版本上传至平台。
   • 上传完成后，等待约 10–15 分钟，平台同步新版本信息。

2. 验证新版本：

   • 进入 Administrator > Marketplace > Upload Packages
   • 切换到 Cluster Plugin 标签页
   • 插件详情显示新上传版本

3. 查看插件：

   • 进入 Administrator > Marketplace > Cluster Plugins
   • 选择目标集群
   • 在列表页或插件详情页查看插件信息

4. 执行升级：

   • 若插件生命周期为 Aligned 或 Agnostic，可在列表页或详情页启动单独升级
   • 平台将已安装插件升级到新发布版本

5. 处理 Core 插件：

   • Core 插件不支持单独升级
   • 检测到新版本时，插件详情页会提示升级集群

注意： Upgrade 指更改已安装插件版本，Update 仍为插件特定操作，用于修改配置或执行插件定义的更新逻辑。