Доступно в редакциях:  Open/CE, BE, SE, SE+, Ultimate/EE, Core, Certified Core/CSE Lite (1.73), Certified Pro/CSE Pro (1.73)

Стадия жизненного цикла модуля: General Availability

У модуля нет обязательных настроек.

В модуле реализовано 9 алертов.

Модуль включен по умолчанию в наборах модулей: Default, Managed. Модуль выключен по умолчанию в наборе модулей Minimal.

Как явно включить или отключить модуль...

Явно включить или выключить модуль можно одним из следующих способов:

  • С помощью веб-интерфейса Deckhouse. В разделе «Система» → «Управление системой» → «Deckhouse» → «Модули», откройте модуль documentation, включите (или выключите) переключатель «Модуль включен». Сохраните изменения.

    Пример:

    Интерфейс включения и выключения модуля

  • С помощью Deckhouse CLI (d8).

    Используйте команду d8 system module enable для включения модуля, или d8 system module disable для выключения модуля (требуется Deckhouse CLI (d8), настроенный на работу с кластером).

    Пример включения модуля documentation:

    d8 system module enable documentation
    
  • С помощью ModuleConfig documentation.

    Установите spec.enabled в true или false в ModuleConfig documentation (создайте его, при необходимости).

    Пример манифеста для включения модуля documentation:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: documentation
    spec:
      enabled: true
    

Как настроить модуль...

Настроить модуль можно одним из следующих способов:

  • С помощью веб-интерфейса Deckhouse.

    В разделе «Система» → «Управление системой» → «Deckhouse» → «Модули», откройте модуль documentation, включите переключатель «Дополнительные настройки». Заполните необходимые поля формы на вкладке «Конфигурация», или укажите настройки модуля в формате YAML на вкладке «YAML», не включая секцию settings. Сохраните изменения.

    Пример:

    Интерфейс настройки модуля

    Вы также можете отредактировать объект ModuleConfig documentation на вкладке «YAML» в окне настроек модуля («Система» → «Управление системой» → «Deckhouse» → «Модули», откройте модуль documentation), указав версию схемы в параметре spec.version и необходимые параметры модуля в секции spec.settings.

  • С помощью Deckhouse CLI (d8) (требуется Deckhouse CLI (d8), настроенный на работу с кластером).

    Отредактируйте существующий ModuleConfig documentation (подробнее о настройке Deckhouse читайте в документации), выполнив следующую команду:

    d8 k edit mc documentation
    

    Внесите необходимые изменения в секцию spec.settings. При необходимости укажите версию схемы в параметре spec.version. Сохраните изменения.

    Вы также можете создать файл манифеста ModuleConfig documentation, используя пример ниже. Заполните секцию spec.settings необходимыми параметрами модуля. При необходимости укажите версию схемы в параметре spec.version.

    Примените манифест с помощью следующей команды (укажите имя файла манифеста):

    d8 k apply -f <FILENAME>
    

    Пример файла манифеста ModuleConfig documentation:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: documentation
    spec:
      version: 1
      enabled: true
      settings: # Параметры модуля из раздела "Параметры" ниже.
    

Параметры

