Сервис API-ключей | On-Premise | 2GIS Documentation
On-Premise
Карты
Поиск
Навигация
On-Premise
2ГИС Про
ру
en

Установка сервиса API-ключей

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

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

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

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

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

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

    1. Подготовка к установке
    2. Получение артефактов установки

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

    Объект Значение Как получить значение
    Эндпоинт зеркала реестра Docker в приватной сети docker.storage.example.local:5000 См. Получение артефактов установки
    Секрет Kubernetes для доступа к эндпоинту зеркала реестра Docker onpremise-registry-creds См. Получение артефактов установки
    Домен S3-хранилища с артефактами установки artifacts.example.com См. Получение артефактов установки
    Название бакета с артефактами установки onpremise-artifacts См. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLE См. Получение артефактов установки
    Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY См. Получение артефактов установки
    Путь к файлу манифеста manifests/1640661259.json См. Получение артефактов установки

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

    * Эти требования к хранилищу могут меняться в зависимости от настроенного временного периода для хранения статистики. Чем больше этот период, тем больший объем хранилища потребуется.

    Примечание

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

  5. Определите доменные имена для сервиса API-ключей.

    Пример: keys.example.com

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

Настройка PostgreSQL

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

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

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

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

    create user keys_superuser_rw password 'KEYS_Db_Owner_Password_1234';
create user keys_user_ro password 'KEYS_Db_RO_User_Password_5678';

  3. Создайте базу данных, принадлежащую одному из пользователей.

    create database onpremise_keys owner keys_superuser_rw;

  4. Добавьте ограниченные права к этой базе данных другому пользователю.

    \c onpremise_keys

ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON TABLES TO keys_user_ro;
ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON SEQUENCES TO keys_user_ro;

Настройка LDAP

Чтобы сервисы могли выполнять аутентификацию администраторов сервиса API-ключей, рекомендуется использовать LDAP-сервер (например, Microsoft Active Directory). Этот шаг можно пропустить, если у вас нет возможности развернуть LDAP-сервер и вы собираетесь использовать аутентификацию по plaintext-паролям в конфигурационном файле.

Разместите LDAP-сервер с доменным именем keys-ldap.storage.example.local в приватной сети. В этом руководстве предполагается, что сервер работает на стандартном порту 3268.

  1. Получите значения необходимых настроек LDAP.

    Настройка Пример значения
    Пользователь для подключения к службе LDAP keys_ldap_user
    Пароль пользователя для подключения к службе LDAP KEYS_LDAP_PaSSw0rd_8901
    Основное уникальное имя (base relative distinguished name), относительно которого выполняется поиск в каталоге LDAP dc=2gis
    Фильтр LDAP, используемый для идентификации записей в поисковых запросах (&(objectClass=user)(sAMAccountName=%s))

  2. Добавьте в LDAP пользователя admin, которому будет назначена роль администратора в сервисе API-ключей.

3. Установите сервис API-ключей

  1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

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

    values-keys.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

dgctlStorage:
    host: artifacts.storage.example.local:443
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json
    secure: false
    region: ''
    verifySsl: true

postgres:
    ro:
        host: keys-postgresql.storage.example.local
        port: 5432
        name: onpremise_keys
        username: keys_user_ro
        password: KEYS_Db_RO_User_Password_5678
    rw:
        host: keys-postgresql.storage.example.local
        port: 5432
        name: onpremise_keys
        username: keys_superuser_rw
        password: KEYS_Db_Owner_Password_1234

ldap:
    host: ldap.keys.example.com
    port: 3268

    useStartTLS: false
    useLDAPS: false
    skipServerCertificateVerify: false
    serverName: ldap.keys.example.com
    clientCertificatePath: /home/user/certificates/cert.crt
    clientKeyPath: /home/user/certificates/cert.key
    rootCertificateAuthoritiesPath: /home/user/certificates/root.cer

    bind:
        dn: keys_ldap_user
        password: KEYS_LDAP_PaSSw0rd_8901

    search:
        baseDN: dc=2gis
        filter: (&(objectClass=user)(sAMAccountName=%s))

