API поиска | On-Premise | 2GIS Documentation
On-Premise

Установка API для работы с поиском

Важное примечание:

Все пароли и ключи в этом разделе приведены в иллюстративных целях.

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

  1. По возможности познакомьтесь с:

  2. Убедитесь, что выполнены необходимые предварительные шаги:

    1. Подготовка к установке
    2. Получение артефактов установки
    3. Установка сервиса лицензий
    4. Установка сервиса ключей
  3. Соберите необходимые данные, заданные или полученные на предыдущих шагах:

    Объект Пример значения Как получить значение
    Эндпоинт зеркала реестра Docker docker.storage.example.local:5000 См. Получение артефактов установки
    Секрет Kubernetes для доступа к зеркалу реестра Docker onpremise-registry-creds См. Получение артефактов установки
    Домен S3-хранилища с артефактами установки artifacts.example.com См. Получение артефактов установки
    Название бакета с артефактами установки onpremise-artifacts См. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLE См. Получение артефактов установки
    Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY См. Получение артефактов установки
    Путь к файлу манифеста manifests/1640661259.json См. Получение артефактов установки
    Эндпоинт сервиса лицензий http://license См. Установка сервиса лицензий
    Эндпоинт API сервиса ключей http://keys-api См. Установка сервиса ключей
    Сервисные токены* CATALOG_TOKEN
    PLACES_TOKEN
    GEOCODER_TOKEN
    SUGGEST_TOKEN
    CATEGORIES_TOKEN
    REGIONS_TOKEN
    См. Установка сервиса ключей

    * В иллюстративных целях предполагается, что сервисные токены доступны для всех продуктов поиска.

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

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

    Примечание

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

  5. Определите доменные имена для сервисов поиска.

    Пример:

    • Доменное имя для Search API: search-api.example.com
    • Доменное имя для Catalog APIs: catalog-api.example.com

Разместите кластер PostgreSQL с доменным именем catalog-postgresql.storage.example.local в приватной сети. В этом руководстве предполагается, что кластер работает на стандартном порту 5432.

