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

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

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

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

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

По возможности познакомьтесь с:
- Документацией сервиса API-ключей
- Архитектурой программного комплекса 2ГИС
- Системными требованиями к программному обеспечению и вычислительным ресурсам.
Убедитесь, что выполнены подготовительные шаги.

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

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

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

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

Примечание

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

Пример:
- Веб-интерфейс администратора: keys-admin.example.com
- API backend: keys-api.example.com

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

Настройте PostgreSQL

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

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

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

Создайте двух пользователей базы данных и установите пароли для них:

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

Создайте базу данных, принадлежащую одному из пользователей:
```
create database onpremise_keys owner keys_superuser_rw;
```

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

\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.

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

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

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

Настройте Apache Kafka

Разместите кластер Apache Kafka с доменным именем keys-kafka.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 9092.
Создайте пользователя, который будет использоваться для сервиса:

Пример:

username: kafka
password: kafka_password

Запомните реквизиты для этого пользователя.

Настройте Redis

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

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

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

Создайте конфигурационный файл для 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/core/1640661259.json secure: false region: '' verifySsl: true redis: enabled: false 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 kafka: bootstrapServers: 'keys-kafka.storage.example.local:9092' username: kafka password: kafka_password securityProtocol: SASL_PLAINTEXT saslMechanism: SCRAM-SHA-512 stats: topic: 'stat_master_type.401' groupId: 'keys-counter' clientId: 'keys-counter' counter: enabled: true preloader: refreshTick: 10s 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/core/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - region: регион S3-хранилища.
  - verifySsl: включить ли проверку SSL-сертификатов при подключении к dgctlStorage.host по HTTP. Значение по умолчанию: true.
- redis: настройки доступа к серверу Redis.
  - enabled: включить ли использование Redis. Значение по умолчанию: false.
  - 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.
- kafka: настройки доступа к Apache Kafka.
  - bootstrapServers: адреса и порты брокеров Apache Kafka через запятую. Пример: HOST1:PORT1,HOST2:PORT2.
  - username: имя пользователя для аутентификации через SASL.
  - password: пароль пользователя для аутентификации через SASL.
  - securityProtocol: протокол безопасности для подключения.
  - saslMechanism: механизм SASL-аутентификации.
  - stats: настройки для сбора статистики использования API-ключей.
    - topic: имя топика Kafka, из которого сервис API-ключей будет считывать данные о статистике использования ключей.
    - groupId: идентификатор группы потребителей Kafka.
    - clientId: идентификатор клиента Kafka.
- counter: настройки сервиса подсчёта использования API-ключей.
  - enabled: включить ли сервис. Значение по умолчанию: false.
  - preloader.refreshTick: период (в секундах), с которым сервис будет обновлять кеш с информацией о лимитах.
- 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: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-keys.yaml:
```
helm upgrade --install --version=VERSION --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
```
В параметре --version укажите нужную версию базовых сервисов. Список версий см. в разделе Релизы базовых сервисов.
Добавьте пользователей в сервис с помощью утилиты keysctl. Этим пользователям будет назначена роль администратора сервиса API-ключей.

Чтобы добавить одного пользователя, выполните эту команду из любого пода keys-api:
```
keysctl users add admin 'Keys Service Admin'
```

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

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

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

keysctl services

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

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

Откройте в браузере веб-интерфейс для администрирования сервиса (используйте значение настройки admin.host из конфигурационного файла values-keys.yaml):
```
https://keys-admin.example.com
```
Войдите в веб-интерфейс, используя учетные данные пользователя с правами администратора (это пользователь, которому была назначена роль администратора с помощью утилиты keysctl). Вы должны увидеть веб-интерфейс для управления API-ключами.

Что дальше?

Узнайте, как обновить сервис API-ключей.
Установите продукты программного комплекса 2ГИС:
Изучите рекомендации по обслуживанию системы.

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

2. Подготовьте инфраструктуру​

Настройте PostgreSQL​

Настройте LDAP​

Настройте Apache Kafka​

Настройте Redis​

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

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

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

Что дальше?​