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

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

Edge Microgateway версии 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:

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 – это среда в вашей организации (например, "тестовая" или "производственная").
   • 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 – это среда в вашей организации (например, "тестовая" или "рабочая").
   • key – это ключ, который ранее возвращался командой configure.
   • secret – это ключ, который ранее возвращался командой configure.

   Пример:

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

Вот пример файла конфигурации. Подробнее о настройках файла конфигурации…

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

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

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

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

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

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

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

https://localhost:8000/myapi

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

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

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

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

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

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

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

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

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

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

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

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

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

Вот пример для TLS:

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

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

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

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

Как использовать собственный сервис аутентификации

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

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

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

Как управлять файлами журналов

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

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

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

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

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

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

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

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

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

edgemicro:
  logging:
    to_console: true

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

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

Вы можете задать следующие уровни журнала: info, warn и error. Рекомендуется использовать уровень "Информация". Регистрируются все запросы и ответы 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. В этот файл также записываются счетчики API (статистика) и ошибки.
• err – регистрирует все, что отправляется в stderr.
• out – регистрирует все, что отправляется в stdout.

Вот правила именования:

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

Пример:

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

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

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

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

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

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

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

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

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

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

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

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

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

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

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

• 1436403888651 – временная метка Unix.
• info – зависит от контекста. Может быть информацией, предупреждением или ошибкой в зависимости от уровня журнала. Может содержать статистику, предупреждения или ошибки.
• 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 – зависит от контекста. Может быть информацией, предупреждением или ошибкой в зависимости от уровня журнала. Может содержать статистику, предупреждения или ошибки.
• treq – идентифицирует событие. В этом случае – целевой запрос.
• m – HTTP-метод, используемый в целевом запросе.
• u – часть URL после базового пути.
• h – хост и номер порта целевого сервера.
• i – идентификатор записи в журнале. Все четыре записи о событиях будут иметь один и тот же идентификатор.

3. Пример входящего ответа от целевого сайта

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

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

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

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

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

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

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

Расписание файлов журналов

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

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

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

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

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

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

Атрибуты edge_config

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

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

Атрибуты edgemicro

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

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

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

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

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

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

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

• x-forwarded-for (по умолчанию: true). Задайте значение false, чтобы запретить передачу целевому объекту заголовков x-forwarded-for. Если в запросе есть заголовок x-forwarded-for, его значение будет задано как значение 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. Чтобы требовать заголовок Authorization (по умолчанию), установите значение false.
• 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 с токеном доступа на предъявителя. Позволяет разрешить только модель безопасности OAuth (сохраняя обратную совместимость). (добавлено в версии 2.4.x)
• allowAPIKeyOnly – если задано значение true, каждый API должен иметь заголовок x-api-key (или специальное местоположение) с ключом API.Позволяет разрешить только модель безопасности с ключом API (сохраняя обратную совместимость). (Добавлено в версии 2.4.x)
• gracePeriod – этот параметр помогает избежать ошибок, вызванных небольшими расхождениями между системными часами и временем, указанным в параметрах "Не ранее" (nbf) или "Выдано" (iat) в токене авторизации JWT. Укажите в этом параметре количество секунд, в течение которых допускаются расхождения. (Добавлено в версии 2.5.7)

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

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

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

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

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

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

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

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

Пример:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Деидентификация данных аналитики

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

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

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

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

edgemicro_proxyname-health

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

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

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

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

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

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

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

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

Поддерживаемая версия 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 Community.

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

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

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

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

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

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

Веб-токен JSON (JWT) – это стандарт токенов, описанный в документе RFC7519. 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 – это среда в вашей организации (например, "тестовая" или "производственная").
• client_id – это идентификатор потребителя в созданном вами ранее приложении разработчика.
• client_secret – это секретный код потребителя в созданном вами ранее приложении для разработчиков.

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

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

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

Ключи KVM:

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

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

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

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

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

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

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

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

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

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

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

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

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

upgradekvm -o org -e env -u username

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

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

upgradeauth -o org -e env -u username

Подробнее об обновлении прокси-сервера edgemicro-auth…

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

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

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

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

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

Пример:

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

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

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

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

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

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

Пример:

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

Подробнее об использовании ключей API с запросами прокси-сервера можно узнать в статье Secure Edge Microgateway.

Как обеспечить безопасность токенов OAuth2

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

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

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

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

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. Этот вызов API необходимо выполнить с типом гранта password. Ниже описано, как это сделать.

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, который можно настроить, чтобы указать, сколько раз и с какими интервалами Edge Microgateway должен перезапускаться. Этот файл настраивает сервис Forever под названием forever-monitor, который управляет Forever программным способом.

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

Локальный режим прокси-сервера полезен, когда вам нужно связать только один прокси-сервер с экземпляром Edge Microgateway. Например, вы можете внедрить Edge Microgateway в Kubernetes в качестве прокси-сервера sidecar, где микрошлюз и сервис работают в одном контейнере, а микрошлюз управляет трафиком к своему сервису и от него. На рисунке ниже показана архитектура, в которой 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 Microgateway.

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

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

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

   export EDGEMICRO_LOCAL_PROXY=1

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

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

   Где:

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

   Пример:

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

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

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

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

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