API поиска | On-Premise | 2GIS Documentation
On-Premise
Карты
Поиск
Навигация
On-Premise
ру
en

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

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

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

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

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

  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(S)://HOST См. Установка сервиса лицензий
    Эндпоинт API сервиса ключей keys.example.local См. Установка сервиса ключей
    Сервисные токены* CATALOG_TOKEN
    PLACES_TOKEN
    GEOCODER_TOKEN
    SUGGEST_TOKEN
    CATEGORIES_TOKEN
    REGIONS_TOKEN    		 См. Установка сервиса ключей

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

  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

2. Подготовьте инфраструктуру, необходимую для работы сервисов

Настройка PostgreSQL

Разместите кластер 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 EXTENSION postgis WITH SCHEMA public;
CREATE EXTENSION jsquery WITH SCHEMA public;

3. Установите сервисы поиска

Установка сервиса Search API

  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

Установка сервиса Catalog 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:
    url: http://search.example.com

keys:
    url: https://keys.example.local
    tokens:
        places: PLACES_TOKEN
        geocoder: GEOCODER_TOKEN
        suggest: SUGGEST_TOKEN
        categories: CATEGORIES_TOKEN
        regions: REGIONS_TOKEN

license:
    url: ''
    requestTimeout: 1s

    Где:

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

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

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

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

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

    • keys: настройки сервиса ключей.

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

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

      • url: URL-адрес сервиса лицензий. Пример: HTTP(S)://HOST.
      • requestTimeout: период времени для запроса сервиса лицензий.

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

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

4. Проверьте работоспособность установленных сервисов

Search API

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

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

Проверка сервиса Catalog API

С хоста в приватной сети 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

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

Что дальше?