Guide d'utilisation

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Comment obtenir une clé API

L'exemple suivant explique comment obtenir une clé API que vous pouvez utiliser pour valider les appels d'API à un service cible envoyé par proxy via Apigee Adapter for Envoy.

1. Se connecter à Apigee

  1. Connectez-vous à l'UI Apigee.
  2. Sélectionnez la même organisation que celle utilisée pour provisionner Apigee Adapter for Envoy.

2. Créer un développeur

Vous pouvez utiliser un développeur existant pour effectuer des tests ou en créer un autre en procédant comme suit :

  1. Sélectionnez Publier > Développeurs dans le menu de navigation latéral.
  2. Cliquez sur + Développeur.
  3. Renseignez les champs de la boîte de dialogue pour créer un développeur. Vous pouvez utiliser le nom et l'adresse e-mail du développeur de votre choix.

3. Créer un produit d'API

Suivez l'exemple de création de produit fourni ci-dessous.

  1. Dans le menu de navigation latéral, sélectionnez Publier > Produits API.
  2. Cliquez sur +CRÉER.
  3. Renseignez la section d'informations détaillées sur le produit comme suit. Seuls les champs obligatoires sont mentionnés dans le tableau suivant :
    Champ Valeur Description
    Nom httpbin-product Nom unique du produit d'API.
    Nom à afficher httpbin product Nom descriptif que vous souhaitez afficher dans l'interface utilisateur ou dans d'autres contextes d'affichage.
    Accès Public Pour les besoins de cet exemple, Public constitue un bon choix.
  4. Dans la section "Opérations", cliquez sur +AJOUTER UNE OPÉRATION.
  5. Dans la section Source, sélectionnez service distant.
  6. Activez le bouton Source pour saisir manuellement le nom d'un service distant dans le champ "service distant".
  7. Dans le champ Service à distance, saisissez le nom d'un service distant. Il s'agit d'un service cible vers lequel l'adaptateur sert de proxy pour les requêtes HTTP entrantes. À des fins de test, utilisez httpbin.org ou httpbin.default.svc.cluster.local avec Kubernetes.

    La case d'option "service distant" est cochée, l'activation de la saisie manuelle du texte est activée, et le service distant httpbin.org est saisi dans le champ "service distant".

  8. Dans la section Opération, saisissez / en tant que chemin d'accès. Pour en savoir plus sur les options de chemin d'accès, consultez la section Configurer des chemins de ressources.
  9. Cliquez sur Enregistrer pour enregistrer l'opération.
  10. Cliquez sur Enregistrer pour enregistrer le produit d'API.

Pour plus d'informations, consultez la page Gérer les produits d'API.

4. Créer une application de développeur

L'application de développeur contient la clé API requise pour effectuer des appels de proxy d'API via l'adaptateur.

  1. Sélectionnez Publier applications dans le menu de navigation latéral.
  2. Cliquez sur + App (+ Application).
  3. Renseignez la section d'informations sur l'application comme suit. Seuls les champs obligatoires sont mentionnés dans le tableau suivant :
    4. Nom httpbin-app
    Developer Sélectionnez le développeur que vous avez créé précédemment ou sélectionnez un développeur de votre choix dans la liste.
  4. Dans la section "Identifiants", cliquez sur + Ajouter un produit et sélectionnez le produit que vous venez de configurer : httpbin-product.
  5. Cliquez sur Créer.
  6. Sous "Identifiants", cliquez sur Afficher à côté de la Clé.
  7. Copiez la valeur de la clé client. Cette valeur est la clé API que vous utiliserez pour effectuer des appels d'API au service httpbin via Apigee Adapter for Envoy.

Utiliser l'authentification basée sur JWT

Vous pouvez utiliser un jeton JWT pour effectuer des appels de proxy d'API authentifiés au lieu d'utiliser une clé API. Cette section explique comment utiliser la commande apigee-remote-service-cli token pour créer, inspecter et faire pivoter des jetons JWT. Pour un environnement hybride Apigee, vous pouvez utiliser cette commande pour créer un secret Kubernetes contenant le(s) jeton(s) JWT.

Aperçu

La validation et l'authentification JWT sont gérées par Envoy à l'aide de son filtre d'authentification JWT.

