Справочник по операциям и конфигурации Edge Microgateway

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. info

Edge Microgateway версии 2.5.x

В этой статье рассказывается, как настраивать Edge Microgateway и управлять им.

Как обновить Edge Microgateway, если у вас есть подключение к интернету

1. Чтобы перейти на последнюю версию Edge Microgateway, выполните следующую команду npm:

   npm upgrade edgemicro -g

   Чтобы перейти на определенную версию Edge Microgateway, укажите номер версии в команде обновления. Если вы не укажете номер версии, будет установлена последняя версия. Например, чтобы выполнить обновление до версии 2.5.26, используйте следующую команду:

   npm upgrade edgemicro@2.5.26 -g

2. Проверьте номер версии. Например, если вы установили версию 2.5.26:

   edgemicro --version
   current nodejs version is v8.9.0
   current edgemicro version is 2.5.26
       

3. Наконец, обновите прокси-сервер edgemicro-auth до последней версии:

   edgemicro upgradeauth -o org_name -e env_name -u username

Изменение конфигурации

Вам нужно знать о следующих файлах конфигурации:

• Файл конфигурации системы по умолчанию
• Файл конфигурации по умолчанию для нового экземпляра Edge Microgateway
• Файл динамической конфигурации для запущенных экземпляров

В этом разделе рассказывается об этих файлах и о том, что нужно знать об их изменении.

Файл конфигурации системы по умолчанию

При установке Edge Microgateway файл конфигурации системы по умолчанию размещается в следующем каталоге:

prefix/lib/node_modules/edgemicro/config/default.yaml

где prefix – каталог префикса npm. Если вы не можете найти этот каталог, прочитайте статью Где установлен Edge Microgateway.

Если вы измените файл конфигурации системы, вам нужно будет повторно инициализировать, настроить и перезапустить Edge Microgateway:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

Файл конфигурации по умолчанию для новых экземпляров Edge Microgateway

При запуске edgemicro init файл конфигурации системы (описанный выше) default.yaml помещается в каталог ~/.edgemicro.

Если вы измените файл конфигурации в ~/.edgemicro, вам нужно будет заново настроить и перезапустить Edge Microgateway:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

Файл динамической конфигурации для запущенных экземпляров

При запуске edgemicro configure [params] в ~/.edgemicro создается динамический файл конфигурации. Название файла соответствует следующему шаблону: org-env-config.yaml, где org и env – названия организации и среды Apigee Edge. Вы можете использовать этот файл, чтобы вносить изменения в конфигурацию, а затем перезагружать их без простоев. Например, если вы добавите и настроите плагин, то сможете перезагрузить конфигурацию без простоев, как описано ниже.

Если Edge Microgateway работает (вариант без простоя):

1. Перезагрузите конфигурацию Edge Microgateway:

   edgemicro reload -o org_name -e env_name -k key -s secret

   Где:

   • org_name – название вашей организации Edge (вы должны быть ее администратором).
   • env_name – это среда в вашей организации (например, test или prod).
   • key – ключ, возвращенный ранее командой configure.
   • secret – ключ, возвращенный ранее командой configure.

   Примеры:

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
     -s 05c14356e42ed1...4e34ab0cc824

Если Edge Microgateway остановлен:

1. Перезапустите Edge Microgateway:

   edgemicro start -o org_name -e env_name -k key -s secret

   Где:

   • org_name – название вашей организации Edge (вы должны быть ее администратором).
   • env_name – среда в вашей организации (например, test или prod).
   • key – ключ, возвращенный ранее командой configure.
   • secret – ключ, возвращенный ранее командой configure.

   Пример:

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

Ниже приведен пример файла конфигурации. Подробные сведения о настройках файла конфигурации приведены в справочнике по конфигурации Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Настройка переменных среды

Команды интерфейса командной строки, для которых требуются значения организации и среды Edge, а также ключ и секретный код, необходимые для запуска Edge Microgateway, можно хранить в следующих переменных среды:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

Задавать эти переменные необязательно. Если вы зададите их, вам не нужно будет указывать их значения при использовании интерфейса командной строки (CLI) для настройки и запуска Edge Microgateway.

Настройка SSL на сервере Edge Microgateway

Вы можете настроить сервер Microgateway для использования SSL. Например, если настроен протокол SSL, вы можете вызывать API через Edge Microgateway по протоколу HTTPS, например:

https://localhost:8000/myapi

Чтобы настроить SSL на сервере Microgateway, выполните следующие действия:

1. Сгенерируйте или получите SSL-сертификат и ключ с помощью утилиты openssl или другого удобного вам метода.
2. Добавьте атрибут edgemicro:ssl в файл конфигурации Edge Microgateway. Полный список вариантов приведен в таблице ниже. Примеры:
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. Перезапустите Edge Microgateway. Выполните инструкции из раздела Изменение конфигурации в зависимости от того, какой файл конфигурации вы редактировали: файл по умолчанию или файл конфигурации среды выполнения.

Ниже приведен пример раздела edgemicro файла конфигурации с настроенным SSL:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Ниже приведен список всех поддерживаемых серверов.

Использование параметров SSL/TLS клиента

Вы можете настроить Edge Microgateway в качестве клиента TLS или SSL при подключении к целевым конечным точкам. В файле конфигурации Microgateway используйте элемент targets, чтобы задать параметры SSL/TLS.

В этом примере приведены настройки, которые будут применены ко всем хостам:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

В этом примере настройки применяются только к указанному хосту:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Пример для TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Ниже приведен список всех поддерживаемых клиентских параметров.

Настройка прокси-сервера edgemicro-auth

По умолчанию Edge Microgateway использует прокси-сервер, развернутый на Apigee Edge, для аутентификации OAuth2. Этот прокси-сервер развертывается при первом запуске edgemicro configure. Вы можете изменить конфигурацию этого прокси-сервера по умолчанию, чтобы добавить поддержку пользовательских утверждений в веб-токен JSON (JWT), настроить срок действия токена и создать токены обновления. Подробную информацию можно найти на странице edgemicro-auth в GitHub.

