Dokumentacja operacji i konfiguracji Edge Microgateway

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Edge Microgateway w wersji 3.3.x

Z tego tematu dowiesz się, jak zarządzać i konfigurować Edge Microgateway.

Przejście na Edge Microgateway, jeśli masz połączenie z internetem

W tej sekcji opisaliśmy, jak uaktualnić istniejącą instalację Edge Microgateway. Jeśli nie masz połączenia z internetem, zapoznaj się z artykułem Czy mogę zainstalować Edge Microgateway bez połączenia z internetem?.

Firma Apigee zaleca przetestowanie bieżącej konfiguracji z nową wersją przed uaktualnieniem środowiska produkcyjnego.

1. Aby przejść na najnowszą wersję Microgateway, uruchom to polecenie npm:

   npm upgrade edgemicro -g

   Aby zainstalować określoną wersję Edge Microgateway, musisz podać numer wersji w komendzie instalacji. Aby na przykład zainstalować wersję 3.2.3, użyj tego polecenia:

   npm install edgemicro@3.2.3 -g

2. Sprawdź numer wersji. Jeśli na przykład masz zainstalowaną wersję 3.2.3:

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

3. Na koniec zaktualizuj do najnowszej wersji serwera proxy edgemicro-auth:

   edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

Wprowadzanie zmian w konfiguracji

Poniżej znajdziesz informacje o plikach konfiguracji, które warto poznać:

• Domyślny plik konfiguracji systemu
• Domyślny plik konfiguracji dla nowo zainicjowanej instancji Edge Microgateway
• Dynamiczny plik konfiguracji dla uruchomionych instancji

W tej sekcji znajdziesz informacje o tych plikach oraz o tym, co musisz wiedzieć o ich zmianie.

Domyślny plik konfiguracji systemu

Po zainstalowaniu Edge Microgateway domyślny plik konfiguracji systemu zostanie umieszczony tutaj:

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

Gdzie prefix to katalog z prefiksem npm. Jeśli nie możesz znaleźć tego katalogu, zapoznaj się z artykułem Gdzie jest zainstalowany Edge Microgateway.

Jeśli zmienisz plik konfiguracji systemu, musisz ponownie zainicjować i skonfigurować urządzenie Edge, a następnie je ponownie uruchomić. Microgateway:

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

Domyślny plik konfiguracji dla nowo zainicjowanych instancji Edge Microgateway

Po uruchomieniu edgemicro init plik konfiguracji systemu (opisany powyżej), default.yaml, jest umieszczany w katalogu ~/.edgemicro.

Jeśli zmienisz plik konfiguracji w ~/.edgemicro, musisz ponownie skonfigurować i zrestartować Edge Microgateway:

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

Dynamiczny plik konfiguracji dla uruchomionych instancji

Gdy uruchomisz edgemicro configure [params], w ~/.edgemicro zostanie utworzony dynamiczny plik konfiguracji. Nazwa pliku jest tworzona według tego wzoru: org-env-config.yaml, gdzie org i env to nazwy organizacji i środowiska Apigee Edge. Za pomocą tego pliku możesz wprowadzać zmiany w konfiguracji, a następnie ponownie wczytywać je bez przestojów. Jeśli na przykład dodasz i skonfigurujesz wtyczkę, możesz ponownie wczytać konfigurację bez powodowania przerw w działaniu usługi, jak opisano poniżej.

Jeśli mikrobramka Edge działa (opcja bez przestojów):

1. Ponownie załaduj konfigurację Edge Microgateway:

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

   Gdzie:

   • $ORG to nazwa Twojej organizacji w usłudze Edge (musisz być administratorem organizacji).
   • $ENV to środowisko w Twojej organizacji (np. „test” lub „prod”).
   • $KEY to klucz zwrócony wcześniej przez polecenie configure.
   • $SECRET to klucz zwrócony wcześniej przez polecenie configure.

   Przykład

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

Jeśli Edge Microgateway jest zatrzymany:

1. Ponownie uruchom Edge Microgateway:

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

   Gdzie:

   • $ORG to nazwa Twojej organizacji w usłudze Edge (musisz być administratorem organizacji).
   • $ENV to środowisko w Twojej organizacji (np. „test” lub „prod”).
   • $KEY to klucz zwrócony wcześniej przez polecenie configure.
   • $SECRET to klucz zwrócony wcześniej przez polecenie configure.

   Na przykład:

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

Oto przykładowy plik konfiguracji. Szczegółowe informacje o ustawieniach pliku konfiguracji znajdziesz w artykule Informacje o konfiguracji 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

Ustawianie zmiennych środowiskowych

Polecenia interfejsu wiersza poleceń, które wymagają wartości organizacji i środowiska Edge, a także klucza i tajemnicy potrzebnych do uruchomienia mikrobramki Edge, można przechowywać w tych zmiennych środowiskowych:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

Ustawienie tych zmiennych jest opcjonalne. Jeśli je ustawisz, nie musisz podawać ich wartości podczas konfigurowania i uruchamiania Edge Microgateway za pomocą interfejsu wiersza poleceń (CLI).

Konfigurowanie SSL na serwerze Edge Microgateway

Aby dowiedzieć się więcej o konfigurowaniu TLS w usłudze Apigee Edge Microgateway, obejrzyj te filmy:

Możesz skonfigurować serwer Microgateway, aby używał protokołu SSL. Na przykład po skonfigurowaniu SSL możesz wywoływać interfejsy API za pomocą Edge Microgateway za pomocą protokołu „https”, na przykład:

https://localhost:8000/myapi

Aby skonfigurować SSL na serwerze Microgateway, wykonaj te czynności:

1. Wygeneruj lub pobierz certyfikat SSL i klucz za pomocą narzędzia openssl lub dowolnej innej metody.
2. Dodaj atrybut edgemicro:ssl do pliku konfiguracji Edge Microgateway. Pełną listę opcji znajdziesz w tabeli poniżej. Na przykład:
   

   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. Ponownie uruchom Edge Microgateway. Wykonaj czynności opisane w sekcji Wprowadzanie zmian w konfiguracji, w zależności od tego, który plik konfiguracji został zmodyfikowany: domyślny czy plik konfiguracji w czasie wykonywania.

Oto przykład sekcji edgemicro w pliku konfiguracji z skonfigurowanym 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

Oto lista wszystkich obsługiwanych opcji serwera:

Korzystanie z opcji SSL/TLS klienta

Podczas łączenia się z punktami końcowymi docelowymi możesz skonfigurować bramę Edge Microgateway jako klienta TLS lub SSL. W pliku konfiguracji Microgateway użyj elementu targets, aby ustawić opcje SSL/TLS. Pamiętaj, że możesz określić wiele konkretnych wartości docelowych. Poniżej znajdziesz przykład kampanii z wieloma celami.

Ten przykład przedstawia ustawienia, które zostaną zastosowane do wszystkich hostów:

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

W tym przykładzie ustawienia są stosowane tylko do określonego hosta:

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

Oto przykład dla TLS:

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

Jeśli chcesz zastosować ustawienia TLS/SSL do wielu konkretnych celów, musisz w konfiguracji ustawić pierwszego hosta jako „pusty”, co umożliwi żądania uniwersalne, a następnie określić konkretnych hostów w dowolnej kolejności. W tym przykładzie ustawienia są stosowane do wielu konkretnych hostów:

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true

Oto lista wszystkich obsługiwanych opcji klienta:

Dostosowywanie serwera proxy edgemicro-auth

Domyślnie Edge Microgateway używa serwera proxy wdrożonego w Apigee Edge do uwierzytelniania OAuth2. Ten serwer proxy jest wdrażany podczas pierwszego uruchomienia edgemicro configure. Możesz zmienić domyślną konfigurację tego serwera proxy, aby dodać obsługę niestandardowych deklaracji do tokena sieciowego JSON (JWT), skonfigurować wygaśnięcie tokena i wygenerować tokeny odświeżania. Szczegółowe informacje znajdziesz na stronie edgemicro-auth w GitHub.

Korzystanie z niestandardowej usługi uwierzytelniania

Domyślnie Edge Microgateway używa serwera proxy wdrożonego w Apigee Edge do uwierzytelniania OAuth2. Ten serwer proxy jest wdrażany podczas pierwszego uruchomienia edgemicro configure. Domyślnie adres URL tego serwera proxy jest określony w pliku konfiguracyjnym Edge Microgateway w ten sposób:

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

Jeśli chcesz używać własnej usługi niestandardowej do obsługi uwierzytelniania, zmień wartość authUri w pliku konfiguracji, aby wskazywała na Twoją usługę. Możesz na przykład mieć usługę, która do weryfikacji tożsamości używa LDAP.

Zarządzanie plikami dziennika

Edge Microgateway rejestruje informacje o każdym żądaniu i odpowiedzi. Pliki dziennika zawierają przydatne informacje do debugowania i rozwiązywania problemów.

Miejsce przechowywania plików dziennika

Domyślnie pliki dziennika są przechowywane w /var/tmp.

Jak zmienić domyślny katalog z plikami dziennika

