Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
Esta página descreve como adicionar políticas de runtime do Apigee e uma Google política de injeção de tokens ao gateway do Google Kubernetes Engine (GKE) com o operador do Apigee para Kubernetes. A adição de um conjunto de políticas disponíveis ao Gateway permite-lhe expandir a funcionalidade do Gateway para além da aplicação do produto API, de modo a incluir regras empresariais e de segurança adicionais.
O Apigee Operator para Kubernetes pode ser usado para adicionar as seguintes políticas ao gateway:
- Política SpikeArrest
- Política de JavaScript
- Google política de injeção de tokens
- Política GenerateJWT
- Política de KVM
- Política de validação da OAS
- Política de textos destacados de serviços
- Política de OAuthv2
- Política ResponseCache
- Política VerifyAPIKey
Vista geral
As secções seguintes descrevem como:
- Adicione políticas ao GKE Gateway.
- Crie uma regra de modelo para aplicar a utilização das políticas.
- Crie um modelo do Apigee para usar a regra de modelo.
- Implemente a política do Apigee Gateway com o modelo.
- Valide a aplicação de políticas.
Antes de começar
Para modificar o GKE Gateway com o conjunto completo de políticas usado como exemplo neste guia, tem de ter uma conta de serviço com as funções necessárias para criar tokens no Apigee e implementar proxies e extensões. Se optar por não criar tokens, não tem de adicionar as funções adicionais à sua conta de serviço e pode avançar para a secção seguinte. Google
Para criar uma conta de serviço com as autorizações necessárias:
- Se criou uma conta de serviço com o nome
apigee-apim-gsa
no guia de instalação do Apigee Operator para Kubernetes, pode ignorar este passo e avançar para o passo seguinte. Caso contrário, crie a conta de serviço:gcloud iam service-accounts create apigee-apim-gsa --project=$PROJECT_ID
- Conceda à conta de serviço a função necessária para criar tokens:
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/iam.serviceAccountTokenCreator"
- Conceda à conta de serviço
apigee-apim-gsa
a função necessária para implementar proxies e extensões:gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/iam.serviceAccountUser"
Modifique o GKE Gateway com políticas
Pode optar por modificar o GKE Gateway com uma ou mais políticas para estender a respetiva funcionalidade. Este exemplo
passo a passo aplica um ficheiro yaml
ao gateway que inclui as
especificações para duas políticas do Apigee e uma política de injeção de tokens Google .
Cada uma das políticas aplicadas ao gateway através do ficheiro yaml
seguinte desempenha uma função diferente quando
avalia os pedidos enviados para o gateway:
- A política SpikeArrest controla a taxa de mensagens de pico definindo uma taxa máxima de pedidos permitidos durante uma unidade de tempo. Neste exemplo, a taxa máxima está definida como cinco por minuto. Para saber mais sobre como a política SpikeArrest é usada para suavizar picos súbitos no tráfego, consulte o artigo Política SpikeArrest.
- A política de JavaScript permite-lhe adicionar código JavaScript personalizado aos pedidos de gateway. Neste exemplo, a política é usada para adicionar um cabeçalho personalizado ao pedido. Para mais informações sobre como a política de JavaScript é usada para adicionar código personalizado, consulte o artigo Política de JavaScript.
- A política de injeção de tokens Google é usada para injetar um token de acesso de autenticação Google nos pedidos de gateway, através da política AssignMessage. O Apigee suporta a utilização de Google tokens OAuth ou tokens OpenID Connect para autenticar com Google serviços. Para saber mais sobre os tokens de autenticação, consulte o artigo Usar a autenticação Google.
Adicione as políticas ao gateway:
- Crie um novo ficheiro com o nome
apigee-policies.yaml
no espaço de nomesapim
. - Copie o conteúdo do seguinte ficheiro para o novo ficheiro que criou:
# 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"
- Aplique o ficheiro
yaml
ao gateway através do seguinte comando:kubectl -n apim apply -f apigee-policies.yaml
Crie uma TemplateRule como modelo de SharedFlow
Neste passo, vai criar um TemplateRule
para aplicar as políticas que adicionou ao Gateway.
Uma regra de modelo é uma regra para SharedFlows criada por administradores da organização para garantir que apenas as políticas aprovadas são aplicadas ao tráfego do gateway pelos programadores de serviços. Uma regra de modelo garante que os programadores compreendem que políticas estão disponíveis para eles, que políticas são necessárias para exemplos de utilização específicos e que políticas não podem ser usadas pelos programadores de serviços.
Crie uma regra de modelo
Crie uma regra de modelo para aplicar a utilização da política AssignMessage:
- Crie um novo ficheiro
yaml
com o nometemplate-rule.yaml
no espaço de nomesapim
. - Copie o conteúdo do seguinte ficheiro para o novo ficheiro que criou:
# 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: []
Neste exemplo, a regra do modelo indica aos programadores que a política AssignMessage que descreve a Google política de injeção de tokens é obrigatória. Também indica aos programadores que podem usar as políticas SpikeArrest, JavaScript, GenerateJWT, KVM, OASValidation, OAuthv2 e ServiceCallout na gestão de APIs. Não existem políticas especificadas na lista de rejeição.
Aplique a regra do modelo
Aplique a regra do modelo com o seguinte comando:
kubectl apply -f template-rule.yaml
Crie um modelo do Apigee para usar a regra de modelo
Crie um modelo do Apigee para incluir a regra de modelo que criou na secção anterior:
- Crie um novo ficheiro
yaml
com o nomenew-admin-template.yaml
no espaço de nomesapim
. - Copie o conteúdo do seguinte ficheiro para o novo ficheiro que criou:
# 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
- Aplique o novo modelo com o seguinte comando:
kubectl apply -f new-admin-template.yaml
Implemente a política do Apigee Gateway
Neste passo, vai aplicar um novo ficheiro ao seu Gateway que inclui as especificações de um ApigeeGatewayPolicy
.
Esta política é usada para implementar o modelo do Apigee no gateway.
Implemente a política do Apigee Gateway:
- Crie um novo ficheiro
yaml
com o nomeapigee-gateway-policy-withSA.yaml
no espaço de nomesapim
. - Copie o conteúdo do seguinte ficheiro para o novo ficheiro que criou:
# 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
Substitua PROJECT_ID pelo ID do seu Google Cloud projeto.
Substitua APIMEXTENSION_POLICY_NAME pelo nome da APIMExtensionPolicy que quer usar para aplicar a política do Apigee Gateway. Se criou uma APIMExtensionPolicy para criar uma extensão de tráfego, use o nome da política que criou. Se usou um ApigeeBackendService para criar uma extensão de tráfego, use o nome do ApigeeBackendService. Quando cria um ApigeeBackendService, o operador Apigee para Kubernetes cria uma APIMExtensionPolicy com o mesmo nome e espaço de nomes que o BackendService.
- Aplique a política:
kubectl apply -f apigee-gateway-policy-withSA.yaml
- Valide o estado de implementação da nova política de gateway:
kubectl -n apim get ApigeeGatewayPolicy
Após a implementação, a política
STATUS
deve apresentarCREATED
.
Após a implementação da nova política de gateway, aguarde dois minutos antes de enviar um pedido ao gateway para permitir que a política se propague ao cluster.
Valide a aplicação de políticas
Para confirmar que as políticas do Apigee Gateway estão a funcionar como esperado, envie pedidos para o Gateway, conforme descrito nas secções seguintes.
Aplicação da política AssignMessage
Para confirmar que o token {company_name} é injetado no pedido através da política AssignMessage, envie um pedido para o gateway através do seguinte comando:
curl http://GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME" -H "x-api-key: API_KEY"
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando:kubectl get gateway GATEWAY_NAME
HOST_NAME
é o nome do anfitrião.API_KEY
é o valor da chave da API.
Uma resposta bem-sucedida deve incluir um cabeçalho Authorization
com o token de autorização gerado,
semelhante ao seguinte:
{ "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" }
Aplicação da política SpikeArrest
Pode testar a aplicação da política SpikeArrest enviando um pedido ao gateway dez vezes no espaço de um minuto.
Pode executar o seguinte script para gerar os pedidos:
#!/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
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando, em queGATEWAY_NAME
é o nome do gateway:kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
é o nome de anfitrião definido noHTTPRoute
do gateway.API_KEY
é o valor da chave da API obtido em Testar configuração.
A resposta vai ter um aspeto semelhante ao seguinte:
"fault":{"faultstring":"Spike arrest violation. Allowed rate : MessageRate{capacity=5, period=Minutes}","detail":{"errorcode":"policies.ratelimit.SpikeArrestViolation"}}}
Aplicação da política de JavaScript
Para confirmar que a política de JavaScript está a funcionar como esperado, envie um pedido ao gateway através do seguinte comando:
curl http://GATEWAY_IP_ADDRESS/get \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -i
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando, em queGATEWAY_NAME
é o nome do gateway:kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
é o nome de anfitrião definido noHTTPRoute
do gateway.API_KEY
é o valor da chave da API obtido em Testar configuração.
A política de JavaScript define três cabeçalhos de pedidos: First
, Second
e Sum
, como se pode ver
na resposta:
HTTP/1.1 200 OK ... { "args": {}, "headers": { ... "First": "1.0", ... "Second": "1.0", "Sum": "2", ... }, ... }
Aplicação da política OASValidation
Para confirmar que a política OASValidation está a funcionar como esperado, envie um pedido ao gateway através do seguinte comando:
curl "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: badvalue"
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando, em queGATEWAY_NAME
é o nome do gateway:kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
é o nome de anfitrião definido noHTTPRoute
do gateway.API_KEY
é o valor da chave da API obtido em Testar configuração.
O comando inclui um valor inválido para o cabeçalho X-Request-Type
. O pedido falha
com uma resposta semelhante à seguinte:
{"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"}}}
O envio do mesmo pedido com um valor válido para o cabeçalho X-Request-Type
tem êxito. Por exemplo:
curl "http://GATEWAY_IP_ADDRESS/get" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -i
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando, em queGATEWAY_NAME
é o nome do gateway:kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
HOST_NAME
é o nome de anfitrião definido noHTTPRoute
do gateway.API_KEY
é o valor da chave da API obtido em Testar configuração.
Aplicação da política ServiceCallout
Pode validar a aplicação da política ServiceCallout abrindo uma sessão de depuração e enviando alguns pedidos válidos para o proxy.
Para abrir uma sessão de depuração, siga estes passos:
- Na Google Cloud consola, aceda à página Proxies de API.
- Selecione o
global-ext-lb1-apim-policy
proxy que implementou no ambiente criado para o Apigee Operator for Kubernetes. - Clique no separador Depurar.
- Na janela Sessão de depuração, clique em Iniciar sessão de depuração.
- No painel Sessão de depuração, faça as seguintes seleções:
- Ambiente: selecione o ambiente que criou para o Apigee Operator for Kubernetes na lista de ambientes disponíveis.
- Filtro: selecione Nenhum (todas as transações).
- Clique em Iniciar.
Assim que a sessão for iniciada, pode enviar pedidos válidos para o proxy:
curl "GATEWAY_IP_ADDRESSget" \ -H "Host: HOST_NAME" \ -H "x-api-key: API_KEY" \ -H "X-Request-Type: external" -i
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando, em queGATEWAY_NAME
é o nome do gateway:kubectl get gateway GATEWAY_NAME
HOST_NAME
é o nome de anfitrião definido noHTTPRoute
do gateway.API_KEY
é o valor da chave da API obtido em Testar configuração.
As transações de pedidos e respostas são apresentadas no painel Transações. Selecione uma transação bem-sucedida na lista para apresentar o fluxo. Deverá conseguir ver que a política ServiceCallout
foi executada com êxito.
Aplicação da política de KVM
Quando a política de KVM é executada com êxito, inicializa a KVM com um valor inicial para a chave mykey
.
Quando existe uma transação de resposta, a política KVM obtém o valor de mykey
e armazena-o no cabeçalho de resposta mykvm
.
Quando a política KVM é executada novamente, insere o novo valor para mykey
obtido a partir do cabeçalho do pedido mykvm
.
Pode verificar os cabeçalhos de cada transação para confirmar que a política está a armazenar um valor no KVM numa transação e a obter o mesmo valor na transação seguinte, conforme mostrado no exemplo seguinte.
Teste a política de KVM:
- Envie um pedido ao 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
Onde:
GATEWAY_IP_ADDRESS
é o endereço IP do gateway. Pode obter o endereço IP do gateway através do seguinte comando, em queGATEWAY_NAME
é o nome do gateway:kubectl get gateway GATEWAY_NAME
HOST_NAME
é o nome de anfitrião definido noHTTPRoute
do gateway.API_KEY
é o valor da chave da API obtido em Testar configuração.KVM_NAME
é o nome do KVM.
- Verifique os cabeçalhos de resposta para confirmar que a política de KVM foi executada com êxito e que foi armazenado um valor inicial
para
mykvm
. A resposta deve ser semelhante à seguinte: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" } }
- Envie outro pedido ao 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
A resposta deve ser semelhante à seguinte:
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" } }
Pode ver que a política de KVM foi executada com êxito porque o valor do cabeçalho
mykvm
é atualizado para o valor do cabeçalho do pedidomykvm
. - Enviar mais um pedido:
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
A resposta deve ser semelhante à seguinte:
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" } }
O valor do cabeçalho
mykvm
é atualizado novamente, mostrando que o valor apresentado na resposta é o valor armazenado na transação anterior.
Resolver problemas
Se tiver problemas ao adicionar políticas ao GKE Gateway, consulte o artigo Resolva problemas do operador Apigee para Kubernetes para encontrar soluções para erros comuns.
O que se segue?
- Saiba mais acerca da política de SpikeArrest.
- Saiba mais acerca da política de JavaScript.