Перейти к основному содержимому

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

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

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

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

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

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

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

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

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

    ОбъектЗначениеКак получить значение
    Endpoint зеркала реестра Docker в приватной сетиdocker.storage.example.local:5000См. Получение артефактов установки
    Секрет Kubernetes для доступа к endpoint зеркала реестра Dockeronpremise-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-admin.example.com
    • API backend: keys-api.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.

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

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

Настройте Redis​

  1. Разместите Redis в приватной сети.

  2. Создайте пользователя и установите пароль для него.

    Пример:

    • Имя пользователя: redisuser
    • Пароль: Redis_Password_6379

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

    redis:
        host: redis.cache.example.local
        port: 6379
        db: 1
        password: Redis_Password_6379

    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-admin.example.com

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

    api:
        adminUsers: 'admin:8k7RVCP8m3AABDzD'

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

    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.

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

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

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

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

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

        • host: имя хоста или IP-адрес сервера. Вы можете добавить несколько хостов или 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: настройки API сервиса.

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

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

        Примечание:

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

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

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

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

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

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

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

    Чтобы добавить одного пользователя, выполните эту команду из любого пода 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-admin.example.com

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

Что дальше?​