Exemple Apigee hybrid avec Kubernetes

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

Cet exemple montre comment utiliser l'adaptateur Apigee pour Envoy avec un déploiement hybride Apigee.

Prérequis

Avant de commencer :

Présentation

Cet exemple explique comment utiliser l'adaptateur Apigee pour Envoy avec Apigee hybride. Dans cet exemple, vous allez déployer un service HTTP simple dans le même cluster Kubernetes où est déployé Apigee hybride. Vous allez ensuite configurer l'adaptateur Apigee pour Envoy pour gérer les appels d'API à ce service avec Apigee.

La figure suivante illustre l'architecture de base pour l'intégration hybride Apigee :

Vue d'ensemble de l'adaptateur Envoy intégré à un environnement hybride Apigee, y compris le plan de gestion, le plan d'exécution et les services GCP

Un proxy Envoy est déployé avec le service HTTP cible en tant que side-car Istio dans le maillage de services Istio. Le side-car gère le trafic de l'API vers et depuis le service cible, et communique avec le service distant. Le service distant communique également avec le plan de gestion hybride pour récupérer des informations sur le proxy et le produit d'API.

Vérifier votre configuration gcloud

  1. Vérifiez que votre configuration gcloud est définie sur le projet GCP associé à votre organisation hybride.

    Pour répertorier les paramètres actuels :

    gcloud config list

    Si nécessaire, définissez l'ID correct du projet GCP avec la commande suivante :

    gcloud config set project project-id
  2. Vous devez être authentifié avec le SDK Google Cloud (gcloud) pour votre projet GCP :
    gcloud auth login

Provisionner Apigee hybrid

Au cours de cette étape, vous allez utiliser la CLI du service distant pour provisionner Apigee hybrid avec le proxy d'API remote-service. La commande de provisionnement configure également un certificat sur Apigee et génère des identifiants que le service distant utilisera pour se reconnecter de manière sécurisée à Apigee.

  1. Accédez au répertoire $CLI_HOME :
    cd $CLI_HOME
  2. Si vous n'êtes pas le propriétaire du projet GCP associé à l'organisation hybride Apigee, assurez-vous que votre compte utilisateur GCP inclut le rôle Administrateur de l'organisation Apigee ou les rôles Créateur d'API et Déployeur.

    Consultez la section Accorder, modifier et révoquer les accès à des ressources.

  3. Exécutez la commande suivante pour obtenir un jeton d'accès :
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  4. (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.
  5. 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
    export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

    Où :

    Variable Description
    organization_name Nom de l'organisation Apigee pour l'installation Apigee hybrid.
    environment_name Nom d'un environnement dans votre organisation Apigee hybrid.
    host_alias_url URL incluant la valeur hostAlias pour un hôte virtuel défini dans votre configuration hybride. L'URL doit commencer par https://. Par exemple : https://apitest.apigee-hybrid-docs.net.
    hybrid_runtime_namepace Espace de noms dans lequel les composants d'exécution hybrides 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.
  6. Exécutez la commande suivante pour provisionner le proxy de service distant sur Apigee hybride :

    Si vous n'effectuez pas la mise à niveau, utilisez cette commande pour provisionner Apigee :

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
         --runtime $RUNTIME --namespace $NAMESPACE --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 :

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
         --runtime $RUNTIME --namespace $NAMESPACE --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: GCP)
    # 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.example.com/remote-service
          org_name: hybrid-gke
          env_name: test
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.example.com/remote-token/token
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hybrid-gke-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: hybrid-gke-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
  8. Appliquez la configuration du service (la sortie du fichier par la commande de provisionnement) au cluster :
    kubectl apply -f $CLI_HOME/config.yaml
  9. Vérifiez votre proxy et votre certificat. La commande suivante doit renvoyer un JSON valide :
    curl -i $RUNTIME/remote-token/certs

    Le résultat ressemble à ceci :

    {
        "keys": [
            {
                "alg": "RS256",
                "e": "AQAB",
                "kid": "2020-05-11T11:32:26-06:00",
                "kty": "RSA",
                "n": "0v-nbTQyAmtVZ-wZRP0ZPIbrVaX91YO9JZ9xCQPb4mOdOSS7yKfTDJGg0KM130sGVYBvR76alN8
                fhrrSDEG5VXG8YYMqPXarwRC7MRJWocCQ_ECYrjDD0_Q018M2HyXZYSd8fhAogi9mVUYsEmCKqJH53Dh1
                jqsHOQzBLKsX0iDO9hEZNFtjbX0UCbSxsUlmBCub7Uj2S-PahA6DEQOMhQjZM7bBMtkTMpFmaJ_RZTmow
                BHP57qMna17R8wHD4kUsO2u_-3HHs5PSj1NrEYoVU2dwLQw0GlkB__ZWeFgXTqot81vb-PmoM9YxwoZrm
                TcHdljugWy_s7xROPzTod0uw"
            }
        ]
    }

