Сценарии администрирования#

Администратором является член команды с ролью Пользователь, который выполняет дополнительные административные задачи. Отдельной роли для администратора в продукте не предусмотрено.

Конфигурирование состава документации на сайте#

Конфигурация сайта хранится в репозитории content-configuration и имеет следующую структуру:

site-config/
  product-registry/
    products.json
    components.json
  <PRODUCT-CODE-1>/ # Вариант с отдельным файлом для каждой версии продукта
    <VERSION-11>
      components.ini
    <VERSION-12>
      components.ini
    ...
    <VERSION-1N>
      components.ini
  <PRODUCT-CODE-N>/ # Вариант с единым файлом для всех версий продукта
    components.ini
  ...
  doc-config.ini

Пример структуры каталогов в репозитории конфигурации сайта:

content-configuration/
├── BD/                        // каталог с названием кода продукта
│   ├── 5.11.2/                // каталог с названием версии продукта
│   │   └── components.ini     // файл конфигурации продукта
│   ├── 5.15.0/
│   │   └── components.ini
│   └── ...
├── SEI/
│   ├── 3.7/
│   │   └── components.ini
│   └── ...
└── ...

По умолчанию сайт документации имеет несколько пространств, которые определяют стадию (stage) готовности документации:

draft — собранная документация изначально попадает в это пространство. Данная сборка позволяет получить отчет сборки и информацию об исходном репозитории документации;
approved — перевод в пространство approved означает, что документация прошла внутреннее согласование и готова к внутренней приемке и публикации;
release — перевод в пространство release означает доступность документации для пользователей.

Каждый продукт может быть самостоятельным или включать в себя компоненты. Для перевода документации в нужное пространство, необходимо в файле components.ini продукта поставить соответствующий тег:

Стадия (stage)	Тег
draft	отсутствует
approved	approved
release	release

Пример components.ini для продукта с кодом PIF:

[PIF 1.0.0 release] # Раздел продукта в формате: код версия теги
common # Общая документация на продукт
PINF: 1.0.0 # Компонент, который есть в продукте (<COMPONENT-CODE>: <COMPONENT-VERSION>)
GDOC: 1.0.0 # Каждый компонент и его версия указываются на новой строке

[PIF 1.1.0 approved]
common
PINF: 1.1.0
GDOC: 1.1.0

[PIF 1.2.0]
common
PINF: 1.2.0
GDOC: 1.2.0

Установка тега release на головной элемент продукта (например, [PIF 1.0.0 release]) означает, что все элементы этой секции (общая документация и компоненты) должны быть доступны пользователям.

Важно

Головным элементом может быть только продукт - его трехбуквенный код и версия.

Установка тега release на отдельные элементы внутри головного (например, PINF: 1.0.0 release) означает, что только помеченные тегом release комплекты документации будут доступны пользователям.

Это действие может выполнять только релизный менеджер, контролирующий публикацию (список таких сотрудников указан в поле release-managers в doc-config.ini). Коммит с добавлением тега release, сделанный не релизным менеджером, будет отклонен автоматически.

Описание doc-config.ini:

[env]                                                     # Правила сборки
stage: draft, approved, release                           # Пространство для публикации. Доступны: draft - документация в разработке, approved - документация прошла внутренние согласования, release - готовая документация для пользователей
package: <PACKAGE-1>, <PACKAGE-2>, ..., <PACKAGE-N>       # Состав комплекта документации
audience: <AUDIENCE-1>, <AUDIENCE-2>, ..., <AUDIENCE-N>   # Целевая аудитория

# Пользователи, которые могут устанавливать тег release для публикации контента
release-managers:       user1,
                        user2

# Правила группировки документов
# [Имя группы документов]
[Общие документы]
# имя-директории-с-разделом-документации-в-репозитории: отображаемое-на-сайте-название-раздела
about:                  Описание
architecture:           Детальная архитектура
pmi:                    Программа и методика испытаний
release-notes:          Примечания к релизу
sizing:                 Методика расчета сайзинга
deployment-diagrams:    Диаграммы развертывания

[Руководства]
installation-guide:     Руководство по установке
administration-guide:   Руководство по системному администрированию
developer-guide:        Руководство прикладного разработчика
operators-guide:        Руководство оператора
security-guide:         Руководство по безопасности

[*]
*:      {title}

[Дополнительная документация]
*:      {title}

[Справочники API]
apis:   {title}

Ведение правил валидации контента#

Правила валидации документации хранятся в репозитории content-validation.

Структура правил в репозитории content-validation имеет следующую структуру:

.
└── content-validation/
    ├── rules/
    │   ├── software.yaml
    ├── styles/
    │   ├── <STYLE-1>/
    │   │   ├── <RULE-11>.yaml
    │   │   ├── <RULE-12>.yaml
    │   │   ├── ...
    │   │   └── <RULE-1N>.yaml
    │   ├── <STYLE-2>/
    │   │   ├── <RULE-21>.yaml
    │   │   ├── <RULE-22>.yaml
    │   │   ├── ...
    │   │   └── <RULE-2N>.yaml
    │   ├── ...
    │   ├── <STYLE-N>/
    │   │   ├── <RULE-N1>.yaml
    │   │   ├── <RULE-N2>.yaml
    │   │   ├── ...
    │   │   └── <RULE-NN>.yaml
    │   └── Vocab/
    │       ├── <VOCAB-1>/
    │       │   ├── accept.txt
    │       │   └── reject.txt
    │       ├── <VOCAB-2>/
    │       │   ├── accept.txt
    │       │   └── reject.txt
    │       ├── ...
    │       └── <VOCAB-N>/
    │           ├── accept.txt
    │           └── reject.txt
    └── .vale.ini

