Aggiungi criteri al gateway GKE

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come aggiungere criteri di runtime Apigee e un criterio di inserimento token al gateway Google Kubernetes Engine (GKE) con l'operatore APIM Apigee per Kubernetes. Google L'aggiunta di un insieme di policy disponibili al gateway consente di estendere la funzionalità del gateway oltre l'applicazione del prodotto API per includere regole aziendali e di sicurezza aggiuntive.

L'operatore Apigee APIM per Kubernetes può essere utilizzato per aggiungere i seguenti criteri al gateway:

Panoramica

Nelle sezioni seguenti viene descritto come:

Prima di iniziare

Per modificare il gateway GKE con il set completo di criteri utilizzato come esempio in questa guida, devi disporre di un account di servizio con i ruoli necessari per creare token in Apigee e implementare proxy ed estensioni. Se scegli di non creare token Google , non devi aggiungere i ruoli aggiuntivi al account di servizio e puoi passare alla sezione successiva.

Per creare un account di servizio con le autorizzazioni richieste:

  1. Se hai creato un account di servizio denominato apigee-apim-gsa nella guida all'installazione di Apigee APIM Operator per Kubernetes, puoi saltare questo passaggio e procedere al successivo. In caso contrario, crea il account di servizio: 
    gcloud iam service-accounts create apigee-apim-gsa --project=$PROJECT_ID
  2. Concedi al account di servizio il ruolo necessario per creare token: 
    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/iam.serviceAccountTokenCreator"
  3. Concedi al account di servizio apigee-apim-gsa il ruolo necessario per il deployment di proxy ed estensioni: 
    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/iam.serviceAccountUser"

Modifica il gateway GKE con le policy

Puoi scegliere di modificare il gateway GKE con uno o più criteri per estenderne la funzionalità. Questo esempio applica un file yaml al gateway che include le specifiche per due criteri Apigee e un criterio di inserimento di token Google .

Ognuna delle policy applicate al gateway utilizzando il seguente file yaml svolge un ruolo diverso durante la valutazione delle richieste inviate al gateway:

  • Il criterio Spike Arrest controlla la frequenza massima dei messaggi definendo una frequenza massima di richieste consentite in un'unità di tempo. In questo esempio, la frequenza massima è impostata su cinque al minuto. Per scoprire di più su come viene utilizzato il criterio SpikeArrest per smussare i picchi improvvisi di traffico, consulta Criterio SpikeArrest.
  • Il criterio JavaScript consente di aggiungere codice JavaScript personalizzato alle richieste del gateway. In questo esempio, il criterio viene utilizzato per aggiungere un'intestazione personalizzata alla richiesta. Per saperne di più su come vengono utilizzati i criteri JavaScript per aggiungere codice personalizzato, consulta la sezione Criteri JavaScript.
  • Il criterio di inserimento del token Google viene utilizzato per inserire un token di accesso di autenticazione Google nelle richieste del gateway utilizzando il criterio AssignMessage. Apigee supporta l'utilizzo di token OAuth o OpenID Connect per l'autenticazione con i servizi Google . Google Per scoprire di più sui token di autenticazione, consulta Utilizzo dell'autenticazione Google.

Aggiungi le policy al gateway:

  1. Crea un nuovo file denominato apigee-policies.yaml nello spazio dei nomi apim.
  2. Copia i contenuti del seguente file nel nuovo file che hai creato: 
    # 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"
  3. Applica il file yaml al gateway utilizzando il seguente comando: 
    kubectl -n apim apply -f apigee-policies.yaml

Crea una TemplateRule come modello SharedFlow

In questo passaggio creerai un TemplateRule per applicare le policy che hai aggiunto al gateway. Una regola modello è una regola per SharedFlows creata dagli amministratori dell'organizzazione per garantire che solo le norme approvate vengano applicate al traffico del gateway dagli sviluppatori di servizi. Una regola del modello garantisce che gli sviluppatori comprendano quali norme sono a loro disposizione, quali sono necessarie per casi d'uso specifici e quali non possono essere utilizzate dagli sviluppatori di servizi.

Creare una regola di modello

Crea una regola di modello per applicare l'utilizzo del criterio AssignMessage:

  1. Crea un nuovo file yaml denominato template-rule.yaml nello spazio dei nomi apim.
  2. Copia i contenuti del seguente file nel nuovo file che hai creato: 
    # 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: []

    In questo esempio, la regola del modello indica agli sviluppatori che è obbligatoria la norma AssignMessage che descrive la norma di inserimento del token Google . Inoltre, indica agli sviluppatori che possono utilizzare i criteri SpikeArrest, JavaScript, GenerateJWT, KVM, OASValidation, OAuthv2 e ServiceCallout nella gestione delle API. Non sono specificate policy nell'elenco di negazione.