Une fois authentifié, le filtre ext-authz Envoy envoie les en-têtes de requête et le jeton JWT à apigee-remote-service-envoy. Il associe les revendications api_product_list et scope du jeton JWT aux produits API Apigee pour les autoriser par rapport à la cible de la requête.

Créer des jetons JWT Apigee

Les jetons JWT Apigee peuvent être créés à l'aide de la CLI :

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

Ou en utilisant le point de terminaison de jeton OAuth standard. Exemple 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"

Utiliser le jeton JWT

Une fois que vous disposez du jeton, il vous suffit de le transmettre à Envoy dans l'en-tête d'autorisation. Exemple :

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

Échec du jeton JWT

Refus Envoy

Si Envoy refuse le jeton, un message de ce type peut s'afficher :

Jwks remote fetch has failed

Si tel est le cas, assurez-vous que votre configuration Envoy contient un URI valide dans la section remote_jwks, qu'il est accessible par Envoy et que vous avez correctement défini les certificats lorsque vous avez installé le proxy Apigee. Vous devez pouvoir appeler directement l'URI avec un appel GET et recevoir une réponse JSON valide.

Exemple :

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

D'autres messages d'Envoy peuvent se présenter comme suit :

  • "Les audiences de Jwt ne sont pas autorisées"
  • "L'émetteur Jwt n'est pas configuré"

Ces messages proviennent des exigences de votre configuration Envoy, que vous devrez peut-être modifier.

Inspecter un jeton

Vous pouvez utiliser la CLI pour inspecter votre jeton. Exemple

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

ou

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

Débogage

Consultez la section Échec d'une clé API valide.

Utiliser votre propre fournisseur d'identité

Par défaut, Apigee Adapter for Envoy utilise le proxy d'API remote-token en tant que service de fournisseur d'identité pour authentifier les applications clientes et fournir des jetons JWT en fonction du type d'attribution des identifiants client OAuth 2.0. Toutefois, dans certains cas, vous ne pourrez peut-être pas utiliser le proxy remote-token. Si vous devez utiliser un fournisseur d'identité autre que celui fourni par Apigee, vous pouvez configurer l'adaptateur pour utiliser un autre fournisseur d'identité. Pour en savoir plus sur ce cas d'utilisation d'un fournisseur d'identité non-Apigee et la configuration requise, consultez cet article de la communauté Apigee : Utiliser votre propre fournisseur d'identité avec l'adaptateur Apigee Envoy.

Journalisation

Vous pouvez ajuster le niveau de journalisation sur le service $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Toutes les données de journalisation sont envoyées à stderr.

Élément Obligatoire Description
-l, --log-level Niveaux valides : débogage, informations, avertissement, erreur. Ajuste le niveau de journalisation. Valeur par défaut : info
-j, --json-log Émet la sortie du journal sous forme d'enregistrements JSON.

Envoy comprend la journalisation. Pour en savoir plus, consultez la documentation Envoy aux liens suivants :

Modifier le nom du secret de règle

Un secret Kubernetes déployé sur le cluster contient les identifiants dont l'adaptateur a besoin pour authentifier la communication avec le proxy du service distant. Ce secret requiert un point d'installation de volume, qui peut être configuré. Par défaut, le point d'installation est /policy-secret. Pour modifier le point d'installation, procédez comme suit :

  1. Exécutez la commande suivante :
    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

    Exemple :

    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point
  2. Ouvrez $CLI_HOME/samples/apigee-envoy-adapter.yaml dans un éditeur.
  3. Remplacez le nom du point d'installation par le nouveau nom :
    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. Enregistrez le fichier et appliquez-le au maillage de services :
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

Utiliser un proxy réseau

Un proxy HTTP peut être inséré à l'aide des variables d'environnement HTTP_PROXY et HTTPS_PROXY dans l'environnement du binaire apigee-remote-service-envoy. Lorsque vous utilisez ces variables, la variable d'environnement NO_PROXY vous permet également d'empêcher l'envoi d'hôtes spécifiques via le proxy.

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

N'oubliez pas que le proxy doit être accessible à partir de apigee-remote-service-envoy.

À propos des métriques et des données d'analyse

