Usar políticas de gerenciamento de API com o operador Apigee APIM para Kubernetes

Esta página se aplica à Apigee, mas não à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como modificar o gateway do Google Kubernetes Engine (GKE) em execução no cluster para aplicar políticas de gerenciamento de API do Apigee usando o operador APIM do Apigee para Kubernetes.

Antes de começar

Antes de começar esta tarefa, conclua as seguintes etapas:

Funções exigidas

Se você atribuiu os papéis necessários à sua conta de serviço conforme descrito em Instalar o operador de APIM do Apigee para Kubernetes, não são necessários outros papéis ou permissões do IAM para concluir essas tarefas.

É possível autorizar ações em recursos no cluster do Google Kubernetes Engine usando o mecanismo integrado de controle de acesso baseado em papéis (RBAC, na sigla em inglês) no Kubernetes. Para mais informações, consulte Autorizar ações em clusters usando o controle de acesso baseado em papéis.

Visão geral

As seções a seguir descrevem as etapas necessárias para modificar o GKE Gateway e usar políticas da Apigee com o operador do APIM. Neste tutorial, você vai:

  1. Defina a política de extensão do APIM.
  2. Defina o produto da API.
  3. Defina o conjunto de operações da API.
  4. Teste a extensão de serviço da Apigee.
  5. Confira a análise de APIs da Apigee no console Google Cloud .

Definir a política de extensão do APIM

Nesta etapa, você vai definir a política de extensão da API Management e aplicá-la ao gateway do GKE em execução no cluster. Essa política rege todo o tráfego que passa pelo gateway e pelo HTTPRoutes associado, funcionando de maneira semelhante a um flowhook no nível do ambiente no Apigee hoje.

Defina a política de extensão do APIM:

  1. Crie um novo arquivo chamado global-ext-lb1-apim-policy.yaml no namespace apim.
  2. Copie o conteúdo a seguir no novo arquivo: 
    # global-ext-lb1-apim-policy.yaml
apiVersion: apim.googleapis.com/v1
kind: APIMExtensionPolicy
metadata:
  name: global-ext-lb1-apim-policy
  namespace: apim
spec:
  apigeeenv: ENV_NAME # optional
  location: global
  failOpen: false
  timeout: 1000ms
  defaultSecurityEnabled: true
  targetRef: # identifies the Gateway where the extension should be applied
    name: global-ext-lb1
    kind: Gateway
    namespace: default

    Em que ENV_NAME é o nome do ambiente da Apigee criado na etapa de instalação Criar um ambiente da Apigee.

    É possível conferir todos os ambientes disponíveis na página Ambientes do Apigee no console Google Cloud :

    Acessar "Ambientes"

  3. Aplique a política: 
    kubectl -n apim apply -f global-ext-lb1-apim-policy.yaml

    Depois que o yaml é aplicado, o operador da API Management cria recursos de rede em segundo plano.

  4. Verifique o status da política de extensão de API usando o seguinte comando: 
    kubectl -n apim get APIMExtensionPolicy

    A saída será parecida com esta, com um State de RUNNING: 

    NAME                         STATE      ERRORMESSAGE
global-ext-lb1-apim-policy   RUNNING
  5. Use o comando a seguir para enviar uma solicitação ao gateway: 
    curl http://GATEWAY_IP_ADDRESS/get -H "Host: HOST_NAME"

    Em que:

    • GATEWAY_IP_ADDRESS é o endereço IP do gateway. É possível recuperar o endereço IP do gateway usando o seguinte comando, em que GATEWAY_NAME é o nome do gateway: 
      kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
    • HOST_NAME é o nome do host definido no HTTPRoute do gateway.
  6. A solicitação vai falhar porque a segurança padrão é ativada definindo defaultSecurityEnabled: true no recurso de política de extensão da API. Uma resposta semelhante a esta vai aparecer: 
    {"fault":{"faultstring":"Raising fault. Fault name : RF-insufficient-request-raise-fault","detail":{"errorcode":"steps.raisefault.RaiseFault"}}}

    Isso indica que a política de extensão da Apigee está ativa e que a aplicação de chaves de API e a verificação de token de acesso estão ativas.

