如何自定义部署模板

自定义流程

自定义模板流程如下：

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

配置模板

模板结构

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

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

apiVersion: v1
kind: ConfigMap
## 第一部分：基本信息
metadata:
  labels:
    tools.cpaas.io/template: harbor
  name: harbor-template-quickstart
  namespace: cpaas-system
  annotations:
    ui.cpaas.io/displayName.en: Quick Start Template
    ui.cpaas.io/description.en: This template is used to quickly create a lightweight Harbor instance, suitable for development and testing scenarios, not recommended for production environments.
## 第二部分：UI 动态表单
    ui.cpaas.io/descriptors: >-
      - path: httpPort
        x-descriptors:
          - urn:alm:descriptor:label:zh:HTTP 端口
          - urn:alm:descriptor:label:en:HTTP Port
          - 'urn:alm:descriptor:description:zh:Harbor 服务访问端口'
          - 'urn:alm:descriptor:description:en:Harbor server port'
          - urn:alm:descriptor:placeholder:zh:输入范围 30000 ~ 32767
          - urn:alm:descriptor:placeholder:en:Input range between 30000 and 32767.
          - urn:alm:descriptor:com.tectonic.ui:validation:required
          - 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
        ...
## 第三部分：部署模板
data:
  template: >-
    externalURL: http://{{ $displayIP }}:{{ .Values.httpPort }}
    helmValues:
      existingSecretAdminPassword: {{ .Values.adminPasswordSecret }}
      existingSecretAdminPasswordKey: password

      externalURL: http://{{ $displayIP }}:{{ .Values.httpPort }}
          ...

基本信息

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

字段	说明
`metadata.name`	模板资源的唯一标识，用于区分系统中的不同模板
`metadata.namespace`	模板资源所在的命名空间，目前 UI 仅展示 `cpaas-system` 命名空间下的模板
`metadata.labels[tools.cpaas.io/template]`	指定模板适用的工具类型，例如 `harbor` 表示该模板用于部署 Harbor。该值通常对应工具实例的资源名称
`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: harbor-template-quickstart
  namespace: cpaas-system
  labels:
    tools.cpaas.io/template: harbor
  annotations:
    ui.cpaas.io/displayName.en: Quick Start Template
    ui.cpaas.io/configuration.en: >-
      Configuration: <br/>
      Compute resources: 2 CPU cores, 4 Gi memory <br/>
      Storage: Use node local storage, configure the storage node IP and path <br/>
      Network access: Use NodePort to access the service, share the node IP with storage, and specify the port <br/>
      Dependencies: Configure existing Redis and PostgreSQL access credentials <br/>
      Other settings: Configure account credentials, SSO feature is disabled by default
    ui.cpaas.io/description.en: This template is used to quickly create a lightweight Harbor instance, suitable for development and testing scenarios, not recommended for production environments.

UI 动态表单

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

template form

动态表单的配置信息存储在 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 资源中获取的配置信息

template input

从用户输入获取参数

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: harbor-template
  ...
  annotations:
    ui.cpaas.io/descriptors: >-
      - path: domain
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:text
          - urn:alm:descriptor:com.tectonic.ui:validation:required
          - urn:alm:descriptor:label:en:Domain Name
          - urn:alm:descriptor:label:zh:域名
          - 'urn:alm:descriptor:description:en:'
          - 'urn:alm:descriptor:description:zh:'
spec:
  template: |
    ...
    externalURL: http://{{ .Values.domain }}
    helmValues:
      existingSecretAdminPassword: {{ .Values.adminPasswordSecret }}
      existingSecretAdminPasswordKey: password

      externalURL: http://{{ .Values.domain }}

      expose:
        type: ingress
        tls:
          enabled: false
        ingress:
          hosts:
            core: {{ .Values.domain }}

从 k8s 资源获取参数

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: harbor-template
  ...
spec:
  template: |
    ...
    global:
      {{- $secret := (lookup "v1" "Secret" "tools" "harbor-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: harbor-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: |
    ...
    {{- $secret := (lookup "v1" "Secret" .Values.namespace .Values.redisSecret) }}
    redis:
      external:
        {{- if and (hasKey $secret.data "masterName") $secret.data.masterName }}
        addr: "{{ $secret.data.address | b64dec | trim }}"
        sentinelMasterSet: {{ default "mymaster" $secret.data.masterName | b64dec | trim }}
        {{- else }}
        addr: {{ $secret.data.host | b64dec | trim }}:{{ $secret.data.port | b64dec | trim }}
        {{- end }}
        existingSecret: {{ .Values.redisSecret }}
        existingSecretKey: password
      type: external

配置国际化

模板支持国际化配置。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 中添加带语言代码的描述符，系统可根据用户语言偏好动态显示对应文本。

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

控件名称（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

示例 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:节点路径
  - 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`	定义选项值字段

示例：从 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

注册并验证模板

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

常见问题

如何访问内置模板内容？

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

进入平台“管理视图”
选择“集群管理” > “资源管理”
选择资源类型为 ConfigMap
搜索关键字 template 查找对应模板

如何隐藏产品内置模板？

若需隐藏产品内置模板，可在模板资源中添加 ui.cpaas.io/hidden 标签并设置为 true，同时需添加 skip-sync 注解，否则 Operator 重启或升级时会恢复模板内容。

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

如何自定义部署模板#

#目录

#自定义流程

#配置模板

#模板结构

#基本信息

#UI 动态表单

#部署模板

#配置国际化

#配置动态表单

#控件类型

#动态表单变量

#控件国际化

#控件显示信息

#字段校验

#动态选择

#注册并验证模板

#常见问题

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

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