Un point de terminaison de métriques Prometheus est disponible à l'adresse :5001/metrics. Vous pouvez configurer ce numéro de port. Consultez la section Fichier de configuration.

Analyses Envoy

Les liens suivants fournissent des informations sur l'obtention de données d'analyse de proxy Envoy :

Analyses Istio

Les liens suivants fournissent des informations sur l'obtention de données d'analyse de proxy Envoy :

Analyse Apigee

Apigee Remote Service for Envoy envoie des statistiques de requête à Apigee pour traitement. Apigee signale ces requêtes sous le nom de produit API associé.

Pour plus d'informations sur l'analyse Apigee, voir Présentation des services d'analyse.

Compatibilité avec les environnements mutualisés

Vous pouvez désormais activer l'adaptateur pour gérer plusieurs environnements au sein d'une organisation Apigee. Cette fonctionnalité vous permet d'utiliser une instance d'Apigee Adapter for Envoy associée à une organisation Apigee afin de gérer plusieurs environnements. Avant ce changement, un adaptateur était nécessaire pour chaque environnement Apigee.

Pour configurer la compatibilité avec plusieurs environnements, remplacez la valeur de tenant:env_name par "*" dans le fichier config.yaml. Exemple :

  1. Ouvrez le fichier config.yaml dans un éditeur.
  2. Remplacez la valeur de tenant.env_name par "*". Exemple : 
    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. Enregistrez le fichier.
  4. Appliquez le fichier : 
    kubectl apply -f $CLI_HOME/config.yaml

Lorsque vous configurez le mode multi-environnement, vous devez également configurer Envoy pour qu'il envoie une valeur d'environnement appropriée à l'adaptateur en ajoutant les métadonnées suivantes dans la section virtual_hosts:routes du fichier envoy-config.yaml. Exemple :

  1. Générez le fichier envoy-config.yaml à l'aide de la CLI. Exemple : 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  2. Ouvrez le fichier généré (appelé envoy-config.yaml).
  3. Ajoutez les métadonnées suivantes dans la section virtual_host ou routes du fichier : 
    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

    L'exemple suivant illustre la configuration d'un virtual_host avec plusieurs routes définies, où chaque route envoie le trafic vers un environnement spécifique : 

    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. Répétez la dernière étape pour ajouter d'autres environnements si nécessaire.
  5. Enregistrez le fichier et appliquez-le.

Capturer les données des rapports personnalisés

L'adaptateur est compatible avec la transmission de métadonnées Envoy vers la fonctionnalité de capture de données d'Apigee qui envoie les données capturées dans des variables que vous spécifiez à Apigee Analytics afin de les utiliser ultérieurement dans des rapports personnalisés. Cette fonctionnalité offre une capacité semblable à la stratégie de capture de données d'Apigee.

Pour utiliser cette fonction :

  1. Créez une ressource REST Data Collector.
  2. Définissez les variables de capture de données à l'aide de l'API Datacollectors d'Apigee.
  3. Si vous ne l'avez pas déjà fait, générez le fichier envoy-config.yaml à l'aide de la CLI. Exemple : 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. Ouvrez le fichier généré (appelé envoy-config.yaml).
  5. Utilisez un filtre Envoy afin de définir des valeurs pour vos variables personnalisées dans l'espace de noms envoy.filters.http.apigee.datacapture. Par exemple, vous pouvez utiliser un filtre En-tête de métadonnées ou Lua. Pour en savoir plus sur ces filtres, consultez les sections En-tête de métadonnées et Lua.

    Les noms des variables personnalisées doivent être au format dc.XXXXX.

    Exemple d'en-tête de filtre de métadonnées : 

     - 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

    Exemple de filtre 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. Ajoutez le filtre souhaité au fichier. Voir les exemples ci-dessous.
  7. Enregistrez le fichier et appliquez-le.

Configurer mTLS entre l'adaptateur et l'environnement d'exécution Apigee

Pour utiliser l'authentification mTLS entre l'adaptateur et l'environnement d'exécution Apigee, vous pouvez fournir des certificats TLS côté client dans la section tenant du fichier config.yaml de l'adaptateur. Cette modification s'applique à toutes les plates-formes Apigee compatibles. Elle active également mTLS pour l'analytique sur Apigee Edge pour Cloud Platform. Exemple : 

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