Использование собственного сервиса аутентификации

По умолчанию Edge Microgateway использует прокси-сервер, развернутый на Apigee Edge, для аутентификации OAuth2. Этот прокси-сервер развертывается при первом запуске edgemicro configure. По умолчанию URL этого прокси-сервера указывается в файле конфигурации Edge Microgateway следующим образом:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Если вы хотите использовать собственный сервис для обработки аутентификации, измените значение authUri в файле конфигурации, чтобы оно указывало на ваш сервис. Например, у вас может быть сервис, который использует LDAP для подтверждения личности.

Управление файлами журналов

Edge Microgateway регистрирует в журнале информацию о каждом запросе и ответе. Файлы журналов содержат полезную информацию для отладки и устранения неполадок.

Где хранятся файлы журналов

По умолчанию файлы журналов хранятся в папке /var/tmp.

Как изменить каталог файлов журнала по умолчанию

Каталог, в котором хранятся файлы журналов, указан в файле конфигурации Edge Microgateway. Подробнее об изменении конфигурации…

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Чтобы указать другой каталог для файлов журналов, измените значение dir.

Отправка журналов в консоль

Вы можете настроить ведение журнала так, чтобы информация отправлялась в стандартный вывод, а не в файл журнала. Установите для флага to_console значение true, как показано ниже.

edgemicro:
  logging:
    to_console: true

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

Как задать уровень детализации журналов

Вы можете задать следующие уровни ведения журнала: info, warn и error. Рекомендуется уровень info. Он регистрирует все запросы к API и ответы и используется по умолчанию.

Как изменить интервалы записи

Эти интервалы можно настроить в файле конфигурации Edge Microgateway. Подробнее об изменении конфигурации…

Доступны следующие атрибуты:

• stats_log_interval – интервал в секундах, с которым запись статистики добавляется в файл журнала API (по умолчанию – 60).
• rotate_interval – интервал в часах, через который выполняется ротация файлов журнала (по умолчанию 24). Пример:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Рекомендации по работе с файлами журналов

Поскольку данные файлов журналов со временем накапливаются, Apigee рекомендует применять следующие методы:

• Файлы журналов могут быть очень большими, поэтому убедитесь, что в каталоге достаточно места. Ознакомьтесь с разделами Где хранятся файлы журналов и Как изменить каталог по умолчанию для файлов журналов.
• Удаляйте файлы журналов или перемещайте их в отдельный архивный каталог не реже одного раза в неделю.
• Если в вашей организации принято удалять журналы, вы можете использовать команду CLI edgemicro log -c, чтобы удалить старые журналы.

Правила именования файлов журналов

Каждый экземпляр Edge Microgateway создает три типа файлов журнала:

• api – регистрирует все запросы и ответы, проходящие через Edge Microgateway. В этот файл также записываются счетчики API (статистика) и ошибки.
• err – регистрирует все, что отправлено в stderr.
• out – регистрирует все, что отправлено в stdout.

Вот как они называются:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

Пример:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

Содержимое файла журнала

Добавлено в версии 2.3.3

По умолчанию сервис ведения журналов пропускает JSON скачанных прокси-серверов, продуктов и веб-токенов JSON (JWT). Если вы хотите выводить эти объекты в файлы журналов, задайте DEBUG=* при запуске Edge Microgateway. Пример:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Содержимое файла журнала api

Файл журнала api содержит подробную информацию о потоке запросов и ответов через Edge Microgateway. Файлы журнала API имеют следующие названия:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Для каждого запроса, отправленного в Edge Microgateway, в файле журнала api регистрируются четыре события:

• Входящий запрос от клиента
• Исходящий запрос к целевому объекту
• Входящий ответ от цели
• Исходящий ответ клиенту

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

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Рассмотрим их по очереди.

1. Пример входящего запроса от клиента:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651 – временная метка Unix.
• info – зависит от контекста. Может быть info, warn или error в зависимости от уровня журнала. Возможные значения: stats (статистика), warn (предупреждения) или error (ошибки).
• req – идентифицирует событие. В данном случае – запрос от клиента.
• m – HTTP-глагол, используемый в запросе.
• u – часть URL, следующая за базовым путем.
• h – хост и номер порта, которые прослушивает Edge Microgateway.
• r – удаленный хост и порт, с которого поступил запрос клиента.
• i – идентификатор запроса. Этот идентификатор будет у всех четырех записей. Каждому запросу присваивается уникальный идентификатор. Сопоставление записей журнала по идентификатору запроса может дать ценную информацию о задержке цели.
• d – продолжительность в миллисекундах с момента получения запроса Edge Microgateway. В примере выше ответ на запрос 0 был получен через 7 миллисекунд (строка 3) и отправлен клиенту ещё через 4 миллисекунды (строка 4). Другими словами, общая задержка запроса составила 11 миллисекунд, из которых 7 миллисекунд было занято целью и 4 миллисекунды самим Edge Microgateway.

2. Пример исходящего запроса к целевому объекту:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651 – временная метка Unix.
• info – зависит от контекста. Может быть info, warn или error в зависимости от уровня журнала. Возможные значения: stats (статистика), warn (предупреждения) или error (ошибки).
• treq – идентификатор события. В данном случае это целевой запрос.
• m – HTTP-глагол, используемый в целевом запросе.
• u – часть URL, следующая за базовым путем.
• h – хост и номер порта целевого сервера.
• i – идентификатор записи в журнале. Этот идентификатор будет одинаковым для всех четырех записей.

3. Пример входящего ответа от целевого объекта

1436403888672 info tres s=200, d=7, i=0

1436403888651 – временная метка Unix.

