Betriebsanleitung

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Wie Sie einen API-Schlüssel erhalten

Im folgenden Beispiel wird erläutert, wie Sie einen API-Schlüssel erhalten, mit dem Sie API-Aufrufe an einen Zieldienst validieren können, der über den Apigee Adapter for Envoy weitergeleitet wird.

1. Bei Apigee anmelden

  1. Öffnen Sie die Apigee-Benutzeroberfläche in einem Browser.
  2. Wählen Sie in der Benutzeroberfläche die Organisation aus, die Sie zum Konfigurieren des Apigee-Adapters für Envoy verwendet haben.

2. Entwickler erstellen

Sie können einen vorhandenen Entwickler zum Testen verwenden oder einen neuen Entwickler erstellen:

  1. Klicken Sie im seitlichen Navigationsmenü auf Veröffentlichen > Entwickler.
  2. Klicken Sie auf + Entwickler.
  3. Füllen Sie das Dialogfeld aus, um einen neuen Entwickler zu erstellen. Sie können einen beliebigen Entwicklernamen oder eine beliebige E-Mail-Adresse verwenden.

3. API-Produkt erstellen

Unten finden Sie ein Beispiel zur Produkterstellung. Weitere Informationen finden Sie unter Informationen zur API-Produktkonfiguration.

  1. Wählen Sie im seitlichen Navigationsmenü Veröffentlichen > API-Produkte aus.
  2. Klicken Sie auf + API Product.
  3. Füllen Sie die Seite mit den Produktdetails so aus:
  4. Feld Wert
    Name httpbin-product
    Display Name httpbin product
    Environment your_environment

    Legen Sie hier die Umgebung fest, die Sie bei der Bereitstellung des Apigee-Adapters für Envoy verwendet haben.

    Access Private
    Kontingent 5 Anfragen pro Minute

    Siehe auch Kontingent.

  5. Klicken Sie im Abschnitt Apigee-Remote-Dienstziele auf Apigee-Remote-Dienstziel hinzufügen.
  6. Geben Sie im Dialogfeld für das Apigee-Remote-Dienstziel die folgenden Werte ein:
    Attribut Wert Beschreibung
    Name des Ziels Geben Sie den Namen des Zieldienstes ein. Beispiel: httpbin.org Der vom Envoy-Proxy angezeigte Ziel-Endpunkt.
    Pfad Geben Sie einen Ressourcenpfad für den Dienst ein, der abgeglichen werden soll. Beispiel: /headers. Der Anfragepfad für den Zielendpunkt. API-Proxyaufrufe an diesen Pfad entsprechen diesem API-Produkt.
  7. Klicken Sie auf Speichern.

