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

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

Процесс настройки пользовательского шаблона выглядит следующим образом:

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

#Configure Template

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

Шаблон развертывания инструмента определяется и управляется через ресурс 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: 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
          ...

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

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

Пример:

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 и поддерживает все встроенные template functions Helm, такие как обработка строк, математические операции, управление потоком выполнения и т. д. Эти функции можно использовать для создания гибких шаблонов развертывания.

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

1. Значение, введенное пользователем в форме
2. Информация о конфигурации, полученная из ресурсов 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

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

#Configure Internationalization

Шаблон поддерживает настройку интернационализации. При отображении в 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

#Configure Dynamic Form

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

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

Пример:

- 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} : текущий namespace (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
  ...

#Интернационализация элементов управления

Шаблон развертывания инструмента поддерживает настройку международного отображаемого содержимого имени, описания и placeholder элемента управления. Добавляя дескрипторы с кодами языков в x-descriptors, система может динамически отображать соответствующий текст в соответствии с языковыми предпочтениями пользователя.

Поддерживаемые типы настройки интернационализации включают:

• Имя элемента управления (label): urn:alm:descriptor:label:<language>:<name>
• Описание элемента управления (description): urn:alm:descriptor:description:<language>:<description>
• Placeholder элемента управления (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 из namespace devops тестового кластера и использовать 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

#Register and Verify the Template

• Зарегистрируйте пользовательский шаблон:

  • Создайте ресурс шаблона (ConfigMap) в namespace cpaas-system целевого кластера, чтобы завершить регистрацию.

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

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

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

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

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

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

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

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

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

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

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

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

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