• info – зависит от контекста. Может быть info, warn или error в зависимости от уровня журнала. Возможные значения: stats (статистика), warn (предупреждения) или error (ошибки).
• tres – идентифицирует событие. В данном случае это целевой ответ.
• s – статус HTTP-ответа.
• d – продолжительность в миллисекундах. Время, которое потребовалось целевому объекту для вызова API.
• i – идентификатор записи в журнале. Этот идентификатор будет одинаковым для всех четырех записей.

4. Пример исходящего ответа клиенту

1436403888676 info res s=200, d=11, i=0

1436403888651 – временная метка Unix.

• info – зависит от контекста. Может быть info, warn или error в зависимости от уровня журнала. Возможные значения: stats (статистика), warn (предупреждения) или error (ошибки).
• res – идентифицирует событие. В этом случае ответ клиенту
• s – статус HTTP-ответа.
• d – продолжительность в миллисекундах. Это общее время, затраченное на вызов API, включая время, затраченное целевым API и самим Edge Microgateway.
• i – идентификатор записи в журнале. Этот идентификатор будет одинаковым для всех четырех записей.

Расписание для файла журнала

Файлы журналов ротируются с интервалом, указанным в атрибуте конфигурации rotate_interval. Записи будут добавляться в один и тот же файл журнала до истечения интервала ротации. Однако при каждом перезапуске Edge Microgateway получает новый UID и создает новый набор файлов журнала с этим UID. Рекомендуем также ознакомиться с советами по работе с файлами журналов.

Сообщения об ошибках

Некоторые записи в журнале будут содержать сообщения об ошибках. Чтобы определить, где и почему возникают ошибки, ознакомьтесь со статьей Сообщения об ошибках Edge Microgateway.

Справочник по конфигурации Edge Microgateway

Расположение файла конфигурации

Атрибуты конфигурации, описанные в этом разделе, находятся в файле конфигурации Edge Microgateway. Подробнее об изменении конфигурации…

Атрибуты edge_config

Эти настройки используются для настройки взаимодействия между экземпляром Edge Microgateway и Apigee Edge.

• bootstrap (по умолчанию: none) – URL, указывающий на сервис Edge Microgateway, который работает на Apigee Edge. Edge Microgateway использует этот сервис для связи с Apigee Edge. Этот URL возвращается при выполнении команды для создания пары открытого и закрытого ключей: edgemicro genkeys. Подробную информацию вы найдете в статье Как настроить Edge Microgateway.
• jwt_public_key (по умолчанию: нет) – URL, указывающий на прокси-сервер Edge Microgateway, развернутый в Apigee Edge. Этот прокси-сервер служит конечной точкой аутентификации для выдачи клиентам подписанных токенов доступа. Этот URL возвращается при выполнении команды для развертывания прокси-сервера: edgemicro configure. Подробную информацию вы найдете в статье Как настроить Edge Microgateway.

атрибуты edgemicro

Эти настройки задают параметры процесса Edge Microgateway.

• port – номер порта, который прослушивает процесс Edge Microgateway (по умолчанию 8000).
• max_connections (по умолчанию -1) – максимальное количество одновременных входящих подключений, которые может принимать Edge Microgateway. Если это число превышено, возвращается следующий статус:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard (по умолчанию – -1) – максимальное количество одновременных запросов, которое может получить Edge Microgateway, прежде чем закрыть подключение. Этот параметр предназначен для предотвращения DoS-атак. Обычно это значение должно быть больше, чем max_connections.
• logging:
  • level (по умолчанию: error)
    • info – регистрирует все запросы и ответы, проходящие через экземпляр Edge Microgateway.
    • warn – регистрируются только предупреждения.
    • error – регистрируются только сообщения об ошибках.
  • dir – каталог, в котором хранятся файлы журналов (по умолчанию /var/tmp).
  • stats_log_interval – интервал в секундах, с которым запись статистики добавляется в файл журнала API (по умолчанию 60).
  • rotate_interval – интервал в часах, через который выполняется ротация файлов журналов (по умолчанию 24).

• plugins – плагины, добавляющие функциональность в Edge Microgateway. Подробнее о разработке собственных плагинов…

• dir – относительный путь от каталога ./gateway до каталога ./plugins или абсолютный путь.
• sequence – список модулей плагинов, которые нужно добавить в экземпляр Edge Microgateway. Модули будут выполняться в указанном здесь порядке.

• debug: добавляет удаленную отладку в процесс Edge Microgateway.
  • port – номер порта, который нужно прослушивать. Например, настройте отладчик IDE на прослушивание этого порта.
  • args – аргументы для процесса отладки. Пример: args --nolazy
    
• config_change_poll_interval: (по умолчанию 600 секунд) Edge Microgateway периодически загружает новую конфигурацию и перезагружает ее, если что-то изменилось. При опросе регистрируются все изменения, внесенные в Edge (изменения в продуктах, прокси-серверах, поддерживающих микрошлюзы, и т. д.), а также изменения, внесенные в локальный файл конфигурации.
  
• disable_config_poll_interval: (по умолчанию: false). Установите значение true, чтобы отключить автоматический опрос изменений.
• request_timeout – устанавливает время ожидания для целевых запросов. Время ожидания указывается в секундах. Если время ожидания истекает, Edge Microgateway возвращает код статуса 504. Добавлено в версии 2.4.x.

атрибуты заголовков

Эти настройки определяют, как обрабатываются определенные HTTP-заголовки.

• x-forwarded-for (по умолчанию true). Установите значение false, чтобы заголовки x-forwarded-for не передавались целевому объекту. Обратите внимание, что если в запросе есть заголовок x-forwarded-for, то в Edge Analytics его значение будет установлено равным значению client-ip.
• x-forwarded-host (по умолчанию true). Установите значение false, чтобы заголовки x-forwarded-host не передавались целевому объекту.
• x-request-id (по умолчанию true). Установите значение false, чтобы запретить передачу заголовков x-request-id в целевой объект.
• x-response-time (по умолчанию: true). Установите значение false, чтобы запретить передачу заголовков x-response-time целевому объекту.
• via (по умолчанию: true). Установите значение false, чтобы заголовки via не передавались целевому серверу.

