Установка сервиса лицензий

Пароли и ключи приведены для примера

При реальной установке используйте более сложные и надёжные пароли.

1. Перед установкой

Ознакомьтесь с основной информацией:
- архитектура программного комплекса 2ГИС;
- системные требования к программному обеспечению и вычислительным ресурсам.
Убедитесь, что выполнены подготовительные шаги.

Соберите необходимые данные, заданные или полученные на предыдущих шагах:

Объект	Значение	Как получить значение
Ключ лицензии на программный комплекс 2ГИС	`DEMO-KEY-DGCTL-AAAAAA-BBBBBB`	См. Подготовка к установке
Endpoint S3-совместимого хранилища артефактов установки	`artifacts.example.com`	См. Получение артефактов установки
Инфраструктура доставки артефактов	`example.com` `example-external.com` `example-internal.com`	См. Получение артефактов установки
Имя бакета для хранения артефактов	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Имя пользователя для реестра Docker	`registry`	См. Получение артефактов установки
Пароль для реестра Docker	`DOCKERregistryP@ssW0rd`	См. Получение артефактов установки

Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чарте. Подробнее о том, как это сделать, см. в документе Системные требования.

Используйте подходящий чарт

Содержание Helm-чарта, описанное в данном разделе, актуально для последней версии базовых сервисов (см. Релизы базовых сервисов). Чтобы изучить параметры для предыдущих версий, откройте values.yaml в GitHub и в списке тегов слева выберите тег Core-<версия>.

2. Установите сервис лицензий

Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь. Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-license.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] dgctlStorage: host: artifacts.example.com secure: true bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY region: '' license: type: '' retryPeriod: 30s softBlockPeriod: 2w persistence: host: artifacts.example.com secure: true region: '' bucket: onpremise-artifacts root: 'license_state' accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY tpm: mountTPMDevice: false pvcBind: enable: false storageClassName: '' customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: '' affinity: {}
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- dgctlStorage: настройки доступа к хранилищу артефактов установки.
  - host: endpoint S3-совместимого хранилища артефактов установки в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - bucket: имя бакета S3.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
  - region: регион S3-совместимого хранилища.
- license: настройки сервиса лицензий.
  - type: тип лицензии (не версия). Скопируйте цифровое значение из файла values/general.yaml, который генерируется автоматически на этапе загрузки артефактов установки. Не изменяйте это значение вручную.
  - retryPeriod: через какой период времени повторить проверку лицензии, если предыдущая проверка не удалась.
  - softBlockPeriod: за какой период времени появляется уведомление об истечении срока лицензии. Поддерживаются дополнительные единицы измерения времени: d для дней и w для недель.
- persistence: настройки доступа к хранилищу для состояний сервиса лицензий.
  - host: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - region: регион S3-совместимого хранилища.
  - bucket: имя бакета S3.
  - root: корневая директория бакета S3, в которой будут храниться файлы состояния.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
    
    предупреждение
    При потере указанных данных текущая лицензия перестанет работать. Для получения новой лицензии см. Продвинутые способы получения лицензии.
- tpm: настройки для доступа к Trusted Platform Module (TPM). Только для типа лицензии 2 (license.type: 2). Тип лицензии — это цифровое значение из файла values/general.yaml, который генерируется автоматически на этапе загрузки артефактов установки.
  - mountTPMDevice: способ предоставления доступа к TPM:
    - true: монтировать TPM внутрь пода Kubernetes. Включается привилегированный доступ к основному контейнеру.
    - false: использовать плагин для автоматического монтирования TPM-устройства внутрь пода Kubernetes. Вы можете использовать готовый плагин от 2ГИС или собрать и установить свой плагин в кластере Kubernetes.
  - pvcBind: создать Persistent Volume Claim (PVC), чтобы привязать под сервиса лицензий к узлу кластера.
    - enable: использовать ли PVC. Значение по умолчанию: false.
    - storageClassName: имя класса хранения (StorageClass) в Kubernetes.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
- affinity: настройки affinity-правил для привязки подов сервиса лицензий к конкретным узлам кластера.
Примеры настройки affinity-правил:
- Для всех типов лицензий, кроме 1 (тип лицензии — это цифровое значение из файла values/general.yaml, который генерируется автоматически на этапе загрузки артефактов установки), рекомендуется располагать поды сервиса лицензий на разных узлах кластера:
  
  affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - topologyKey: kubernetes.io/hostname labelSelector: matchExpressions: - key: app.kubernetes.io/name operator: In values: - '' # значение этого параметра зависит от настроек вашего окружения
