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

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

Edge Microgateway v. 2.5.x

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

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

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

   npm upgrade edgemicro -g

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

   npm upgrade edgemicro@2.5.26 -g

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

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

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

   edgemicro upgradeauth -o org_name -e env_name -u username

Внесение изменений в конфигурацию

Файлы конфигурации, о которых вам нужно знать, включают:

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

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

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

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

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

Где prefix — это каталог префикса npm . См. раздел «Где установлен Edge Microgateway», если вы не можете найти этот каталог.

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

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

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

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

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

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

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

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

Если Edge Microgateway работает (опция с нулевым временем простоя):

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

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

   Где:

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

   Например

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

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

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

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

   Где:

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

   Например:

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

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

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

Установка переменных среды

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

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

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

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

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

https://localhost:8000/myapi

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

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

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

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

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

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

Вот список всех поддерживаемых опций сервера:

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

Вы можете настроить Edge Microgateway в качестве клиента TLS или SSL при подключении к целевым конечным точкам. В файле конфигурации Microgateway используйте элемент target для установки параметров 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

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

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

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

Это соглашение об именах:

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

Например:

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

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

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

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

3. Образец входящего ответа от цели

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

1436403888651 — отметка даты Unix

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

4. Образец исходящего ответа клиенту

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

1436403888651 — отметка даты Unix

• информация - Зависит от контекста. Может быть информация, предупреждение или ошибка, в зависимости от уровня журнала. Это может быть статистика для записи статистики, предупреждение для предупреждений или ошибка для ошибок.
• 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 : (по умолчанию: нет) URL-адрес, указывающий на службу Edge Microgateway, работающую в Apigee Edge. Edge Microgateway использует эту службу для связи с Apigee Edge. Этот URL-адрес возвращается при выполнении команды для создания пары открытого и закрытого ключей: edgemicro genkeys . Подробности см. в разделе Установка и настройка Edge Microgateway .
• jwt_public_key : (по умолчанию: нет) URL-адрес, указывающий на прокси-сервер Edge Microgateway, развернутый в Apigee Edge. Этот прокси-сервер служит конечной точкой аутентификации для выдачи клиентам подписанных токенов доступа. Этот URL-адрес возвращается при выполнении команды для развертывания прокси: Edgemicro configure . Подробности см. в разделе Установка и настройка Edge Microgateway .

Атрибуты EdgeMicro

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

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

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

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

• отладка: добавляет удаленную отладку в процесс Edge Microgateway.
  • порт : номер порта для прослушивания. Например, настройте отладчик IDE на прослушивание этого порта.
  • args : Аргументы процесса отладки. Например: args --nolazy
    
• config_change_poll_interval: (по умолчанию: 600 секунд) Edge Microgateway периодически загружает новую конфигурацию и выполняет перезагрузку, если что-то изменилось. Опрос фиксирует любые изменения, внесенные в Edge (изменения в продуктах, прокси-серверах с поддержкой микрошлюзов и т. д.), а также изменения, внесенные в локальный файл конфигурации.
  