tasker:
    resources:
        requests:
            cpu: 10m
            memory: 32Mi
        limits:
            cpu: 100m
            memory: 64Mi

    delay: 30s

admin:
    host: https://keys.example.com

    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: keys.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - keys.example.com
        #  secretName: secret.tls

api:
    adminUsers: 'admin:8k7RVCP8m3AABDzD'

customCAs:
    bundle: ''
    # bundle: |
    #   -----BEGIN CERTIFICATE-----
    #   ...
    #   -----END CERTIFICATE-----
    certsPath: ''

    Где:

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

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

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

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

      Сервис API-ключей работает с данными в двух режимах: только чтение (ro) и чтение-запись (rw). В обоих режимах сервис работает с одной базой, но от имени пользователей с разными правами (см. подробности в шаге 1).

      Задайте:

      • Настройки, общие для обоих режимов:

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

      • Реквизиты для доступа к базе пользователя с правами только на чтение (секция ro).

      • Реквизиты для доступа к базе пользователя с правами на чтение и запись (секция rw).

      Для хранения настроек password в группах ro и rw Helm-чарт использует Kubernetes Secrets.

    • ldap: настройки доступа к серверу LDAP.

      • host: имя хоста или IP-адрес сервера.

      • port: порт, на котором слушает сервер.

      • Группа настроек для обеспечения защищенного соединения с сервером LDAP:

        • useStartTLS: использовать StartTLS.
        • useLDAPS: использовать Secure LDAP.
        • skipServerCertificateVerify: не проверять сертификат сервера.
        • serverName: строка с именем сервера. Используется при проверке сертификата сервера.
        • clientCertificatePath: путь к сертификату клиента.
        • clientKeyPath: путь к ключу клиента.
        • rootCertificateAuthoritiesPath: путь к файлу с корневыми сертификатами от центров сертификации (root certificate authorities).

      • bind: реквизиты для доступа к серверу LDAP:

        • dn: уникальное имя пользователя (distinguished name).
        • password: пароль пользователя.

      • search: настройки поиска LDAP:

        • baseDN: основное относительное уникальное имя (base relative distinguished name).
        • filter: фильтр LDAP, используемый для идентификации записей в поисковых запросах.

    • tasker: настройки сервиса Tasker, который выполняет административные задачи, связанные с API-ключами.

      • resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
      • delay: период (в секундах). Эта настройка определяет, с каким периодом проверять задачи, которые связаны с настроенными отложенными действиями (например, блокировкой API-ключа).

    • admin: настройки веб-сервиса администратора (предоставляет доступ к веб-интерфейсу для администрирования сервиса).

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

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

    • api.adminUsers: список реквизитов пользователей с административными правами в формате username1:password1,username2:password2,....

      Для хранения этой настройки Helm-чарт использует Kubernetes Secrets.

      Примечание:

      Если у вас есть сервер LDAP, то рекомендуется использовать его для аутентификации, а настройку api.adminUsers пропустить.

    • customCAs: настройки пользовательских сертификатов.

      • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
      • certsPath: директория для монтирования сертификата внутри контейнера.

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

    helm upgrade --install --version=1.22.0 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys

  3. Добавьте пользователей в сервис с помощью утилиты keysctl. Этим пользователям будет назначена роль администратора сервиса API-ключей.

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

    При использовании LDAP достаточно добавить одного пользователя. При использовании списка реквизитов (настройка api.adminUsers) необходимо добавить всех пользователей из этого списка.

    Чтобы добавить одного пользователя, выполните эту команду из любого пода keys-api:

    keysctl users add admin 'Keys Service Admin'

4. Получите сервисные токены

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

Выполните следующую команду из любого пода keys-api, чтобы получить список доступных сервисных ключей.

keysctl services

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

Чтобы проверить работоспособность сервиса API-ключей:

  1. Откройте в браузере веб-интерфейс для администрирования сервиса (используйте значение настройки admin.host из конфигурационного файла values-keys.yaml):

    https://keys.example.com/

  2. Войдите в веб-интерфейс, используя учетные данные пользователя с правами администратора (это пользователь, которому была назначена роль администратора с помощью утилиты keysctl). Вы должны увидеть веб-интерфейс для управления API-ключами.

Что дальше?