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

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

Edge Microgateway версии 3.3.x

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

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

В этом разделе рассказывается, как обновить существующую установку Edge Microgateway. Если у вас нет подключения к интернету, прочитайте статью Можно ли установить Edge Microgateway без подключения к интернету?

Прежде чем обновлять рабочую среду, рекомендуется протестировать существующую конфигурацию с новой версией.

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

   npm upgrade edgemicro -g

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

   npm install edgemicro@3.2.3 -g

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

   edgemicro --version
   current nodejs version is v12.5.0
   current edgemicro version is 3.2.3
       

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

   edgemicro upgradeauth -o $ORG -e $ENV -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 -e $ENV -k $KEY -s $SECRET

   Где:

   • $ORG – название вашей организации Edge (вы должны быть ее администратором).
   • $ENV – это среда в вашей организации (например, 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 -e $ENV -k $KEY -s $SECRET

   Где:

   • $ORG – название вашей организации Edge (вы должны быть ее администратором).
   • $ENV – среда в вашей организации (например, 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

Посмотрите следующие видео, чтобы узнать, как настроить TLS в Apigee 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

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

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       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 и в файл журнала нельзя.

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

Уровень детализации журнала указывается в конфигурации edgemicro. Полный список уровней ведения журнала и их описания приведены в разделе Атрибуты edgemicro.

Например, в следующей конфигурации задан уровень ведения журнала debug:

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

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

Эти интервалы можно настроить в файле конфигурации 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

Как ослабить строгие разрешения для файлов журналов

По умолчанию Edge Microgateway создает файл журнала приложения (api-log.log) с уровнем разрешений файла 0600. Этот уровень доступа не позволяет внешним приложениям или пользователям читать файл журнала. Чтобы смягчить это строгое разрешение, задайте для параметра logging:disableStrictLogFile значение true. Если для этого атрибута задано значение true, файл журнала создается с разрешением 0755. Если задано значение false или атрибут не указан, по умолчанию используется разрешение 0600.

Добавлено в версии 3.2.3.

Пример:

edgemicro:
 logging:
   disableStrictLogFile: true

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

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

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

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

Каждый экземпляр Edge Microgateway создает файл журнала с расширением .log. Названия файлов журналов формируются следующим образом:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Пример:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

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

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

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

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 – уровень ведения журнала. Это значение зависит от контекста транзакции и уровня ведения журнала, заданного в конфигурации edgemicro. Подробнее о том, как задать уровень ведения журнала… Для записей статистики уровень задан как stats. Записи статистики создаются с регулярным интервалом, заданным в конфигурации stats_log_interval. См. также Как изменить интервалы истории изменений.
• 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 – уровень ведения журнала. Это значение зависит от контекста транзакции и уровня ведения журнала, заданного в конфигурации edgemicro. Подробнее о том, как задать уровень ведения журнала… Для записей статистики уровень задан как stats. Записи статистики создаются с регулярным интервалом, заданным в конфигурации stats_log_interval. См. также Как изменить интервалы истории изменений.
• treq – идентификатор события. В данном случае это целевой запрос.
• m – HTTP-глагол, используемый в целевом запросе.
• u – часть URL, следующая за базовым путем.
• h – хост и номер порта целевого сервера.
• i – идентификатор записи в журнале. Этот идентификатор будет одинаковым для всех четырех записей.

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

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

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

• info – уровень ведения журнала. Это значение зависит от контекста транзакции и уровня ведения журнала, заданного в конфигурации edgemicro. Подробнее о том, как задать уровень ведения журнала… Для записей статистики уровень задан как stats. Записи статистики создаются с регулярным интервалом, заданным в конфигурации stats_log_interval. См. также Как изменить интервалы истории изменений.
• tres – идентифицирует событие. В данном случае это целевой ответ.
• s – статус HTTP-ответа.
• d – продолжительность в миллисекундах. Время, которое потребовалось целевому объекту для вызова API.
• i – идентификатор записи в журнале. Этот идентификатор будет одинаковым для всех четырех записей.

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

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

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

• info – уровень ведения журнала. Это значение зависит от контекста транзакции и уровня ведения журнала, заданного в конфигурации edgemicro. Подробнее о том, как задать уровень ведения журнала… Для записей статистики уровень задан как stats. Записи статистики создаются с регулярным интервалом, заданным в конфигурации stats_log_interval. См. также Как изменить интервалы истории изменений.
• 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.
• quotaUri – задайте это свойство конфигурации, если хотите управлять квотами через прокси-сервер edgemicro-auth, развернутый в вашей организации. Если это свойство не задано, конечная точка квоты по умолчанию будет внутренней конечной точкой Edge Microgateway.

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

атрибуты 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 – регистрируются только сообщения об ошибках.
    • debug – регистрирует сообщения отладки, а также информационные сообщения, предупреждения и сообщения об ошибках.
    • trace – в журнал записывается информация о трассировке ошибок, а также информационные сообщения, предупреждения и сообщения об ошибках.
    • none – не создавать файл журнала.
  • 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.
• keep_alive_timeout – это свойство позволяет задать время ожидания Edge Microgateway (в миллисекундах). Значение по умолчанию: 5 секунд. Добавлено в версии 3.0.6.
• headers_timeout – этот атрибут ограничивает время (в миллисекундах), в течение которого синтаксический анализатор HTTP будет ожидать получения полных HTTP-заголовков.

  Пример:

  edgemicro:
    keep_alive_timeout: 6000
    headers_timeout: 12000

  Внутренне параметр задает атрибут Node.js Server.headersTimeout для запросов. По умолчанию это значение на 5 секунд больше, чем заданное с помощью edgemicro.keep_alive_timeout. Эта настройка по умолчанию предотвращает ошибочное прерывание соединения балансировщиками нагрузки или прокси-серверами. (Добавлено в версии 3.1.1)

• noRuleMatchAction: (строка) действие, которое нужно выполнить (разрешить или запретить доступ), если правило соответствия, указанное в плагине accesscontrol, не разрешено (не соответствует). Допустимые значения: ALLOW или DENY. Значение по умолчанию: ALLOW (добавлено в версии 3.1.7).
• enableAnalytics: (по умолчанию: true). Чтобы плагин аналитики не загружался, задайте для этого атрибута значение false. В этом случае вызовы аналитики Apigee Edge не выполняются. Если задано значение true или атрибут не указан, плагин аналитики будет работать как обычно. Подробные сведения приведены в разделе Атрибуты edgemicro. Добавлено в версии 3.1.8.

  Пример:

  edgemicro
    enableAnalytics=false|true

• on_target_response_abort – этот атрибут позволяет управлять поведением Edge Microgateway в случае преждевременного закрытия соединения между клиентом (Edge Microgateway) и целевым сервером.

  Значение	Описание
  По умолчанию	Если параметр on_target_response_abort не указан, то режим работы по умолчанию — усечение ответа без показа ошибки. В файлах журнала предупреждение показывается с кодом ответа targetResponse aborted и 502.
  appendErrorToClientResponseBody	Клиенту возвращается специальная ошибка TargetResponseAborted. В файлах журнала предупреждение показывается с кодом ответа targetResponse aborted и 502. Кроме того, в журнал заносится ошибка TargetResponseAborted с сообщением Target response ended prematurely..
  abortClientRequest	Edge Microgateway прерывает запрос, и в файлы журнала записывается предупреждение TargetResponseAborted с кодом статуса запроса 502.

Пример:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

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

Эти настройки определяют, как обрабатываются определенные 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.

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

Фильтрация товаров по названию включена.

Чтобы ограничить количество продуктов API, которые Edge Microgateway скачивает и обрабатывает, используйте следующую конфигурацию. Чтобы отфильтровать скачанные продукты, добавьте параметр запроса productnamefilter в API /products, указанный в файле *.config.yaml Edge Microgateway. Пример:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-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://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

Обратите внимание, что значение параметра запроса должно быть указано в формате регулярного выражения и закодировано в URL. Например, регулярное выражение ^[Ee]dgemicro.*$ позволяет найти такие названия, как edgemicro-test-1, edgemicro_demo и Edgemicro_New_Demo. Закодированное значение URL, подходящее для использования в параметре запроса: %5E%5BEe%5Ddgemicro.%2A%24.

В выходных данных отладки ниже показано, что были скачаны только отфильтрованные товары:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Фильтрация товаров по настраиваемым атрибутам

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

1. В пользовательском интерфейсе Edge выберите прокси-сервер edgemicro_auth в организации или среде, где вы настроили Edge Microgateway.
2. На вкладке Develop (Разработка) откройте в редакторе правило JavaCallout.
3. Добавьте настраиваемый атрибут с ключом products.filter.attributes и списком названий атрибутов, разделенных запятыми. В Edge Microgateway будут возвращены только продукты, содержащие любое из названий настраиваемых атрибутов.
4. Вы можете отключить проверку того, включен ли продукт для текущей среды, задав для настраиваемого атрибута products.filter.env.enable значение false. Значение по умолчанию – true.
5. (Только для Private Cloud) Если вы используете Edge для Private Cloud, задайте для свойства org.noncps значение true, чтобы получать продукты для сред, не относящихся к CPS.

Пример:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

Фильтрация товаров по статусу отзыва

У продуктов API есть три кода статуса: "Ожидает рассмотрения", "Одобрено" и "Отозвано". В правило Задать переменные JWT в прокси-сервере edgemicro-auth добавлено новое свойство allowProductStatus. Чтобы использовать это свойство для фильтрации продуктов API, перечисленных в JWT:

1. Откройте прокси-сервер edgemicro-auth в редакторе прокси-серверов Apigee.
2. Добавьте свойство allowProductStatus в XML-код правила SetJWTVariables и укажите список кодов статуса, разделенных запятыми, для фильтрации. Например, чтобы отфильтровать по статусам Ожидает рассмотрения и Отозвано:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript timeLimit="20000" async="false" continueOnError="false"
       enabled="true" name="Set-JWT-Variables">
       <DisplayName>Set JWT Variables</DisplayName>
       <FaultRules/>
       <Properties>
           <Property name="allowProductStatus">Pending,Revoked</Property>
       </Properties>
       <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
   </Javascript>

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

   <Property name="allowProductStatus">Approved</Property>

3. Сохраните настройки прокси-сервера.

   Если тег Property отсутствует, в JWT будут перечислены товары со всеми кодами статуса.

   Чтобы использовать это новое свойство, необходимо обновить прокси-сервер edgemicro-auth.

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

Используйте эти параметры конфигурации, чтобы контролировать частоту, с которой 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 за корпоративным брандмауэром

Использование HTTP-прокси для связи с Apigee Edge

Добавлено в версии 3.1.2.

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

1. Задайте переменные среды HTTP_PROXY, HTTPS_PROXY и NO_PROXY. Эти переменные управляют хостами для каждого HTTP-прокси, который вы хотите использовать для связи с Apigee Edge, или хостами, которые не должны обрабатывать связь с Apigee Edge. Пример:

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

   Обратите внимание, что NO_PROXY может быть списком доменов, разделенных запятыми, на которые Edge Microgateway не должен перенаправлять трафик.

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

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

Использовать HTTP-прокси для связи с целевым сервером

Добавлено в версии 3.1.2.

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

1. Добавьте в файл конфигурации микрошлюза следующий код:

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   Где:

   • tunnel (необязательно). Если задано значение true, Edge Microgateway использует метод HTTP CONNECT для туннелирования HTTP-запросов через одно TCP-подключение. (То же самое относится к переменным среды, упомянутым ниже, если для настройки прокси-сервера включен протокол TLS). По умолчанию: false
   • url – URL HTTP-прокси.
   • bypass – необязательный параметр, в котором указываются один или несколько разделенных запятыми URL целевых хостов, которые должны обходить HTTP-прокси. Если это свойство не задано, то для указания целевых URL, которые нужно обходить, используйте переменную среды NO_PROXY.
   • enabled – если задано значение true и настроено правило proxy.url, для HTTP-прокси используется значение proxy.url. Если задано значение true и не задано значение proxy.url, используйте прокси-серверы, указанные в переменных среды HTTP-прокси HTTP_PROXY и HTTPS_PROXY, как описано в разделе Использование HTTP-прокси для связи с Apigee Edge.

   Пример:

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

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

Использование подстановочных знаков в прокси-серверах, поддерживающих 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.

Вы можете сгенерировать JWT с помощью CLI и использовать его в заголовке авторизации вызовов API вместо ключа API. Пример:

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

Информацию о создании JWT с помощью CLI можно найти в разделе Как создать токен.

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

Через некоторое время после создания 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, представленные для проверки, будут проверяться с помощью нового открытого ключа. Если проверка не удалась, будет использоваться старый открытый ключ, пока не истечет срок действия JWT (после интервала token_expiry*, по умолчанию 30 минут). Таким образом вы можете "ротировать" ключи, не прерывая трафик API.

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

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

1. Чтобы обновить KVM, используйте команду edgemicro upgradekvm. Подробные сведения о выполнении этой команды приведены в разделе Обновление KVM. Это нужно сделать только один раз.
2. Чтобы обновить прокси-сервер edgemicro-oauth, используйте команду edgemicro upgradeauth. Подробные сведения о выполнении этой команды приведены в статье Обновление прокси-сервера edgemicro-auth. Это нужно сделать только один раз.
3. Добавьте в файл ~/.edgemicro/org-env-config.yaml следующую строку, указав ту же организацию и среду, которые вы настроили для использования микрошлюза:

   jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

4. Выполните команду ротации ключей. Подробные сведения об этой команде приведены в разделе Ротация ключей.

   edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

   Пример:

   edgemicro rotatekey -o docs -e test \
   -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
   -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
   

После ротации ключей 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"
    }
  ]
}