Базовые правила#

Данные правила проверяются при сборке документации (workflow build-doc), при запуске базовой валидации контента (workflow validate-doc) и валидации изображений (workflow validate-doc-images). К базовым проверкам могут относиться проверки правил внутреннего глоссария, стайлгайда, проверки на наличие запрещенной информации и т.д.

Ведение файла конфигурации .vale.ini и создание правил валидации описано в официальной документации Vale:

Правила проверки системных требований#

В GetDocs доступна проверка корректности указания системных требований в документации.

Одна из проверок проверяет, что упомянутое в документации программное обеспечение не является запрещенным и что версия этого ПО рекомендована к использованию. Список запрещенного ПО и рекомендуемых версий хранится в файле software.yaml в репозитории content-validation. Ниже приведен пример данного файла:

# в блок можно добавить слова, которые ошибочно распознаются валидатором, как ПО
ignore:
  - 'CLOSED|ERROR|FAIL|URL'
  - 'List|Map|String|Session|Data|Context|Value|Service'

# в блоке перечисляются рекомендуемые версии для разрешенного ПО в формате 'SoftwareName: version1, version2'
allow:
  - Kubernetes: 1.0, 1.21, 1.24
  - Prometheus: 2.21.0, 2.31
  - РЕД ОС: 7.3

# в блоке перечисляется нерекомендуемое ПО
prohibit:
  - (Atlassian )?BitBucket
  - (Red ?Hat )?Enterprise Linux

Значения в каждом блоке поддерживают регулярные выражения.

См. также

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

Ведение продуктового учета#

Продуктовый учет - это набор продуктов и их компонентов, для которых готовится документация. Каждый продукт может быть самостоятельным или включать в себя компоненты.

Сайт с документацией формируется автоматически на основе данных из продуктового учета по модели: Категория > Продукты > Компоненты.

Продуктовый учет располагается в папке product-registry/.

Важно

Для корректной работы GetDocs с продуктовым учетом необходимо, чтобы продукты имели трехбуквенные коды-идентификаторы (поле code).

Продукты в учете регистрируются по кодам и ведутся в файле products.json:

{
  "entities": [
    {
      "code": "XYZ",
      "name": "Имя продукта.",
      "longDescription": "Длинное описание продукта.",
      "shortDescription": "Краткое описание продукта.",
      "category": {
        "name": "Имя категории, в которую входит продукт.",
        "description": "Описание категории, в которую входит продукт."
      },
      "type": {
        "name": "Зарезервировано для будущего использования."
      }
    }
  ]
}

Компоненты в учете регистрируются по кодам и ведутся в файле components.json:

{
  "entities": [
    {
      "code": "XYZA",
      "name": "Имя компонента.",
      "longDescription": "Длинное описание компонента.",
      "shortDescription": "Краткое описание компонента.",
      "category": {
        "name": "Имя категории продуктов, в которую входит компонент."
        "description": "Описание категории продуктов, в которую входит компонент."
      },
      "type": {
        "name": "Зарезервировано для будущего использования."
      }
    }
  ]
}

API token для Argo Workflows#

Создание токена#

Создайте следующий скрипт create_argowf_token.sh, который создает API token для пользователя:

#!/bin/bash

if [ -z "$1" ]; then
    echo "ERROR: Please specify service account name."
    exit 1
fi
SA_NAME="$1"
if [ -z "$2" ]; then
    echo "INFO: Privileges set to getdocs-prod namespace"
    NAMESPACE='getdocs-prod'
else
  NAMESPACE="$2"
  echo "INFO: Privileges set to $NAMESPACE namespace"
fi
kubectl -n argo-wf create sa "$SA_NAME"
kubectl -n $NAMESPACE create rolebinding "$SA_NAME" --role=argo-workflows-rx --serviceaccount=argo-wf:"$SA_NAME"
kubectl -n argo-wf apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: $SA_NAME.service-account-token
  annotations:
    kubernetes.io/service-account.name: $SA_NAME
type: kubernetes.io/service-account-token
EOF

ARGO_TOKEN="Bearer $(kubectl -n argo-wf get secret "$SA_NAME.service-account-token" -o=jsonpath='{.data.token}' | base64 --decode)"
echo
echo "Token for '$SA_NAME': $ARGO_TOKEN"

Выполните данный скрипт с указанием имени пользователя <ACCOUNT_NAME>, для которого создается token:
```
create_argowf_token.sh <ACCOUNT_NAME> <NAMESPACE>
```
Параметр <NAMESPACE> является опциональным. Если он не передан, token будет создан для стандартного пространства имен getdocs-prod.

Удаление токена#

Создайте следующий скрипт delete_argowf_token.sh, который удаляет пользовательский API token:

#!/bin/bash

if [ -z "$1" ]; then
    echo "ERROR: Please specify service account name."
    exit 1
fi
SA_NAME="$1"
if [ -z "$2" ]; then
    echo "INFO: Privileges set to getdocs-prod namespace"
    NAMESPACE='getdocs-prod'
else
  NAMESPACE="$2"
fi

kubectl -n argo-wf delete sa "$SA_NAME"
kubectl -n $NAMESPACE delete rolebinding "$SA_NAME"
kubectl -n argo-wf delete secret $SA_NAME.service-account-token

echo
echo "Deleted token for '$SA_NAME'"

Выполните данный скрипт с указанием имени пользователя <ACCOUNT_NAME>, чей token необходимо удалить:
```
delete_argowf_token.sh <SERVICE_ACCOUNT_NAME> <NAMESPACE>
```
Параметр <NAMESPACE> является опциональным. Если он не передан, token будет удален для стандартного пространства имен getdocs-prod.