Créer des exemples de fichiers de configuration

Utilisez la commande apigee-remote-service-cli samples create pour générer des exemples de fichiers de configuration.

Pour cet exemple, vous avez besoin des fichiers générés :

  • httpbin.yaml : configuration de déploiement pour un service HTTP.
  • apigee-envoy-adapter.yaml : configuration de déploiement du service distant pour Envoy.
  • envoyfilter-sidecar.yaml : configuration qui installe un EnvoyFilter à l'espace de noms par défaut.

Pour générer les exemples, procédez comme suit :

  1. Accédez au répertoire $CLI_HOME :
  2. Exécutez cette commande pour générer les fichiers :

    ./apigee-remote-service-cli samples create -c ./config.yaml --template istio-1.12

    Les fichiers suivants renvoient le répertoire ./samples :

    ls samples
    apigee-envoy-adapter.yaml envoyfilter-sidecar.yaml httpbin.yaml request-authentication.yaml
    

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

Déployer un service de test sur le cluster

Au cours de cette étape, vous allez déployer un service de test de requêtes/réponse HTTP simple sur le même cluster que celui où Apigee hybrid est déployé.

  1. Activez l'injection Istio dans l'espace de noms default du cluster. Dans une étape ultérieure, vous allez déployer un side-car Envoy sur ce même cluster. L'activation de l'injection Istio permet le déploiement side-car. Cet exemple utilise l'espace de noms default et toutes les instructions suivantes utilisent le même.

    Si vous utilisez Istio Open Source :

    kubectl label namespace default istio-injection=enabled --overwrite

    Si vous utilisez ASM :

    kubectl label namespace default istio-injection- istio.io/rev=REVISION --overwrite
  2. Appliquez le service httpbin simple au cluster dans l'espace de noms par défaut :
    kubectl apply -f $CLI_HOME/samples/httpbin.yaml
  3. Testez maintenant le service. Démarrez un service curl exécuté dans le cluster et ouvrez un terminal :
    kubectl run -it curl --image=curlimages/curl --restart=Never -- sh
  4. Testez le service en l'appelant à partir du cluster :
    curl -i httpbin.default.svc.cluster.local/headers

    Si l'opération réussit, l'état 200 s'affiche et le service renvoie une liste d'en-têtes. Exemple :

    HTTP/1.1 200 OK
    server: envoy
    date: Tue, 12 May 2020 17:09:01 GMT
    content-type: application/json
    content-length: 328
    access-control-allow-origin: *
    access-control-allow-credentials: true
    x-envoy-upstream-service-time: 7
    
    {
      "headers": {
        "Accept": "*/*",
        "Content-Length": "0",
        "Host": "httpbin.default.svc.cluster.local",
        "User-Agent": "curl/7.70.0-DEV",
        "X-B3-Parentspanid": "69f88bc3e322e157",
        "X-B3-Sampled": "0",
        "X-B3-Spanid": "8dd725f30e393d8b",
        "X-B3-Traceid": "38093cd817ad30a569f88bc3e322e157"
      }
    }

Exécuter le service distant pour Envoy

Au cours de cette étape, vous allez démarrer le service Remote Service pour le client Envoy. Ce service fournit les points de terminaison aux side-cars Istio installés sur les services cibles. Vous installerez également un side-car avec le service httpbin.

  1. Appliquez le service distant Apigee au maillage de services :
    kubectl apply -f $CLI_HOME/samples/apigee-envoy-adapter.yaml
  2. Appliquez l'objet EnvoyFilter aux side-cars Istio dans l'espace de noms par défaut. EnvoyFilter permet au side-car httpbin de communiquer avec le service distant Apigee.
    kubectl apply -f $CLI_HOME/samples/envoyfilter-sidecar.yaml

Tester l'installation

  1. Revenez à l'interface système curl que vous avez ouverte à l'étape Déployer un service de test sur le cluster et appelez le service httpbin :
    curl -i httpbin.default.svc.cluster.local/headers
    

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

    curl -i httpbin.default.svc.cluster.local/headers
    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
  2. Configurez un produit d'API et obtenez une clé API comme expliqué dans la section Comment obtenir une clé API.
  3. Effectuez un appel d'API à l'aide de la clé :
    export APIKEY=YOUR_API_KEY
    curl -i httpbin.default.svc.cluster.local/headers -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. 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": "kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS",
        "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": "kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS",
        "X-Apigee-Developeremail": "jdoe@example.com",
        "X-Apigee-Environment": "envoy",
        "X-Apigee-Organization": "acme-org",
        "X-Apigee-Scope": "",
        "X-B3-Parentspanid": "1476f9a2329bbdfa",
        "X-B3-Sampled": "0",
        "X-B3-Spanid": "1ad5c19bfb4bc96f",
        "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
      }
    }

É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.
  • Utilisez l'interface de ligne de commande pour gérer, créer des jetons et contrôler les liaisons. Pour plus d'informations sur la CLI, consultez la documentation de référence.