Как настроить задержку "не ранее"

В версиях 3.1.5 и более ранних новый закрытый ключ, созданный с помощью команды rotatekey, начинал действовать сразу, и новые токены подписывались им. Однако новый открытый ключ становился доступен экземплярам Edge Microgateway только каждые 10 минут (по умолчанию), когда обновлялась конфигурация микрошлюза. Из-за этой задержки между подписанием токена и обновлением экземпляра микрошлюза токены, подписанные последним ключом, будут отклоняться до тех пор, пока все экземпляры не получат последний открытый ключ.

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

Начиная с версии 3.1.6, новый флаг в команде rotatekey позволяет указать задержку, после которой новый закрытый ключ вступит в силу. Это дает время на обновление всех экземпляров микрошлюза и получение нового открытого ключа. Новый флаг --nbf означает "не ранее". В качестве значения указывается целое число – количество минут задержки.

В примере ниже задержка составляет 15 минут:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

Рекомендуем задать задержку, превышающую значение параметра config_change_poll_internal (по умолчанию 10 минут). См. также атрибуты edgemicro.

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

По умолчанию 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 $ORG -e $ENV -k $KEY -s $SECRET

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

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

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.

Включить коды ответов вышестоящего сервера

По умолчанию плагин oauth возвращает только коды статуса ошибки 4xx, если ответ не имеет статус 200. Вы можете изменить это поведение, чтобы всегда возвращался точный код 4xx или 5xx в зависимости от ошибки.