атрибуты oauth

Эти настройки определяют, как Edge Microgateway обеспечивает аутентификацию клиентов.

• allowNoAuthorization (по умолчанию false). Если задано значение true, вызовы API могут проходить через Edge Microgateway без заголовка Authorization. Если задать значение false, заголовок Authorization будет обязательным (по умолчанию).
• allowInvalidAuthorization (по умолчанию false). Если задано значение true, вызовы API разрешены, даже если токен, переданный в заголовке авторизации, недействителен или срок его действия истек. Если задать значение false, будут требоваться действительные токены (по умолчанию).
• authorization-header (по умолчанию Authorization: Bearer) – заголовок, используемый для отправки токена доступа в Edge Microgateway. Вы можете изменить значение по умолчанию, если целевому объекту необходимо использовать заголовок Authorization для других целей.
• api-key-header (по умолчанию x-api-key) – название заголовка или параметра запроса, используемого для передачи ключа API в Edge Microgateway. Подробнее об использовании ключей API…
• keep-authorization-header (по умолчанию false). Если задано значение true, заголовок Authorization, отправленный в запросе, передается целевому объекту (сохраняется).
• allowOAuthOnly – если задано значение true, каждый API должен содержать заголовок авторизации с токеном доступа Bearer. Позволяет разрешить только модель безопасности OAuth (с сохранением обратной совместимости). (Добавлено в версии 2.4.x)
• allowAPIKeyOnly – если задано значение true, каждый API должен содержать заголовок x-api-key (или пользовательское местоположение) с ключом API.Позволяет разрешить только модель безопасности ключа API (с сохранением обратной совместимости). (Добавлено в версии 2.4.x)
• gracePeriod – этот параметр помогает предотвратить ошибки, вызванные небольшими расхождениями между системными часами и временем Not Before (nbf) или Issued At (iat), указанным в токене авторизации JWT. Укажите в этом параметре количество секунд, которое будет допускаться для таких расхождений. (Добавлено в версии 2.5.7)

Атрибуты, относящиеся к плагину

Подробные сведения о настраиваемых атрибутах для каждого плагина приведены в разделе "Использование плагинов".

Фильтрующие прокси-серверы

Вы можете отфильтровать прокси-серверы, поддерживающие микрошлюз, которые будут обрабатываться экземпляром Edge Microgateway. При запуске Edge Microgateway скачивает все прокси-серверы, поддерживающие микрошлюз, в организации, с которой он связан. Чтобы ограничить список прокси-серверов, которые будет обрабатывать микрошлюз, используйте следующую конфигурацию: Например, в этой конфигурации количество прокси-серверов, которые будет обрабатывать микрошлюз, ограничено тремя: edgemicro_proxy-1, edgemicro_proxy-2 и edgemicro_proxy-3.

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Как настроить частоту отправки данных в Аналитику

Используйте эти параметры конфигурации, чтобы контролировать частоту, с которой Edge Microgateway отправляет аналитические данные в Apigee:

• bufferSize (необязательно) – максимальное количество записей аналитики, которое может храниться в буфере до того, как самые старые записи начнут удаляться. Значение по умолчанию: 10 000.
• batchSize (необязательно) – максимальный размер пакета записей аналитики, отправляемых в Apigee. Значение по умолчанию: 500.
• flushInterval (необязательно). Количество миллисекунд между отправками пакетов записей аналитики в Apigee. Значение по умолчанию: 5000.

Пример:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Маскирование данных аналитики

Следующая конфигурация предотвращает появление информации о пути запроса в аналитике Edge. Чтобы замаскировать URI запроса и/или путь запроса, добавьте в конфигурацию микрошлюза следующее: Обратите внимание, что URI состоит из имени хоста и пути запроса.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Разделение вызовов API в Edge Analytics

Вы можете настроить плагин аналитики так, чтобы он выделял определенный путь API и показывал его как отдельный прокси-сервер на панелях управления Edge Analytics. Например, вы можете отделить API проверки работоспособности на панели управления, чтобы не путать его с фактическими вызовами прокси-сервера API. На панели управления Аналитики изолированные прокси-серверы имеют следующие названия:

edgemicro_proxyname-health

На изображении ниже показаны два прокси-сервера, разделенные на панели статистики: edgemicro_hello-health и edgemicro_mock-health.

Эти параметры позволяют разделять относительные и абсолютные пути в панели управления Аналитики как отдельные прокси-серверы:

• relativePath (необязательно). Указывает относительный путь для разделения в панели управления Аналитики. Например, если вы укажете /healthcheck, все вызовы API, содержащие путь /healthcheck, будут отображаться на панели управления как edgemicro_proxyname-health. Обратите внимание, что этот флаг игнорирует базовый путь прокси. Чтобы разделить данные на основе полного пути, включая базовый, используйте флаг proxyPath.
• proxyPath (необязательно) – полный путь к прокси-серверу API, включая базовый путь, для разделения на панели аналитики. Например, если вы укажете /mocktarget/healthcheck, где /mocktarget – базовый путь прокси-сервера, все вызовы API с путем /mocktarget/healthcheck будут отображаться на панели управления как edgemicro_proxyname-health.

Например, в следующей конфигурации любой путь API, содержащий /healthcheck, будет разделен плагином аналитики. Это означает, что /foo/healthcheck и /foo/bar/healthcheck будут выделены в отдельный прокси-сервер под названием edgemicro_proxyname-health на панели аналитики.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

В следующей конфигурации любой API с путем прокси /mocktarget/healthcheck будет выделен как отдельный прокси с названием edgemicro_proxyname-health на панели аналитики.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Настройка Edge Microgateway за корпоративным брандмауэром

Поддерживается v2.4.x

Если Edge Microgateway установлен за брандмауэром, шлюз может не иметь возможности взаимодействовать с Apigee Edge. В этом случае у вас есть два варианта:

Вариант 1