Katalog, w którym są przechowywane pliki dziennika, jest określony w pliku konfiguracji Edge Microgateway. Zobacz też Wprowadzanie zmian w konfiguracji.

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

Zmień wartość dir, aby podać inny katalog plików dziennika.

Wysyłanie dzienników do konsoli

Możesz skonfigurować rejestrowanie tak, aby informacje o logach były wysyłane do standardowego wyjścia zamiast do pliku dziennika. Ustaw flagę to_console na wartość prawda w ten sposób:

edgemicro:
  logging:
    to_console: true

Przy tym ustawieniu dzienniki będą wysyłane do standardowego wyjścia. Obecnie nie można wysyłać logów zarówno do stdout, jak i do pliku dziennika.

Jak ustawić poziom rejestrowania

Poziom logowania, którego chcesz użyć, określasz w konfiguracji edgemicro. Pełną listę poziomów logowania i ich opisów znajdziesz w sekcji Atrybuty edgemicro.

Na przykład w ramach tej konfiguracji poziom logowania jest ustawiony na debug:

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

Jak zmienić interwały logowania

Możesz skonfigurować te interwały w pliku konfiguracyjnym Edge Microgateway. Zobacz też Wprowadzanie zmian w konfiguracji.

Atrybuty, które można konfigurować:

• stats_log_interval: (domyślnie: 60) Interwał w sekundach, w jakim rekord statystyk jest zapisywany do pliku dziennika interfejsu API.
• rotate_interval: (domyślnie 24) Interwał w godzinach, w jakim są rotowane pliki dziennika. Na przykład:

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

Jak poluzować ścisłe uprawnienia do plików dziennika

Domyślnie Edge Microgateway generuje plik dziennika aplikacji (api-log.log) z uprawnieniami pliku ustawionymi na poziom 0600. Ten poziom uprawnień nie zezwala aplikacjom zewnętrznym ani użytkownikom na odczyt pliku dziennika. Aby osłabić ten ścisły poziom uprawnień, ustaw logging:disableStrictLogFile na true. Gdy ten atrybut ma wartość true, plik dziennika jest tworzony z uprawnieniami pliku ustawionymi na 0755. Jeśli atrybut ma wartość false lub nie jest podany, domyślnie ustawiona jest wartość 0600.

Dodano w wersji 3.2.3.

Na przykład:

edgemicro:
 logging:
   disableStrictLogFile: true

Sprawdzone metody konserwacji plików dziennika

Z czasem gromadzą się dane w pliku dziennika, dlatego Apigee zaleca stosowanie tych praktyk:

• Ponieważ pliki dzienników mogą być dość duże, upewnij się, że w katalogu plików dzienników jest wystarczająco dużo wolnego miejsca. Zapoznaj się z sekcjami Gdzie są przechowywane pliki dziennika i Jak zmienić domyślny katalog plików dziennika.
• Co najmniej raz w tygodniu usuwaj pliki dziennika lub przenoś je do osobnego katalogu archiwum.
• Jeśli Twoja zasada polega na usuwaniu logów, możesz użyć polecenia wiersza poleceń edgemicro log -c, aby usunąć (wyczyścić) starsze logi.

Konwencja nazewnictwa plików dziennika

Każda instancja Edge Microgateway generuje plik dziennika o rozszerzeniu .log. Konwencja nazewnictwa plików dziennika:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Na przykład:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

Informacje o zawartości pliku dziennika

Dodano w wersji 2.3.3

Domyślnie usługa rejestrowania pomija dane JSON dotyczące pobranych serwerów proxy, produktów i tokenów sieciowych JSON (JWT). Jeśli chcesz wyświetlać te obiekty na konsoli, ustaw flagę wiersza poleceńDEBUG=* podczas uruchamiania Edge Microgateway. Na przykład:

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

Treść pliku dziennika „api”

Plik dziennika „api” zawiera szczegółowe informacje o przepływie żądań i odpowiedzi przez Edge Microgateway. Pliki dziennika „api” mają takie nazwy:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

W pliku dziennika „api” rejestrowane są 4 zdarzenia dotyczące każdej żądania wysłanego do Edge Microgateway:

• Odbiór prośby od klienta
• Żądanie wychodzące wysłane do celu
• Odpowiedź od docelowego odbiorcy
• Odpowiedź wysyłana do klienta

Każdy z tych wpisów jest reprezentowany za pomocą skrótu, aby pliki dziennika były bardziej zwarte. Oto 4 przykładowe wpisy odpowiadające 4 zdarzenia. W pliku dziennika wyglądają tak (numery wierszy służą tylko do celów informacyjnych w dokumencie i nie pojawiają się w pliku dziennika):