Чтобы включить эту функцию, добавьте свойство oauth.useUpstreamResponse: true в конфигурацию Edge Microgateway. Пример:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Использование токенов безопасности 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: отправка учетных данных в заголовке Basic Auth

Отправьте учетные данные клиента в виде заголовка Basic Authentication, а grant_type – в виде параметра формы. Эта форма команды также описана в документе RFC 6749: The OAuth 2.0 Authorization Framework.

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": 1799
}

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

Чтобы получить токен обновления, выполните вызов 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 возвращает токен доступа и токен обновления. Ответ выглядит примерно так: Обратите внимание, что значения expires_in являются целыми числами и указываются в секундах.

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": 108,
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": 431,
       "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"
       }

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

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

Если вы используете несколько экземпляров 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. Создайте файл конфигурации со следующим названием: $HOME/.edgemicro/$ORG-$ENV-config.yaml.

   Пример:

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

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

   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

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

   export EDGEMICRO_LOCAL=1

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

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   Где:

   • $ORG – это название организации, которое вы использовали в названии файла конфигурации.
   • $ENV – это название среды, которое вы использовали в названии файла конфигурации.
   • $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 /

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

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

   edgemicro configure -o your_org -e your_env -u your_apigee_username

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

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

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

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

   export EDGEMICRO_LOCAL_PROXY=1