Definir o produto de API

Defina o produto de API:

  1. Crie um novo arquivo chamado api-product.yaml no namespace apim.
  2. Copie o conteúdo a seguir no novo arquivo: 
    # api-product.yaml
  apiVersion: apim.googleapis.com/v1
  kind: APIProduct
  metadata:
    name: api-product
    namespace: apim
  spec:
    approvalType: auto
    description: Http bin GET calls
    displayName: api-product
    enforcementRefs:
      - name: global-ext-lb1-apim-policy
        kind: APIMExtensionPolicy
        group: apim.googleapis.com
        namespace: apim
    attributes:
      - name: access
        value: private
  3. Aplique o arquivo ao gateway usando o seguinte comando: 
    kubectl -n apim apply -f api-product.yaml

Definir o conjunto de operações da API

Defina o conjunto de operações de API para o produto de API criado na etapa anterior:

  1. Crie um novo arquivo chamado apim-policies.yaml no namespace apim.
  2. Copie o conteúdo a seguir no novo arquivo. Esse arquivo define uma política de cotas e as operações REST disponíveis para o produto da API definido na etapa anterior: 
    # apim-policies.yaml
  apiVersion: apim.googleapis.com/v1
  kind: APIOperationSet
  metadata:
    name: item-set
    namespace: apim
  spec:
    apiProductRefs:
      - name: api-product
        kind: APIProduct
        group: apim.googleapis.com
        namespace: apim
    quota:
      limit: 10
      interval: 1
      timeUnit: minute
    restOperations:
      - name: GetItems
        path: /get
        methods:
          - GET
  3. Aplique o arquivo ao gateway: 
    kubectl -n apim apply -f apim-policies.yaml

Testar a extensão de serviço da Apigee

Nesta etapa, você vai usar a interface da Apigee no console Google Cloud para testar a extensão de serviço da Apigee e a política de extensão da Apigee aplicada ao seu gateway.

Configuração de teste

Configure os recursos de API necessários para o teste:

  1. Acesse a página Gerenciamento de APIs do Apigee no console do Google Cloud :

    Gerenciamento de APIs da Apigee

  2. Selecione a organização da Apigee em que você instalou o operador da APIM.
  3. Crie um desenvolvedor:
    1. Selecione Distribuição > Desenvolvedores.
    2. Na página Desenvolvedores, clique em + Criar.
    3. Na página Adicionar desenvolvedor, preencha os campos obrigatórios com os valores que quiser.
    4. Clique em Adicionar.
  4. Crie um app:
    1. Selecione Distribuição> Apps.
    2. Na página Apps, clique em + Criar.
    3. Na página Criar app, preencha os campos obrigatórios na seção Detalhes do app usando os seguintes valores:
      • Nome do app: demo-app
      • Desenvolvedor: selecione o desenvolvedor que você criou na etapa anterior ou outro desenvolvedor na lista.
    4. Na seção Credenciais do app, clique em + Adicionar credencial.
    5. Na seção Credencial, preencha os campos obrigatórios em Detalhes da credencial com os seguintes valores:
      • Nome da credencial: demo-credential
      • Tipo de credencial: selecione Chave de API.
    6. Clique em Criar.
    7. Na seção Produtos, clique em + Adicionar produtos.
    8. Selecione o api-product-1 criado na etapa anterior.
    9. Clique em Adicionar.
    10. Clique em Criar.
  5. Na página Detalhes do app, na seção Credencial, clique em para mostrar o valor da Chave.

    Copie o valor de Key. Você vai usar essa chave para fazer chamadas de API ao seu serviço em uma etapa posterior.

  6. Na página Detalhes do app, na seção Credencial, clique em para mostrar o valor do Secret do app.

    Copie o valor de Chave secreta do app. Você vai usar esse valor para gerar um token de acesso em uma etapa posterior.