Настройте кластер PostgreSQL для использования в качестве хранилища:

  1. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).

  2. Создайте пользователя базы данных, который будет использоваться для сервиса. Установите пароль для него.

    create user dbuser_catalog password '650D7AmZjSR1dkNa';
    
  3. Создайте базу данных, принадлежащую этому пользователю.

    create database onpremise_catalog owner dbuser_catalog;
    
  4. Установите требуемые расширения для базы данных:

    \c onpremise_catalog
    create schema extensions;
    grant usage on schema extensions to public;
    grant execute on all functions in schema extensions to public;
    alter default privileges in schema extensions grant execute on functions to public;
    alter default privileges in schema extensions grant usage on types to public;
    create extension if not exists plpgsql with schema pg_catalog;
    create extension if not exists jsquery with schema extensions;
    create extension if not exists postgis with schema extensions;
    
  1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

    Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

    values-search.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    imagePullSecrets:
        - name: onpremise-registry-creds
    
    imagePullPolicy: IfNotPresent
    
    dgctlStorage:
        host: artifacts.storage.example.local:443
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
        secure: false
        region: ''
    
    api:
        resources:
            limits:
                cpu: 1
                memory: 3G
            requests:
                cpu: 100m
                memory: 1G
    nginx:
        resources:
            limits:
                cpu: 1
                memory: 1G
            requests:
                cpu: 100m
                memory: 200Mi
    
    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: search-api.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - search-api.example.com
        #  secretName: secret.tls
    

    Где:

    • dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    • dgctlStorage: настройки хранилища артефактов развертывания.

      • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
      • manifest: укажите путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • region: регион S3-хранилища.
    • api.resources: настройки вычислительных ресурсов для бэкенд-сервиса API. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. Системные требования.

    • nginx.resources: настройки вычислительных ресурсов для бэкенд-сервиса NGINX. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. Системные требования.

    • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. Этот URL должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл:

    helm upgrade --install --version=1.24.0 --atomic --values ./values-search.yaml search-api 2gis-on-premise/search-api
    
  1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

    Примечание:

    Вы можете настроить процесс импорта новых данных для Catalog APIs. За это отвечают настройки группы importer конфигурационного файла (см. ниже).

    Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

    values-catalog.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    imagePullSecrets:
        - name: onpremise-registry-creds
    
    imagePullPolicy: IfNotPresent
    
    dgctlStorage:
        host: artifacts.storage.example.local:443
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
        secure: false
        region: ''
        verifySsl: true
    
    api:
        postgres:
            host: catalog-postgresql.storage.example.local
            port: 5432
            name: onpremise_catalog
            username: dbuser_catalog
            password: 650D7AmZjSR1dkNa
        ingress:
            enabled: true
            className: nginx
            hosts:
                - host: catalog-api.example.com
                  paths:
                      - path: /
                        pathType: Prefix
            tls: []
            #- hosts:
            #  - catalog-api.example.com
            #  secretName: secret.tls
    
    search:
        url: http://search-api
    
    keys:
        url: http://keys-api
        token: CATALOG_APIS_TOKEN
    
    importer:
        postgres:
            host: catalog-postgresql.storage.example.local
            port: 5432
            name: onpremise_catalog
            username: dbuser_catalog
            password: 650D7AmZjSR1dkNa
            schemaSwitchEnabled: true
        cleaner:
            enabled: true
            versionLimit: 2
    
    license:
        url: 'http://license'
        requestTimeout: 1s
    
    customCAs:
        bundle: ''
        # bundle: |
        #   -----BEGIN CERTIFICATE-----
        #   ...
        #   -----END CERTIFICATE-----
        certsPath: ''
    

    Где:

    • dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    • dgctlStorage: настройки хранилища артефактов развертывания.

      • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
      • manifest: укажите путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • region: регион S3-хранилища.
      • verifySsl: включить ли проверку SSL-сертификатов при подключении к dgctlStorage.host по HTTP. Значение по умолчанию: true.
    • api.postgres: настройки доступа к серверу PostgreSQL.

      • host: имя хоста или IP-адрес сервера.
      • port: порт, на котором слушает сервер.
      • name: имя базы данных.
      • username: имя пользователя.
      • password: пароль пользователя.
    • api.ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

    • search: настройки доступа к сервису Search API.

      • url: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
    • keys: настройки сервиса ключей.

      • url: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • token: сервисный токен для сохранения статистики использования (см. Установка сервиса ключей).
    • importer: настройки процесса импорта (Kubernetes Importer job). Импорт новых наборов данных происходит, только если для указанного манифеста не происходил импорт ранее.

      • postgres: настройки доступа к серверу PostgreSQL для импорта новых данных об объектах.

        • host: имя хоста или IP-адрес сервера.
        • port: порт, на котором слушает сервер.
        • name: имя базы данных.
        • username: имя пользователя.
        • password: пароль пользователя.
        • schemaSwitchEnabled: разрешить ли работу со схемами.
          • true: каждый импорт данных происходит в новую схему, возможно переключение на старые схемы и их очистка.
          • false: создание новых схем и очистка базы производятся администратором вручную.

        Подробнее см. в разделе Обновление сервиса Catalog APIs.

      • cleaner: настройки автоматического удаления старых наборов данных.

        • enabled: включено ли автоматическое удаление старых наборов данных. Подробнее см. в разделе Обновление сервиса Catalog APIs.
        • versionLimit: количество старых наборов данных, которые нужно хранить.

        См. Жизненный цикл артефактов установки для получения дополнительной информации о работе процесса импорта.

    • license: настройки сервиса лицензий.

      • url: URL-адрес сервиса лицензий. Пример: http://license.
      • requestTimeout: период времени для запроса сервиса лицензий.
    • customCAs: настройки пользовательских сертификатов.

      • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
      • certsPath: директория для монтирования сертификата внутри контейнера.
  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл:

    helm upgrade --install --version=1.24.0 --atomic --values ./values-catalog.yaml catalog-api 2gis-on-premise/catalog-api
    

    Если в конфигурационном файле были указаны настройки importer, то при установке сервиса проверяется наличие данных в базе и при необходимости происходит импорт этих данных в PostgreSQL. Затем Helm выполняет установку самого сервиса.

Чтобы проверить работоспособность сервиса Search API, выполните GET-запрос к endpoint status:

curl search-api.example.com/v2/status?f=common

С хоста в приватной сети example.com:

  1. С помощью веб-интерфейса администратора сервиса ключей создайте API-ключ, который предоставляет доступ к Places API и Regions API.

  2. Выполните следующий GET-запрос, заменив:

    • API_KEY на значение созданного ключа.
    • City на имя любого города, о котором вы хотите найти информацию.
    curl catalog-api.example.com/3.0/items/geocode?key=API_KEY&q=City
    

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

Что дальше?