Справочник по эксплуатации и настройке Edge Microgateway

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

Edge Microgateway v. 2.5.x

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

Обновление Edge Microgateway при наличии подключения к интернету.

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

   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 Web Token (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

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

Как установить уровень логирования

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

Как изменить интервалы логирования

Эти интервалы можно настроить в конфигурационном файле Edge Microgateway. См. также раздел «Внесение изменений в конфигурацию» .

К настраиваемым атрибутам относятся:

• stats_log_interval : (по умолчанию: 60) Интервал в секундах, через который запись статистики записывается в файл журнала API.
• 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 - Записывает в лог всё, что отправляется в стандартный поток ошибок.
• out - Выводит в лог все данные, отправляемые в стандартный поток вывода.

Вот существующая система именования:

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

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

Добавлено в: v2.3.3

По умолчанию служба логирования не записывает JSON-данные о загруженных прокси-серверах, продуктах и ​​JSON Web Token (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 : (по умолчанию: none) URL-адрес, указывающий на прокси-сервер Edge Microgateway, развернутый на Apigee Edge. Этот прокси-сервер служит конечной точкой аутентификации для выдачи подписанных токенов доступа клиентам. Этот URL-адрес возвращается при выполнении команды развертывания прокси-сервера: edgemicro configure . См. раздел «Настройка и конфигурирование Edge Microgateway» для получения подробной информации.

атрибуты edgemicro

Эти параметры настраивают процесс Edge Microgateway.

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

• Плагины : Плагины добавляют функциональность в Edge Microgateway. Подробную информацию о разработке плагинов см. в разделе «Разработка пользовательских плагинов» .

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

• debug: Добавляет удаленную отладку в процесс Edge Microgateway.
  • порт : Номер порта, на котором будет осуществляться прослушивание. Например, настройте отладчик вашей IDE на прослушивание этого порта.
  • args : Аргументы для процесса отладки. Например: args --nolazy
    
• config_change_poll_interval: (по умолчанию: 600 секунд) Edge Microgateway периодически загружает новую конфигурацию и выполняет перезагрузку, если что-либо изменилось. Опрос отслеживает любые изменения, внесенные в Edge (изменения в продуктах, прокси-серверы, поддерживающие Microgateway и т. д.), а также изменения, внесенные в локальный файл конфигурации.
  
• 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 присутствует в запросе, его значение будет установлено равным значению client-ip в Edge Analytics.
• 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 разрешаются, если токен, переданный в заголовке Authorization, недействителен или истек. Установите значение 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 должен содержать заголовок Authorization с токеном доступа Bearer. Позволяет разрешить только модель безопасности OAuth (с сохранением обратной совместимости). (Добавлено в версии 2.4.x)
• allowAPIKeyOnly — Если установлено значение true, каждый API должен содержать заголовок x-api-key (или пользовательское местоположение) с ключом API. Позволяет разрешить только модель безопасности с использованием ключа API (с сохранением обратной совместимости). (Добавлено в версии 2.4.x)
• gracePeriod — Этот параметр помогает предотвратить ошибки, вызванные незначительными расхождениями между системными часами и временем «Не раньше» (nbf) или «Выдано в» (iat), указанными в токене авторизации JWT. Установите этот параметр равным количеству секунд, которое следует учитывать при таких расхождениях. (Добавлено в версии 2.5.7)

Атрибуты, специфичные для плагина

Подробную информацию о настраиваемых атрибутах каждого плагина см. в разделе «Использование плагинов».

Фильтрация прокси

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

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

Настройка частоты отправки аналитических уведомлений

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

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

Например:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

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

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

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

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

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

edgemicro_proxyname-health

На следующем изображении показаны два отдельных прокси-сервера на панели аналитики: edgemicro_hello-health и edgemicro_mock-health :

Используйте эти параметры для разделения относительных и абсолютных путей на панели аналитики в качестве отдельных прокси-объектов:

• relativePath (необязательно): указывает относительный путь для разделения на панели мониторинга Analytics. Например, если вы укажете /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 за корпоративным брандмауэром

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

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

Вариант 1:

Первый вариант — установить параметр edgemicro: proxy_tunnel в значение true в конфигурационном файле микрошлюза:

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 в заголовке Authorization вызовов 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, используя 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-сервере «микрошлюза» в вашей организации/среде 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 и используется для поддержки ротации ключей. Это значение совпадает с идентификатором закрытого ключа kid.

• 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, скопировав значение ключа потребителя (также называемого идентификатором клиента) из продукта 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

По умолчанию для заголовка ключа API и параметра запроса используется имя x-api-key . Вы можете изменить это значение по умолчанию в файле конфигурации, как описано в разделе «Внесение изменений в конфигурацию» . Например, чтобы изменить имя на 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-адресе, а значения идентификатора потребителя (Consumer Id) и секретного ключа потребителя (Consumer Secret), полученные из приложения разработчика на 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 . ОБЯЗАТЕЛЬНО используйте тип предоставления доступа password для этого вызова API. Следующие шаги описывают весь процесс.

1. Получите токен доступа и обновления с помощью API /token . Обратите внимание, что тип предоставления доступа — 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 , в котором можно настроить количество перезапусков и интервалы их выполнения. Этот файл настраивает службу 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» в справочнике командной строки.

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

Если вы используете несколько экземпляров 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

Running Edge Microgateway в автономном режиме

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

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

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

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

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

Для запуска Edge Microgateway в автономном режиме:

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

   npm install -g edgemicro

   Если вам нужна помощь, см. раздел «Установка 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, который должен присутствовать в заголовке Authorization вызова API. В следующем разделе вы получите JWT, который позволит выполнять вызовы API без этой ошибки.

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

В следующем примере показано, как получить JWT из конечной точки JWT Edge Microgateway на 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, вам необходимо подключение к Интернету, чтобы получить JWT от этой конечной точки.
3. Остановить микрошлюз Edge:

   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, как делали ранее, используя имена org/env, которые вы указывали в имени файла конфигурации. Например:

   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 не требует развертывания прокси-сервера, поддерживающего микрошлюз , на 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

   Если вам нужна помощь, см. раздел «Установка 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» .

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. Ключ можно найти в созданном вами ранее приложении для разработчиков. Откройте приложение в интерфейсе 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":""
}