如何自定义部署模板

自定义流程配置模板模板结构基本信息 UI 动态表单部署模板配置国际化配置动态表单控件类型动态表单变量控件国际化控件显示信息字段校验动态选择注册并验证模板常见问题如何访问内置模板内容？如何隐藏产品的内置模板？

自定义流程

自定义模板流程如下：

配置模板：根据配置模板章节中的说明，按需配置模板内容
注册并验证模板：根据注册并验证模板章节中的说明，在目标集群中注册模板并验证模板内容

配置模板

模板结构

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

基本信息：包含模板的名称、描述和标签等基础配置信息
UI 动态表单：定义用户在部署工具时需要填写的表单项
部署模板：包含工具部署所需的具体资源定义

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: Deploy a lightweight Gitlab instance, suitable for development and testing scenarios, not recommended for production environments.
## 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` 注解配合使用
`metadata.annotations[ui.cpaas.io/description.<language>]`	模板的详细描述，帮助用户了解模板的用途和适用场景。`<language>` 为语言代码，支持国际化配置
`metadata.annotations[ui.cpaas.io/configuration.<language>]`	模板的技术规范，包括资源需求、存储配置和网络访问方式等关键信息。`<language>` 为语言代码，支持国际化配置
`metadata.annotations[skip-sync]`	控制 operator 是否管理内置模板。如果模板设置了该注解，operator 在重启或升级时不会更新模板内容

示例：

kind: ConfigMap
apiVersion: v1
metadata:
  name: gitlab-template-quickstart
  namespace: cpaas-system
  labels:
    tools.cpaas.io/template: gitlabofficial
  annotations:
    ui.cpaas.io/displayName.en: Quick Start Template
    ui.cpaas.io/configuration.en: >-
      Configuration: <br/>
      Compute Resources: CPU 3 cores, Memory 6Gi <br/>
      Storage Method: Use node local storage, need to configure storage node IP and path <br/>
      Network Access: Use NodePort mode, share node IP with storage, need to specify port <br/>
    ui.cpaas.io/description.en: This template is used to quickly create a lightweight GitLab instance, suitable for development and testing scenarios, not recommended for production environments.

UI 动态表单

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

模板表单

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

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:To declare the persistent storage capacity, a unit is required, such as 10Gi.
          - urn:alm:descriptor:description:zh:声明持久化存储容量，需要带单位，如 10Gi。

字段	描述
`path`	表单字段的唯一标识符，用于在部署模板中引用用户输入的值
`x-descriptors`	定义表单控件的属性，包括标签名称、描述文本、控件类型、数据校验规则等

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

部署模板

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

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

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

模板输入

从用户输入中获取参数

在模板中，可以使用 {{ .Values.<field name> }} 语法获取用户输入的值。例如，如果在表单中定义了一个名为 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 中显示时，会根据用户选择的语言显示对应的名称和描述。

支持的国际化配置注解包括：

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

动态表单变量

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

${context.cluster}：当前集群名称
${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 中添加带语言代码的 descriptor，系统可以根据用户的语言偏好动态显示对应文本。

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

控件名称（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:Domain
  - 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 描述

字段校验

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

控件字段	描述
`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

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

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

示例 3：限制用户输入的路径为绝对路径

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

示例 4：限制用户输入长度为 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`	定义选项值字段

示例：从测试集群的 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

注册并验证模板

注册自定义模板：
- 在目标集群的 cpaas-system 命名空间中创建模板资源（ConfigMap），完成注册。
验证模板注册：
- 进入工具 operator 详情页
- 单击 Create Resource 按钮进入模板选择页面
- 如果可以看到新添加的模板，说明注册成功
验证模板内容：
- 进入工具 Operator 详情页
- 单击 Create Resource 按钮进入模板选择页面
- 如果可以看到新添加的模板，说明注册成功
验证模板内容：
- 选择自定义模板
- 按照界面提示创建工具实例
- 如果工具实例可以成功部署，说明模板内容正确

常见问题

如何访问内置模板内容？

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

进入平台 Management View
选择 Cluster Management > Resource Management
将资源类型选择为 ConfigMap
搜索关键字 template，找到对应模板

如何隐藏产品的内置模板？

如果需要隐藏产品的内置模板，可以在模板资源上添加 ui.cpaas.io/hidden 标签并将其设置为 true。此外，还需要添加 skip-sync 注解，否则 operator 在重启或升级时会恢复模板内容。

metadata:
  labels:
    ui.cpaas.io/hidden: "true"
  annotations:
    skip-sync: "true"

如何自定义部署模板#

#目录

#自定义流程

#配置模板

#模板结构

#基本信息

#UI 动态表单

#部署模板

#配置国际化

#配置动态表单

#控件类型

#动态表单变量

#控件国际化

#控件显示信息

#字段校验

#动态选择

#注册并验证模板

#常见问题

#如何访问内置模板内容？

#如何隐藏产品的内置模板？