(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

Przyjrzyjmy się im kolejno:

1. Przykład żądania przychodzącego od klienta:

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

• 1436403888651 – sygnatura czasu w formie daty w systemie uniksowym
• info – poziom rejestrowania. Ta wartość zależy od kontekstu transakcji i poziomu rejestrowania ustawionego w konfiguracji edgemicro. Zobacz Jak ustawić poziom rejestrowania. W przypadku rekordów statystyk poziom jest ustawiony na stats. Dane statystyczne są raportowane w regularnych odstępach czasu określonych w konfiguracji stats_log_interval. Zobacz też Jak zmienić interwały logowania.
• req – identyfikuje zdarzenie. W takim przypadku poproś o to klienta.
• m – czasownik HTTP użyty w żądaniu.
• u – część adresu URL po ścieżce podstawowej.
• h – nazwa hosta i numer portu, na którym Edge Microgateway nasłuchuje.
• r – zdalny host i port, z których pochodzi żądanie klienta.
• i – identyfikator żądania. Wszystkie 4 wejścia zdarzenia będą miały ten sam identyfikator. Każde żądanie ma przypisany unikalny identyfikator żądania. Korelacja rekordów logów według identyfikatora żądania może dostarczyć cennych informacji o opóźnieniu docelowym.
• d – czas w milisekundach od momentu otrzymania żądania przez Edge Microgateway. W tym przykładzie odpowiedź docelowa dla żądania 0 została odebrana po 7 milisekundach (wiersz 3), a odpowiedź została wysłana do klienta po kolejnych 4 milisekundach (wiersz 4). Innymi słowy łączny czas oczekiwania na żądanie wynosił 11 milisekund, z czego 7 milisekund zajęło to docelowe urządzenie, a 4 milisekundy – sama Edge Microgateway.

2. Przykład żądania wychodzącego wysłanego do celu:

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

• 1436403888651 – sygnatura czasu w formie daty w systemie uniksowym
• info – poziom rejestrowania. Ta wartość zależy od kontekstu transakcji i poziomu rejestrowania ustawionego w konfiguracji edgemicro. Zobacz Jak ustawić poziom rejestrowania. W przypadku rekordów statystyk poziom jest ustawiony na stats. Dane statystyczne są raportowane w regularnych odstępach czasu określonych w konfiguracji stats_log_interval. Zobacz też Jak zmienić interwały logowania.
• treq – identyfikuje zdarzenie. W tym przypadku jest to prośba o cel.
• m – czasownik HTTP użyty w żądaniu docelowym.
• u – część adresu URL po ścieżce podstawowej.
• h – nazwa hosta i numer portu docelowego backendu.
• i – identyfikator wpisu w dzienniku. Wszystkie 4 wejścia zdarzenia będą miały ten sam identyfikator.

3. Przykład odpowiedzi od odbiorcy

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

1436403888651 – sygnatura czasu w formie daty w systemie uniksowym

• info – poziom rejestrowania. Ta wartość zależy od kontekstu transakcji i poziomu rejestrowania ustawionego w konfiguracji edgemicro. Zobacz Jak ustawić poziom rejestrowania. W przypadku rekordów statystyk poziom jest ustawiony na stats. Dane statystyczne są raportowane w regularnych odstępach czasu określonych w konfiguracji stats_log_interval. Zobacz też Jak zmienić interwały logowania.
• tres – identyfikuje zdarzenie. W tym przypadku jest to odpowiedź docelowa.
• s – stan odpowiedzi HTTP.
• d – czas trwania w milisekundach. Czas wykonania wywołania interfejsu API przez obiekt docelowy.
• i – identyfikator wpisu w dzienniku. Wszystkie 4 wejścia zdarzenia będą miały ten sam identyfikator.

4. Przykład odpowiedzi wysyłanej do klienta

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

1436403888651 – sygnatura czasu w formie daty w systemie uniksowym

• info – poziom rejestrowania. Ta wartość zależy od kontekstu transakcji i poziomu rejestrowania ustawionego w konfiguracji edgemicro. Zobacz Jak ustawić poziom rejestrowania. W przypadku rekordów statystyk poziom jest ustawiony na stats. Dane statystyczne są raportowane w regularnych odstępach czasu określonych w konfiguracji stats_log_interval. Zobacz też Jak zmienić interwały logowania.
• res – identyfikuje zdarzenie. W tym przypadku odpowiedź na klienta.
• s – stan odpowiedzi HTTP.
• d – czas trwania w milisekundach. Jest to łączny czas trwania wywołania interfejsu API, w tym czas trwania wywołania docelowego interfejsu API i czas trwania wywołania przez Edge Microgateway.
• i – identyfikator wpisu w dzienniku. Wszystkie 4 wejścia zdarzenia będą miały ten sam identyfikator.

Harmonogram plików dziennika

Pliki dziennika są rotowane w okresie określonym przez atrybut rotate_interval konfiguracji. Do tego samego pliku z logami będą nadal dodawane wpisy, dopóki nie upłynie interwał rotacji. Jednak za każdym razem, gdy Edge Microgateway zostanie ponownie uruchomiony, otrzyma nowy identyfikator UID i utworzy nowy zestaw plików dziennika z tym identyfikatorem. Zobacz też sprawdzone metody konserwacji plików dzienników.

Komunikaty o błędach

Niektóre wpisy w logu będą zawierać komunikaty o błędach. Aby dowiedzieć się, gdzie i dlaczego występują błędy, zapoznaj się z informacjami o błędach Edge Microgateway.

Informacje o konfiguracji Edge Microgateway

Lokalizacja pliku konfiguracji

Atrybuty konfiguracji opisane w tej sekcji znajdują się w pliku konfiguracji Edge Microgateway. Zobacz też Wprowadzanie zmian w konfiguracji.

Atrybuty edge_config

Te ustawienia służą do konfigurowania interakcji między wystąpieniem Edge Microgateway a Apigee Edge.

• bootstrap: (domyślnie: brak) adres URL wskazujący na usługę w Microgateway działającą w Apigee Edge. Edge Microgateway używa tej usługi do komunikowania się z Apigee Edge. Ten adres URL jest zwracany po wykonaniu polecenia generowania pary kluczy publiczno-prywatnej: edgemicro genkeys. Szczegółowe informacje znajdziesz w artykule Konfigurowanie i konfigurowanie Edge Microgateway.
• jwt_public_key: (domyślnie: brak) adres URL wskazujący na serwer proxy Edge Microgateway, który jest wdrożony w Apigee Edge. Ten serwer proxy służy jako punkt końcowy uwierzytelniania do wydawania podpisanych tokenów dostępu klientom. Ten adres URL jest zwracany po wykonaniu polecenia wdrażania serwera proxy: edgemicro configure. Szczegółowe informacje znajdziesz w artykule Konfigurowanie i konfigurowanie Edge Microgateway.
• quotaUri: ustaw tę właściwość konfiguracji, jeśli chcesz zarządzać limitami za pomocą serwera proxy edgemicro-auth, który jest wdrażany w Twojej organizacji. Jeśli ta właściwość nie jest ustawiona, punkt końcowy limitu jest domyślnie ustawiany na wewnętrzny punkt końcowy Edge Microgateway.

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

Atrybuty edgemicro

Te ustawienia konfigurują proces Edge Microgateway.

• port: (domyślnie 8000) numer portu, na którym nasłuchuje proces Edge Microgateway.
• max_connections: (domyślnie -1) Określa maksymalną liczbę jednoczesnych połączeń przychodzących, które może odbierać Edge Microgateway. Jeśli ta liczba zostanie przekroczona, zwrócony zostanie ten stan:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (domyślnie -1) Maksymalna liczba jednoczesnych żądań, które Edge Microgateway może otrzymać przed zamknięciem połączenia. To ustawienie ma na celu zapobieganie atakom typu DoS. Zwykle ustawia się wartość większą niż max_connections.
• Logowanie:
  • level: (domyślnie: błąd)
    • info – (zalecane) rejestruje wszystkie żądania i odpowiedzi przesyłane przez instancję Edge Microgateway.
    • warn – rejestruje tylko komunikaty ostrzegawcze.
    • error – rejestruje tylko komunikaty o błędach.
    • debug – rejestruje komunikaty debugowania wraz z informacjami, ostrzeżeniami i komunikatami o błędach.
    • trace (Śledzenie) – rejestruje informacje o błędach wraz z informacjami, ostrzeżeniami i komunikatami o błędach.
    • brak – plik dziennika nie jest tworzony;
  • dir: (domyślnie /var/tmp) Katalog, w którym są przechowywane pliki dziennika.
  • stats_log_interval: (domyślnie 60) Przerwa w sekundach, w której rekord statystyk jest zapisywany w pliku dziennika interfejsu API.
  • rotate_interval: (domyślnie 24) Interwał w godzinach, w jakim są obracane pliki dziennika.

• wtyczki: wtyczki zwiększają funkcjonalność Edge Microgateway; Szczegółowe informacje o tworzeniu wtyczek znajdziesz w artykule Tworzenie niestandardowych wtyczek.

• dir: ścieżka względna z katalogu ./gateway do katalogu ./plugins lub ścieżka bezwzględna.
• sequence: lista modułów wtyczki do dodania do instancji Edge Microgateway. Moduły będą się wykonywać w kolejności, w jakiej są tu podane.

• debug: dodaje debugowanie zdalne do procesu Edge Microgateway.
  • port: numer portu, na którym ma nasłuchiwać. Na przykład możesz skonfigurować debuger IDE do nasłuchiwania na tym porcie.
  • args: argumenty procesu debugowania. Na przykład: args --nolazy
    
• config_change_poll_interval: (domyślnie 600 sekund) Edge Microgateway okresowo wczytuje nową konfigurację i wykonuje odświeżanie, jeśli coś się zmieniło. Odpytywanie rejestruje wszystkie zmiany wprowadzone w Edge (np. zmiany produktów, proxy obsługujące mikrobramki itp.), a także zmiany wprowadzone w lokalnym pliku konfiguracji.
  
• disable_config_poll_interval: (domyślnie: fałsz) ustaw na prawda, aby wyłączyć automatyczne sprawdzanie zmian.
• request_timeout: ustawia limit czasu dla żądań docelowych. Czas oczekiwania jest ustawiany w sekundach. Jeśli wystąpi limit czasu, Edge Microgateway odpowie kodem stanu 504. (Dodano w wersji 2.4.x)
• keep_alive_timeout: ta właściwość umożliwia ustawienie limitu czasu (w milisekundach) dla Edge Microgateway. (domyślnie 5 sekund) (dodano w wersji 3.0.6)
• headers_timeout: ten atrybut ogranicza czas (w milisekundach), przez który rozsyłacz HTTP będzie oczekiwał na otrzymanie pełnych nagłówków HTTP.

  Na przykład:

  edgemicro:
    keep_alive_timeout: 6000
    headers_timeout: 12000

  Wewnętrznie parametr ustawia atrybut Node.js Server.headersTimeout w żądaniach. (domyślnie o 5 sekund więcej niż czas ustawiony za pomocą parametru edgemicro.keep_alive_timeout). To domyślne ustawienie zapobiega błędnemu rozłączaniu połączeń przez systemy równoważenia obciążenia lub serwery proxy. (dodano w wersji 3.1.1)

• noRuleMatchAction: (String) działanie do wykonania (zezwalanie lub odmawianie dostępu), jeśli reguła zgodności określona w pluginie accesscontrol nie została rozwiązana (nie ma dopasowania). Prawidłowe wartości: ALLOW lub DENY. Wartość domyślna: ALLOW (dodano w wersji 3.1.7).
• enableAnalytics: (domyślnie: true) ustaw atrybut na false, aby zapobiec wczytywaniu wtyczki analitycznej. W takim przypadku nie będzie wykonywanych żadnych wywołań do usług analitycznych Apigee Edge. Jeśli atrybut ma wartość prawda lub nie jest podany, wtyczka analityczna będzie działać normalnie. Więcej informacji znajdziesz w sekcji Atrybuty edgemicro. (dodano w wersji 3.1.8).

  Przykład:

  edgemicro
    enableAnalytics=false|true

• on_target_response_abort: ten atrybut umożliwia kontrolowanie zachowania Edge Microgateway, jeśli połączenie między klientem (Edge Microgateway) a serwerem docelowym zostanie zamknięte przedwcześnie.

  Wartość	Opis
  Domyślny	Jeśli wartość on_target_response_abort nie jest określona, domyślnym działaniem jest obcinanie odpowiedzi bez wyświetlania błędu. W plikach dziennika wyświetlany jest komunikat ostrzeżenia z wartością targetResponse aborted i kodem odpowiedzi 502.
  appendErrorToClientResponseBody	Klientowi zwracany jest błąd niestandardowy TargetResponseAborted. W plikach dziennika wyświetlany jest komunikat ostrzeżenia z wartością targetResponse aborted i kodem odpowiedzi 502. Ponadto błąd TargetResponseAborted jest rejestrowany z komunikatem Target response ended prematurely.
  abortClientRequest	Edge Microgateway przerywa żądanie, a w plikach dziennika zapisywane jest ostrzeżenie: TargetResponseAborted z kodem stanu żądania 502.

Przykład:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

atrybuty nagłówków

Te ustawienia określają sposób traktowania niektórych nagłówków HTTP.

• x-forwarded-for: (domyślnie: prawda) ustaw na wartość false, aby zapobiec przekazywaniu do miejsca docelowego nagłówków x-forwarded-for. Pamiętaj, że jeśli w żądaniu występuje nagłówek x-forwarded-for, jego wartość zostanie ustawiona na wartość client-ip w Edge Analytics.
• x-forwarded-host: (domyślnie: prawda) ustaw na wartość false, aby zapobiec przekazywaniu do celu nagłówków x-forwarded-host.
• x-request-id: (domyślnie: prawda) ustaw jako fałsz, aby zapobiec przekazywaniu nagłówków x-request-id do miejsca docelowego.
• x-response-time: (domyślnie: prawda) ustaw na fałsz, aby zapobiec przekazywaniu do celu nagłówków x-response-time.
• via: (domyślnie: prawda) ustaw wartość na fałsz, aby zapobiec przekazywaniu nagłówków via do elementu docelowego.

atrybuty oauth

Te ustawienia określają sposób wymuszania uwierzytelniania klienta przez Edge Microgateway.

• allowNoAuthorization: (domyślnie: false) jeśli ma wartość true, wywołania interfejsu API mogą przechodzić przez Edge Microgateway bez nagłówka Authorization. Ustaw tę opcję na „false” (fałsz), aby wymagać nagłówka Authorization (domyślnie).
• allowInvalidAuthorization: (domyślnie: fałsz) jeśli ta opcja ma wartość prawda, wywołania interfejsu API mogą się powieść, jeśli token przekazany w nagłówku Authorization jest nieprawidłowy lub wygasł. Ustaw tę opcję na „fałsz”, aby wymagać prawidłowych tokenów (domyślnie).
• authorization-header: (domyślnie: Authorization: Bearer) nagłówek używany do wysyłania tokena dostępu do Edge Microgateway. Warto zmienić domyślne ustawienie w przypadku, gdy miejsce docelowe musi używać nagłówka Authorization do innego celu.
• api-key-header: (domyślnie: x-api-key) nazwa nagłówka lub parametru zapytania służącego do przekazywania klucza interfejsu API do Edge Microgateway. Zobacz też Korzystanie z klucza interfejsu API.
• keep-authorization-header: (domyślnie: fałsz) jeśli ustawisz tę opcję na prawdę, nagłówek Authorization wysłany w żądaniu zostanie przekazany do docelowego adresu (zostanie zachowany).
• allowOAuthOnly – jeśli ta opcja jest ustawiona na wartość true (prawda), każdy interfejs API musi zawierać nagłówek Authorization z tokenem dostępu Bearer. Umożliwia zezwolenie na korzystanie tylko z modelu zabezpieczeń OAuth (przy zachowaniu zgodności wstecznej). (dodano w wersji 2.4.x)
• allowAPIKeyOnly – jeśli ta opcja jest ustawiona na wartość true, każdy interfejs API musi zawierać nagłówek x-api-key (lub niestandardową lokalizację) z kluczem API.Umożliwia zezwolenie tylko na model zabezpieczeń z kluczem API (przy zachowaniu zgodności wstecznej). (Dodano w wersji 2.4.x)
• gracePeriod – ten parametr pomaga zapobiegać błędom spowodowanym niewielkimi rozbieżnościami między zegarem systemowym a czasem wystawienia (iat) lub czasem ważności (nbf) określonym w tokenie autoryzacji JWT. Ustaw ten parametr na liczbę sekund, aby uwzględnić takie rozbieżności. (dodano w wersji 2.5.7)

Atrybuty specyficzne dla wtyczki

Szczegółowe informacje o atrybutach, które można skonfigurować w poszczególnych wtyczkach, znajdziesz w sekcji Korzystanie z wtyczek.

Filtrowanie serwerów proxy

Możesz filtrować, które proxy obsługujące mikrobramki będą przetwarzane przez instancję Edge Microgateway. Gdy Edge Microgateway się uruchamia, pobiera wszystkie proxy obsługujące mikrobramki w organizacji, z którą jest powiązany. Aby ograniczyć liczbę proxy, które będzie przetwarzać mikrobramka, użyj tej konfiguracji. Na przykład ta konfiguracja ogranicza serwery proxy, które przetwarza mikrobramka, do 3 wartości: edgemicro_proxy-1, edgemicro_proxy-2 i edgemicro_proxy-3:

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

Filtrowanie usług według nazwy

Aby ograniczyć liczbę produktów API, które Edge Microgateway pobiera i przetwarza, użyj tej konfiguracji. Aby filtrować pobrane produkty, dodaj parametr zapytania productnamefilter do interfejsu API /products wymienionego w pliku Edge Microgateway *.config.yaml. Na przykład:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

Pamiętaj, że wartość parametru zapytania musi być podana w formacie wyrażenia regularnego i musi być zakodowana na potrzeby adresu URL. Na przykład wyrażenie regularne ^[Ee]dgemicro.*$ odfiltrowuje takie nazwy jak: "edgemicro-test-1", "edgemicro_demo" i "Edgemicro_New_Demo". Wartość zakodowana na potrzeby adresu URL, odpowiednia do użycia w parametrze zapytania, to: %5E%5BEe%5Ddgemicro.%2A%24.

Z tego wyjścia debugowania wynika, że pobrane zostały tylko produkty z filtra:

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

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

         ]
      },
      {
         "apiResources":[

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

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

         ]
      }
   ]
}