• Disable_config_poll_interval: (по умолчанию: false) Установите значение true , чтобы отключить автоматический опрос изменений.
• request_timeout : устанавливает тайм-аут для целевых запросов. Таймаут задается в секундах. Если происходит тайм-аут, Edge Microgateway отвечает кодом состояния 504. (Добавлено v2.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 вообще без какого-либо заголовка авторизации. Установите для этого параметра значение false, чтобы требовать заголовок авторизации (по умолчанию).
• allowInvalidAuthorization : (по умолчанию: false) Если установлено значение true, вызовы API разрешаются, если токен, переданный в заголовке авторизации, недействителен или срок его действия истек. Установите для этого параметра значение false, чтобы требовать действительные токены (по умолчанию).
• авторизационный-заголовок : (по умолчанию: Авторизация: Носитель) Заголовок, используемый для отправки токена доступа в Edge Microgateway. Возможно, вы захотите изменить значение по умолчанию в тех случаях, когда целевому объекту необходимо использовать заголовок авторизации для какой-либо другой цели.
• api-key-header : (по умолчанию: x-api-key) Имя заголовка или параметра запроса, используемого для передачи ключа API в Edge Microgateway. См. также Использование ключа API .
• Keep-authorization-header : (по умолчанию: false) Если установлено значение true, заголовок авторизации, отправленный в запросе, передается цели (он сохраняется).
• allowOAuthOnly — если установлено значение true, каждый API должен содержать заголовок авторизации с токеном доступа к носителю. Позволяет разрешить только модель безопасности 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:

• ufferSize (необязательно): максимальное количество аналитических записей, которое может храниться в буфере, прежде чем самые старые записи начнут удаляться. По умолчанию: 10000
• BatchSize (необязательно): максимальный размер пакета аналитических записей, отправляемых в Apigee. По умолчанию: 500
• lushInterval (необязательно): количество миллисекунд между каждой очисткой пакета аналитических записей, отправляемых в 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. На панели управления Analytics отдельные прокси-серверы имеют следующий шаблон именования:

edgemicro_proxyname-health

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

Используйте эти параметры, чтобы разделить относительные и абсолютные пути на панели мониторинга Analytics как отдельные прокси:

• относительный путь (необязательно): указывает относительный путь для разделения на панели мониторинга Analytics. Например, если вы укажете /healthcheck , все вызовы API, содержащие путь /healthcheck будут отображаться на информационной панели как edgemicro_ proxyname -health . Обратите внимание, что этот флаг игнорирует базовый путь прокси. Для разделения на основе полного пути, включая базовый путь, используйте флаг proxyPath .
• proxyPath (необязательно): указывает полный путь прокси-сервера API, включая базовый путь прокси-сервера, для разделения на панели аналитики. Например, если вы укажете /mocktarget/healthcheck , где /mocktarget — это базовый путь прокси-сервера, все вызовы API с путем /mocktarget/healthcheck будут отображаться на панели мониторинга как edgemicro_ proxyname -health .

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

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

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

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

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

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

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

Вариант 1:

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

edge_config:

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

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

Вариант 2:

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

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

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

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

export NO_PROXY='localhost,localhost:8080'

Установите HTTP_PROXY и HTTPS_PROXY для конечной точки HTTP-прокси. Edge Microgateway может отправлять на нее сообщения. Например:

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

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

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

См. также

Как настроить Edge Microgateway за брандмауэром компании в сообществе Apigee.

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

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

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

Вращение ключей JWT

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

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

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

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

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

Создание нового JWT

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

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

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

Или вы также можете создать JWT с помощью API управления:

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

Где:

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

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

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

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

Ключи KVM включают в себя:

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

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

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

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

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

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

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

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

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

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

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

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

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

upgradekvm -o org -e env -u username

Дополнительную информацию об этой команде см. в разделе «Обновление KVM» .

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

upgradeauth -o org -e env -u username

Дополнительные сведения об этой команде см. в разделе Обновление прокси-сервера Edgemicro-auth .

Вращение клавиш

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

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

Запустите команду вращения клавиш, чтобы повернуть клавиши. (Дополнительную информацию об этой команде см. в разделе «Вращение клавиш» .)

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

Например:

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

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

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

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

Фильтрация загруженных прокси

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

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

   edge_config:
   …
   proxyPattern: edgemicro_f*

Указание продуктов без API-прокси

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Настройка имени ключа API

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

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

В этом примере и параметр запроса, и имя заголовка изменяются на apiKey . Имя x-api-key больше не будет работать в любом случае. См. также Внесение изменений в конфигурацию .

Например:

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

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

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

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

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

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

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

API 1

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

Вы можете найти файл ever.json в корневом каталоге установки Edge Microgateway. См. раздел Где установлен Edge Microgateway . Подробную информацию о параметрах конфигурации можно найти в документации Forever-Monitor .

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

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

Для получения дополнительной информации см. мониторинг Forever в справочнике по 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 — это имя «org», которое вы использовали в имени файла конфигурации.
   • your_environment — это имя «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 /

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

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

   Поскольку плагин extauth находится в файле foo-bar-config.yaml , вы получаете ошибку «missing_authorization». Этот плагин проверяет JWT, который должен присутствовать в заголовке авторизации вызова 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. Вам необходимо выполнить стандартную установку и настройку Edge Microgateway, чтобы развернуть прокси-сервер edgemicro-auth в вашей организации/среде на Apigee Edge. Если вы уже выполнили этот шаг ранее, повторять его не нужно.
2. Если вы развернули Edge Microgateway в Apigee Cloud, вы должны быть подключены к Интернету, чтобы вы могли получить JWT из этой конечной точки.
3. Остановить пограничный микрошлюз:

   edgemicro stop

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

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

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

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

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

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

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

Где:

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

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

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

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

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

Пример:

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

Пример вывода:

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

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

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

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

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

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

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

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

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

   npm install -g edgemicro

   Если вам нужна помощь, см. раздел Установка Edge Microgateway .

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

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Эта команда развертывает политику Edgemicro-auth в Edge и возвращает ключ и секрет, которые вам понадобятся для запуска микрошлюза. Если вам нужна помощь, см. раздел Настройка Edge 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":""
}