Exemple d'Envoy natif pour Apigee et Apigee hybrid

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

Consultez la documentation d'Apigee Edge.

Cet exemple montre comment utiliser Apigee Adapter for Envoy en installant et en exécutant Envoy localement, et non dans un cluster Kubernetes. Vous pouvez suivre l'exemple de ce document pour les installations Apigee et Apigee hybrid.

Les appels de proxy d'API passent par Envoy s'exécutant en tant qu'application native. Apigee fournit des services de gestion d'API, tels que la création de produits d'API et d'applications de développement. Envoy communique avec le plan de gestion Apigee via le service distant de l'adaptateur. L'adaptateur transfère également les données d'analyse vers Apigee que vous pouvez consulter dans Apigee Analytics.

Prérequis

Avant de commencer :

Vérifier votre configuration gcloud

  1. Vérifiez que votre configuration gcloud est définie sur le projet Google Cloud associé à votre organisation Apigee.

    Pour répertorier les paramètres actuels, consultez également gcloud config.

    gcloud config list

    Si nécessaire, définissez l'ID correct du projet Google Cloud à l'aide de cette commande :

    gcloud config set project project-id
  2. Vous devez être authentifié avec Google Cloud SDK (gcloud) pour votre projet Google Cloud. Consultez également la page gcloud auth login.
    gcloud auth login

Provisionner Apigee

Au cours de cette étape, vous allez utiliser la CLI Remote Service pour provisionner des éléments d'Apigee Adapter for Envoy vers Apigee. La commande de provisionnement déploie les proxys d'API utilisés pour les opérations de l'adaptateur Apigee, configure un certificat sur Apigee et génère des identifiants que le service distant utilisera pour se connecter en toute sécurité à partir de votre système à Apigee.

  1. Accédez au répertoire $CLI_HOME :
    cd $CLI_HOME
  2. (Facultatif) Par défaut, l'adaptateur recherche les identifiants du compte de service par défaut dans votre projet Google Cloud pour autoriser l'envoi de données d'analyse à Apigee. Si vous ne souhaitez pas utiliser les identifiants de compte de service par défaut, vous pouvez créer un compte de service et référencer sa clé dans la commande de provisionnement. Le compte de service doit disposer du rôle apigee.analyticsAgent. Pour obtenir des instructions, consultez la page Créer et gérer des comptes de service.
  3. Créez les variables d'environnement suivantes. Ces variables seront utilisées en tant que paramètres du script de provisionnement :
    export ORG=organization_name
    export ENV=environment_name
    export RUNTIME=host_alias_url
    export NAMESPACE=hybrid_runtime_namespace  ## Apigee hybrid only
    export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

    Où :

    Variable Description
    organization_name Nom de votre organisation Apigee
    environment_name Nom d'un environnement dans votre organisation
    host_alias_url
    • Pour Apigee hybrid, une URL qui inclut le hostAlias pour un hôte virtuel défini dans votre configuration hybride ;
    • Pour Apigee, un nom d'hôte du groupe d'environnements qui inclut l'environnement. Vous pouvez trouver les groupes d'environnement dans l'interface utilisateur d'Apigee sous Administration > Environnements > Groupes.
    • Remarque : L'URL doit commencer par https://. Par exemple : https://apitest.mydomain.net

    hybrid_runtime_namepace (Apigee hybrid uniquement) Espace de noms dans lequel les composants d'exécution Hybrid sont déployés.

    Remarque : L'espace de noms par défaut pour un déploiement hybride est apigee.

    analytics_service_account (Facultatif) Chemin d'accès à un fichier JSON de clé de compte de service Google Cloud possédant le rôle Apigee Analytics Agent. Pour obtenir une description détaillée de ce paramètre, consultez la section Commande de provisionnement.
  4. Si vous n'êtes pas le propriétaire du projet Google Cloud associé à l'organisation Apigee, assurez-vous que votre compte utilisateur Google Cloud inclut le rôle Administrateur de l'organisation Apigee ou les rôles Créateur d'API et Déployeur. Consultez Accorder, modifier et révoquer les accès à des ressources.
  5. Obtenir un jeton d'accès :
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  6. Provisionnez le proxy de service distant vers Apigee. Le résultat de la commande est redirigé vers un fichier de configuration que vous utiliserez ultérieurement.

    Si vous n'effectuez pas la mise à niveau, utilisez cette commande pour provisionner Apigee. Si vous provisionnez Apigee hybrid, veillez à ajouter le paramètre --namespace $NAMESPACE :

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
         --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml

    Si vous mettez à niveau, exécutez cette commande avec l'option --force-proxy-install pour provisionner Apigee. Si vous provisionnez Apigee hybrid, veillez à ajouter le paramètre --namespace $NAMESPACE :

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
         --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
  7. Vérifiez le contenu du fichier config.yaml. Voici un exemple :
    # Configuration for apigee-remote-service-envoy (platform: Google Cloud)
    # generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee
    data:
      config.yaml: |
        tenant:
          remote_service_api: https://apitest.mydomain.com/remote-service
          org_name: my-org
          env_name: test
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.mydomain.com/remote-service/token
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: my-org-new-test-policy-secret
      namespace: apigee
    type: Opaque
    data:
      remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
      remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
      remote-service.properties: a2lkPTIwMjAtMDctMDZ...
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: my-org-new-test-analytics-secret
      namespace: apigee
    type: Opaque
    data:
      client_secret.json: ewogICJ0eXBlIjogInNlcnZ...
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee

Exécuter apigee-remote-service-envoy

Vous pouvez exécuter Remote Service en tant que binaire natif ou sur Docker.

Exécuter le service de manière native

Exécutez le binaire du service avec le fichier de configuration généré par la commande de provisionnement :

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml

Exécuter le service sur Docker

Les images Docker sont publiées avec des tags de version. Pour cette installation, utilisez la dernière version. Il existe trois variantes d'image :

Variante Image
Distroless Google google/apigee-envoy-adapter:v2.0.3
Ubuntu google/apigee-envoy-adapter:v2.0.3-ubuntu
Ubuntu avec Boring Crypto google/apigee-envoy-adapter:v2.0.3-boring

Par exemple, pour exécuter l'image test avec votre fichier config.yaml local disponible sous le nom /config.yaml via une installation de volume, utilisez la commande suivante :

docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.3

Créer un exemple de fichier de configuration Envoy

Générez un exemple de fichier de configuration Envoy à l'aide de la CLI :

  1. Assurez-vous que vous vous trouvez dans le répertoire $ENVOY_HOME.
  2. Répertoriez les modèles de configuration disponibles :
    $CLI_HOME/apigee-remote-service-cli samples templates
  3. Exécutez la commande d'exemples. Remplacez TEMPLATE par l'un des modèles Envoy compatibles :

    $CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml

    La commande crée le fichier ./samples/envoy-config.yaml.

Pour en savoir plus, consultez la section Commande d'exemples.

Installer et exécuter le proxy Envoy

Pour installer et exécuter le proxy Envoy, procédez comme suit :

  1. Téléchargez un binaire Envoy ou compilez-le.
  2. Exécutez Envoy à l'aide d'un exemple de fichier de configuration que vous avez généré précédemment pour le service httpbin.org :
    envoy -c ./samples/envoy-config.yaml

Tester l'installation

  1. Configurez un produit d'API et obtenez une clé API comme expliqué dans la section Comment obtenir une clé API.
  2. Appelez le service httpbin sans clé API :
    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
    

    Le service est désormais géré par Apigee, et puisque vous n'avez pas fourni de clé API, cet appel renvoie l'erreur suivante.

    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
    HTTP/1.1 403 Forbidden
    date: Tue, 12 May 2020 17:51:36 GMT
    server: envoy
    content-length: 0
    x-envoy-upstream-service-time: 11
  3. Effectuez un appel d'API à l'aide de la clé :
    export APIKEY=YOUR_API_KEY
    curl -i http://localhost:8080/headers -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"

    L'appel doit réussir avec un code d'état 200 et renvoyer une liste d'en-têtes dans la réponse. Par exemple :

    curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS"
    HTTP/1.1 200 OK
    server: envoy
    date: Tue, 12 May 2020 17:55:34 GMT
    content-type: application/json
    content-length: 828
    access-control-allow-origin: *
    access-control-allow-credentials: true
    x-envoy-upstream-service-time: 301
    
    {
      "headers": {
        "Accept": "*/*",
        "Content-Length": "0",
        "Host": "httpbin.default.svc.cluster.local",
        "User-Agent": "curl/7.70.0-DEV",
        "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS",
        "X-Apigee-Accesstoken": "",
        "X-Apigee-Api": "httpbin.default.svc.cluster.local",
        "X-Apigee-Apiproducts": "httpbin",
        "X-Apigee-Application": "httpbin",
        "X-Apigee-Authorized": "true",
        "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS",
        "X-Apigee-Developeremail": "user@mydomain.com",
        "X-Apigee-Environment": "test",
        "X-Apigee-Organization": "my-org",
        "X-Apigee-Scope": "",
        "X-B3-Parentspanid": "1476f9a2329bbdfa",
        "X-B3-Sampled": "0",
        "X-B3-Spanid": "1ad5c19bfb4bc96f",
        "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
      }
    }

Désinstaller l'adaptateur Apigee Envoy

Pour supprimer l'installation d'un adaptateur Apigee Envoy, procédez comme suit :

  1. Quel que soit l'endroit où vous avez choisi d'exécuter l'adaptateur Envoy (en mode natif ou sur Docker), supprimez-le.
  2. Supprimez les proxys remote-service et remote-token de vos environnements Apigee. Consultez la page Supprimer un proxy d'API.
  3. Supprimez tous les produits d'API inutilisés ou les opérations d'API utilisées par les cas d'utilisation de l'adaptateur Envoy. Consultez la section Supprimer un produit d'API.

Étapes suivantes

Le trafic d'API vers le service httpbin est désormais géré par Apigee. Voici quelques fonctionnalités que vous pouvez explorer et essayer :

  • Accédez à Apigee Analytics dans l'interface utilisateur Edge. Accédez à Analyser> Métriques API > Performances des proxys d'API.
  • Découvrez les options de la CLI dans la Documentation de référence.