Applicare la regola del modello

Applica la regola del modello utilizzando il seguente comando: 

kubectl apply -f template-rule.yaml

Crea un modello Apigee per utilizzare la regola del modello

Crea un modello Apigee per includere la regola del modello creata nella sezione precedente:

  1. Crea un nuovo file yaml denominato new-admin-template.yaml nello spazio dei nomi apim.
  2. Copia i contenuti del seguente file nel nuovo file che hai creato: 
    # 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
  3. Applica il nuovo modello utilizzando il seguente comando: 
    kubectl apply -f new-admin-template.yaml

Esegui il deployment del criterio del gateway Apigee

In questo passaggio, applicherai a Gateway un nuovo file che include le specifiche per un ApigeeGatewayPolicy. Questo criterio viene utilizzato per eseguire il deployment del modello Apigee sul gateway.

Esegui il deployment del criterio del gateway Apigee:

  1. Crea un nuovo file yaml denominato apigee-gateway-policy-withSA.yaml nello spazio dei nomi apim.
  2. Copia i contenuti del seguente file nel nuovo file che hai creato: 
    # 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: global-ext-lb1-apim-policy
    namespace: apim
  3. Applica la norma: 
    kubectl apply -f apigee-gateway-policy-withSA.yaml
  4. Verifica lo stato del deployment della nuova norma del gateway: 
    kubectl -n apim get ApigeeGatewayPolicy

    Una volta implementato, il criterio STATUS dovrebbe mostrare CREATED.

Dopo il deployment del nuovo criterio del gateway, attendi due minuti prima di inviare una richiesta al gateway per consentire la propagazione del criterio al cluster.

Convalida l'applicazione dei criteri

Per verificare che le norme del gateway Apigee funzionino come previsto, invia richieste al gateway come descritto nelle sezioni seguenti.

Applicazione del criterio AssignMessage

Per verificare che il token {company_name} venga inserito nella richiesta utilizzando il criterio AssignMessage, invia una richiesta al gateway utilizzando il seguente comando: 

curl http://GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME" -H "x-api-key: API_KEY"

Dove:

  • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando: 
    kubectl get gateway GATEWAY_NAME
  • HOST_NAME è il nome dell'host.
  • API_KEY è il valore della chiave API.

Una risposta corretta deve includere un'intestazione Authorization con il token di autenticazione generato, simile alla seguente: 

{
  "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"
}

Applicazione del criterio SpikeArrest

Puoi testare l'applicazione della norma Spike Arrest inviando una richiesta al gateway dieci volte nell'arco di un minuto.

Puoi eseguire lo script seguente per generare le richieste: 

#!/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

Dove:

  • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando, dove GATEWAY_NAME è il nome del gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME è il nome host definito in HTTPRoute del gateway.
  • API_KEY è il valore della chiave API ottenuto in Configurazione del test.

La risposta sarà simile alla seguente: 

"fault":{"faultstring":"Spike arrest violation. Allowed rate : MessageRate{capacity=5, period=Minutes}","detail":{"errorcode":"policies.ratelimit.SpikeArrestViolation"}}}

Applicazione delle norme JavaScript

Per verificare che la policy JavaScript funzioni come previsto, invia una richiesta al gateway utilizzando il seguente comando: 

curl http://GATEWAY_IP_ADDRESS/get \
  -H "Host: HOST_NAME" \
  -H "x-api-key: API_KEY" \
  -H "X-Request-Type: external" -i

Dove:

  • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando, dove GATEWAY_NAME è il nome del gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME è il nome host definito in HTTPRoute del gateway.
  • API_KEY è il valore della chiave API ottenuto in Configurazione del test.

La policy JavaScript imposta tre intestazioni delle richieste: First, Second e Sum, come mostrato nella risposta: 

HTTP/1.1 200 OK
...
{
  "args": {},
  "headers": {
    ...
    "First": "1.0",
    ...
    "Second": "1.0",
    "Sum": "2",
    ...
  },
  ...
}

Applicazione delle norme OASValidation

Per verificare che la policy OASValidation funzioni come previsto, invia una richiesta al gateway utilizzando il seguente comando: 

curl "http://GATEWAY_IP_ADDRESS/get"  \
  -H "Host: HOST_NAME" \
  -H "x-api-key: API_KEY" \
  -H "X-Request-Type: badvalue"

Dove:

  • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando, dove GATEWAY_NAME è il nome del gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME è il nome host definito in HTTPRoute del gateway.
  • API_KEY è il valore della chiave API ottenuto in Configurazione del test.

