Alauda Build of SonarQube Docs
简体中文

如何自定义工具部署模板

自定义流程

自定义模板流程如下：

  1. 配置模板：按照 配置模板 章节的讲解，按需配置模板的内容
  2. 注册模板并验证：按照 注册模板并验证 章节的讲解，注册模板到目标集群中，并验证模板内容是否正确

配置模板

模板结构

工具部署模板通过 ConfigMap 资源定义和管理。每个模板由以下三个主要部分组成：

  1. 基本信息：包含模板的名称、描述、标签等基础配置信息
  2. UI 动态表单：定义用户在部署工具时需要填写的表单项
  3. 部署模板：包含工具部署所需的具体资源定义
apiVersion: v1
kind: ConfigMap
## Part 1: Basic Information
metadata:
  labels:
    tools.cpaas.io/template: gitlabofficial
  name: gitlab-template-quickstart
  namespace: cpaas-system
  annotations:
    ui.cpaas.io/displayName.en: Gitlab Quickstart Template
    ui.cpaas.io/description.en: 部署一个轻量级 GitLab 实例，适合开发和测试场景，不推荐用于生产环境。
## Part 2: UI Dynamic Form
    ui.cpaas.io/descriptors: >-
      - path: storageClass
        x-descriptors:
          - urn:alm:descriptor:label:zh:Gitaly 存储类
          - urn:alm:descriptor:label:en:Gitaly Storage Class
          - 'urn:alm:descriptor:description:zh:选择存储类，用于存放代码仓库'
          - 'urn:alm:descriptor:description:en:Select a storage class for storing repositories'
          - urn:alm:descriptor:com.tectonic.ui:validation:required
          - urn:alm:descriptor:com.tectonic.ui:select:expression
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/storage.k8s.io/v1/storageclasses
          - urn:alm:descriptor:expression:props.options:label:path:metadata.name
          - urn:alm:descriptor:expression:props.options:value:path:metadata.name
        ...
## Part 3: Deployment Template
data:
  template: >-
    helmValues:
      gitlab:
        gitaly:
          init:
            resources:
              limits:
                cpu: 1
                memory: 1Gi
              requests:
                cpu: 100m
                memory: 100Mi
          ...

配置基本信息

基本信息包含模板名称、描述、标签、注释、显示名称和描述。

字段说明
metadata.name模板资源的唯一标识符，用于在系统中区分不同的模板
metadata.namespace模板资源所在的命名空间，目前 UI 只展示 cpaas-system 命名空间下的模板
metadata.labels[tools.cpaas.io/template]指定模板适用的工具类型，例如 gitlabofficial 表示此模板用于部署 GitLab。该值通常与工具实例的资源名称一致
metadata.labels[ui.cpaas.io/hidden]控制模板是否在 UI 中展示。注意，如果需要隐藏产品内置模板需要配合 skip-sync annotation 一起使用
metadata.annotations[ui.cpaas.io/description.<language>]模板的详细描述，帮助使用者理解模板的用途和适用场景。<language> 是语言代码，支持配置国际化
metadata.annotations[ui.cpaas.io/configuration.<language>]模板的技术规格说明，包括资源需求、存储配置和网络访问方式等关键信息。<language> 是语言代码，支持配置国际化
metadata.annotations[skip-sync]控制 Operator 对内置模板的管理。如果模板设置了该 annotation，Operator 在重启或升级时不会更新模板内容

示例：

kind: ConfigMap
apiVersion: v1
metadata:
  name: gitlab-template-quickstart
  namespace: cpaas-system
  labels:
    tools.cpaas.io/template: gitlabofficial
  annotations:
    ui.cpaas.io/displayName.zh: 快速开始模板
    ui.cpaas.io/configuration.zh: >-
      配置说明: <br/>
      计算资源: CPU 3核，内存 6Gi <br/>
      存储方式: 使用节点本地存储，需配置存储节点IP和路径 <br/>
      网络访问: 采用 NodePort 方式，与存储共用节点IP，需指定端口 <br/>
    ui.cpaas.io/description.zh: 此模板用于快速创建一个轻量级的 GitLab 实例，适用于开发测试场景，不建议用于生产环境。

