How to Customize Deployment Templates#

#Custom Process

The custom template process is as follows:

1. Configure the template: According to the explanation in the Configure Template section, configure the content of the template as needed
2. Register and verify the template: According to the explanation in the Register and Verify the Template section, register the template in the target cluster and verify the template content

#Configure Template

#Template Structure

The tool deployment template is defined and managed through the ConfigMap resource. Each template consists of the following three main parts:

1. Basic information: Contains basic configuration information such as the name, description, and tags of the template
2. UI dynamic form: Defines the form items that the user needs to fill in when deploying the tool
3. Deployment template: Contains the specific resource definitions required for tool deployment

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

#Basic Information

Basic information includes the template name, description, tags, comments, display name, and description.

Example:

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 Dynamic Form

The tool deployment UI provides dynamic form functionality, which can automatically generate the corresponding form interface according to the form description information in the template, simplifying the user's configuration process.

The configuration information of the dynamic form is stored in the ui.cpaas.io/descriptors annotation, the specific format is as follows:

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。

Please refer to the Configure Dynamic Form section for the supported control types of the dynamic form.

#Deployment Template

The template engine is implemented based on Helm Template and supports all Helm built-in template functions, such as string processing, mathematical operations, flow control, etc. You can use these functions to build flexible deployment templates.

The main function of the template is to replace the input parameters into the predefined template. The input parameters mainly come from two sources:

1. The value entered by the user in the form
2. Configuration information obtained from Kubernetes resources.

Get parameters from user input

In the template, you can use the {{ .Values.<field name> }} syntax to get the value entered by the user. For example, if a field named domain is defined in the form for entering the deployment domain, then in the template, you can use {{ .Values.domain }} to reference this value.

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 }}

Get parameters from k8s resources

In the template, you can use the lookup function provided by Helm Template to get configuration information from Kubernetes resources. For example, to get the Redis connection information (such as Host, Port) from the gitlab-redis Secret resource in the tools namespace, you can use the lookup function as follows:

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 }}

The name of the Secret can also be entered by the user. For example, if a field named redisSecret is defined, you can use .Values.redisSecret to reference the Secret name entered by the user in the template.

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 }}

#Configure Internationalization

The template supports internationalization configuration. When displayed on the UI, the corresponding name and description will be displayed according to the language selected by the user.

The supported internationalization configuration annotations include:

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

To configure internationalization, just add the language code at the end of the field, such as:

• zh: Display when Chinese is selected
• en: Display when English is selected

Example:

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

#Configure Dynamic Form

#Control Types

Common control types include: string, number, and drop-down box.

Example:

- 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

#Dynamic Form Variables

The following variables can be used when describing the dynamic form:

1. ${context.cluster} : The name of the current cluster
2. ${context.namespace} : The current namespace (the namespace where the user selects the tool to be deployed)

Example:

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

#Control Internationalization

The tool deployment template supports configuring the international display content of the control's name, description, and placeholder. By adding descriptors with language codes in the x-descriptors, the system can dynamically display the corresponding text according to the user's language preference.

The supported internationalization configuration types include:

• Control Name (label): urn:alm:descriptor:label:<language>:<name>
• Control Description (description): urn:alm:descriptor:description:<language>:<description>
• Control Placeholder (placeholder): urn:alm:descriptor:placeholder:<language>:<placeholder>

Where <language> is the language code, currently supported:

• zh: Chinese
• en: English

Example: Configure a domain input box that supports Chinese and English:

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

#Control Display Information

Dynamic form controls support configuring international display content. When displayed on the UI, the corresponding name and description will be displayed according to the user's language selection.

#Field Validation

The dynamic form supports validating user input. The supported validation rules are as follows:

Example 1: Limit the value range to: 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

Example 2: Limit the string field to be required

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

Example 3: Limit the path entered by the user to be an absolute path

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+-]+)$

Example 4: Limit the length of the user input to 2-32 characters

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

#Dynamic Selection

The dynamic form supports dynamically loading the option list by calling the API.

Example: Get the Secret resource from the devops namespace of the test cluster and use metadata.name as the display name and value of the option.

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

#Register and Verify the Template

• Register the custom template:

  • Create the template resource (ConfigMap) in the cpaas-system namespace of the target cluster to complete the registration.

• Verify the template registration:

  • Enter the tool operator details page
  • Click the Create Resource button to enter the template selection page
  • If you can see the newly added template, the registration is successful

• Verify the template content:

  • Access the tool Operator details page
  • Click the Create Resource button to enter the template selection page
  • If the newly added template is visible, it indicates successful registration

• Verify template content:

  • Select the custom template
  • Follow the interface prompts to create a tool instance
  • If the tool instance can be successfully deployed, it indicates that the template content is correct

#Frequently Asked Questions

#How to access the built-in template content?

After the tool operator is deployed, it will automatically register the built-in deployment templates in the cpaas-system namespace of the current cluster. You can view the template content through the following path:

1. Enter the platform Management View
2. Select Cluster Management > Resource Management
3. Select the resource type as ConfigMap
4. Search for the keyword template to find the corresponding template

#How to hide the product's built-in template?

If you need to hide the product's built-in template, you can add the ui.cpaas.io/hidden label to the template resource and set it to true. Additionally, you need to add the skip-sync annotation; otherwise, the operator will restore the template content when restarting or upgrading.

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