Первый вариант – установить для параметра edgemicro: proxy_tunnel значение true в файле конфигурации microgateway:

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

Если для параметра proxy_tunnel задано значение true, Edge Microgateway использует метод HTTP CONNECT для туннелирования HTTP-запросов через одно TCP-подключение. (То же самое относится к переменным среды для настройки прокси-сервера с поддержкой TLS).

Вариант 2

Второй вариант – указать прокси-сервер и задать для параметра proxy_tunnel значение false в файле конфигурации микрошлюза. Пример:

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

В этом случае вы можете задать следующие переменные, чтобы управлять хостами для каждого HTTP-прокси, который вы хотите использовать, или указать, какие хосты не должны обрабатывать прокси Edge Microgateway: HTTP_PROXY, HTTPS_PROXY и NO_PROXY.

Вы можете задать NO_PROXY как список доменов, разделенных запятыми, для которых Edge Microgateway не должен использовать прокси. Пример:

export NO_PROXY='localhost,localhost:8080'

Установите для HTTP_PROXY и HTTPS_PROXY конечную точку HTTP-прокси, чтобы Edge Microgateway мог отправлять на нее сообщения. Пример:

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

Подробную информацию об этих переменных можно найти на странице https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.

Статьи по теме

Как настроить Edge Microgateway за корпоративным брандмауэром (на английском языке) в сообществе Apigee.

Использование подстановочных знаков в прокси-серверах, поддерживающих Microgateway

В базовом пути прокси-сервера edgemicro_* (с поддержкой Microgateway) можно использовать один или несколько подстановочных знаков (*). Например, базовый путь /team/*/members позволяет клиентам вызывать https://[host]/team/blue/members и https://[host]/team/green/members без необходимости создавать новые прокси-серверы API для поддержки новых команд. Обратите внимание, что /**/ не поддерживается.