Filtrowanie produktów według atrybutów niestandardowych

Aby filtrować produkty według atrybutów niestandardowych:

1. W interfejsie Edge wybierz serwer proxy edgemicro_auth w organizacji lub środowisku, w którym skonfigurowano Edge Microgateway.
2. W sekcji Rozwijanie otwórz w edytorze zasadę JavaCallout.
3. Dodaj atrybut niestandardowy o kluczu products.filter.attributes z listą nazw atrybutów rozdzielonych przecinkami. Do Edge Microgateway będą zwracane tylko produkty, które zawierają dowolne nazwy atrybutów niestandardowych.
4. Opcjonalnie możesz wyłączyć sprawdzanie, aby sprawdzić, czy produkt jest włączony w bieżącym środowisku. Aby to zrobić, ustaw atrybut niestandardowy products.filter.env.enable na false. (wartość domyślna to „PRAWDA”).
5. (dotyczy tylko chmury Private Cloud) Jeśli korzystasz z Edge for Private Cloud, ustaw właściwość org.noncps na true, aby pobierać produkty w środowiskach innych niż CPS.

Na przykład:

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

Filtrowanie produktów według stanu odwołania

Produkty API mają 3 kody stanu: Oczekujący, Zatwierdzony i Odwołany. Do zasady Ustaw zmienne JWT w proxy edgemicro-auth dodano nową właściwość o nazwie allowProductStatus. Aby użyć tej właściwości do filtrowania produktów interfejsu API wymienionych w JWT:

1. Otwórz w edytorze proxy Apigee proxy edgemicro-auth.
2. Dodaj do pliku XML reguły SetJWTVariables właściwość allowProductStatus i wskaż rozdzieloną przecinkami listę kodów stanu, według których chcesz filtrować. Aby na przykład filtrować według stanu Oczekuje i Anulowano:

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

   Jeśli chcesz, aby wyświetlane były tylko produkty zatwierdzone, ustaw tę właściwość w ten sposób:

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

3. Zapisz serwer proxy.

   Jeśli tag Usługa jest nieobecny, w tokenie JWT będą wymienione produkty ze wszystkimi kodami stanu.

   Aby korzystać z tej nowej usługi, musisz zaktualizować serwer proxy edgemicro-auth.

Konfigurowanie częstotliwości przesyłania danych analitycznych

Za pomocą tych parametrów konfiguracji możesz kontrolować częstotliwość wysyłania danych analitycznych z Edge Microgateway do Apigee:

• bufferSize (opcjonalnie): maksymalna liczba rekordów Analytics, które może pomieścić bufor, zanim zacznie usuwać najstarsze rekordy. Wartość domyślna: 10000
• batchSize (opcjonalnie): maksymalny rozmiar partii rekordów analitycznych wysyłanych do Apigee. Wartość domyślna: 500
• flushInterval (opcjonalnie): liczba milisekund między każdym opróżnieniem zbioru rekordów analitycznych wysyłanych do Apigee. Domyślnie: 5000

Na przykład:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Maskowanie danych analitycznych

Poniższa konfiguracja uniemożliwia wyświetlanie informacji o ścieżce żądania w statystykach Edge. Aby ukryć identyfikator URI żądania lub ścieżkę żądania, dodaj do konfiguracji mikrobramki następujące informacje. Pamiętaj, że identyfikator URI składa się z części nazwy hosta i ścieżki żądania.

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

Separowanie wywołań interfejsu API w Edge Analytics

Możesz skonfigurować wtyczkę analityczną, aby oddzielić konkretną ścieżkę interfejsu API, tak aby była widoczna jako osobny serwer proxy na panelach Edge Analytics. Możesz na przykład oddzielić interfejs API kontroli stanu na panelu, aby uniknąć pomylenia go z rzeczywistymi wywołaniami interfejsu API proxy. W panelu Analytics oddzielone proksy mają następujący schemat nazewnictwa:

edgemicro_proxyname-health

Na ilustracji widać 2 oddzielne serwery proxy w panelu Analytics: edgemicro_hello-health i edgemicro_mock-health:

Używaj tych parametrów, aby oddzielić ścieżki względne od bezwzględnych na panelu Analytics jako oddzielne proxy:

• relativePath (opcjonalnie): określa ścieżkę względną do podziału w panelu Analytics. Jeśli np. określisz wartość /healthcheck, wszystkie wywołania interfejsu API zawierające ścieżkę /healthcheck będą widoczne na panelu jako edgemicro_proxyname-health. Pamiętaj, że ten parametr ignoruje ścieżkę domyślną serwera proxy. Aby podzielić dane na podstawie pełnej ścieżki, w tym ścieżki podstawowej, użyj flagi proxyPath.
• proxyPath (opcjonalnie): określa pełną ścieżkę serwera proxy interfejsu API, w tym ścieżkę podstawową serwera proxy, która służy do podziału na panele analityki. Jeśli np. podasz wartość /mocktarget/healthcheck, gdzie /mocktarget jest ścieżką podstawową serwera proxy, wszystkie wywołania interfejsu API z ścieżką /mocktarget/healthcheck będą widoczne w panelu jako edgemicro_proxyname-health.

Na przykład w poniższej konfiguracji każda ścieżka interfejsu API zawierająca /healthcheck będzie oddzielona przez wtyczkę Analytics. Oznacza to, że /foo/healthcheck i /foo/bar/healthcheck będą rozdzielane jako osobne serwery proxy o nazwie edgemicro_proxyname-health na pulpicie Analytics.

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

W tej konfiguracji każdy interfejs API z ścieżką proxy /mocktarget/healthcheck będzie oddzielony jako osobny serwer proxy o nazwie edgemicro_proxyname-health na panelu Analytics.

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

Konfigurowanie bramki Edge Microgateway za zaporą sieciową firmy

Używanie serwera proxy HTTP do komunikacji z Apigee Edge

Dodano w wersji 3.1.2.

Aby używać serwera proxy HTTP do komunikacji między Edge Microgateway a Apigee Edge:

1. Ustaw zmienne środowiskowe HTTP_PROXY, HTTPS_PROXY i NO_PROXY. Te zmienne kontrolują hosty dla każdego serwera proxy HTTP, którego chcesz używać do komunikacji z Apigee Edge, lub hosty, które nie powinny obsługiwać komunikacji z Apigee Edge. Na przykład:

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

   Pamiętaj, że NO_PROXY może być rozdzieloną przecinkami listą domen, do których Edge Microgateway nie powinien przekierowywać ruchu.

   Więcej informacji o tych zmiennych znajdziesz na stronie https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.

2. Ponownie uruchom Edge Microgateway.

Używanie serwera proxy HTTP do komunikacji docelowej

Dodano w wersji 3.1.2.

Aby używać serwera proxy HTTP do komunikacji między Edge Microgateway a celami w backendzie: wykonaj te czynności:

1. Dodaj do pliku konfiguracji mikrobramki następującą konfigurację:

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

   Gdzie:

   • tunnel: (opcjonalnie) jeśli ta opcja jest ustawiona na wartość true, Edge Microgateway używa metody HTTP CONNECT do tunelowania żądań HTTP przez pojedyncze połączenie TCP. (to samo dotyczy zmiennych środowiskowych, o których mowa poniżej, służących do konfigurowania serwera proxy, jeśli są one włączone do obsługi TLS). Wartość domyślna: false
   • url: adres URL serwera proxy HTTP.
   • bypass: (opcjonalnie) określa co najmniej 1 adres URL docelowego serwera hosta, oddzielony przecinkami, który ma pomijać serwer proxy HTTP. Jeśli ta właściwość nie jest ustawiona, użyj zmiennej środowiskowej NO_PROXY, aby określić, które adresy URL docelowe mają być pomijane.
   • enabled: jeśli wartość parametru proxy.url to true, użyj wartości proxy.url dla serwera proxy HTTP. Jeśli wartość to prawda, a zmienna proxy.url nie jest ustawiona, używaj serwerów proxy określonych w zmiennych środowiskowych HTTP_PROXY i HTTPS_PROXY, zgodnie z opisem w artykule Używanie serwera proxy HTTP do komunikacji z Apigee Edge.

   Na przykład:

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

2. Ponownie uruchom Edge Microgateway.

Używanie symboli wieloznacznych w serwerach proxy obsługujących Microgateway

W ścieżce podstawowej serwera proxy edgemicro_* (z obsługą mikrobramki) możesz użyć co najmniej jednego symbolu wieloznacznego „*”. Na przykład ścieżka podstawowa /team/*/members pozwala klientom wywoływać adresy https://[host]/team/blue/members i https://[host]/team/green/members bez konieczności tworzenia nowych serwerów proxy API do obsługi nowych zespołów. Pamiętaj, że /**/ nie jest obsługiwany.