Testar a aplicação da chave de API

Use o comando a seguir para enviar uma solicitação ao gateway usando a chave de API obtida em uma etapa anterior: 

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

Em que:

  • GATEWAY_IP_ADDRESS é o endereço IP do gateway. É possível recuperar o endereço IP do gateway usando o seguinte comando, em que GATEWAY_NAME é o nome do gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME é o nome do host definido no HTTPRoute do gateway.
  • API_KEY é o valor da chave de API obtido em Configuração de teste.

A solicitação precisa ser bem-sucedida e retornar uma resposta semelhante a esta: 

{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Host": "apigee-apim-operator-test.apigee.net",
    "User-Agent": "curl/8.7.1",
    "X-Api-Key": "f0N6sYYYclGYYYe0oP5YYYdA20PjgrP2x8YYYh7z4YYYKiYt",
    "X-Cloud-Trace-Context": "bb3a768787099bda628781188bfb318b/15554891713516675739"
  },
  "origin": "34.54.193.72",
  "url": "https://34.54.193.72/get"
}

Testar a aplicação de cota

Para testar a aplicação de cota definida na política de extensão do APIM, envie a solicitação da etapa anterior para o gateway dez vezes em um minuto.

Você pode executar o script a seguir para gerar as solicitações: 

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

Em que:

  • GATEWAY_IP_ADDRESS é o endereço IP do gateway. É possível recuperar o endereço IP do gateway usando o seguinte comando, em que GATEWAY_NAME é o nome do gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME é o nome do host definido no HTTPRoute do gateway.
  • API_KEY é o valor da chave de API obtido em Configuração de teste.

Essa ação vai acionar uma violação de cota e gerar uma falha semelhante a esta: 

{"fault":{"faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default","detail":{"errorcode":"policies.ratelimit.QuotaViolation"}}}

Testar a aplicação de operações REST

Para testar a aplicação das operações de REST, use o comando a seguir para enviar uma solicitação ao gateway usando um URL que não está no conjunto de operações da API: 

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

Em que:

  • GATEWAY_IP_ADDRESS é o endereço IP do gateway. É possível recuperar o endereço IP do gateway usando o seguinte comando, em que GATEWAY_NAME é o nome do gateway: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses[0].value}"
  • HOST_NAME é o nome do host definido no HTTPRoute do gateway.
  • API_KEY é o valor da chave de API obtido em Configuração de teste.

A solicitação vai falhar com uma resposta semelhante a esta: 

{"fault":{"faultstring":"Invalid ApiKey for given resource","detail":{"errorcode":"oauth.v2.InvalidApiKeyForGivenResource"}}}

Ver a análise de APIs da Apigee no Google Cloud console

É possível conferir o tráfego da API processado pelo gateway do GKE e a APIMExtensionPolicy instalada usando a análise da API Apigee no console Google Cloud :

  1. Acesse a página Gerenciamento de APIs do Apigee no console Google Cloud :

    Gerenciamento de APIs da Apigee

  2. Selecione a organização da Apigee em que você instalou o operador da APIM.
  3. Selecione Analytics > Métricas da API no menu de navegação lateral.
  4. Na guia Performance do proxy de API, escolha o ambiente criado na etapa de instalação opcional Criar um ambiente da Apigee ou o ambiente criado pelo operador do APIM durante a instalação. O nome do ambiente vai começar com o prefixo apigee-ext-proc-enabled-env.
  5. Observe o tráfego da API registrado.

Resolver problemas

Se você tiver problemas ao usar políticas de gerenciamento de API com o operador APIM, consulte Solução de problemas do operador APIM para encontrar soluções para erros comuns.

A seguir