- Для типа лицензии 2 рекомендуется ограничить набор узлов кластера, к которым получает доступ сервис лицензий:
  
  affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: kubernetes.io/hostname operator: In values: - node-1 # название узла кластера - node-2 # название узла кластера
Подробное описание параметров affinity-правил см. в документации Kubernetes.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-license.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
В параметре --version укажите нужную версию базовых сервисов. Список версий см. в разделе Релизы базовых сервисов.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.

При первом запуске команда вернёт ошибку, что под сервиса лицензий не может быть запущен. Это ожидаемое поведение, переходите к следующим шагам.

3. Получите лицензию

Ниже описан стандартный способ получения лицензии

Чтобы получить лицензию после обновления сертификата сервера Kubernetes API, смены ключа, типа лицензирования или в других частных случаях, см. Продвинутые способы получения лицензии.

Для операций с лицензиями используется конфигурационный файл утилиты 2GIS CLI. Подробнее о процессе получения лицензии см. в описании режима утилиты license.

Процесс может быть запущен как на одном хосте с доступом к S3-совместимому хранилищу и интернету, так и на двух отдельных хостах с разными доступами. Выполните следующие действия в зависимости от выбранной конфигурации хостов.

Использование одного хоста
Использование двух хостов с разными доступами

Зайдите по SSH на хост example.com и создайте конфигурационный файл dgctl-config.yaml. Подробнее о доступных параметрах см. в описании конфигурационного файла 2GIS CLI.

dgctl-config.yaml

key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json

storage:
  type: s3
  host: artifacts.example.com
  bucket: onpremise-artifacts
  access-key: AKIAIOSFODNN7EXAMPLE
  secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

docker:
  registry:
    username: registry
    password: DOCKERregistryP@ssW0rd
    server-address: https://docker.registry.example.com
    image-prefix: /

# Для утилиты версии 3
components:
  core:
    version: <core-version>
  api-platform:
    version: <api-platform-version>

Запросите лицензию:
```
docker run --rm \
  -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
  --user $(id -u):$(id -g) \
  2gis/dgctl:3 \
  license --config=/dgctl-config.yaml
```
Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
Снова установите сервис с помощью Helm:
```
helm upgrade --install --version=VERSION --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
В параметре --version укажите ту же версию базовых сервисов, что и при прошлом выполнении команды.

Перед началом работы убедитесь, что у вас настроены два хоста:

example-external.com с доступом в публичную сеть или только к следующим адресам:
- datagateway.api.2gis.com — для получения файла лицензии и файла манифеста;
- origin-disk.2gis.com — для получения файлов приложений и данных.
example-internal.com с доступом к реестру Docker и S3-совместимому хранилищу.

Подробнее см. в разделе Настройка хостов.

При использовании двух хостов скопируйте файлы из S3-совместимого хранилища и в него. Для этого можно использовать утилиту 2GIS CLI (рекомендуется) или другой клиент для работы с S3.

На обоих хостах создайте директорию для переноса файлов. Вы можете сохранить путь к директории в переменной окружения COPY_DIR. Например:
```
COPY_DIR=/mnt/dgctl-source
```

Зайдите по SSH на хост example-internal.com и создайте конфигурационный файл dgctl-config.yaml. Подробнее о доступных параметрах см. в описании конфигурационного файла 2GIS CLI.

dgctl-config.yaml

key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json

storage:
  type: s3
  host: artifacts.example.com
  bucket: onpremise-artifacts
  access-key: AKIAIOSFODNN7EXAMPLE
  secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

docker:
  registry:
    username: registry
    password: DOCKERregistryP@ssW0rd
    server-address: https://docker.registry.example.com
    image-prefix: /

# Для утилиты версии 3
components:
  core:
    version: <core-version>
  api-platform:
    version: <api-platform-version>

Сформируйте файлы для запроса лицензии на хосте example-internal.com:
1. Проверьте наличие всех необходимых файлов для запроса лицензии (если используете утилиту 2GIS CLI):
```
docker run --rm \
  -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
  --user $(id -u):$(id -g) \
  2gis/dgctl:3 \
  license --config=/dgctl-config.yaml --dry-run
