#集群插件

#概述

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

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

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

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

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

#查看可用插件

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

1. 进入平台管理视图。
2. 点击左侧导航菜单：管理员 > Marketplace > 集群插件

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

#通过 Web Console 安装

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

1. 下载插件软件包：

   • 访问 Customer Portal，下载对应的插件软件包。
   • 如果无法访问 Customer Portal，请联系技术支持。

2. 将软件包上传到平台：

   • 使用 violet 工具将软件包发布到平台。
   • 有关如何使用此工具的详细说明，请参阅 CLI。

3. 验证上传：

   • 导航至 管理员 > Marketplace > 上架软件包
   • 切换到 集群插件 选项卡
   • 找到已上传的插件名称
   • 插件详情中会显示已上传软件包的版本

4. 安装插件：

   • 如果插件状态显示为“ready”，请点击 安装
   • 某些插件需要安装参数；详情请参阅插件专属文档
   • 无需安装参数的插件会在点击“安装”后立即开始安装

#通过 YAML 安装

安装方法因插件类型而异：

• 无配置插件：无需额外参数，安装过程简单直接。
• 配置插件：需要填写配置参数；详情请参阅插件文档。

以下示例演示如何通过 YAML 安装。

#无配置

示例： Web Terminal

#1. 检查可用版本

在 global 集群中检查 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 集群中存在 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 集群中。.spec.config 为空，表示插件无需配置，可以直接安装。

#2. 创建 ModuleInfo

在 global 集群中创建 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>-<hash of content>，例如 global-ee98c9991ea1464aaa8054bdacbab313。

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

  注意：此标签不会更改应用 YAML 的位置——仍必须在 global 集群中应用 YAML。

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

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

• .spec.config：如果相应的 ModuleConfig 为空，此字段可以留空。

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

#3. 验证安装

由于创建后 ModuleInfo 名称会发生变化，请在 global 集群中通过标签查找资源，以检查插件状态和版本：

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：可供安装的最新版本

#带配置

示例： GPU Device Plugin

#1. 检查可用版本

在 global 集群中检查 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 集群中存在 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 集群中创建 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

字段说明与无配置插件相同。配置详情请参阅插件文档。

#3. 验证安装

在 global 集群中通过标签查找 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

字段说明与无配置插件相同。

#集群插件生命周期值

Cluster Plugins 页面使用 cpaas.io/lifecycle-type 标签来指示集群插件的维护和升级方式。如果没有此标签，插件将被视为 Agnostic。

在此上下文中，Core 表示插件会与集群 Distribution Version 一起遵循 ACP Core 的发布和升级周期。

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 仍是插件专属操作，用于更改配置或运行插件定义的更新逻辑。