7. Выполните следующую команду 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":""
}

Использование синхронизатора

В этом разделе объясняется, как использовать синхронизатор – дополнительную функцию, которая повышает отказоустойчивость Edge Microgateway, позволяя ему получать данные конфигурации из Apigee Edge и записывать их в локальную базу данных Redis. Когда экземпляр синхронизатора запущен, другие экземпляры Edge Microgateway, работающие на разных узлах, могут получать свою конфигурацию непосредственно из этой базы данных.

Функция синхронизации в настоящее время поддерживается для работы с Redis 5.0.x.

Что такое синхронизатор?

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

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

Синхронизатор Edge Microgateway предоставляет альтернативный механизм для экземпляров Edge Microgateway, позволяющий получать данные конфигурации, необходимые для запуска и обработки трафика прокси-сервера API. Данные конфигурации, полученные из вызовов Apigee Edge, включают: вызов jwk_public_keys, вызов jwt_public_key, вызов начальной загрузки и вызов продуктов API. Синхронизатор позволяет всем экземплярам Edge Microgateway, работающим на разных узлах, правильно запускаться и оставаться синхронизированными, даже если подключение к интернету между Edge Microgateway и Apigee Edge прервано.

Синхронизатор – это специально настроенный экземпляр Edge Microgateway. Единственная его цель – опрашивать Apigee Edge (время настраивается), получать данные конфигурации и записывать их в локальную базу данных Redis. Сам экземпляр синхронизатора не может обрабатывать трафик прокси-сервера API. Другие экземпляры Edge Microgateway, работающие на разных узлах, можно настроить для получения данных конфигурации из базы данных Redis, а не из Apigee Edge. Поскольку все экземпляры микрошлюза получают данные конфигурации из локальной базы данных, они могут запускаться и обрабатывать запросы к API даже в случае сбоя в работе интернета.