Важно! Apigee не поддерживает использование подстановочного знака "*" в качестве первого элемента базового пути. Например, не поддерживается такой вариант: /*/ search.

Ротация ключей JWT

Через некоторое время после создания JWT вам может потребоваться изменить пару открытого и закрытого ключей, хранящуюся в зашифрованном KVM Edge. Этот процесс называется ротацией ключей.

Как Edge Microgateway использует JWT

JSON Web Token (JWT) – это стандарт токенов, описанный в документе RFC7519. JWT позволяет подписывать набор утверждений, которые могут быть надежно проверены получателем JWT.

Edge Microgateway использует JWT в качестве токенов на предъявителя для обеспечения безопасности OAuth. При создании токена OAuth для Edge Microgateway вы получаете JWT. Затем вы можете использовать JWT в заголовке авторизации вызовов API. Пример:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Как создать новый JWT

Вы можете создать JWT для Edge Microgateway с помощью команды edgemicro token или API. Пример:

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Эта команда запрашивает у Apigee Edge создание JWT, который затем можно использовать для проверки вызовов API. Параметры -i и -s – это идентификатор потребителя и секретные значения из приложения разработчика в вашей организации Apigee Edge.

Вы также можете сгенерировать JWT с помощью Management API:

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your consumer key",
    "client_secret": "your consumer secret",
    "grant_type": "client_credentials"
  }'

Где:

• org – название организации Edge (вы должны быть ее администратором).
• env – это среда в вашей организации (например, test или prod).
• client_id – идентификатор потребителя в приложении разработчика, которое вы создали ранее.
• client_secret – секретный ключ клиента в созданном ранее приложении разработчика.

Что такое ротация ключей?

Через некоторое время после создания JWT вам может потребоваться изменить пару открытого и закрытого ключей, хранящуюся в зашифрованном KVM Edge. Этот процесс называется ротацией ключей. При ротации ключей создается новая пара из закрытого и открытого ключей, которая сохраняется в KVM microgateway в организации или среде Apigee Edge. Кроме того, старый открытый ключ сохраняется вместе с исходным значением идентификатора ключа.

Для создания JWT Edge использует информацию, хранящуюся в зашифрованном KVM. Хранилище KVM с названием microgateway было создано и заполнено ключами при первоначальной настройке Edge Microgateway. Ключи в KVM используются для подписи и шифрования JWT.

Ключи KVM включают:

• private_key – последний (созданный недавно) закрытый ключ RSA, используемый для подписи токенов JWT.

• public_key – последний (созданный недавно) сертификат, используемый для проверки токенов JWT, подписанных с помощью private_key.

• private_key_kid – идентификатор последнего (созданного недавно) закрытого ключа. Этот идентификатор ключа связан со значением private_key и используется для поддержки ротации ключей.

• public_key1_kid – идентификатор последнего (созданного недавно) открытого ключа. Этот ключ связан со значением public_key1 и используется для поддержки ротации ключей. Это значение совпадает с идентификатором закрытого ключа.

• public_key1 – последний (созданный недавно) открытый ключ.

При ротации ключей существующие значения ключей заменяются в сопоставлении, а новые ключи добавляются для сохранения старых открытых ключей. Пример:

• public_key2_kid – идентификатор старого открытого ключа. Этот ключ связан со значением public_key2 и используется для поддержки ротации ключей.

• public_key2 – старый открытый ключ.

Токены JWT, представленные для проверки, будут проверяться с помощью нового открытого ключа. Если проверка не удастся, будет использоваться старый открытый ключ, пока не истечет срок его действия (через 30 минут). Таким образом вы можете "ротировать" ключи, не прерывая трафик API.

Как выполнить ротацию ключей

В этом разделе объясняется, как выполнить ротацию ключей.

Если вы настроили экземпляр Edge Microgateway до версии 2.5.2

Если вы настроили экземпляр Edge Microgateway до версии 2.5.2, то для обновления KVM и правила аутентификации необходимо выполнить следующие две команды:

upgradekvm -o org -e env -u username

Подробнее об обновлении KVM…

Следующая команда обновляет прокси-сервер edgemicro-oauth, который был развернут в вашей организации Apigee при настройке Edge Microgateway. Этот прокси-сервер предоставляет сервисы, необходимые для создания токенов.

upgradeauth -o org -e env -u username

Подробную информацию об этой команде можно найти в статье Обновление прокси-сервера edgemicro-auth.

Ротация ключей

Добавьте в файл ~/.edgemicro/org-env-config.yaml следующую строку, указав ту же организацию и среду, которые вы настроили для использования микрошлюза:

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

Выполните команду ротации ключей. Подробнее о ротации ключей…

edgemicro rotatekey -o org -e env -u username -k kid_value

Пример:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v6.9.1
current edgemicro version is 2.5.7
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

Параметр -k указывает идентификатор ключа (kid). Этот идентификатор используется для сопоставления с определенным ключом. Edge Microgateway использует это значение, чтобы выбрать ключ из набора во время ротации ключей. Дополнительную информацию можно найти в разделе 4.5 спецификации JSON Web Key.

После ротации ключей Edge возвращает несколько ключей в Edge Microgateway. Обратите внимание, что в примере ниже у каждого ключа есть уникальное значение kid (идентификатор ключа). Затем микрошлюз использует эти ключи для проверки токенов авторизации. Если проверка токена не удалась, микрошлюз проверяет, есть ли в наборе ключей более старый ключ, и пробует его. Формат возвращаемых ключей – JSON Web Key (JWK). Подробнее об этом формате можно узнать в документе RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Фильтрация скачанных прокси-серверов

По умолчанию Edge Microgateway скачивает все прокси-серверы в вашей организации Edge, названия которых начинаются с префикса "edgemicro_". Вы можете изменить это значение по умолчанию, чтобы скачивать прокси-серверы, имена которых соответствуют шаблону.

1. Откройте файл конфигурации Edge Micro: ~/.edgemicro/org-env-config.yaml.
2. Добавьте элемент proxyPattern в раздел edge_config. Например, следующий шаблон скачает прокси-серверы edgemicro_foo, edgemicro_fast и edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Как указать продукты без прокси-серверов API

В Apigee Edge можно создать продукт API, который не содержит прокси-серверов API. Такая конфигурация продукта позволяет ключу API, связанному с этим продуктом, работать с любым прокси-сервером, развернутым в вашей организации. Начиная с версии 2.5.4, Edge Microgateway поддерживает эту конфигурацию продукта.

Отладка и устранение неполадок

Подключение к отладчику

Вы можете запустить Edge Microgateway с отладчиком, например node-inspector. Это полезно для устранения неполадок и отладки пользовательских плагинов.

1. Перезапустите Edge Microgateway в режиме отладки. Для этого добавьте DEBUG=* в начало команды start. Пример:

   DEBUG=* edgemicro start -o  myorg -e test -k
         db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
         6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed

2. Запустите отладчик и настройте его на прослушивание номера порта для процесса отладки.
3. Теперь вы можете пошагово выполнять код Edge Microgateway, устанавливать точки останова, отслеживать выражения и т. д.

Вы можете указать стандартные флаги Node.js, связанные с режимом отладки. Например, --nolazy помогает отлаживать асинхронный код.

Проверка файлов журналов

Если у вас возникли проблемы, обязательно изучите файлы журналов, чтобы получить подробные сведения о выполнении и информацию об ошибках. Подробнее об управлении файлами журналов…

Использование ключа API

Ключи API – это простой механизм аутентификации клиентов, отправляющих запросы к Edge Microgateway. Чтобы получить ключ API, скопируйте значение Consumer Key (также называется Client ID) из продукта Apigee Edge, который включает прокси-сервер аутентификации Edge Microgateway.

Кеширование ключей

Ключи API обмениваются на токены на предъявителя, которые кешируются. Вы можете отключить кеширование, установив заголовок Cache-Control: no-cache для входящих запросов к Edge Microgateway.

Как использовать ключ API

Ключ API можно передать в запросе к API в качестве параметра запроса или в заголовке. По умолчанию заголовок и параметр запроса называются x-api-key.

Пример параметра запроса:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Пример заголовка:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Как настроить название ключа API

По умолчанию x-api-key – это название, которое используется и для заголовка ключа API, и для параметра запроса. Вы можете изменить это значение по умолчанию в файле конфигурации, как описано в разделе Как изменить конфигурацию. Например, чтобы изменить название на apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

В этом примере и параметр запроса, и название заголовка изменены на apiKey. Название x-api-key больше не будет работать ни в одном из случаев. Подробнее об изменении конфигурации…

Пример:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Подробнее о том, как использовать ключи API с запросами прокси, рассказывается в статье Secure Edge Microgateway.

Использование токенов безопасности OAuth2

В этом разделе рассказывается, как получить токены доступа и токены обновления OAuth2. Токены доступа используются для безопасных вызовов API через микрошлюз. Токены обновления используются для получения новых токенов доступа.

Как получить токен доступа

В этом разделе рассказывается, как использовать прокси-сервер edgemicro-auth для получения токена доступа.

Вы также можете получить токен доступа с помощью команды CLI edgemicro token. Подробнее о CLI см. в разделе Управление токенами.

API 1

Подставьте в URL названия организации и среды, а также замените значения идентификатора потребителя и секретного кода клиента, полученные из приложения разработчика в Apigee Edge, на параметры client_id и client_secret в теле запроса.

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Пример кода

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

Как получить токен обновления

Чтобы получить токен обновления, выполните вызов API к конечной точке /token прокси-сервера edgemicro-auth. Вызов API должен выполняться с типом предоставления доступа password. Ниже описано, как это сделать.

1. Получите токен доступа и токен обновления с помощью /token API. Обратите внимание, что тип предоставления доступа – password:

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   API возвращает токен доступа и токен обновления. Ответ выглядит примерно так:

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Теперь вы можете использовать токен обновления, чтобы получить новый токен доступа, вызвав конечную точку /refresh того же API. Пример:

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   API возвращает новый токен доступа. Ответ выглядит примерно так:

   {
       "token": "your-new-access-token"
       }

Постоянный мониторинг

Forever – это инструмент Node.js, который автоматически перезапускает приложение Node.js в случае сбоя или ошибки. В Edge Microgateway есть файл forever.json, который можно настроить, чтобы контролировать, сколько раз и с какими интервалами должен перезапускаться Edge Microgateway. Этот файл настраивает сервис Forever под названием forever-monitor, который управляет Forever программно.

Файл forever.json находится в корневом каталоге установки Edge Microgateway. Подробнее о том, где установлен Edge Microgateway… Подробные сведения о параметрах конфигурации приведены в документации по forever-monitor.

Команда edgemicro forever включает флаги, позволяющие указать местоположение файла forever.json (флаг -f), а также запустить или остановить процесс мониторинга Forever (флаг -a). Пример:

edgemicro forever -f ~/mydir/forever.json -a start

Дополнительную информацию можно найти в разделе Forever monitoring справочника по CLI.

Как указать конечную точку файла конфигурации

Если вы используете несколько экземпляров Edge Microgateway, то можете управлять их конфигурациями из одного места. Для этого укажите конечную точку HTTP, из которой Edge Micro сможет скачать файл конфигурации. Вы можете указать эту конечную точку при запуске Edge Micro с помощью флага -u.

Пример:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

где конечная точка mgconfig возвращает содержимое файла конфигурации. По умолчанию этот файл находится в папке ~/.edgemicro и имеет название org-env-config.yaml.

Отключение буферизации данных TCP-подключения

Вы можете использовать атрибут конфигурации nodelay, чтобы отключить буферизацию данных для TCP-подключений, используемых Edge Microgateway.

По умолчанию TCP-подключения используют алгоритм Нагла для буферизации данных перед их отправкой. Если задать для nodelay значение true, это поведение будет отключено (данные будут отправляться сразу же при каждом вызове socket.write()). Дополнительную информацию можно найти в документации по Node.js.

Чтобы включить nodelay, измените файл конфигурации Edge Micro следующим образом:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Запуск Edge Microgateway в автономном режиме

Вы можете запустить Edge Microgateway, полностью отключив его от любой зависимости Apigee Edge. Этот сценарий, называемый автономным режимом, позволяет запускать и тестировать Edge Microgateway без подключения к Интернету.

В автономном режиме не работают следующие функции, так как для них требуется подключение к Apigee Edge:

• OAuth и ключ API
• Квота
• Аналитика

При этом пользовательские плагины и функция Spike Arrest работают в обычном режиме, поскольку им не требуется подключение к Apigee Edge. Кроме того, новый плагин extauth позволяет авторизовать вызовы API к микрошлюзу с помощью JWT в автономном режиме.

Настройка и запуск шлюза

Чтобы запустить Edge Microgateway в автономном режиме, выполните следующие действия:

1. Убедитесь, что у вас установлена версия Edge Microgateway 2.5.25 или более поздняя. Если нет, выполните следующую команду, чтобы обновить его до последней версии:

   npm install -g edgemicro

   Если вам нужна помощь, ознакомьтесь со статьей Installing Edge Microgateway (Установка Edge Microgateway).

2. Создайте файл конфигурации со следующим названием: $HOME/.edgemicro/org_name-env_name-config.yaml.

   Пример:

   vi $HOME/.edgemicro/foo-bar-config.yaml

3. Вставьте в файл следующий код:

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

4. Экспортируйте следующую переменную среды со значением "1":

   export EDGEMICRO_LOCAL=1

5. Выполните следующую команду start, указав значения для создания экземпляра локального прокси-сервера:

   edgemicro start -o org_name -e environment_name -a local_proxy_name \
     -v local_proxy_version -t target_url -b base_path

   Где:

   • your_org – это название организации, которое вы использовали в названии файла конфигурации.
   • your_environment – это название среды, которое вы использовали в названии файла конфигурации.
   • local_proxy_name – название локального прокси-сервера, который будет создан. Вы можете использовать любое название.
   • local_proxy_version – номер версии прокси-сервера.
   • target_url – URL целевого объекта прокси-сервера. Целевой объект – это сервис, который вызывает прокси-сервер.
   • base_path – базовый путь прокси-сервера. Это значение должно начинаться с символа косой черты. Для корневого базового пути укажите только косую черту, например "/".

   Пример:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Протестируйте конфигурацию.

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Поскольку плагин extauth находится в файле foo-bar-config.yaml, вы получите ошибку missing_authorization. Этот плагин проверяет JWT, который должен присутствовать в заголовке авторизации вызова API. В следующем разделе вы получите JWT, который позволит выполнять вызовы API без ошибок.

Пример получения токена авторизации

В примере ниже показано, как получить JWT из конечной точки Edge Microgateway JWT в Apigee Edge (edgemicro-auth/jwkPublicKeys). Эта конечная точка развертывается при выполнении стандартной настройки и конфигурации Edge Microgateway. Чтобы получить JWT от конечной точки Apigee, сначала необходимо выполнить стандартную настройку Edge Microgateway и подключиться к интернету. Конечная точка Apigee используется здесь только в качестве примера и не является обязательной. При желании вы можете использовать другую конечную точку токена JWT. Если вы это сделаете, вам нужно будет получить JWT с помощью API, предоставленного для этой конечной точки.

Ниже описано, как получить токен с помощью конечной точки edgemicro-auth/jwkPublicKeys.

1. Чтобы развернуть прокси-сервер edgemicro-auth в организации или среде на платформе Apigee Edge, необходимо выполнить стандартную настройку и конфигурацию Edge Microgateway. Если вы уже выполнили этот шаг, повторять его не нужно.
2. Если вы развернули Edge Microgateway в Apigee Cloud, вам необходимо подключиться к интернету, чтобы получить JWT из этой конечной точки.
3. Остановите Edge Microgateway:

   edgemicro stop

4. В созданном ранее файле конфигурации ($HOME/.edgemicro/org-env-config.yaml) укажите для атрибута extauth:publickey_url конечную точку edgemicro-auth/jwkPublicKeys в организации или среде Apigee Edge. Пример:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Перезапустите Edge Microgateway, как вы делали ранее, используя названия организации и среды, которые вы указали в имени файла конфигурации. Пример:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Получите токен JWT из конечной точки авторизации. Поскольку вы используете конечную точку edgemicro-auth/jwkPublicKeys, вы можете использовать следующую команду CLI:

Вы можете создать JWT для Edge Microgateway с помощью команды edgemicro token или API. Пример:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Где:

• your_org – название организации Apigee, для которой вы ранее настроили Edge Microgateway.
• your_env – это среда в организации.
• Параметр i указывает идентификатор клиента из приложения разработчика, в котором есть продукт, включающий прокси-сервер edgemicro-auth.
• Параметр s указывает секретный код клиента из приложения разработчика, в котором есть продукт, включающий прокси-сервер edgemicro-auth.

Эта команда запрашивает у Apigee Edge создание JWT, который затем можно использовать для проверки вызовов API.

Как протестировать автономную конфигурацию

Чтобы протестировать конфигурацию, вызовите API с токеном, добавленным в заголовок Authorization, следующим образом:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Пример:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Примеры результатов:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Используется режим локального прокси-сервера

В режиме локального прокси-сервера Edge Microgateway не требует развертывания прокси-сервера, совместимого с Microgateway, в Apigee Edge. Вместо этого вы настраиваете "локальный прокси-сервер", указывая его имя, базовый путь и целевой URL при запуске микрошлюза. Вызовы API к микрошлюзу затем отправляются на целевой URL локального прокси-сервера. Во всех остальных отношениях режим локального прокси-сервера работает точно так же, как и запуск Edge Microgateway в обычном режиме. Аутентификация работает так же, как и остановка пиков и применение квот, пользовательские плагины и так далее.

Пример использования

Режим локального прокси-сервера полезен, когда вам нужно связать только один прокси-сервер с экземпляром Edge Microgateway. Например, вы можете внедрить Edge Microgateway в Kubernetes в качестве служебного прокси-сервера, где микрошлюз и сервис работают в одном поде, а микрошлюз управляет трафиком к сопутствующему сервису и от него. На рисунке ниже показана архитектура, в которой Edge Microgateway работает как служебный прокси-сервер в кластере Kubernetes. Каждый экземпляр микрошлюза взаимодействует только с одной конечной точкой сопутствующего сервиса:

Преимущество такой архитектуры заключается в том, что Edge Microgateway обеспечивает управление API для отдельных сервисов, развернутых в контейнерной среде, например в кластере Kubernetes.

Настройка режима локального прокси-сервера

Чтобы настроить Edge Microgateway для работы в режиме локального прокси-сервера, выполните следующие действия:

1. Убедитесь, что у вас установлена версия Edge Microgateway 2.5.25 или более поздняя. Если нет, выполните следующую команду, чтобы обновить его до последней версии:

   npm install -g edgemicro

   Если вам нужна помощь, ознакомьтесь со статьей Installing Edge Microgateway (Установка Edge Microgateway).

2. Выполните команду edgemicro init, чтобы настроить локальную среду конфигурации, как при обычной настройке Edge Microgateway. Подробнее о настройке Edge Microgateway…
3. Запустите edgemicro configure, как при обычной настройке Edge Microgateway. Пример:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Эта команда развертывает правило edgemicro-auth в Edge и возвращает ключ и секретный код, которые потребуются для запуска микрошлюза. Если вам нужна помощь, ознакомьтесь со статьей Как настроить Edge Microgateway.

4. В Apigee Edge создайте продукт API со следующими обязательными требованиями к конфигурации (все остальные конфигурации можно настроить по своему усмотрению):
   • Вы должны добавить прокси-сервер edgemicro-auth в продукт. Этот прокси-сервер был развернут автоматически при запуске edgemicro configure.
   • Необходимо указать путь к ресурсу. Apigee рекомендует добавить в продукт следующий путь: /**. Подробнее о том, как настроить поведение пути к ресурсу… Дополнительную информацию можно найти в разделе Создание продуктов API документации по Edge.

5. В Apigee Edge создайте разработчика или используйте существующего. Подробнее о том, как добавлять разработчиков с помощью интерфейса управления Edge…

6. В Apigee Edge создайте приложение для разработчиков. Вы должны добавить в приложение только что созданный продукт API. Подробную информацию можно найти в статье Регистрация приложения в интерфейсе управления Edge.
7. На компьютере, где установлен Edge Microgateway, экспортируйте следующую переменную среды со значением "1".

   export EDGEMICRO_LOCAL_PROXY=1

8. Выполните следующую команду start:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Где:

   • your_org – ваша организация Apigee.
   • your_environment – это среда в вашей организации.
   • your_key – ключ, возвращенный при выполнении команды edgemicro configure.
   • your_secret – секретный ключ, полученный при выполнении команды edgemicro configure.
   • local_proxy_name – название локального прокси-сервера, который будет создан.
   • local_proxy_version – номер версии прокси-сервера.
   • target_url – URL целевого объекта прокси (сервиса, который будет вызывать прокси).
   • base_path – базовый путь прокси-сервера. Это значение должно начинаться с символа косой черты. Для корневого базового пути укажите только косую черту, например "/".

   Пример:

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Тестирование конфигурации

Вы можете протестировать конфигурацию локального прокси-сервера, вызвав конечную точку прокси-сервера. Например, если вы указали базовый путь /echo, то можете вызвать прокси следующим образом:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Этот первоначальный вызов API привел к ошибке, поскольку вы не указали действительный ключ API. Ключ можно найти в приложении Developer, которое вы создали ранее. Откройте приложение в интерфейсе Edge, скопируйте идентификатор клиента и используйте его следующим образом:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Пример:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Примеры результатов:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}