Betriebsanleitung

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Wie Sie einen API-Schlüssel erhalten

Im folgenden Beispiel wird beschrieben, wie Sie einen API-Schlüssel erhalten, mit dem Sie API-Aufrufe validieren können, die über Apigee Adapter for Envoy an einen Zieldienst weitergeleitet werden.

1. Bei Apigee anmelden

  1. Melden Sie sich bei der Apigee-UI an.
  2. Wählen Sie die Organisation aus, die Sie zur Bereitstellung von Apigee Adapter for 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.

  1. Wählen Sie im seitlichen Navigationsmenü Veröffentlichen > API-Produkte aus.
  2. Klicken Sie auf +Erstellen.
  3. Füllen Sie den Abschnitt Produktdetails wie nachfolgend beschrieben aus. In der folgenden Tabelle werden nur die Pflichtfelder erwähnt:
    Feld Wert Beschreibung
    Name httpbin-product Der eindeutige Name des API-Produkts.
    Anzeigename httpbin product Der beschreibende Name, den Sie in der Benutzeroberfläche oder in anderen Anzeigekontexten sehen möchten.
    Zugriff Public Für dieses Beispiel ist Öffentlich eine gute Wahl.
  4. Klicken Sie im Abschnitt "Vorgänge" auf +VORGANG HINZUFÜGEN.
  5. Wählen Sie im Abschnitt Quelle die Option Remotedienst aus.
  6. Stellen Sie den Schalter Quelle um, damit Sie den Namen eines Remotedienstes manuell in das Feld des Remotedienstes eingeben können.
  7. Geben Sie im Feld Remote-Dienst den Namen eines Remote-Dienstes ein. Dies ist ein Zieldienst, an den der Adapter eingehende HTTP-Anfragen weiterleitet. Verwenden Sie zu Testzwecken httpbin.org oder httpbin.default.svc.cluster.local mit Kubernetes.

    Das Optionsfeld "Remotedienst" ist ausgewählt, das Aktivieren der manuellen Texteingabe ist aktiviert und der Remotedienst "httpbin.org" wird in das Feld "Remotedienst" eingegeben.

  8. Geben Sie im Abschnitt Vorgang / für den Pfad ein. Informationen zu Pfadoptionen finden Sie unter Ressourcenpfade konfigurieren.
  9. Klicken Sie auf SPEICHERN, um den Vorgang zu speichern.
  10. Klicken Sie auf SPEICHERN, um das API-Produkt zu speichern.

Weitere Informationen finden Sie unter API-Produkte verwalten.

4. Entwickler-App erstellen

Die Entwickler-App enthält den API-Schlüssel, der erforderlich ist, um API-Proxyaufrufe über den Adapter auszuführen.

  1. Klicken Sie im seitlichen Navigationsmenü auf Apps veröffentlichen.
  2. Klicken Sie auf + App.
  3. Füllen Sie den Abschnitt App-Details wie nachfolgend beschrieben aus. In der folgenden Tabelle werden nur die Pflichtfelder erwähnt:
    4. Name httpbin-app
    Developer Wählen Sie den Entwickler aus, den Sie zuvor erstellt haben, oder wählen Sie einen Entwickler aus der Liste aus.
  4. Klicken Sie im Abschnitt "Anmeldedaten" auf + Produkt hinzufügen und wählen Sie das soeben konfigurierte Produkt aus: httpbin-product.
  5. Klicken Sie auf Erstellen.
  6. Klicken Sie unter „Anmeldedaten“ neben dem Schlüssel auf Anzeigen.
  7. Kopieren Sie den Wert des Consumer-Schlüssels. Dieser Wert ist der API-Schlüssel, mit dem Sie API-Aufrufe an den httpbin-Dienst über den Apigee Adapter for Envoy senden.

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. Für eine Hybrid-Umgebung von Apigee können Sie mit diesem Befehl ein Kubernetes-Secret erstellen, das die JWTs enthält.

Übersicht

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:

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 has 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

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

oder

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

Debugging

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

Eigenen Identitätsanbieter verwenden

