Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'
Apigee Edge.
Cette page explique comment ajouter des règles d'exécution Apigee et une règle d'injection de jeton Google à la passerelle Google Kubernetes Engine (GKE) avec l'opérateur Apigee pour Kubernetes. L'ajout d'un ensemble de règles disponibles à la passerelle vous permet d'étendre la fonctionnalité de la passerelle au-delà de l'application des produits d'API pour inclure des règles de sécurité et d'entreprise supplémentaires.
L'opérateur Apigee pour Kubernetes peut être utilisé pour ajouter les règles suivantes à la passerelle :
- Règle SpikeArrest
- Règle JavaScript
- Règlement sur l'injection de jetonsGoogle
- Règle GenerateJWT
- Règle KVM
- Règle OASValidation
- Règle ServiceCallout
- Règle OAuthv2
- Règle ResponseCache
- Règle de vérification des clés API
Présentation
Dans les sections suivantes, nous allons voir comment effectuer les tâches suivantes :
- Ajoutez des règles à GKE Gateway.
- Créez une règle de modèle pour appliquer l'utilisation des stratégies.
- Créez un modèle Apigee pour utiliser la règle de modèle.
- Déployez la règle de passerelle Apigee avec le modèle.
- Validez l'application des règles.
Avant de commencer
Pour modifier votre passerelle GKE avec l'ensemble complet de règles utilisées comme exemple dans ce guide, vous devez disposer d'un compte de service avec les rôles requis pour créer des jetons dans Apigee et déployer des proxys et des extensions. Si vous choisissez de ne pas créer de jetons Google , vous n'avez pas besoin d'ajouter les rôles supplémentaires à votre compte de service et vous pouvez passer à la section suivante.
Pour créer un compte de service disposant des autorisations requises, procédez comme suit :
- Si vous avez créé un compte de service nommé
apigee-apim-gsa
dans le guide d'installation d'Apigee Operator pour Kubernetes, vous pouvez ignorer cette étape et passer à la suivante. Sinon, créez le compte de service :gcloud iam service-accounts create apigee-apim-gsa --project=$PROJECT_ID
- Attribuez au compte de service le rôle nécessaire pour créer des jetons :
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/iam.serviceAccountTokenCreator"
- Attribuez au compte de service
apigee-apim-gsa
le rôle nécessaire pour déployer des proxys et des extensions :gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/iam.serviceAccountUser"
Modifier votre passerelle GKE avec des règles
Vous pouvez choisir de modifier votre passerelle GKE avec une ou plusieurs règles pour étendre ses fonctionnalités. Cet exemple de procédure pas à pas applique un fichier yaml
à la passerelle, qui inclut les spécifications de deux règles Apigee et d'une règle d'injection de jeton Google .
Chacune des règles appliquées à la passerelle à l'aide du fichier yaml
suivant joue un rôle différent lors de l'évaluation des requêtes envoyées à la passerelle :
- La règle SpikeArrest contrôle le débit maximal des messages en définissant un débit maximal de requêtes autorisées sur une unité de temps. Dans cet exemple, le débit maximal est défini sur cinq requêtes par minute. Pour en savoir plus sur l'utilisation de la règle SpikeArrest pour lisser les pics soudains de trafic, consultez Règle SpikeArrest.
- La règle JavaScript vous permet d'ajouter du code JavaScript personnalisé aux requêtes de passerelle. Dans cet exemple, la règle est utilisée pour ajouter un en-tête personnalisé à la requête. Pour en savoir plus sur l'utilisation de la règle JavaScript pour ajouter du code personnalisé, consultez Règle JavaScript.
- La règle d'injection de jeton Google est utilisée pour injecter un jeton d'accès à l'authentification Google dans les requêtes de passerelle, à l'aide de la règle AssignMessage. Apigee accepte l'utilisation de jetons OAuth ou OpenID Connect pour l'authentification auprès des services Google . Google Pour en savoir plus sur les jetons d'authentification, consultez Utiliser l'authentification Google.
Ajoutez les règles à la passerelle :
- Créez un fichier nommé
apigee-policies.yaml
dans l'espace de nomsapim
. - Copiez le contenu du fichier suivant dans le nouveau fichier que vous avez créé :
# apigee-policies.yaml apiVersion: apim.googleapis.com/v1 kind: SpikeArrest metadata: name: spike-arrest namespace: apim spec: identifier: ref: request.header.name useEffectiveCount: true peakMessageRate: value: "5pm" --- apiVersion: apim.googleapis.com/v1 kind: Javascript metadata: name: js-add-headers namespace: apim spec: timeLimit: 2000 source: | var sum = 1+1; context.setVariable("request.header.first", 1); context.setVariable("request.header.second", 1); context.setVariable("request.header.sum", sum); --- apiVersion: apim.googleapis.com/v1 kind: AssignMessage metadata: name: google-token-policy namespace: apim spec: setActions: - authentication: googleAccessToken: scopes: - 'https://www.googleapis.com/auth/cloud-platform' AssignTo: createNew: false type: request --- apiVersion: apim.googleapis.com/v1 kind: KVM metadata: name: kvm-1 namespace: apim spec: delete: - keys: - value: mykey exclusiveCache: true expiryTimeInSecs: 3600 get: - assignTo: response.header.mykvm keys: - value: mykey initialEntries: - keys: - key1 values: - val1 - keys: - mykey values: - initvalue isEncrypted: false put: - keys: - value: mykey values: - value: request.header.mykvm scope: environment --- apiVersion: apim.googleapis.com/v1 kind: OASValidation metadata: name: oas-validation-1 namespace: apim spec: openApiSpec: | openapi: 3.0.4 info: title: Sample API description: Optional multi/single line description. version: 0.1.9 servers: - url: http://apigee-apim-operator-test.apigee.net description: Optional server description, our main host in httproute paths: /get: get: summary: just for test description: Optional extended description in CommonMark or HTML. parameters: - name: X-Request-Type in: header description: Must be 'internal' or 'external'. required: true schema: type: string enum: - internal - external responses: '200': # status code description: A JSON object content: application/json: schema: type: object properties: headers: type: object source: request --- apiVersion: apim.googleapis.com/v1 kind: ServiceCallout metadata: name: service-callout-1 namespace: apim spec: request: clearPayload: true variable: myRequest ignoreUnresolvedVariables: true removeActions: - payload: true - queryParams: - name: rq-param1 - name: rq-param2 copyActions: - version: true - verb: true addActions: - headers: - name: X-header1 value: value1 - name: X-header2 value: value2 - queryParams: - name: q-param1 value: value1 - name: q-param2 value: value2 setActions: - verb: PUT - formParams: - name: f-param1 value: value1 - name: f-param2 value: value2 response: calloutResponse timeout: 30000 httpTargetConnection: URL: https://httpbin.org/put properties: - name: success.codes value: 1xx,2xx,3xx,400 - name: supports.http11 value: "true"
- Appliquez le fichier
yaml
à la passerelle à l'aide de la commande suivante :kubectl -n apim apply -f apigee-policies.yaml
Créer une TemplateRule en tant que modèle SharedFlow
À cette étape, vous allez créer un TemplateRule
pour appliquer les règles que vous avez ajoutées à la passerelle.
Une règle de modèle est une règle pour les SharedFlows créée par les administrateurs de l'organisation afin de s'assurer que seules les règles approuvées sont appliquées au trafic Gateway par les développeurs de services. Une règle de modèle permet aux développeurs de comprendre quelles règles sont à leur disposition, quelles règles sont requises pour des cas d'utilisation spécifiques et quelles règles ne peuvent pas être utilisées par les développeurs de services.
Créer une règle de modèle
Créez une règle de modèle pour appliquer l'utilisation de la règle AssignMessage :
- Créez un fichier
yaml
nommétemplate-rule.yaml
dans l'espace de nomsapim
. - Copiez le contenu du fichier suivant dans le nouveau fichier que vous avez créé :
# template-rule.yaml apiVersion: apim.googleapis.com/v1 kind: ApimTemplateRule metadata: name: template-rule namespace: apim spec: allowList: [SpikeArrest, Javascript, GenerateJWT, KVM, OASValidation, OAuthv2, ServiceCallout] requiredList: [AssignMessage] denyList: []
Dans cet exemple, la règle de modèle indique aux développeurs que la règle AssignMessage décrivant la stratégie d'injection de jetons Google est requise. Il indique également aux développeurs qu'ils peuvent utiliser les règles SpikeArrest, JavaScript, GenerateJWT, KVM, OASValidation, OAuthv2 et ServiceCallout dans leur gestion des API. Aucune règle n'est spécifiée dans la liste de refus.
Appliquer la règle du modèle
Appliquez la règle de modèle à l'aide de la commande suivante :
kubectl apply -f template-rule.yaml
Créer un modèle Apigee pour utiliser la règle de modèle
Créez un modèle Apigee pour inclure la règle de modèle que vous avez créée dans la section précédente :
- Créez un fichier
yaml
nomménew-admin-template.yaml
dans l'espace de nomsapim
. - Copiez le contenu du fichier suivant dans le nouveau fichier que vous avez créé :
# new-admin-template.yaml apiVersion: apim.googleapis.com/v1 kind: ApimTemplate metadata: name: new-admin-template namespace: apim spec: apimTemplateRule: group: apim.googleapis.com kind: ApimTemplateRule name: template-rule namespace: apim templates: - mode: REQUEST flows: - name: preflow policies: - group: apim.googleapis.com kind: OASValidation name: oas-validation-1 namespace: apim - group: apim.googleapis.com kind: SpikeArrest name: spike-arrest namespace: apim - name: ConditionalGetFlow policies: - group: apim.googleapis.com kind: Javascript name: js-add-headers namespace: apim condition: request.verb="GET" - name: postflow policies: - group: apim.googleapis.com kind: AssignMessage name: google-token-policy namespace: apim - group: apim.googleapis.com kind: ServiceCallout name: service-callout-1 namespace: apim - mode: RESPONSE flows: - name: postflow policies: - group: apim.googleapis.com kind: KVM name: kvm-1 namespace: apim
- Appliquez le nouveau modèle à l'aide de la commande suivante :
kubectl apply -f new-admin-template.yaml
Déployer la stratégie Apigee Gateway
Dans cette étape, vous allez appliquer un nouveau fichier à votre passerelle, qui inclut les spécifications d'un ApigeeGatewayPolicy
.
Cette règle permet de déployer le modèle Apigee sur la passerelle.
Déployez la règle de passerelle Apigee :
- Créez un fichier
yaml
nomméapigee-gateway-policy-withSA.yaml
dans l'espace de nomsapim
. - Copiez le contenu du fichier suivant dans le nouveau fichier que vous avez créé :
# apigee-gateway-policy-withSA.yaml apiVersion: apim.googleapis.com/v1 kind: ApigeeGatewayPolicy metadata: name: apim-template-injection namespace: apim spec: serviceAccount: apigee-apim-gsa@PROJECT_ID.iam.gserviceaccount.com ref: group: apim.googleapis.com kind: ApimTemplate name: new-admin-template namespace: apim targetRef: group: apim.googleapis.com kind: APIMExtensionPolicy name: APIMEXTENSION_POLICY_NAME namespace: apim
Remplacez PROJECT_ID par l'ID du projet Google Cloud .
Remplacez APIMEXTENSION_POLICY_NAME par le nom de l'APIMExtensionPolicy que vous souhaitez utiliser pour appliquer la règle Apigee Gateway. Si vous avez créé une APIMExtensionPolicy pour créer une extension de trafic, utilisez le nom de la règle que vous avez créée. Si vous avez utilisé un ApigeeBackendService pour créer une extension de trafic, utilisez le nom de l'ApigeeBackendService. Lorsque vous créez un ApigeeBackendService, l'opérateur Apigee pour Kubernetes crée une APIMExtensionPolicy avec le même nom et le même espace de noms que le BackendService.
- Appliquez la règle :
kubectl apply -f apigee-gateway-policy-withSA.yaml
- Vérifiez l'état du déploiement de la nouvelle règle de passerelle :
kubectl -n apim get ApigeeGatewayPolicy
Une fois la règle
STATUS
déployée, l'étatCREATED
doit s'afficher.
Une fois la nouvelle règle de passerelle déployée, attendez deux minutes avant d'envoyer une requête à la passerelle pour permettre à la règle de se propager au cluster.
Valider l'application des règles
Pour vérifier que les règles de la passerelle Apigee fonctionnent comme prévu, envoyez des requêtes à la passerelle comme décrit dans les sections suivantes.
Application de la règle AssignMessage
Pour vérifier que le jeton {company_name} est injecté dans la requête à l'aide de la règle AssignMessage, envoyez une requête à la passerelle à l'aide de la commande suivante :
curl http://GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME" -H "x-api-key: API_KEY"
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante :kubectl get gateway GATEWAY_NAME
HOST_NAME
est le nom de l'hôte.API_KEY
correspond à la valeur de la clé API.
Une réponse réussie doit inclure un en-tête Authorization
avec le jeton du porteur généré, semblable à ce qui suit :
{ "args": {}, "headers": { "Accept": "*/*", "Authorization": "Bearer ya29.c.c0ASRK0Gbw03y9cfvxL11DxaRYBQUU18SmUP4Vu63OckHI5cX7wJ4DmGMG2vbDDS69HXJHqMj-lak4tcqOsJGmE65crn2gNuJLanXidwM8", "First": "1.0", "Host": "apigee-apim-operator-test.apigee.net", "Second": "1.0", "Sum": "2", "User-Agent": "curl/8.7.1", "X-Api-Key": "McYcHGR3PTSGLXExvKADwQ1JJeCjgPDUvAakCl0rJKCFaX0Y", "X-Cloud-Trace-Context": "0fd3dadc2a3c328fa968d5f5f1434c29/18300783092696918345" }, "origin": "34.54.108.129", "url": "apigee-apim-operator-test.apigee.net/get" }
Application de la règle SpikeArrest
Vous pouvez tester l'application de la règle SpikeArrest en envoyant une requête à la passerelle dix fois en une minute.
Vous pouvez exécuter le script suivant pour générer les requêtes :
#!/bin/sh for i in $(seq 1 11); do curl http://GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME" -H "x-api-key: API_KEY" sleep 1 done
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante, oùGATEWAY_NAME
est le nom de la passerelle :kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
correspond au nom d'hôte défini dans la ressourceHTTPRoute
de la passerelle.API_KEY
correspond à la valeur de la clé API obtenue dans Tester la configuration.
La réponse devrait ressembler à ce qui suit :
"fault":{"faultstring":"Spike arrest violation. Allowed rate : MessageRate{capacity=5, period=Minutes}","detail":{"errorcode":"policies.ratelimit.SpikeArrestViolation"}}}
Application de la règle JavaScript
Pour vérifier que la règle JavaScript fonctionne comme prévu, envoyez une requête à la passerelle à l'aide de la commande suivante :
curl http://GATEWAY_IP_ADDRESS/get \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -i
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante, oùGATEWAY_NAME
est le nom de la passerelle :kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
correspond au nom d'hôte défini dans la ressourceHTTPRoute
de la passerelle.API_KEY
correspond à la valeur de la clé API obtenue dans Tester la configuration.
La règle JavaScript définit trois en-têtes de requête : First
, Second
et Sum
, comme indiqué dans la réponse :
HTTP/1.1 200 OK ... { "args": {}, "headers": { ... "First": "1.0", ... "Second": "1.0", "Sum": "2", ... }, ... }
Application de la règle OASValidation
Pour vérifier que la règle OASValidation fonctionne comme prévu, envoyez une requête à la passerelle à l'aide de la commande suivante :
curl "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: badvalue"
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante, oùGATEWAY_NAME
est le nom de la passerelle :kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
correspond au nom d'hôte défini dans la ressourceHTTPRoute
de la passerelle.API_KEY
correspond à la valeur de la clé API obtenue dans Tester la configuration.
La commande inclut une valeur non valide pour l'en-tête X-Request-Type
. La requête échouera et renverra une réponse semblable à celle-ci :
{"fault":{"faultstring":"OASValidation oas-validation-1 with resource \"oas:\/\/oas-validation-1.yaml\": failed with reason: \"[ERROR - Instance value (\"badvalue\") not found in enum (possible values: [\"internal\",\"external\"]): []]\"","detail":{"errorcode":"steps.oasvalidation.Failed"}}}
Si vous envoyez la même requête avec une valeur valide pour l'en-tête X-Request-Type
, elle aboutira. Exemple :
curl "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -i
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante, oùGATEWAY_NAME
est le nom de la passerelle :kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
correspond au nom d'hôte défini dans la ressourceHTTPRoute
de la passerelle.API_KEY
correspond à la valeur de la clé API obtenue dans Tester la configuration.
Application de la règle ServiceCallout
Vous pouvez vérifier l'application de la règle ServiceCallout en ouvrant une session de débogage et en envoyant quelques requêtes valides au proxy.
Pour ouvrir une session de débogage, procédez comme suit :
- Dans la console Google Cloud , accédez à la page Proxys d'API.
- Sélectionnez le proxy
global-ext-lb1-apim-policy
que vous avez déployé dans l'environnement créé pour l'opérateur Apigee pour Kubernetes. - Cliquez sur l'onglet Débogage.
- Dans la fenêtre Session de débogage, cliquez sur Démarrer la session de débogage.
- Dans le volet Session de débogage, effectuez les sélections suivantes :
- Environnement : sélectionnez l'environnement que vous avez créé pour l'opérateur Apigee pour Kubernetes dans la liste des environnements disponibles.
- Filtre : sélectionnez Aucun (toutes les transactions).
- Cliquez sur Démarrer.
Une fois la session démarrée, vous pouvez envoyer des requêtes valides au proxy :
curl "GATEWAY_IP_ADDRESSget" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -i
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante, oùGATEWAY_NAME
est le nom de la passerelle :kubectl get gateway GATEWAY_NAME
HOST_NAME
correspond au nom d'hôte défini dans la ressourceHTTPRoute
de la passerelle.API_KEY
correspond à la valeur de la clé API obtenue dans Tester la configuration.
Les transactions de requête et de réponse s'affichent dans le volet Transactions. Sélectionnez une transaction réussie dans la liste pour afficher le flux. Vous devriez voir que la règle ServiceCallout
a bien été exécutée.
Application des règles KVM
Lorsque la règle KVM s'exécute correctement, elle initialise le KVM avec une valeur de départ pour la clé mykey
.
Lorsqu'une transaction de réponse est effectuée, la règle KVM récupère la valeur de mykey
et la stocke dans l'en-tête de réponse mykvm
.
Lorsque la règle KVM s'exécute à nouveau, elle insère la nouvelle valeur de mykey
obtenue à partir de l'en-tête de requête mykvm
.
Vous pouvez vérifier les en-têtes de chaque transaction pour confirmer que la règle stocke une valeur dans le KVM lors d'une transaction et récupère la même valeur lors de la transaction suivante, comme illustré dans l'exemple suivant.
Testez la règle KVM :
- Envoyez une requête à la passerelle :
curl -i "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" \ -H "KVM_NAME: next-value1" -i
Où :
GATEWAY_IP_ADDRESS
est l'adresse IP de la passerelle. Vous pouvez récupérer l'adresse IP de la passerelle à l'aide de la commande suivante, oùGATEWAY_NAME
est le nom de la passerelle :kubectl get gateway GATEWAY_NAME
HOST_NAME
correspond au nom d'hôte défini dans la ressourceHTTPRoute
de la passerelle.API_KEY
correspond à la valeur de la clé API obtenue dans Tester la configuration.KVM_NAME
est le nom du KVM.
- Vérifiez les en-têtes de réponse pour confirmer que la règle KVM s'est exécutée correctement et qu'une valeur initiale a été stockée pour
mykvm
. La réponse devrait ressembler à ceci :HTTP/1.1 200 OK access-control-allow-credentials: true access-control-allow-origin: * Content-Length: 517 content-type: application/json date: ... server: gunicorn/19.9.0 mykvm: initvalue via: 1.1 google { "args": { ... "url": "http://apigee-apim-operator-test.apigee.net/get" } }
- Envoyez une autre requête à la passerelle :
curl -i "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "mykvm: next"X-Request-Type: external" -H "mykvm: next-value2" -i
La sortie devrait ressembler à ce qui suit :
HTTP/1.1 200 OK access-control-allow-credentials: true access-control-allow-origin: * Content-Length: 517 content-type: application/json date: ... server: gunicorn/19.9.0 mykvm: next-value2 via: 1.1 google { "args": { ... "url": "http://apigee-apim-operator-test.apigee.net/get?rq-param2=rq-val1&x-param1=xval1" } }
Vous pouvez constater que la règle KVM s'est exécutée avec succès, car la valeur de l'en-tête
mykvm
est mise à jour avec la valeur de l'en-tête de requêtemykvm
. - Envoyez une autre demande :
curl -i "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -H "mykvm: next-value3" -i
La sortie devrait ressembler à ce qui suit :
HTTP/1.1 200 OK access-control-allow-credentials: true access-control-allow-origin: * Content-Length: 517 content-type: application/json date: ... server: gunicorn/19.9.0 mykvm: next-value2 via: 1.1 google { "args": { ... "url": "http://apigee-apim-operator-test.apigee.net/get?rq-param2=rq-val1&x-param1=xval1" } }
La valeur de l'en-tête
mykvm
est à nouveau mise à jour, ce qui montre que la valeur affichée dans la réponse correspond aux valeurs stockées dans la transaction précédente.
Résoudre les problèmes
Si vous rencontrez des problèmes lors de l'ajout de règles à la passerelle GKE, consultez Résoudre les problèmes liés à l'opérateur Apigee pour Kubernetes pour trouver des solutions aux erreurs courantes.
Étapes suivantes
- En savoir plus sur la règle SpikeArrest
- En savoir plus sur la règle JavaScript