Как настроить шаблоны развертывания#

#Пользовательский процесс

Процесс настройки шаблона следующий:

1. Настройка шаблона: согласно описанию в разделе Configure Template настройте содержимое шаблона по необходимости
2. Регистрация и проверка шаблона: согласно описанию в разделе Register and Verify the Template зарегистрируйте шаблон в целевом кластере и проверьте содержимое шаблона

#Настройка шаблона

#Структура шаблона

Шаблон развертывания инструмента определяется и управляется через ресурс ConfigMap. Каждый шаблон состоит из следующих трёх основных частей:

1. Основная информация: содержит базовую конфигурационную информацию, такую как имя, описание и теги шаблона
2. Динамическая форма UI: определяет элементы формы, которые пользователь должен заполнить при развертывании инструмента
3. Шаблон развертывания: содержит конкретные определения ресурсов, необходимые для развертывания инструмента

apiVersion: v1
kind: ConfigMap
## Часть 1: Основная информация
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.
## Часть 2: Динамическая форма UI
    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
        ...
## Часть 3: Шаблон развертывания
data:
  template: >-
    helmValues:
      gitlab:
        gitaly:
          init:
            resources:
              limits:
                cpu: 1
                memory: 1Gi
              requests:
                cpu: 100m
                memory: 100Mi
          ...

#Основная информация

Основная информация включает имя шаблона, описание, теги, комментарии, отображаемое имя и описание.

Пример:

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。

Пожалуйста, обратитесь к разделу Configure Dynamic Form для списка поддерживаемых типов элементов управления динамической формы.

#Шаблон развертывания

Движок шаблонов реализован на основе Helm Template и поддерживает все встроенные функции шаблонов Helm template functions, такие как обработка строк, математические операции, управление потоком и др. Вы можете использовать эти функции для создания гибких шаблонов развертывания.

Основная функция шаблона — подстановка входных параметров в предопределённый шаблон. Входные параметры поступают из двух основных источников:

1. Значения, введённые пользователем в форме
2. Конфигурационная информация, полученная из ресурсов Kubernetes

Получение параметров из пользовательского ввода

В шаблоне можно использовать синтаксис {{ .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

В шаблоне можно использовать функцию lookup, предоставляемую Helm Template, чтобы получить конфигурационную информацию из ресурсов Kubernetes. Например, чтобы получить информацию для подключения к Redis (например, Host, Port) из ресурса Secret gitlab-redis в пространстве имён tools, можно использовать функцию 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, в шаблоне можно ссылаться на имя Secret, введённое пользователем, как .Values.redisSecret.

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

#Настройка динамической формы

#Типы элементов управления

Распространённые типы элементов управления включают: строка, число и выпадающий список.

Пример:

- 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:Domain
  - urn:alm:descriptor:label:en:Domain

#Отображаемая информация элемента управления

Элементы управления динамической формы поддерживают настройку международного отображения. При отображении в UI будет показано соответствующее имя и описание в зависимости от выбора языка пользователя.

#Валидация полей

Динамическая форма поддерживает валидацию пользовательского ввода. Поддерживаемые правила валидации:

Пример 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.

Пример: получение ресурса Secret из пространства имён devops кластера test с использованием 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 целевого кластера для завершения регистрации.

• Проверка регистрации шаблона:

  • Перейдите на страницу деталей оператора инструмента
  • Нажмите кнопку Create Resource для перехода на страницу выбора шаблона
  • Если вы видите недавно добавленный шаблон, регистрация прошла успешно

• Проверка содержимого шаблона:

  • Зайдите на страницу деталей оператора инструмента
  • Нажмите кнопку Create Resource для перехода на страницу выбора шаблона
  • Если отображается недавно добавленный шаблон, это означает успешную регистрацию

• Проверка содержимого шаблона:

  • Выберите пользовательский шаблон
  • Следуйте подсказкам интерфейса для создания экземпляра инструмента
  • Если экземпляр инструмента успешно развернут, значит содержимое шаблона корректно

#Часто задаваемые вопросы

#Как получить доступ к содержимому встроенного шаблона?

После развертывания оператора инструмента он автоматически регистрирует встроенные шаблоны развертывания в пространстве имён cpaas-system текущего кластера. Вы можете просмотреть содержимое шаблона следующим образом:

1. Перейдите в Management View платформы
2. Выберите Cluster Management > Resource Management
3. Выберите тип ресурса ConfigMap
4. Выполните поиск по ключевому слову template для нахождения соответствующего шаблона

#Как скрыть встроенный шаблон продукта?

Если необходимо скрыть встроенный шаблон продукта, добавьте метку ui.cpaas.io/hidden в ресурс шаблона и установите её в true. Кроме того, нужно добавить аннотацию skip-sync, иначе оператор восстановит содержимое шаблона при перезапуске или обновлении.

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