配置 UI 动态表单

工具部署 UI 提供了动态表单功能，可以根据模板中的表单描述信息自动生成对应的表单界面，简化用户的配置过程。

template form

动态表单的配置信息存储在 ui.cpaas.io/descriptors annotation 中，具体格式如下：

apiVersion: v1
kind: ConfigMap
metadata:
  annotations:
    ui.cpaas.io/descriptors: >-
      - path: storageClass
        x-descriptors:
          - urn:alm:descriptor:label:zh:Gitaly 存储类
          - urn:alm:descriptor:label:en:Gitaly Storage Class
          - 'urn:alm:descriptor:description:zh:选择存储类，用于存放代码仓库'
          - 'urn:alm:descriptor:description:en:Select a storage class for storing repositories'
          - urn:alm:descriptor:com.tectonic.ui:validation:required
          - urn:alm:descriptor:com.tectonic.ui:select:expression
          - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/apis/storage.k8s.io/v1/storageclasses
          - urn:alm:descriptor:expression:props.options:label:path:metadata.name
          - urn:alm:descriptor:expression:props.options:value:path:metadata.name
      - path: storageSize
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:text
          - urn:alm:descriptor:com.tectonic.ui:validation:required
          - urn:alm:descriptor:label:en:Gitaly Storage Size
          - urn:alm:descriptor:label:zh:Gitaly 容量
          - urn:alm:descriptor:description:en:声明持久化存储容量，需要带单位，如 10Gi。
          - urn:alm:descriptor:description:zh:To declare the persistent storage capacity, a unit is required, such as 10Gi.
字段说明
path表单字段的唯一标识符，用于在部署模板中引用用户输入的值
x-descriptors定义表单控件的属性，包括标签名称、描述文本、控件类型、数据校验规则等

关于动态表单支持的控件类型，请参考 配置动态表单 章节。

配置部署模板

模板引擎基于 Helm Template 实现，支持所有 Helm 内置的模板函数，如字符串处理、数学运算、流程控制等。您可以利用这些函数构建灵活的部署模板。

模板的主要功能是将输入参数替换到预定义的模板中。输入参数主要来自两个来源:

  1. 用户在表单中的输入值
  2. 从 Kubernetes 资源中获取的配置信息。

template input

从用户输入获取参数

在模板中可以使用 {{ .Values.<字段名> }} 语法来获取用户输入的值。例如，如果在表单中定义了一个名为 domain 的字段用于输入部署域名，那么在模板中可以通过 {{ .Values.domain }} 来引用该值。

apiVersion: v1
kind: ConfigMap
metadata:
  name: gitlab-template
  ...
  annotations:
    ui.cpaas.io/descriptors: >-
      - path: domain
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:text
          - urn:alm:descriptor:label:zh:域名
          - urn:alm:descriptor:label:en:Domain
          - urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
  template: |
    ...
    global:
      hosts:
        domain: {{ .Values.domain }}
        gitlab:
          hostnameOverride: {{ .Values.domain }}
          https: false
          name: {{ .Values.domain }}
        ssh: {{ .Values.domain }}

从 k8s 资源获取参数

在模板中，您可以使用 Helm Template 提供的 lookup 函数从 Kubernetes 资源中获取配置信息。例如，要从 tools 命名空间中的 gitlab-redis Secret 资源获取 Redis 的连接信息（如 Host、Port），可以按以下方式使用 lookup 函数：

apiVersion: v1
kind: ConfigMap
metadata:
  name: gitlab-template
  ...
spec:
  template: |
    ...
    global:
      {{- $secret := (lookup "v1" "Secret" "tools" "gitlab-redis") }}
      redis:
        host: {{ $secret.data.host | b64dec | trim }}
        port: {{ $secret.data.port | b64dec | trim }}

Secret 的名称也可以通过用户输入。例如，如果定义了一个名为 redisSecret 的字段，就可以在模板中使用 .Values.redisSecret 来引用用户输入的 Secret 名称。