Настройка экземпляра синхронизатора

Добавьте следующую конфигурацию в файл org-env/config.yaml для установки Edge Microgateway, которую вы хотите использовать в качестве синхронизатора:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Пример:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Сохраните файл конфигурации и запустите экземпляр Edge Microgateway. Он начнет опрашивать Apigee Edge и сохранять скачанные данные конфигурации в базе данных Redis.

Настройка обычных экземпляров Edge Microgateway

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

Добавьте следующую конфигурацию в файл org-env/config.yaml каждого дополнительного узла Edge Microgateway. Обратите внимание, что свойство synchronizerMode имеет значение 0. Это свойство настраивает экземпляр для работы в качестве обычного экземпляра Edge Microgateway, который обрабатывает трафик прокси-сервера API, и экземпляр будет получать данные конфигурации из базы данных Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Пример:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Свойства конфигурации

Для поддержки синхронизатора были добавлены следующие свойства конфигурации:

Как настроить исключение URL для плагинов

Вы можете настроить микрошлюз так, чтобы он пропускал обработку плагинов для определенных URL. Эти URL можно исключить глобально (для всех плагинов) или для определенных плагинов.

Пример:

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

В этом примере плагины не будут обрабатывать входящие вызовы прокси-сервера API с путями /hello или /proxy_one. Кроме того, плагин json2xml будет пропущен для API, в пути которых есть /hello/xml.

Как задать атрибуты конфигурации с помощью значений переменных среды

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

В этом примере атрибут key заменяется значением переменной среды TARGETS_SSL_CLIENT_KEY и т. д.

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

В этом примере тег <n> используется для указания целочисленного значения. Поддерживаются только положительные целые числа.

edgemicro:
  port: <E><n>EMG_PORT</n></E>

В этом примере тег <b> используется для указания логического значения (true или false).

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>