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

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

    Содержание

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

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

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

    Получение параметров из ресурсов Kubernetes

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

    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} : текущее пространство имён (пространство имён, в котором пользователь выбирает инструмент для развертывания)

    Пример:

    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 показываются соответствующие имя и описание в зависимости от выбранного языка пользователя.

    Поле элемента управленияОписание
    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: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 из пространства имён 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"