apiVersion: v1
kind: ConfigMap
metadata:
  name: gitlab-template
  ...
  annotations:
    ui.cpaas.io/descriptors: >-
      - path: redisSecret
        x-descriptors:
          - urn:alm:descriptor:label:zh:Redis 凭据
          - urn:alm:descriptor:label:en:Redis Secret
          - urn:alm:descriptor:com.tectonic.ui:validation:required
spec:
  template: |
    ...
    global:
      {{- $secret := (lookup "v1" "Secret" "tools" .Values.redisSecret) }}
      redis:
        host: {{ .Values.redisSecret.host }}
        port: {{ .Values.redisSecret.port }}

配置国际化

模板支持国际化配置，在 UI 显示时，会根据用户选择的语言展示对应的名称和描述。

支持国际化配置的 annotation 包括：

  • ui.cpaas.io/displayName.<language>
  • ui.cpaas.io/description.<language>
  • ui.cpaas.io/configuration.<language>

配置国际化，只需在字段的末尾加上语言代码，比如：

  • zh: 代表中文时展示
  • en: 代表英文时展示

示例：

kind: ConfigMap
apiVersion: v1
metadata:
  annotations:
    ui.cpaas.io/displayName.zh: 快速开始模板
    ui.cpaas.io/displayName.en: Quick Start Template

配置动态表单

控件类型

常见的控件类型包括：字符串、数字和下拉选择框。

控件类型说明
urn:alm:descriptor:com.tectonic.ui:text字符串类型输入框
urn:alm:descriptor:com.tectonic.ui:number数字类型输入框
urn:alm:descriptor:com.tectonic.ui:select:expression下拉选择框

示例：

- path: name
  x-descriptors:
    - urn:alm:descriptor:com.tectonic.ui:text
- path: age
  x-descriptors:
    - urn:alm:descriptor:com.tectonic.ui:number
- path: gender
  x-descriptors:
    - urn:alm:descriptor:com.tectonic.ui:select:expression

动态表单变量

在描述动态表单时可使用以下变量：

  1. ${context.cluster} : 当前集群的名称
  2. ${context.namespace} : 当前命名空间（用户选择部署工具的命名空间）

示例：

x-descriptors:
  - urn:alm:descriptor:com.tectonic.ui:select:expression
  - urn:alm:descriptor:expression:props.options:api:/kubernetes/${context.cluster}/api/v1/namespaces/${context.namespace}/secrets?fieldSelector=type!=kubernetes.io/tls
  ...

控件国际化

工具部署模板支持为控件名称、描述和占位符配置国际化显示内容。通过在 x-descriptors 中添加带有语言代码的描述符，系统可以根据用户的语言偏好动态展示相应的文本。

支持的国际化配置类型包括:

  • 控件名称 (label): urn:alm:descriptor:label:<language>:<name>
  • 控件描述 (description): urn:alm:descriptor:description:<language>:<description>
  • 控件占位符 (placeholder): urn:alm:descriptor:placeholder:<language>:<placeholder>

其中 <language> 是语言代码，当前支持：

  • zh: 中文
  • en: 英文

示例: 配置一个支持中英文的域名输入框:

x-descriptors:
  - urn:alm:descriptor:label:zh:域名
  - urn:alm:descriptor:label:en:Domain

控件展示信息

动态表单控件支持配置国际化，在 UI 显示时会依据用户选择的语言展示对应的名称和描述。

控件字段说明
urn:alm:descriptor:label:<language>:<name>描述控件的名称
- <language> 是语言代码，如 zh 表示中文，en 表示英文
- <name> 是控件显示的名称
urn:alm:descriptor:description:<language>:<description>描述控件的描述
- <language> 是语言代码，如 zh 表示中文，en 表示英文
- <description> 是控件描述
urn:alm:descriptor:placeholder:<language>:<placeholder>描述控件的占位符描述
- <language> 是语言代码，如 zh 表示中文，en 表示英文
- <placeholder> 是控件占位符描述

ui-description

字段验证

动态表单支持对用户输入进行验证，支持的验证规则如下：

