Alauda Build of Harbor Docs
  • Русский

    • How to Customize Deployment Templates

    Содержание

    Пользовательский процессНастройка шаблонаСтруктура шаблонаОсновная информацияДинамическая форма UIШаблон развертыванияНастройка интернационализацииНастройка динамической формыТипы элементов управленияПеременные динамической формыИнтернационализация элементов управленияИнформация об отображении элемента управленияПроверка полейДинамический выборРегистрация и проверка шаблонаЧасто задаваемые вопросыКак получить доступ к содержимому встроенного шаблона?Как скрыть встроенный шаблон продукта?

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

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

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

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

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

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

    1. Основная информация: содержит базовые сведения о шаблоне, такие как имя, описание и теги
    2. Динамическая форма UI: определяет элементы формы, которые пользователь должен заполнить при развертывании инструмента
    3. Шаблон развертывания: содержит конкретные определения ресурсов, необходимые для развертывания инструмента
    apiVersion: v1
kind: ConfigMap
## Часть 1: Основная информация
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.
## Часть 2: Динамическая форма 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
        ...
## Часть 3: Шаблон развертывания
data:
  template: >-
    externalURL: http://{{ $displayIP }}:{{ .Values.httpPort }}
    helmValues:
      existingSecretAdminPassword: {{ .Values.adminPasswordSecret }}
      existingSecretAdminPasswordKey: password

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

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

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

    ПолеОписание
    metadata.nameУникальный идентификатор ресурса шаблона, используемый для различения различных шаблонов в системе
    metadata.namespaceПространство имен, в котором расположен ресурс шаблона; в настоящее время UI отображает только шаблоны из namespace 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]Управляет тем, будет ли оператор управлять встроенным шаблоном. Если для шаблона задана эта аннотация, оператор не будет обновлять содержимое шаблона при перезапуске или обновлении

    Пример:

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

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

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

    template input

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

    В шаблоне можно использовать синтаксис {{ .Values.<field name> }}, чтобы получить значение, введенное пользователем. Например, если в форме для ввода домена развертывания определено поле с именем 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

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

    Переменные динамической формы

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

    1. ${context.cluster}: имя текущего кластера
    2. ${context.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 соответствующие имя и описание будут показаны в соответствии с выбором языка пользователя.

    Поле элемента управленияОписание
    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>Описывает placeholder элемента управления
    - <language> — код языка, например zh для китайского, en для английского
    - <placeholder> — текст 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: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Определяет поле значения опции

    Пример: получить ресурс 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

    Регистрация и проверка шаблона

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

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

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

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

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

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

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

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

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

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

    После развертывания оператора инструмента встроенные шаблоны развертывания будут автоматически зарегистрированы в namespace 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"