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

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

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

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

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

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

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

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

    Объект Пример значения Как получить значение
    Эндпоинт зеркала реестра Docker docker.storage.example.local:5000 См. Получение артефактов установки
    Секрет Kubernetes для доступа к зеркалу реестра Docker onpremise-registry-creds См. Получение артефактов установки
    Домен S3-хранилища с артефактами установки artifacts.example.com См. Получение артефактов установки
    Название бакета с артефактами установки onpremise-artifacts См. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLE См. Получение артефактов установки
    Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY См. Получение артефактов установки
    Путь к файлу манифеста manifests/1640661259.json См. Получение артефактов установки
    Эндпоинт API сервиса ключей keys.example.local См. Установка сервиса ключей
    Сервисные токены* SEARCH_KEY_AAAAAA-111111
    CATALOG_KEY_BBBBBB-222222
    PLACES_KEY_AAAAAA-333333
    GEOCODER_KEY_BBBBBB-444444
    SUGGEST_KEY_CCCCCC-555555
    CATEGORIES_KEY_DDDDDD-666666
    REGIONS_KEY_EEEEEE-777777
    См. Установка сервиса ключей

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

  4. Убедитесь, что удовлетворены следующие требования к ресурсам (требования приведены с учётом минимального числа реплик):

    • Для testing-окружения:

      Сервис vCPU RAM Хранилище
      Сервисы поиска 5 20 ГБ 15 ГБ в хранилище подов Kubernetes
      60 ГБ в хранилище PostgreSQL
      Для хранилища PostgreSQL 6 12 ГБ 60 ГБ
      Итоговое количество: 11 32 ГБ 75 ГБ
    • Для production-окружения:

      Сервис vCPU RAM Хранилище
      Сервисы поиска 17 26 ГБ 15 ГБ в хранилище подов Kubernetes
      60 ГБ в хранилище PostgreSQL
      Для хранилища PostgreSQL 24 48 ГБ 60 ГБ
      Итоговое количество: 41 74 ГБ 75 ГБ

    Примечание:

    Подробная информация о системных требованиях для отдельных сервисов и компонентов программного комплекса 2ГИС приведена в документе Системные требования.

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

    Пример:

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

Разместите кластер PostgreSQL 11 с доменным именем 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 EXTENSION postgis WITH SCHEMA public;
    CREATE EXTENSION jsquery WITH SCHEMA public;
    
  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
    
    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:
        hosts:
            - host: search.example.com
    

    Где:

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

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

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

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

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

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

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

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

    values-catalog.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    imagePullSecrets:
        - name: onpremise-registry-creds
    
    imagePullPolicy: IfNotPresent
    
    api:
        postgres:
            host: catalog-postgresql.storage.example.local
            port: 5432
            name: onpremise_catalog
            username: dbuser_catalog
            password: 650D7AmZjSR1dkNa
    
    search:
        host: http://search.example.com
    
    keys:
        host: https://keys.example.local
        tokens:
            places: PLACES_KEY_AAAAAA-333333
            geocoder: GEOCODER_KEY_BBBBBB-444444
            suggest: SUGGEST_KEY_CCCCCC-555555
            categories: CATEGORIES_KEY_DDDDDD-666666
            regions: REGIONS_KEY_EEEEEE-777777
    

    Где:

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

    • api.postgres: настройки доступа к серверу PostgreSQL.

      • host: имя хоста или IP-адрес сервера.
      • port: порт, на котором слушает сервер.
      • name: имя базы данных.
      • username: имя пользователя.
      • password: пароль пользователя.
    • search: настройки доступа к сервису Search API.

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

      • host: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • tokens: сервисные токены для сохранения статистики использования (см. Установка сервиса ключей).
  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл:

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

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

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

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

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

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

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

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

Что дальше?