Standardmäßig verwendet Apigee Adapter for Envoy den API-Proxy remote-token als Identitätsanbieterdienst, um Clientanwendungen zu authentifizieren und JWT-Tokens basierend auf dem Berechtigungstyp der OAuth 2.0-Clientanmeldedaten bereitzustellen. In einigen Fällen können Sie den remote-token-Proxy möglicherweise nicht verwenden. Wenn Sie einen Identitätsanbieter verwenden müssen, der nicht von Apigee bereitgestellt wird, können Sie den Adapter so konfigurieren, dass er einen anderen Identitätsanbieter verwendet. Weitere Informationen zur Verwendung eines Nicht-Apigee-Identitätsanbieters und der erforderlichen Konfiguration finden Sie in diesem Artikel in der Apigee-Community: Eigene Identitätsanbieter mit dem Apigee Envoy-Adapter verwenden.

Logging

Sie können die Logging-Stufe im Dienst $REMOTE_SERVICE_HOME/apigee-remote-service-envoy anpassen. Alle Logs werden an 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:

Name des Richtlinien-Secrets ändern

Ein im Cluster bereitgestelltes Kubernetes-Secret enthält Anmeldedaten, die der Adapter zur Authentifizierung der Kommunikation mit dem Remotedienst-Proxy benötigt. Für dieses Secret ist ein Volume-Bereitstellungspunkt erforderlich, der konfigurierbar ist. Standardmäßig ist der Bereitstellungspunkt /policy-secret. So ändern Sie den Bereitstellungspunkt:

  1. Führen Sie diesen Befehl aus: 
    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

    Beispiel:

    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point
  2. Öffnen Sie $CLI_HOME/samples/apigee-envoy-adapter.yaml in einem Editor.
  3. Ändern Sie den Namen des Bereitstellungspunkts in den neuen Namen: 
    volumeMounts:
  - mountPath: /config
    name: apigee-remote-service-envoy
    readOnly: true
  - mountPath: /opt/apigee/tls
    name: tls-volume
    readOnly: true
  - mountPath: /my-mount-point
    name: policy-secret
    readOnly: true
  4. Speichern Sie die Datei und wenden Sie sie auf das Service Mesh an: 
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

Netzwerkproxy 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.

Informationen zu Messwerten 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-Analyse

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://apitest.mydomain.net/remote-service
      org_name: my-org
      env_name: "*""
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.net/remote-token/token
  3. Speichern Sie 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 in den Abschnitt virtual_host oder routes der Datei ein: 
    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.

Daten für benutzerdefinierte Berichte erfassen

Der Adapter unterstützt die Übergabe von Envoy-Metadaten an das Apigee-Feature zur Datenerfassung, das erfasste Daten in Variablen sendet, die Sie für die Analyse in benutzerdefinierten Berichten an Apigee Analytics angeben. Dieses Feature bietet eine Funktion, die der Datenerfassungsrichtlinie von Apigee ähnelt.

So verwenden Sie dieses Feature:

  1. Erstellen Sie eine Data Collector REST-Ressource.
  2. Legen Sie Datenerfassungsvariablen mit der Apigee Datacollectors API fest.
  3. Generieren Sie die Datei envoy-config.yaml über die Befehlszeile, falls noch nicht geschehen. Beispiel: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. Öffnen Sie die generierte Datei (sie heißt envoy-config.yaml).
  5. Mit einem Envoy-Filter können Sie Werte für Ihre benutzerdefinierten Variablen im Namespace envoy.filters.http.apigee.datacapture festlegen. Sie können beispielsweise einen Header für Metadaten-Filter oder einen Lua-Filter verwenden. Weitere Informationen zu diesen Filtern finden Sie unter Header-für Metadaten und Lua.

    Die Namen benutzerdefinierter Variablen müssen als dc.XXXXX formatiert sein.

    Beispiel für den Filter "Header-to-Metadata": 

     - name: envoy.filters.http.header_to_metadata
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
    request_rules:
      - header: "Host"
        on_header_present:
          metadata_namespace: envoy.filters.http.apigee.datacapture
          key: dc.host  # host (without the prefix) also works
          type: STRING
        remove: false

    Beispiel für den Filter "Lua": 

    - name: envoy.filters.http.lua
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    inline_code: |
      function envoy_on_request(request_handle)
        metadata = request_handle:streamInfo():dynamicMetadata()
        metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
      end
  6. Fügen Sie der Datei den gewünschten Filter hinzu. Siehe nachstehende Beispiele
  7. 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