控件字段说明
urn:alm:descriptor:com.tectonic.ui:validation:minimum:<number>限定数字类型字段的最小值
urn:alm:descriptor:com.tectonic.ui:validation:maximum:<number>限定数字类型字段的最大值
urn:alm:descriptor:com.tectonic.ui:validation:required限定字段为必填项
urn:alm:descriptor:com.tectonic.ui:validation:pattern:<pattern>限定输入应满足给定的正则表达式
urn:alm:descriptor:com.tectonic.ui:validation:maxLength:<number>限定输入字符串的最大长度
urn:alm:descriptor:com.tectonic.ui:validation:minLength:<number>限定输入字符串的最小长度

示例1：限制数值范围为：30000 ~ 32767

x-descriptors:
  - urn:alm:descriptor:com.tectonic.ui:number
  - urn:alm:descriptor:com.tectonic.ui:validation:minimum:30000
  - urn:alm:descriptor:com.tectonic.ui:validation:maximum:32767

示例二：限制字符串字段为必填

x-descriptors:
  - urn:alm:descriptor:com.tectonic.ui:text
  - urn:alm:descriptor:com.tectonic.ui:validation:required

示例三：限定用户输入的路径必须是绝对路径

x-descriptors:
  - urn:alm:descriptor:label:zh:节点路径
  - urn:alm:descriptor:com.tectonic.ui:text
  - urn:alm:descriptor:com.tectonic.ui:validation:pattern:^\/([\w+-]+\/)*([\w+-]+)$

示例四：限制用户输入的字符长度为 2-32 个字符

x-descriptors:
  - urn:alm:descriptor:com.tectonic.ui:text
  - urn:alm:descriptor:com.tectonic.ui:validation:minLength:2
  - urn:alm:descriptor:com.tectonic.ui:validation:maxLength:32

动态选择

动态表单支持通过调用 API 来动态加载选项列表。

控件字段说明
urn:alm:descriptor:com.tectonic.ui:select:expression描述控件是下拉选择框
urn:alm:descriptor:expression:props.options:api:<api>定义api 地址来获取选项数据
urn:alm:descriptor:expression:props.options:label:path:metadata.name定义选项展示名称的字段
urn:alm:descriptor:expression:props.options:value:path:metadata.name定义选项的值字段

示例: 从 test 集群的 devops 命名空间中获取 Secret 资源，并将 metadata.name 作为选项的显示名称和值。

x-descriptors:
  - urn:alm:descriptor:com.tectonic.ui:select:expression
  - urn:alm:descriptor:expression:props.options:api:/kubernetes/test/api/v1/namespaces/devops/secrets?fieldSelector=type!=kubernetes.io/tls
  - urn:alm:descriptor:expression:props.options:label:path:metadata.name
  - urn:alm:descriptor:expression:props.options:value:path:metadata.name

注册模板并验证

  • 注册自定义模板：

    • 将模板资源 (ConfigMap) 创建到目标集群的 cpaas-system 命名空间即可完成注册。

  • 验证模板注册：

    • 进入工具 Operator 详情页
    • 点击 创建资源 按钮进入模板选择页面
    • 如果能看到新添加的模板，说明注册成功

  • 验证模板内容：

    • 选择自定义模板
    • 按照界面提示创建工具实例
    • 工具实例能成功部署，则说明模板内容正确

常见问题

如何获取内置模板内容？

工具 Operator 部署后会自动在当前集群的 cpaas-system 命名空间中注册内置的部署模板。您可以通过以下路径查看模板内容:

  1. 进入平台管理视图
  2. 选择集群管理 > 资源管理
  3. 选择资源类型为 ConfigMap
  4. 搜索关键字 template 即可找到对应的模板

如何隐藏产品内置模板？

如果需要隐藏产品内置模板，可以在模板资源中添加 ui.cpaas.io/hidden 标签，并设置为 true。同时需添加 skip-sync annotation，否则 Operator 在重启或升级时会还原模板内容。

metadata:
  labels:
    ui.cpaas.io/hidden: "true"
  annotations:
    skip-sync: "true"
本页概览