Il comando include un valore non valido per l'intestazione X-Request-Type. La richiesta non andrà a buon fine e verrà restituita una risposta simile alla seguente: 

{"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"}}}

L'invio della stessa richiesta con un valore valido per l'intestazione X-Request-Type andrà a buon fine. Ad esempio: 

curl "http://GATEWAY_IP_ADDRESS/get"  \
  -H "Host: HOST_NAME" \
  -H "x-api-key: API_KEY" \
  -H "X-Request-Type: external" -i

Dove:

  • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando, dove GATEWAY_NAME è il nome del gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME è il nome host definito in HTTPRoute del gateway.
  • API_KEY è il valore della chiave API ottenuto in Configurazione del test.

Applicazione del criterio ServiceCallout

Puoi verificare l'applicazione delle norme ServiceCallout aprendo una sessione di debug e inviando alcune richieste valide al proxy.

Per aprire una sessione di debug:

  1. Nella console Google Cloud , vai alla pagina Proxy API.

    Vai a Proxy API

  2. Seleziona il proxy global-ext-lb1-apim-policy di cui hai eseguito il deployment nell'ambiente creato per l'operatore Apigee APIM per Kubernetes.
  3. Fai clic sulla scheda Debug.
  4. Nella finestra Sessione di debug, fai clic su Avvia sessione di debug.
  5. Nel riquadro Sessione di debug, seleziona quanto segue:
    • Ambiente: seleziona l'ambiente che hai creato per l'operatore APIM dall'elenco degli ambienti disponibili.
    • Filtro: seleziona Nessuno (tutte le transazioni).
  6. Fai clic su Avvia.

Una volta avviata la sessione, puoi inviare richieste valide al proxy: 

curl "GATEWAY_IP_ADDRESSget"  \
  -H "Host: HOST_NAME" \
  -H "x-api-key: API_KEY" \
  -H "X-Request-Type: external" -i

Dove:

  • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando, dove GATEWAY_NAME è il nome del gateway: 
    kubectl get gateway GATEWAY_NAME
  • HOST_NAME è il nome host definito in HTTPRoute del gateway.
  • API_KEY è il valore della chiave API ottenuto in Configurazione del test.

Le transazioni di richiesta e risposta vengono visualizzate nel riquadro Transazioni. Seleziona una transazione riuscita dall'elenco per visualizzare il flusso. Dovresti essere in grado di vedere che le norme ServiceCallout sono state eseguite correttamente.

Applicazione dei criteri KVM

Quando il criterio KVM viene eseguito correttamente, inizializza KVM con un valore iniziale per la chiave mykey. Quando è presente una transazione di risposta, la norma KVM recupera il valore di mykey e lo memorizza nell'intestazione della risposta mykvm. Quando il criterio KVM viene eseguito di nuovo, inserisce il nuovo valore per mykey ottenuto dall'intestazione della richiesta mykvm.

Puoi controllare le intestazioni di ogni transazione per verificare che il criterio memorizzi un valore nel KVM in una transazione e recuperi lo stesso valore nella transazione successiva, come mostrato nell'esempio seguente.

Testa il criterio KVM:

  1. Invia una richiesta al gateway: 
    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

    Dove:

    • GATEWAY_IP_ADDRESS è l'indirizzo IP del gateway. Puoi recuperare l'indirizzo IP del gateway utilizzando il seguente comando, dove GATEWAY_NAME è il nome del gateway: 
      kubectl get gateway GATEWAY_NAME
    • HOST_NAME è il nome host definito in HTTPRoute del gateway.
    • API_KEY è il valore della chiave API ottenuto in Configurazione del test.
    • KVM_NAME è il nome del KVM.

  2. Controlla le intestazioni della risposta per verificare che la policy KVM sia stata eseguita correttamente e che sia stato memorizzato un valore iniziale per mykvm. La risposta dovrebbe essere simile alla seguente: 
    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"
  }
}
  3. Invia un'altra richiesta al gateway: 
    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 risposta dovrebbe essere simile alla seguente: 

    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"
  }
}

    Puoi vedere che il criterio KVM è stato eseguito correttamente perché il valore dell'intestazione mykvm è stato aggiornato al valore dell'intestazione della richiesta mykvm.

  4. Invia un'altra richiesta: 
    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 risposta dovrebbe essere simile alla seguente: 

    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"
  }
}

    Il valore dell'intestazione mykvm viene aggiornato di nuovo, mostrando che il valore visualizzato nella risposta è quello memorizzato nella transazione precedente.

Risoluzione dei problemi

Se riscontri problemi durante l'aggiunta di policy al gateway GKE, consulta la sezione Risoluzione dei problemi dell'operatore APIM per trovare soluzioni agli errori comuni.

Passaggi successivi