```
  Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
2. Скопируйте файлы для запроса лицензии из S3-совместимого хранилища в COPY_DIR:
  - Если вы используете утилиту 2GIS CLI, выполните следующую команду:
    docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v $COPY_DIR:/data \ --user $(id -u):$(id -g) \ 2gis/dgctl:3 \ save --config=/dgctl-config.yaml --to-dir /data --only-license
    Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
  - Если вы используете сторонний клиент S3, скопируйте всё содержимое директории license-dir из S3 в COPY_DIR.
Скопируйте содержимое директории COPY_DIR с example-internal.com на example-external.com.
Зайдите по SSH на хост example-external.com и создайте конфигурационный файл dgctl-config-fs.yaml. Подробнее о доступных параметрах см. в описании конфигурационного файла 2GIS CLI.
dgctl-config-fs.yaml
key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB log-format: json storage: type: fs directory: /data # Для утилиты версии 3 components: core: version: <core-version> api-platform: version: <api-platform-version>
Запросите лицензию на example-external.com:
```
docker run --rm \
  -v $(pwd)/dgctl-config-fs.yaml:/dgctl-config.yaml \
  -v $COPY_DIR:/data \
  --user $(id -u):$(id -g) \
  2gis/dgctl:3 \
  license --config=/dgctl-config.yaml
```
Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
Скопируйте содержимое директории COPY_DIR с example-external.com на example-internal.com.
На хосте example-internal.com используйте конфигурационный файл dgctl-config.yaml из шага 2 или создайте такой же.
Скопируйте файл с лицензией из COPY_DIR в S3-совместимое хранилище:
- Если вы используете утилиту 2GIS CLI, выполните команду:
```
docker run --rm \
   -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
   -v $COPY_DIR:/data \
   --user $(id -u):$(id -g) \
   2gis/dgctl:3 \
   restore --config=/dgctl-config.yaml --from-dir /data --only-license
```
  Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
- Если вы используете сторонний клиент S3, скопируйте всё содержимое директории license-dir из COPY_DIR в S3-совместимое хранилище.
Снова установите сервис с помощью Helm:
```
helm upgrade --install --version=VERSION --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
В параметре --version укажите ту же версию базовых сервисов, что и при прошлом выполнении команды.

4. Проверьте статус лицензии

Пробросьте порт сервиса с помощью kubectl:
```
kubectl port-forward <namespace> license.svc 8080:80
```

Выполните запрос к endpoint-у /status:

curl -v http://localhost:8080/status -H "Accept: application/json" | jq

Проверьте ответ:

Если лицензия действительна, ответ содержит HTTP-код 200 и информацию о статусе лицензии и сроке её действия в формате JSON.

Пример ответа

curl -s http://localhost:8080/status -H "Accept: application/json" | jq
{
   "status": 200,
   "issued-at": "2025-08-21T13:49:26Z",
   "soft-block-at": "2026-01-17T21:00:00Z",
   "hard-block-at": "2026-01-31T21:00:00Z",
   "services": {
   "pro": {
         "status": 200,
         "soft-block-at": "2026-01-17T21:00:00Z",
         "hard-block-at": "2026-01-31T21:00:00Z"
   }
   }
}

Если лицензия скоро истечёт или уже истекла, в ответе указан код 402 (предупреждение) или 403 (блокировка).

Пример ответа

curl -s http://localhost:8080/status -H "Accept: application/json" | jq
{
   "status": 402,
   "issued-at": "2025-10-16T05:50:46Z",
   "soft-block-at": "2026-01-17T21:00:00Z",
   "hard-block-at": "2026-01-31T21:00:00Z",
   "services": {
   "pro": {
         "status": 402,
         "soft-block-at": "2026-01-17T21:00:00Z",
         "hard-block-at": "2026-01-31T21:00:00Z"
   }
   }
}

Что дальше?

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

1. Перед установкой​

2. Установите сервис лицензий​

3. Получите лицензию​

4. Проверьте статус лицензии​

Что дальше?​

1. Перед установкой

2. Установите сервис лицензий

3. Получите лицензию

4. Проверьте статус лицензии

Что дальше?