Версия схемы: 1

  • settings
    объект
    • settings.auth
      объект

      Опции, связанные с аутентификацией и авторизацией доступа к веб-интерфейсу документации.

      • settings.auth.allowedUserEmails
        массив строк

        Массив адресов электронной почты, пользователям которых разрешён доступ к веб-интерфейсу.

        Используется, если включён модуль user-authn или задан параметр externalAuthentication.

      • settings.auth.allowedUserGroups
        массив строк

        Массив групп, пользователям которых разрешён доступ к просмотру документации.

        Используется, если включён модуль user-authn или задан параметр externalAuthentication.

        Внимание. Если модуль работает вместе с модулем user-authn, добавьте разрешённые группы в настройки DexProvider.

        По умолчанию: []

        Примеры:

        allowedUserGroups:
        - admin
        - users
        
        allowedUserGroups: []
        
      • settings.auth.externalAuthentication
        объект

        Параметры внешней аутентификации. Используется механизм Ingress NGINX external-auth на основе модуля Nginx auth_request.

        Внешняя аутентификация включается автоматически, если включён модуль user-authn.

        • settings.auth.externalAuthentication.authSignInURL
          строка

          URL, куда будет перенаправлен пользователь для прохождения аутентификации (если сервис аутентификации вернул код ответа HTTP, отличный от 200).

          По умолчанию:

          Пример:

          authSignInURL: https://$host/dex-authenticator/sign_in
          
        • settings.auth.externalAuthentication.authURL
          строка

          URL сервиса аутентификации.

          Если пользователь прошёл аутентификацию, сервис должен возвращать код ответа HTTP 200.

          По умолчанию:

          Пример:

          authURL: https://documentation-dex-authenticator.d8-system.svc.cluster.local/dex-authenticator/auth
          
    • settings.highAvailability
      булевый

      Ручное управление режимом отказоустойчивости.

      По умолчанию режим отказоустойчивости определяется автоматически. Подробнее про режим отказоустойчивости.

      В режиме отказоустойчивости документация работает в двух репликах на разных узлах. Требования к узлам и роль S3 описаны в разделе «Режим отказоустойчивости» на странице примеров конфигурации модуля.

      Примеры:

      highAvailability: true
      
      highAvailability: false
      
    • settings.https
      объект

      Тип используемого сертификата.

      При использовании этого параметра полностью переопределяются глобальные настройки global.modules.https.

      Примеры:

      https:
        mode: Disabled
      
      https:
        mode: OnlyInURI
      
      https:
        mode: CustomCertificate
        customCertificate:
          secretName: foobar
      
      https:
        mode: CertManager
        certManager:
          clusterIssuerName: letsencrypt
      
      • settings.https.certManager
        объект

        Настройки для certmanager.

        • settings.https.certManager.clusterIssuerName
          строка

          ClusterIssuer, используемый для заказа SSL-сертификата (доступны letsencrypt, letsencrypt-staging, selfsigned, но можно определить свои).

          По умолчанию: letsencrypt

          Пример:

          clusterIssuerName: letsencrypt
          
      • settings.https.customCertificate
        объект

        Настройки пользовательского сертификата.

        • settings.https.customCertificate.secretName
          строка

          Имя Secret в неймспейсе d8-system, который будет использоваться для веб-интерфейса документации.

          Secret должен быть в формате kubernetes.io/tls.

      • settings.https.mode
        строка

        Режим работы HTTPS:

        • CertManager — доступ по HTTPS с заказом сертификата согласно ClusterIssuer, заданному в параметре certManager.clusterIssuerName.
        • CustomCertificate — доступ по HTTPS с использованием сертификата из неймспейса d8-system.
        • Disabled — доступ только по HTTP.
        • OnlyInURI — доступ по HTTP с внешним HTTPS-балансировщиком. Балансировщик терминирует HTTPS, и все ссылки в user-authn генерируются с HTTPS-схемой. Балансировщик должен обеспечивать перенаправление с HTTP на HTTPS.

        По умолчанию: CertManager

        Допустимые значения: Disabled, CertManager, CustomCertificate, OnlyInURI

    • settings.ingressClass
      строка

      Класс Ingress-контроллера веб-интерфейса документации.

      Опциональный параметр, по умолчанию используется глобальное значение modules.ingressClass.

      Шаблон: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

    • settings.moduleStorage
      объект

      Хранение документации версий модулей, которая готовится при первом открытии версии.

      • settings.moduleStorage.s3
        объект

        Где хранится подготовленная документация версий модулей, кроме кеша пода документации.

        • settings.moduleStorage.s3.external
          объект

          Ваше хранилище S3 для type: External. Модуль берёт настройки подключения и ключи из Secret. Список ключей Secret описан в разделе «Своё хранилище S3» на странице примеров конфигурации модуля.

          • settings.moduleStorage.s3.external.prefix
            строка

            Часть бакета, которую использует модуль: ключи всех объектов, которые он читает, записывает и удаляет, начинаются с этого префикса. Остальные объекты бакета модуль не трогает, поэтому бакет можно делить с другими.

            По умолчанию: documentation/

            Шаблон: ^([A-Za-z0-9][A-Za-z0-9._-]*/)+$

            Примеры:

            prefix: documentation/
            
            prefix: clusters/main/documentation/
            
          • settings.moduleStorage.s3.external.secretRef
            объект

            Обязательный параметр

            Secret с подключением и ключами хранилища S3, в любом неймспейсе.

            Deckhouse Platform копирует его в Secret documentation-s3-connection в d8-system. Этот Secret использует под документации. После того как вы создадите или измените Secret, под документации перезапустится в течение 5 минут. Пока Secret не создан, версии хранятся только в поде.

            • settings.moduleStorage.s3.external.secretRef.name
              строка

              Обязательный параметр

              Имя Secret.

              Шаблон: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

              Максимальная длина: 253

              Пример:

              name: documentation-s3
              
            • settings.moduleStorage.s3.external.secretRef.namespace
              строка

              Обязательный параметр

              Неймспейс Secret.

              Шаблон: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

              Максимальная длина: 63

              Примеры:

              namespace: d8-system
              
              namespace: documentation-storage
              
          • settings.moduleStorage.s3.external.size
            строка

            Сколько места модуль может занять в бакете под префиксом. Когда занято больше 80%, модуль удаляет сохранённые версии, пока не останется 60%, в таком порядке:

            1. Копии, заменённые после обновления шаблона документации.
            2. Версии, которые открывали читатели.
            3. Версии, которые использует поиск.

            Внутри каждой группы первыми удаляются версии, сохранённые раньше остальных.

            По умолчанию: 5Gi

            Шаблон: ^[1-9][0-9]*(Mi|Gi|Ti)$

            Примеры:

            size: 5Gi
            
            size: 20Gi
            
        • settings.moduleStorage.s3.type
          строка
          • Disabled — только в поде: после перезапуска пода версии готовятся заново при открытии. В режиме отказоустойчивости каждая реплика сама готовит и хранит версии. Документация расходует вдвое больше CPU и отправляет вдвое больше запросов в хранилище образов контейнеров. Для этого режима включите S3.
          • System — также в системном хранилище S3 модуля system-s3: после перезапуска пода версии открываются из него за доли секунды. Модуль создаёт для этого бакет на 5 ГиБ. Требует включённого модуля system-s3: без него версии хранятся только в поде, и срабатывает алерт D8DocumentationSystemS3Disabled.
          • External — также в вашем хранилище S3, которое задаётся в разделе external.

          По умолчанию: Disabled

          Допустимые значения: Disabled, System, External

    • settings.nodeSelector
      объект

      Структура, аналогичная spec.nodeSelector пода Kubernetes.

      Если значение не указано или равно false, Deckhouse Platform определяет nodeSelector автоматически.

      Пример:

      nodeSelector:
        disktype: ssd
      
    • settings.tolerations
      массив объектов

      Структура, аналогичная spec.tolerations пода Kubernetes.

      Если значение не указано или равно false, Deckhouse Platform определяет tolerations автоматически.

      Пример:

      tolerations:
      - key: key1
        operator: Equal
        value: value1
        effect: NoSchedule
      
      • settings.tolerations.effect
        строка
      • settings.tolerations.key
        строка
      • settings.tolerations.operator
        строка
      • settings.tolerations.tolerationSeconds
        целочисленный
      • settings.tolerations.value
        строка