Ważne: Apigee NIE obsługuje używania symbolu wieloznacznego „*” jako pierwszego elementu ścieżki podstawowej. Na przykład NIE jest obsługiwane wyszukiwanie /*/.

Rotacja kluczy JWT

Po wygenerowaniu tokena JWT może być konieczna zmiana pary kluczy publiczny-prywatny przechowywanej w zaszyfrowanym KVM w Edge. Proces generowania nowej pary kluczy nazywa się rotacją klucza.

Jak Edge Microgateway korzysta z tokenów JWT

Token internetowy JSON (JWT) to standard tokenów opisany w RFC7519. Token JWT umożliwia podpisywanie zestawu deklaracji, które można zweryfikować w sposób niezawodny przez odbiorcę tokena JWT.

Możesz wygenerować JWT za pomocą interfejsu wiersza poleceń i użyć go w nagłówku Authorization wywołań interfejsu API zamiast klucza API. Na przykład:

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

Informacje o generowaniu tokenów JWT za pomocą interfejsu wiersza poleceń znajdziesz w artykule Generowanie tokena.

Co to jest rotacja klucza?

Po wygenerowaniu tokena JWT może być konieczna zmiana pary kluczy publiczny-prywatny przechowywanej w zaszyfrowanym KVM w Edge. Proces generowania nowej pary kluczy nazywa się rotacją klucza. Gdy rotujesz klucze, nowa para kluczy prywatnych/publicznych jest generowana i przechowywana w KVM „microgateway” w organizacji/środowisku Apigee Edge. Dodatkowo stary klucz publiczny jest przechowywany wraz z pierwotną wartością identyfikatora klucza.

Aby wygenerować token JWT, Edge używa informacji przechowywanych w zaszyfrowanym KVM. Podczas początkowej konfiguracji (konfigurowania) został utworzony i wypełniony kluczami KVM o nazwie microgateway. Klucze w KVM służą do podpisywania i szyfrowania tokena JWT.

Klucze KVM obejmują:

• private_key – najnowszy (najnowiej utworzony) klucz prywatny RSA używany do podpisywania tokenów JWT.

• public_key – najnowszy (najnowiej utworzony) certyfikat używany do weryfikowania tokenów JWT podpisanych za pomocą klucza private_key.

• private_key_kid – najnowszy (najnowo utworzony) identyfikator klucza prywatnego. Ten identyfikator klucza jest powiązany z wartością private_key i służy do obsługi rotacji kluczy.

• public_key1_kid – najnowszy (najnowo utworzony) identyfikator klucza publicznego. Ten klucz jest powiązany z wartością public_key1 i służy do obsługi rotacji kluczy. Ta wartość jest taka sama jak klucz prywatny.

• public_key1 – najnowszy (najnowiej utworzony) klucz publiczny.

Podczas rotacji kluczy dotychczasowe wartości kluczy są zastępowane na mapie, a nowe klucze są dodawane, aby zachować stare klucze publiczne. Na przykład:

• public_key2_kid – stary identyfikator klucza publicznego. Ten klucz jest powiązany z wartością public_key2 i służy do obsługi rotacji kluczy.

• public_key2 – stary klucz publiczny.

Tokeny JWT przedstawione do weryfikacji będą weryfikowane za pomocą nowego klucza publicznego. Jeśli weryfikacja się nie powiedzie, używany będzie stary klucz publiczny, dopóki nie wygaśnie token JWT (po upływie interwału token_expiry*, domyślnie 30 minut). W ten sposób możesz „rotować” klucze bez natychmiastowego zakłócania ruchu w interfejsie API.

Jak wykonać rotację klucza

Z tej sekcji dowiesz się, jak przeprowadzić rotację kluczy.

1. Aby uaktualnić KVM, użyj polecenia edgemicro upgradekvm. Szczegółowe informacje o wykonywaniu tego polecenia znajdziesz w artykule Uaktualnianie KVM. Wystarczy to zrobić tylko raz.
2. Aby uaktualnić serwer proxy edgemicro-oauth, użyj polecenia edgemicro upgradeauth. Szczegółowe informacje o wykonywaniu tego polecenia znajdziesz w artykule Aktualizowanie serwera proxy edgemicro-auth. Wystarczy to zrobić tylko raz.
3. Dodaj ten wiersz do pliku ~/.edgemicro/org-env-config.yaml, w którym musisz podać tę samą organizację i to samo środowisko, które zostały skonfigurowane dla mikrobramki:

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

4. Aby wykonać rotację kluczy, uruchom odpowiednie polecenie. Szczegółowe informacje o tym poleceniu znajdziesz w artykule Rotowanie kluczy.

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

   Na przykład:

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

Po rotacji kluczy Edge zwraca wiele kluczy do Edge Microgateway. W następnym przykładzie każdy klucz ma unikalną wartość „kid” (identyfikator klucza). Następnie mikrobramka używa tych kluczy do sprawdzania tokenów autoryzacji. Jeśli weryfikacja tokena zakończy się niepowodzeniem, mikrobramka sprawdzi, czy w zbiorze kluczy jest starszy klucz, i spróbuje użyć tego klucza. Format zwracanych kluczy to klucz internetowy JSON (JWK). Więcej informacji o tym formacie znajdziesz w dokumencie 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"
    }
  ]
}

Konfigurowanie opóźnienia „nie wcześniej niż”

W wersjach 3.1.5 i starszych nowy klucz prywatny wygenerowany przez polecenie rotatekey zaczął obowiązywać natychmiast, a nowe wygenerowane tokeny były podpisywane nowym kluczem prywatnym. Jednak nowy klucz publiczny był udostępniany instancjom Edge Microgateway tylko co 10 minut (domyślnie), gdy odświeżano konfigurację mikrobramki. Z powodu tego opóźnienia między podpisaniem tokena a odświeżeniem instancji mikrobramki tokeny podpisane najnowszym kluczem byłyby odrzucane, dopóki wszystkie instancje nie otrzymały najnowszego klucza publicznego.

W przypadku istnienia wielu instancji mikrobramki opóźnienie w dostępie do klucza publicznego czasami powodowało sporadyczne błędy w czasie wykonywania z kodem 403, ponieważ weryfikacja tokenu była prawidłowa w jednej instancji, ale nie w innej, dopóki nie odświeżono wszystkich instancji.

Począwszy od wersji 3.1.6 nowy parametr polecenia rotatekey umożliwia określenie opóźnienia, po którym nowy klucz prywatny zacznie obowiązywać. Dzięki temu wszystkie instancje mikrobramki będą miały czas na odświeżenie i otrzymanie nowego klucza publicznego. Nowa flaga to --nbf, która oznacza „nie wcześniej”. Ten parametr przyjmuje wartość całkowitą, czyli liczbę minut opóźnienia.

W tym przykładzie opóźnienie wynosi 15 minut:

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

Pamiętaj, że warto ustawić opóźnienie na dłuższy czas niż parametr konfiguracji config_change_poll_internal, który domyślnie wynosi 10 minut. Zobacz też atrybuty edgemicro.

Filtrowanie pobranych serwerów proxy

Domyślnie Edge Microgateway pobiera wszystkie proxy w organizacji Edge, których nazwy zaczynają się od prefiksu „edgemicro_”. Możesz zmienić to ustawienie domyślne, aby pobierać proxy, których nazwy pasują do określonego wzorca.

1. Otwórz plik konfiguracji Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Dodaj element proxyPattern w sekcji edge_config. Na przykład ten wzór spowoduje pobranie proxy takich jak edgemicro_foo, edgemicro_fast i edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Określanie produktów bez serwerów proxy interfejsu API

W Apigee Edge możesz utworzyć usługę API, która nie zawiera żadnych proxy interfejsu API. Ta konfiguracja produktu umożliwia korzystanie z klucza interfejsu API powiązanego z tym produktem w przypadku dowolnego serwera proxy wdrożonego w organizacji. Od wersji 2.5.4 brama Edge Microgateway obsługuje tę konfigurację produktu.

Debugowanie i rozwiązywanie problemów

Łączenie z debugerem

Edge Microgateway możesz uruchomić za pomocą debugera, takiego jak node-inspector. Jest to przydatne podczas rozwiązywania problemów i debugowania wtyczek niestandardowych.

1. Uruchom ponownie Edge Microgateway w trybie debugowania. Aby to zrobić, dodaj DEBUG=* na początku polecenia start:

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Aby przekierować dane debugowania do pliku, użyj tego polecenia:

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

2. Uruchom debuger i skonfiguruj go tak, aby nasłuchiwał na numerze portu przeznaczonym do procesu debugowania.
3. Możesz teraz przejrzeć kod Edge Microgateway, ustawić punkty kontrolne, obserwować wyrażenia itp.

Możesz określić standardowe flagi Node.js związane z trybem debugowania. Na przykład: --nolazy pomaga w debugowaniu kodu asynchronicznego.

Sprawdzanie plików dziennika

Jeśli wystąpią problemy, sprawdź pliki dziennika pod kątem szczegółów wykonania i informacji o błędach. Więcej informacji znajdziesz w artykule Zarządzanie plikami dzienników.

Zabezpieczanie kluczy interfejsu API

Klucze interfejsu API stanowią prosty mechanizm uwierzytelniania klientów przesyłających żądania do Edge Microgateway. Klucz interfejsu API możesz uzyskać, kopiując wartość klucza konsumenta (zwanego też identyfikatorem klienta) z produktu Apigee Edge, który zawiera proxy uwierzytelniania Edge Microgateway.

Buforowanie kluczy

Klucze interfejsu API są wymieniane na tokeny tożsamości, które są przechowywane w pamięci podręcznej. Możesz wyłączyć buforowanie, ustawiając nagłówek Cache-Control: no-cache w przychodzących żądaniach do Edge Microgateway.

Używanie klucza API

Klucz interfejsu API możesz przekazać w żądaniu do interfejsu API jako parametr zapytania lub w nagłówku. Domyślnie nazwa parametru w nagłówku i w zapytaniu to x-api-key.

Przykład parametru zapytania:

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

Przykładowy nagłówek:

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

Konfigurowanie nazwy klucza interfejsu API

Domyślnie x-api-key jest nazwą używaną zarówno w nagłówku klucza interfejsu API, jak i w parametrze zapytania. Możesz zmienić tę wartość domyślną w pliku konfiguracji, zgodnie z instrukcjami podanymi w artykule Wprowadzanie zmian w konfiguracji. Aby na przykład zmienić nazwę na apiKey:

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

W tym przykładzie zarówno parametr zapytania, jak i nazwa nagłówka zostały zmienione na apiKey. W żadnym z tych przypadków nazwa x-api-key nie będzie już działać. Zobacz też Wprowadzanie zmian w konfiguracji.

Na przykład:

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

Więcej informacji o używaniu kluczy interfejsu API z żądaniami proxy znajdziesz w artykule Secure Edge Microgateway.

Włączanie kodów odpowiedzi na upstream

Domyślnie wtyczka oauth zwraca tylko kody stanu błędu 4xx, jeśli odpowiedź nie ma stanu 200. Możesz zmienić to zachowanie, aby zawsze zwracał kod 4xx lub 5xx, w zależności od błędu.

Aby włączyć tę funkcję, dodaj właściwość oauth.useUpstreamResponse: true do konfiguracji mikrobramki Edge. Na przykład:

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

Zabezpieczanie tokenów OAuth2

Z tej sekcji dowiesz się, jak uzyskać tokeny dostępu OAuth2 i tokeny odświeżania. Tokeny dostępu służą do bezpiecznego wywoływania interfejsów API za pomocą mikrobramki. Tokeny odświeżania służą do uzyskiwania nowych tokenów dostępu.

Jak uzyskać token dostępu

W tej sekcji opisaliśmy, jak użyć serwera proxy edgemicro-auth, aby uzyskać token dostępu.

Token dostępu możesz też uzyskać za pomocą polecenia wiersza poleceń edgemicro token. Więcej informacji o CLI znajdziesz w artykule Zarządzanie tokenami.

Interfejs API 1. Wysyłanie danych logowania jako parametry w ciele zapytania

W adresie URL zastąp nazwy organizacji i środowiska, a także wartości identyfikatora klienta i tajemnego klucza klienta uzyskane z aplikacji dla programistów w usłudze Apigee Edge w przypadku parametrów client_id i client_secret w polu nagłówka:

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"

Interfejs API 2: wysyłanie danych logowania w nagłówku Basic Auth

Wyślij dane logowania klienta jako nagłówek podstawowego uwierzytelniania, a grant_type jako parametr formularza. Ten format polecenia jest też omawiany w dokumentach RFC 6749: The OAuth 2.0 Authorization Framework (w języku angielskim).

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"

Przykładowe dane wyjściowe

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

Jak uzyskać token odświeżania

Aby uzyskać token odświeżania, wyślij wywołanie interfejsu API do punktu końcowego /token proxy edgemicro-auth. Musisz wykonać to wywołanie interfejsu API z typem uprawnień password. Poniżej znajdziesz instrukcje.

1. Uzyskaj token dostępu i odśwież go za pomocą interfejsu API /token. Pamiętaj, że typ grantu to 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"
   }'

   Interfejs API zwraca token dostępu i token odświeżania. Odpowiedź będzie wyglądać mniej więcej tak: Pamiętaj, że wartości expires_in są liczbami całkowitymi i podawane w sekundach.

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

2. Teraz możesz użyć tokena odświeżania, aby uzyskać nowy token dostępu, wywołując punkt końcowy /refresh tego samego interfejsu API. Na przykład:

   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"
   }'

   Interfejs API zwraca nowy token dostępu. Odpowiedź wygląda mniej więcej tak:

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

Monitorowanie bez daty zakończenia

Określanie punktu końcowego pliku konfiguracji

Jeśli używasz wielu instancji Edge Microgateway, możesz zarządzać ich konfiguracjami z jednego miejsca. Aby to zrobić, określ punkt końcowy HTTP, z którego Edge Micro będzie mógł pobrać plik konfiguracji. Możesz określić ten punkt końcowy podczas uruchamiania Edge Micro za pomocą flagi -u.

Na przykład:

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

gdzie punkt końcowy mgconfig zwraca zawartość pliku konfiguracji. Jest to plik, który domyślnie znajduje się w folderze ~/.edgemicro i ma nazwę org-env-config.yaml.

Wyłączanie buforowania danych połączenia TCP

Aby wyłączyć buforowanie danych w przypadku połączeń TCP używanych przez Edge Microgateway, możesz użyć atrybutu konfiguracji nodelay.

Domyślnie połączenia TCP używają algorytmu Nagle do buforowania danych przed ich wysłaniem. Ustawienie wartości nodelay na true wyłącza to zachowanie (dane będą natychmiast wysyłane za każdym razem, gdy zostanie wywołana funkcja socket.write()). Więcej informacji znajdziesz też w dokumentacji Node.js.

Aby włączyć nodelay, zmodyfikuj plik konfiguracji Edge Micro w ten sposób:

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

Uruchamianie Edge Microgateway w trybie samodzielnym

Edge Microgateway może działać całkowicie niezależnie od zależności od Apigee Edge. Ten scenariusz, nazywany trybem samodzielnym, umożliwia uruchamianie i testowanie urządzenia Edge Microgateway bez połączenia z internetem.

W trybie samodzielnym te funkcje nie działają, ponieważ wymagają połączenia z Apigee Edge:

• OAuth i klucz API
• Limit
• Analytics

Z drugiej strony, niestandardowe wtyczki i blokada szczytowa działają normalnie, ponieważ nie wymagają połączenia z Apigee Edge. Dodatkowo nowy wtyczek o nazwie extauth umożliwia autoryzowanie wywołań interfejsu API do mikrobramki za pomocą tokena JWT w trybie samodzielnym.

Konfigurowanie i uruchamianie bramy

Aby uruchomić Edge Microgateway w trybie samodzielnym:

1. Utwórz plik konfiguracji o nazwie: $HOME/.edgemicro/$ORG-$ENV-config.yaml

   Na przykład:

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

2. Wklej do pliku ten kod:

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

3. Wyeksportuj tę zmienną środowiskową z wartością „1”:

   export EDGEMICRO_LOCAL=1

4. Uruchom to polecenie start, podając wartości, które umożliwią utworzenie instancji serwera proxy lokalnego:

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

   Gdzie:

   • $ORG to nazwa „organizacji”, której użyto w nazwie pliku konfiguracji.
   • $ENV to nazwa „env” użyta w pliku konfiguracji.
   • $LOCAL_PROXY_NAME to nazwa lokalnego serwera proxy, który zostanie utworzony. Możesz użyć dowolnej nazwy.
   • $LOCAL_PROXY_VERSION to numer wersji serwera proxy.
   • $TARGET_URL to adres URL celu serwera proxy. (Cel to usługa wywoływana przez serwer proxy).
   • $BASE_PATH to ścieżka podstawowa proxy. Ta wartość musi zaczynać się od ukośnika. W przypadku ścieżki podstawowej katalogu głównego wskaż tylko ukośnik, np. „/”.

   Na przykład:

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

5. Przetestuj konfigurację.

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

   Ponieważ wtyczka extauth znajduje się w pliku foo-bar-config.yaml, wystąpi błąd „missing_authorization”. Ta wtyczka sprawdza poprawność tokena JWT, który musi być obecny w nagłówku Authorization wywołania interfejsu API. W następnej sekcji uzyskasz token JWT, który pozwoli na bezbłędne przechodzenie wywołań interfejsu API.

Przykład: uzyskiwanie tokena autoryzacji

Ten przykład pokazuje, jak uzyskać token JWT z punktu końcowego JWT Edge Microgateway w usłudze Apigee Edge (edgemicro-auth/jwkPublicKeys). Ten punkt końcowy jest wdrażany podczas standardowej konfiguracji i konfiguracji Edge Microgateway. Aby uzyskać token JWT z punktu końcowego Apigee, musisz najpierw skonfigurować standardową bramkę Edge Microgateway i być połączony z internetem. Punkt końcowy Apigee jest tu używany tylko do celów poglądowych i nie jest wymagany. Jeśli chcesz, możesz użyć innego punktu końcowego tokena JWT. Jeśli tak, musisz uzyskać token JWT za pomocą interfejsu API udostępnionego dla tego punktu końcowego.

Aby uzyskać token za pomocą punktu końcowego edgemicro-auth/jwkPublicKeys:

1. Aby wdrożyć serwer proxy edgemicro-auth w organizacji lub środowisku w Apigee Edge, musisz wykonać standardową konfigurację i konfigurację Edge Microgateway. Jeśli ten krok został już wykonany, nie trzeba go powtarzać.
2. Jeśli wdrożyłeś Edge Microgateway w Apigee Cloud, musisz mieć połączenie z internetem, aby uzyskać token JWT z tego punktu końcowego.
3. Zatrzymanie Edge Microgateway:

   edgemicro stop

4. W utworzonym wcześniej pliku konfiguracji ($HOME/.edgemicro/org-env-config.yaml) skieruj atrybut extauth:publickey_url do punktu końcowego edgemicro-auth/jwkPublicKeys w organizacji lub środowisku Apigee Edge. Na przykład:

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

5. Ponownie uruchom Edge Microgateway w taki sam sposób, używając nazw organizacji lub środowiska, które zostały użyte w nazwie pliku konfiguracji. Na przykład:

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

6. Uzyskaj token JWT z punktu końcowego autoryzacji. Ponieważ używasz punktu końcowego edgemicro-auth/jwkPublicKeys, możesz użyć tego polecenia w interfejsie wiersza poleceń:

Możesz wygenerować token JWT dla Edge Microgateway za pomocą polecenia edgemicro token lub interfejsu API. Na przykład:

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

Gdzie:

• your_org to nazwa organizacji Apigee, w której skonfigurowano wcześniej bramkę Edge Microgateway.
• your_env to środowisko w organizacji.
• Opcja i określa klucz klienta z aplikacji dewelopera, która ma produkt, który zawiera element zastępczy edgemicro-auth.
• Opcja s określa tajny klucz klienta z aplikacji dewelopera, która ma produkt zawierający serwer proxy edgemicro-auth.

To polecenie prosi Apigee Edge o wygenerowanie tokena JWT, którego można użyć do weryfikacji wywołań interfejsu API.

Testowanie konfiguracji samodzielnej

Aby przetestować konfigurację, wywołaj interfejs API z tokenem dodanym w nagłówku Authorization w ten sposób:

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

Przykład:

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

Przykładowe dane wyjściowe:

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

Korzystanie z lokalnego serwera proxy

W trybie lokalnego serwera proxy Microgateway nie wymaga wdrażania serwera proxy z obsługą Microgateway w Apigee Edge. Zamiast tego skonfiguruj „lokalny serwer proxy”, podając nazwę lokalnego serwera proxy, ścieżkę bazową i adres URL docelowy podczas uruchamiania mikrobramki. Wywołania interfejsu API do mikrobramki są następnie wysyłane do docelowego adresu URL lokalnego serwera proxy. W pozostałych aspektach lokalny tryb serwera proxy działa tak samo jak Edge Microgateway w normalnym trybie. Uwierzytelnianie działa tak samo jak w przypadku spike zatrzymanie i egzekwowanie limitów, wtyczki niestandardowe itp.

Przypadek użycia i przykład

Tryb lokalnego serwera proxy jest przydatny, gdy musisz powiązać tylko jeden serwer proxy z instancją Edge Microgateway. Możesz na przykład wstrzyknąć Edge Microgateway do Kubernetes jako pomocniczy serwer proxy, gdzie mikrobramka i usługa działają w jednym podzie, a mikrobramka zarządza ruchem do i z usługi towarzyszącej. Na rysunku poniżej widać architekturę, w której Edge Microgateway działa jako serwer proxy w klastrze Kubernetes. Każda instancja mikrobramki komunikuje się tylko z jednym punktem końcowym w powiązanej usłudze:

Zaletą tej architektury jest to, że Edge Microgateway zapewnia zarządzanie interfejsem API w przypadku poszczególnych usług wdrożonych w środowisku kontenera, np. klastrze Kubernetes.

Konfigurowanie lokalnego trybu proxy

Aby skonfigurować Edge Microgateway do działania w trybie lokalnego serwera proxy, wykonaj te czynności:

1. Uruchom edgemicro init, aby skonfigurować lokalne środowisko konfiguracji w taki sam sposób jak w typowej konfiguracji Edge Microgateway. Zobacz też Konfigurowanie Edge Microgateway.
2. Uruchom edgemicro configure, tak jak w przypadku typowej procedury konfiguracji Edge Microgateway. Na przykład:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   To polecenie wdraża w Edge zasadę edgemicro-auth i zwraca klucz i klucz tajny, których będziesz potrzebować do uruchomienia mikrobramki. Jeśli potrzebujesz pomocy, przeczytaj artykuł Konfigurowanie urządzenia Edge Microgateway.

3. W Apigee Edge utwórz usługę API z tymi obowiązkowymi wymaganiami dotyczącymi konfiguracji (wszystkimi innymi konfiguracjami możesz zarządzać według uznania):
   • Musisz dodać do usługi serwer proxy edgemicro-auth. Ten serwer proxy został wdrożony automatycznie podczas wykonywania polecenia edgemicro configure.
   • Musisz podać ścieżkę do zasobu. Apigee zaleca dodanie tej ścieżki do produktu: /**. Więcej informacji znajdziesz w artykule Konfigurowanie działania ścieżki zasobu. Zapoznaj się też z artykułem Tworzenie usług API w dokumentacji Edge.

4. W usłudze Apigee Edge utwórz dewelopera lub, jeśli chcesz, użyj istniejącego dewelopera. Aby uzyskać pomoc, zobacz artykuł Dodawanie deweloperów za pomocą interfejsu zarządzania w Edge.

5. W Apigee Edge utwórz aplikację dla deweloperów. Musisz dodać do niej utworzoną właśnie usługę API. Aby uzyskać pomoc, skorzystaj z instrukcji rejestrowania aplikacji w interfejsie zarządzania Edge.
6. Na maszynie, na której zainstalowano Edge Microgateway, wyeksportuj tę zmienną środowiskową z wartością „1”.

   export EDGEMICRO_LOCAL_PROXY=1

7. Uruchom to polecenie 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

   Gdzie:

   • your_org to Twoja organizacja Apigee.
   • your_environment to środowisko w Twojej organizacji.
   • your_key to klucz zwrócony po wykonaniu polecenia edgemicro configure.
   • your_secret to tajny klucz zwrócony przez wywołanie funkcji edgemicro configure.
   • local_proxy_name to nazwa lokalnego serwera proxy, który zostanie utworzony.
   • local_proxy_version to numer wersji serwera proxy.
   • target_url to adres URL docelowy serwera proxy (usługa, którą serwer proxy będzie wywoływać).
   • base_path to ścieżka podstawowa proxy. Ta wartość musi zaczynać się od ukośnika. W przypadku ścieżki podstawowej katalogu głównego wskaż tylko ukośnik, np. „/”.

   Na przykład:

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

Testowanie konfiguracji

Konfigurację lokalnego serwera proxy możesz przetestować, wywołując punkt końcowy serwera proxy. Jeśli na przykład ścieżka podstawowa to /echo, możesz wywołać serwer proxy w ten sposób:

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

Ten początkowy wywołanie interfejsu API spowodował błąd, ponieważ nie podano prawidłowego klucza interfejsu API. Klucz znajdziesz w aplikacji dla deweloperów, którą utworzyłeś(-aś) wcześniej. Otwórz aplikację w interfejsie Edge, skopiuj klucz konsumenta i użyj go w ten sposób:

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

Na przykład:

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

Przykładowe dane wyjściowe:

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

Korzystanie z synchronizatora

Z tej sekcji dowiesz się, jak korzystać z synchronizatora, opcjonalnej funkcji, która zwiększa odporność Edge Microgateway, umożliwiając mu pobieranie danych konfiguracji z Apigee Edge i zapisywanie ich w lokalnej bazie danych Redis. Gdy instancja synchronizatora jest uruchomiona, inne instancje Edge Microgateway działające na różnych węzłach mogą pobierać konfigurację bezpośrednio z tej bazy danych.

Funkcja synchronizatora jest obecnie obsługiwana w Redis 5.0.x.

Co to jest synchronizator?

Synchronizator zapewnia pewien poziom odporności dla Edge Microgateway. Pomaga to zapewnić, że każda instancja Edge Microgateway używa tej samej konfiguracji i że w przypadku przerwy w działaniu internetu instancje Edge Microgateway mogą się uruchamiać i działać prawidłowo.

Domyślnie instancje Edge Microgateway muszą mieć możliwość komunikacji z Apigee Edge, aby pobierać i odświeżać dane konfiguracji, takie jak konfiguracje proxy API i produktów API. Jeśli połączenie z internetem w Edge zostanie przerwane, instancje mikrobramki będą mogły nadal działać, ponieważ najnowsze dane konfiguracji są przechowywane w pamięci podręcznej. Nowe instancje mikrobramki nie mogą się jednak uruchomić bez wyraźnego połączenia. Ponadto przerwa w działaniu internetu może spowodować, że co najmniej 1 instancja mikrobramki będzie działać z informacjami konfiguracyjnymi, które są niezsynchronizowane z innymi instancjami.

Synchronizator Edge Microgateway zapewnia alternatywne rozwiązanie dla instancji Edge Microgateway, które umożliwia im pobieranie danych konfiguracji potrzebnych do uruchamiania i przetwarzania ruchu w usłudze proxy API. Dane konfiguracji pobrane z wywołań do Apigee Edge obejmują: wywołanie jwk_public_keys, wywołanie jwt_public_key, wywołanie bootstrap i wywołanie produktów interfejsu API. Synchronizator umożliwia prawidłowe uruchamianie się wszystkich instancji Edge Microgateway działających na różnych węzłach i utrzymywanie ich w synchronizacji nawet wtedy, gdy połączenie internetowe między Edge Microgateway a Apigee Edge zostanie przerwane.

Synchronizator to specjalnie skonfigurowana instancja Edge Microgateway. Jego jedynym celem jest odpytywanie Apigee Edge (czas jest konfigurowalny), pobieranie danych konfiguracji i zapisywanie ich w lokalnej bazie danych Redis. Sama instancja synchronizatora nie może przetwarzać ruchu proxy interfejsu API. Inne instancje Edge Microgateway działające na różnych węzłach można skonfigurować tak, aby pobierały dane konfiguracji z bazy danych Redis, a nie z Apigee Edge. Wszystkie instancje mikrobramki pobierają dane konfiguracji z lokalnej bazy danych, dzięki czemu mogą się uruchamiać i przetwarzać żądania interfejsu API nawet w przypadku przerwy w działaniu internetu.

Konfigurowanie instancji synchronizatora

Dodaj do pliku org-env/config.yaml konfigurację dla instalacji Edge Microgateway, której chcesz używać jako synchronizatora:

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

Na przykład:

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

Na koniec zapisz plik konfiguracji i uruchom instancję Edge Microgateway. Zacznie odpytywać Apigee Edge i zapisywać pobrane dane konfiguracji w bazie danych Redis.

Konfigurowanie zwykłych instancji Edge Microgateway

Po uruchomieniu synchronizatora możesz skonfigurować dodatkowe węzły Edge Microgateway, aby uruchamiać zwykłe instancje mikrobramki, które przetwarzają ruch proxy interfejsu API. Jednak te instancje są konfigurowane tak, aby pobierać dane konfiguracji z bazy danych Redis, a nie z Apigee Edge.

Dodaj tę konfigurację do pliku org-env/config.yaml każdego dodatkowego węzła Edge Microgateway. Sprawdź, czy właściwość synchronizerMode ma wartość 0. Ta właściwość powoduje, że instancja działa jak zwykła instancja Edge Microgateway, która przetwarza ruch proxy interfejsu API. Dane konfiguracji są pobierane z bazy danych Redis.

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

Na przykład:

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

Właściwości konfiguracji

Aby umożliwić korzystanie z synchronizatora, dodaliśmy te właściwości konfiguracji:

Konfigurowanie wykluczonych adresów URL w przypadku wtyczek

Możesz skonfigurować mikrobramę, aby pomijała przetwarzanie wtyczek w przypadku określonych adresów URL. Możesz skonfigurować te adresy URL do „wykluczenia” globalnie (dla wszystkich wtyczek) lub dla konkretnych wtyczek.

Na przykład:

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

W tym przykładzie wtyczki nie będą przetwarzać przychodzących wywołań proxy interfejsu API z ścieżkami /hello ani /proxy_one. Dodatkowo wtyczka json2xml zostanie pominięta w przypadku interfejsów API, których ścieżka zawiera parametr /hello/xml.

Ustawianie atrybutów konfiguracji za pomocą wartości zmiennych środowiskowych

Zmienne środowiskowe możesz określić za pomocą tagów w pliku konfiguracyjnym. Tagi określonej zmiennej środowiskowej są zastępowane rzeczywistymi wartościami zmiennej środowiskowej. Zastępcze wersje są przechowywane tylko w pamięci, a nie w pliku konfiguracji ani pliku pamięci podręcznej.

W tym przykładzie atrybut key jest zastępowany wartością zmiennej środowiskowej TARGETS_SSL_CLIENT_KEY itd.

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

W tym przykładzie tag <n> służy do wskazywania wartości całkowitej. Obsługiwane są tylko dodatnie liczby całkowite.

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

W tym przykładzie tag <b> służy do wskazywania wartości logicznej (czyli prawda lub fałsz).

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