4. Entwickler-App erstellen

  1. Klicken Sie im seitlichen Navigationsmenü auf Veröffentlichen > Apps.
  2. Klicken Sie auf + App.
  3. Füllen Sie die Seite „Entwickler-App“ wie unten beschrieben aus. Speichern Sie erst, wenn Sie dazu aufgefordert werden.
  4. Name httpbin-app
    Display Name httpbin app
    Developer Wählen Sie den Entwickler aus, den Sie zuvor erstellt haben, oder wählen Sie einen beliebigen Entwickler aus der Liste aus.
  5. Als Nächstes fügen Sie der App das API-Produkt hinzu:
    1. Klicken Sie im Abschnitt "Anmeldedaten" auf + Produkt hinzufügen und wählen Sie das Produkt aus, das Sie gerade konfiguriert haben: httpbin-product.
    2. Klicken Sie auf Erstellen.
    3. Klicken Sie unter „Anmeldedaten“ neben dem Schlüssel auf Anzeigen.
    4. Kopieren Sie den Wert des Consumer-Schlüssels. Dieser Wert ist der API-Schlüssel, mit dem Sie API-Aufrufe an den Dienst httpbin senden.

    Informationen zu API-Produkten

    API-Produkte sind der zentrale Steuerungspunkt für den Apigee-Remote-Service. Wenn Sie ein API-Produkt erstellen und an einen Zieldienst binden, erstellen Sie eine Richtlinie, die auf alle Anfragen angewendet wird, für die Sie Apigee Adapter for Envoy konfigurieren.

    API-Produktdefinition

    Wenn Sie ein API-Produkt in Apigee definieren, können Sie verschiedene Parameter angeben, die zum Bewerten von Anfragen verwendet werden:

    • Target
    • Anfragepfad
    • Kontingent
    • OAuth-Bereiche

    Remotedienstziele

    Die API-Produktdefinition gilt für eine Anfrage, wenn die Anfrage sowohl mit der Zielbindung (z. B. httpbin.org) als auch mit dem Anfragepfad (z. B. /httpbin) übereinstimmt. Eine Liste potenzieller Ziele wird als Attribut im API-Produkt gespeichert.

    Standardmäßig prüft der Apigee Remote Service den speziellen Header :authority (host) von Envoy mit seiner Liste von Zielen. Er kann jedoch auch so konfiguriert werden, dass andere Header verwendet werden.

    API-Ressourcenpfad

    Der eingegebene Pfad entspricht den folgenden Regeln:

    • Ein einzelner Schrägstrich (/) allein entspricht einem beliebigen Pfad.
    • * ist überall gültig und stimmt innerhalb eines Segments (zwischen Schrägstrichen) überein.
    • ** ist am Ende gültig und passt zu allem, was am Ende der Zeile steht.

    Kontingent

    Ein Kontingent gibt die Anzahl der Anfragenachrichten an, die eine App im Verlauf einer Stunde, eines Tages, einer Woche oder eines Monats senden darf. Wenn eine App das Kontingentlimit erreicht hat, werden nachfolgende API-Aufrufe abgelehnt.

    Anwendungsfälle für Kontingente

    Mit Kontingenten können Sie die Anzahl der Anfragen erzwingen, die ein Client innerhalb eines bestimmten Zeitraums an einen Dienst senden kann. Kontingente werden häufig zur Durchsetzung von Geschäftsverträgen oder SLAs mit Entwicklern und Partnern verwendet und nicht für die betriebliche Trafficverwaltung. Mit einem Kontingent können Sie beispielsweise den Traffic für einen kostenlosen Dienst beschränken und gleichzeitig zahlenden Kunden uneingeschränkten Zugriff gewähren.

    Das Kontingent wird in einem API-Produkt definiert.

    Kontingentparameter werden in API-Produkten konfiguriert. Wenn Sie beispielsweise ein API-Produkt erstellen, können Sie optional das zulässige Kontingentlimit, die Zeiteinheit und das Intervall festlegen.

    API-Schlüssel werden API-Produkten zugeordnet. Daher kann bei jeder Verifizierung eines API-Schlüssels der entsprechende Kontingentzähler verringert werden, sofern im zugehörigen Produkt ein Kontingent definiert ist.

    Anders als in der Apigee-Laufzeit werden Kontingente, die in der Produktdefinition eingegeben werden, automatisch vom Apigee-Remote-Dienst erzwungen. Wenn die Anfrage autorisiert ist, wird sie auf das zulässige Kontingent angerechnet.

    Wo werden Kontingente verwaltet?

    Kontingente werden lokal vom Remote-Dienstprozess verwaltet und geprüft und asynchron mit Apigee Runtime verwaltet. Das bedeutet, dass die Kontingente nicht genau sind und wahrscheinlich etwas überschritten werden, wenn Sie mehr als einen Remotedienst haben, der das Kontingent verwaltet. Wenn die Verbindung zu Apigee Runtime unterbrochen wird, gilt das lokale Kontingent bis zu diesem Zeitpunkt als eigenständiges Kontingent, da es wieder mit Apigee Runtime verbunden werden kann.

    OAuth-Bereiche

    Wenn Sie JWT-Token verwenden, können Sie die Tokens auf Untergruppen der zulässigen OAuth-Bereiche beschränken. Die Bereiche, die Ihrem ausgestellten JWT-Token zugewiesen sind, werden mit den Bereichen des API-Produkts verglichen.

    Informationen zu Entwickler-Apps

    Nachdem Sie die API-Produkte konfiguriert haben, erstellen Sie eine App, die einem Entwickler zugeordnet ist. Über diese App erhält ein Client Zugriff auf die zugehörigen API-Produkte mit einem API-Schlüssel oder JWT-Token.

    JWT-basierte Authentifizierung verwenden

    Sie können authentifizierte API-Proxyaufrufe mit einem JWT-Token durchführen, anstatt einen API-Schlüssel zu verwenden. In diesem Abschnitt wird erläutert, wie Sie mit dem Befehl apigee-remote-service-cli token JWT-Tokens erstellen, prüfen und rotieren.

    Überblick

    Die JWT-Verifizierung und die JWT-Authentifizierung werden von Envoy mit dem zugehörigen JWT-Authentifizierungsfilter ausgeführt.

    Nach der Authentifizierung sendet der Envoy-Filter ext-authz die Anfrageheader und das JWT an apigee-remote-service-envoy. Er vergleicht die api_product_list- und scope-Anforderungen des JWT mit Apigee API-Produkten, um es für das Ziel der Anfrage zu autorisieren.

    Apigee-JWT-Tokens erstellen

    Apigee JWT-Tokens können über die Befehlszeile erstellt werden:

    $CLI_HOME/apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

    Oder Sie verwenden den standardmäßigen OAuth-Token-Endpunkt. Beispiel für Curl:

    curl https://org-env.apigee.net/remote-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

    JWT-Token verwenden

    Sobald Sie das Token haben, übergeben Sie es im Autorisierungs-Header an Envoy. Beispiel:

    curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

    JWT-Tokenfehler

    Ablehnung durch Envoy

    Wenn Envoy das Token ablehnt, wird möglicherweise eine Nachricht wie diese angezeigt:

    Jwks remote fetch is failed

    Wenn dies der Fall ist, stellen Sie sicher, dass Ihre Envoy-Konfiguration einen gültigen URI im Abschnitt remote_jwks enthält, dass sie für Envoy erreichbar ist und dass Sie die Zertifikate bei der Installation des Apigee-Proxys korrekt eingerichtet haben. Sie sollten den URI direkt mit einem GET-Aufruf aufrufen und eine gültige JSON-Antwort erhalten.

    Beispiel:

    curl https://myorg-eval-test.apigee.net/remote-service/certs

    Andere Nachrichten von Envoy könnten so aussehen:

    • „Zielgruppen in Jwt sind nicht zulässig“
    • „Jwt-Aussteller ist nicht konfiguriert“

    Diese Anforderungen stammen aus Ihrer Envoy-Konfiguration, die Sie möglicherweise ändern müssen.

    Token prüfen

    Sie können das Token über die Befehlszeile prüfen. Beispiel

    $CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

    oder

    $CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

    Debugging

    Siehe Gültiger API-Schlüssel schlägt fehl.

    Logging

    Sie können die Logging-Stufe im Dienst $REMOTE_SERVICE_HOME/apigee-remote-service-envoy anpassen. Das gesamte Logging wird an stdout und stderr gesendet.

    Element Erforderlich Beschreibung
    -l, --log-level Gültige Stufen: debug, info, warn, error. Passt die Logging-Ebene an. Standard: info
    -j, --json-log Sendet die Logausgabe als JSON-Datensätze.

    Envoy bietet Logging. Weitere Informationen finden Sie unter den folgenden Links zur Envoy-Dokumentation:

    Netzwerk-Proxy verwenden

    Ein HTTP-Proxy kann mithilfe der Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY in die Umgebung der Binärdatei „apigee-remote-service-envoy“ eingefügt werden. Wenn Sie diese Umgebungsvariablen verwenden, kann die Umgebungsvariable NO_PROXY auch verwendet werden, um bestimmte Hosts vom Proxy auszuschließen.

    HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
    HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
    NO_PROXY=127.0.0.1,localhost

    Denken Sie daran, dass der Proxy über apigee-remote-service-envoy erreichbar sein muss.

    Messwerte und Analysen

    Ein Prometheus-Messwert-Endpunkt ist unter :5001/metrics verfügbar. Sie können diese Portnummer konfigurieren. Siehe Konfigurationsdatei.

    Envoy-Analysen

    Unter den folgenden Links finden Sie Informationen zum Abrufen von Envoy-Proxy-Analysedaten:

    Istio-Analysen

    Unter den folgenden Links finden Sie Informationen zum Abrufen von Envoy-Proxy-Analysedaten:

    Apigee Analytics

    Apigee Remote Service for Envoy sendet Anfragestatistiken zur Verarbeitung von Analysen an Apigee. Apigee erfasst diese Anfragen unter dem zugehörigen API-Produktnamen.

    Informationen zu Apigee Analytics finden Sie in der Übersicht über Analytics-Diensten.

    Unterstützung von Umgebungen mit mehreren Mandanten

    Sie können den Adapter jetzt so aktivieren, dass mehrere Umgebungen in einer Apigee-Organisation bedient werden. Mit diesem Feature können Sie einen einzelnen Apigee Adapter for Envoy, der mit einer einzelnen Apigee-Organisation verknüpft ist, so verwenden, dass mehrere Umgebungen bedient werden. Vor dieser Änderung war ein Adapter immer mit einer Apigee-Umgebung verknüpft.

    Wenn Sie die Unterstützung für mehrere Umgebungen konfigurieren möchten, ändern Sie in der Datei config.yaml den Wert von tenant:env_name in *. Beispiel:

    1. Öffnen Sie die Datei config.yaml in einem Editor.
    2. Ändern Sie den Wert von tenant.env_name in *. Beispiel:
      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: apigee-remote-service-envoy
        namespace: apigee
      data:
        config.yaml: |
          tenant:
            remote_service_api: https://myorg-myenv.apigee.net/remote-service
            org_name: apigee-docs-hybrid-a
            env_name: *
            allow_unverified_ssl_cert: true
          analytics:
            collection_interval: 10s
          auth:
            jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token
    3. Speichere die Datei.
    4. Wenden Sie die Datei an:
      kubectl apply -f $CLI_HOME/config.yaml

    Wenn Sie den Modus für mehrere Umgebungen konfigurieren, müssen Sie Envoy auch so konfigurieren, dass ein geeigneter Umgebungswert an den Adapter gesendet wird. Dazu fügen Sie die folgenden Metadaten zum Abschnitt virtual_hosts:routes der Datei envoy-config.yaml hinzu. Beispiel:

    1. Generieren Sie die Datei envoy-config.yaml mithilfe der Befehlszeile. Beispiel:
      $CLI_HOME/apigee-remote-service-cli samples create \
        -t envoy-1.16 -c ./config.yaml --out myconfigs
    2. Öffnen Sie die generierte Datei (sie heißt envoy-config.yaml).
    3. Fügen Sie die folgenden Metadaten entweder im Abschnitt virtual_host oder routes der Datei hinzu:
      typed_per_filter_config:
        envoy.filters.http.ext_authz:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
          check_settings:
            context_extensions:
              apigee_environment: test

      Das folgende Beispiel veranschaulicht die Konfiguration für einen virtual_host mit mehreren definierten Routen, wobei jede Route Traffic an eine bestimmte Umgebung sendet:

      filter_chains:
          - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                route_config:
                  virtual_hosts:
                  - name: default
                    domains: "*"
                    routes:
                    - match: { prefix: /test }
                      route:
                        cluster: httpbin
                      typed_per_filter_config:
                        envoy.filters.http.ext_authz:
                          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                          check_settings:
                            context_extensions:
                               apigee_environment: test
                    - match: { prefix: /prod }
                      route:
                        cluster: httpbin
                      typed_per_filter_config:
                        envoy.filters.http.ext_authz:
                          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                          check_settings:
                            context_extensions:
                               apigee_environment: prod
    4. Wiederholen Sie den letzten Schritt, um nach Bedarf weitere Umgebungen hinzuzufügen.
    5. Speichern Sie die Datei und wenden Sie sie an.

    mTLS zwischen dem Adapter und der Apigee-Laufzeit konfigurieren

    Sie können clientseitige TLS-Zertifikate im Abschnitt tenant der Datei config.yaml des Adapters bereitstellen, um mTLS zwischen dem Adapter und der Apigee-Laufzeit zu verwenden. Diese Änderung gilt für alle unterstützten Apigee-Plattformen. Außerdem wird mTLS für Analysen für die Apigee Edge for Private Cloud-Plattform aktiviert. Beispiel:

    tenant:
      tls:
        ca_file: path/ca.pem
        cert_file: path/cert.pem
        key_file: path/key.pem
        allow_unverified_ssl_cert: false