Guia de operações

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Como obter uma chave da API

O exemplo seguinte explica como obter uma chave da API que pode usar para validar chamadas da API para um serviço de destino encaminhado através do Apigee Adapter for Envoy.

1. Inicie sessão no Apigee

  1. Abra a IU do Apigee num navegador.
  2. Depois de aceder à IU, selecione a mesma organização que usou para configurar o Apigee Adapter for Envoy.

2. Crie um programador

Pode usar um programador existente para testes ou criar um novo da seguinte forma:

  1. Selecione Publicar > Programadores no menu de navegação lateral.
  2. Clique em + Programador.
  3. Preencha a caixa de diálogo para criar um novo programador. Pode usar qualquer nome/email de programador que quiser.

3. Crie um produto de API

Siga o exemplo de criação de produtos fornecido abaixo. Consulte também Acerca da configuração do produto da API.

  1. Selecione Publicar > Produtos de API no menu de navegação lateral.
  2. Clique em +Criar.
  3. Preencha a página de detalhes do produto da seguinte forma. Não clique em Guardar até receber essa instrução.
    Campo Valor
    Nome httpbin-product
    Nome a apresentar httpbin product
    Ambiente your_environment

    Defina esta opção para o ambiente que usou quando aprovisionou o Apigee Adapter for Envoy com o apigee-remote-service-cli.

    Acesso Private
    Quota 5 pedidos a cada 1 minuto

    Consulte também o artigo Acerca dos produtos de API.

  4. Na secção Atributos personalizados, clique em +ADICIONAR ATRIBUTO PERSONALIZADO.
  5. Introduza este par nome/valor:
    • Nome: introduza este nome de atributo: apigee-remote-service-targets
    • Valor: introduza o nome do serviço de destino. Por exemplo: httpbin.org
  6. Clique em OK.
  7. Clique em Guardar.

4. Crie uma app de programador

  1. Selecione Publicar > Apps no menu de navegação lateral.
  2. Clique em + App.
  3. Preencha a página da app do programador da seguinte forma. Não clique em Guardar até receber essa instrução.
    4. Nome httpbin-app
    Nome a apresentar httpbin app
    Programador Selecione o programador que criou anteriormente ou escolha qualquer programador que pretender na lista.
  4. Na secção Credenciais, clique em + Adicionar produto e selecione o produto que acabou de configurar: httpbin-product.
  5. Clique em Criar.
  6. Em Credenciais, clique em Mostrar junto à Chave.
  7. Copie o valor da chave do consumidor. Este valor é a chave da API que vai usar para fazer chamadas API para o serviço httpbin.

Acerca dos produtos de API

Os produtos de API são o ponto de controlo principal do serviço remoto do Apigee. Quando cria um produto API e o associa a um serviço de destino, está a criar uma política que será aplicada a todos os pedidos que configurar o seu adaptador do Apigee para o Envoy para processar.

Definição do API Product

Quando define um produto de API no Apigee, pode definir vários parâmetros que serão usados para avaliar pedidos:

  • Destino
  • Caminho do pedido
  • Quota
  • âmbitos do OAuth

Destinos de serviços remotos

A definição do produto API aplica-se a um pedido se o pedido corresponder à associação de destino (por exemplo, httpbin.org) e ao caminho do pedido (por exemplo, /httpbin). Uma lista de potenciais destinos é armazenada como um atributo no produto API.

Por predefinição, o serviço remoto do Apigee verifica o cabeçalho especial :authority (host) do Envoy em relação à respetiva lista de destinos. No entanto, pode ser configurado para usar outros cabeçalhos.

Caminho do recurso da API

O caminho introduzido corresponde de acordo com as seguintes regras:

  • Uma única barra (/) corresponde a qualquer caminho.
  • * é válido em qualquer lugar e corresponde a um segmento (entre barras).
  • ** é válido no final e corresponde a qualquer coisa até ao final da linha.

Quota

Uma quota especifica o número de mensagens de pedido que uma app pode enviar para uma API ao longo de uma hora, um dia, uma semana ou um mês. Quando uma app atinge o limite da quota, as chamadas de API subsequentes são rejeitadas.

Exemplos de utilização de quotas

As quotas permitem-lhe aplicar o número de pedidos que um cliente pode fazer a um serviço num determinado período. As quotas são frequentemente usadas para aplicar contratos comerciais ou SLAs com programadores e parceiros, em vez de para a gestão operacional do tráfego. Por exemplo, uma quota pode ser usada para limitar o tráfego de um serviço gratuito, ao mesmo tempo que permite o acesso total aos clientes pagantes.

A quota é definida num produto da API

Os parâmetros de quota são configurados nos produtos de API. Por exemplo, quando cria um produto de API, pode definir opcionalmente o limite de quota permitido, a unidade de tempo e o intervalo.

Definir um limite de quota na IU do Apigee.>

Uma vez que as chaves da API são mapeadas novamente para os produtos da API, sempre que uma chave da API é validada, o contador de quota adequado pode ser decrementado (se for definida uma quota no produto associado).

Ao contrário do tempo de execução do Apigee, as quotas introduzidas na definição do produto são aplicadas automaticamente pelo serviço remoto do Apigee. Se o pedido for autorizado, o pedido é contabilizado em relação à quota permitida.

Onde são mantidas as quotas

As quotas são mantidas e verificadas localmente pelo processo de serviço remoto e mantidas de forma assíncrona com o Apigee Runtime. Isto significa que as quotas não são precisas e é provável que haja algum excesso se tiver mais do que um serviço remoto a manter a quota. Se a ligação ao Apigee Runtime for interrompida, a quota local continua como uma quota autónoma até poder voltar a estabelecer ligação ao Apigee Runtime.

Âmbitos do OAuth

Se estiver a usar tokens JWT, pode restringir os tokens a subconjuntos dos âmbitos OAuth permitidos. Os âmbitos atribuídos ao seu token JWT emitido são verificados em relação aos âmbitos do produto API.

Acerca das apps de programadores

Depois de configurar os seus produtos da API, cria uma app associada a um programador. A app permite que um cliente aceda aos produtos de API associados com uma chave de API ou um token JWT.

Usar a autenticação baseada em JWT

Pode usar um token JWT para fazer chamadas de proxy de API autenticadas em vez de usar uma chave da API. Esta secção explica como usar o comando apigee-remote-service-cli token para criar, inspecionar e rodar tokens JWT. Para o ambiente híbrido do Apigee, pode usar este comando para criar um segredo do Kubernetes para armazenar os JWTs.

Vista geral

A validação e a autenticação JWT são processadas pelo Envoy através do respetivo filtro de autenticação JWT.

Após a autenticação, o filtro ext-authz do Envoy envia os cabeçalhos de pedidos e o JWT para apigee-remote-service-envoy. Faz corresponder as reivindicações api_product_list e scope do JWT aos produtos da API Apigee para o autorizar em relação ao destino do pedido.

Criar tokens JWT do Apigee

Os tokens JWT do Apigee podem ser criados através da CLI:

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

Em alternativa, através do ponto final do token OAuth padrão. Exemplo de curl:

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

Usar o token JWT

Assim que tiver o token, basta transmiti-lo ao Envoy no cabeçalho de autorização. Exemplo:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

Falha do token JWT

Rejeição do Envoy

Se o Envoy rejeitar o token, pode ver uma mensagem como:

Jwks remote fetch is failed

Se for o caso, certifique-se de que a configuração do Envoy contém um URI válido na secção remote_jwks, que o Envoy consegue aceder ao mesmo e que definiu corretamente os certificados quando instalou o proxy do Apigee. Deve conseguir chamar o URI diretamente com uma chamada GET e receber uma resposta JSON válida.

Exemplo:

curl https://myorg-eval-test.apigee.net/remote-service/certs

Outras mensagens da Envoy podem ter o seguinte aspeto:

  • "Audiences in Jwt are not allowed" (Os públicos-alvo em JWT não são permitidos)
  • "Jwt issuer is not configured" (O emissor de JWT não está configurado)

Estes são requisitos na sua configuração do Envoy que pode ter de modificar.

Inspecione um token

Pode usar a CLI para inspecionar o seu token. Exemplo

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

ou 

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

Depuração

Consulte o artigo A chave da API válida falha.

Registo

Pode ajustar o nível de registo no serviço $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Todo o registo é enviado para stderr.

Elemento Obrigatória Descrição
-l, --log-level Níveis válidos: debug, info, warn, error. Ajusta o nível de registo. Predefinição: info
-j, --json-log Emite a saída do registo como registos JSON.

O Envoy fornece registo. Para mais informações, consulte os seguintes links da documentação do Envoy:

Alterar o nome do segredo da política

Um segredo do Kubernetes implementado no cluster contém credenciais de que o adaptador precisa para autenticar a comunicação com o proxy do serviço remoto. Este segredo requer um ponto de montagem de volume, que é configurável. Por predefinição, o ponto de montagem é /policy-secret. Para alterar o ponto de montagem, siga estes passos:

  1. Execute este comando: 
    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

    Por exemplo: 

    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point
  2. Abra $CLI_HOME/samples/apigee-envoy-adapter.yaml num editor.
  3. Altere o nome do ponto de montagem para o novo nome: 
    volumeMounts:
  - mountPath: /config
    name: apigee-remote-service-envoy
    readOnly: true
  - mountPath: /opt/apigee/tls
    name: tls-volume
    readOnly: true
  - mountPath: /my-mount-point
    name: policy-secret
    readOnly: true
  4. Guarde o ficheiro e aplique-o à malha de serviços: 
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

Usar um proxy de rede

Pode inserir um proxy HTTP através das variáveis de ambiente HTTP_PROXY e HTTPS_PROXY no ambiente do ficheiro binário apigee-remote-service-envoy. Quando as usa, também pode usar a variável de ambiente NO_PROXY para excluir anfitriões específicos do envio através do proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

Lembre-se de que o proxy tem de estar acessível a partir de apigee-remote-service-envoy.

Acerca das métricas e das estatísticas

Um ponto final de métricas do Prometheus está disponível em :5001/metrics. Pode configurar este número de porta. Consulte o ficheiro de configuração.

Estatísticas do Envoy

Os links seguintes fornecem informações sobre como obter dados de estatísticas do proxy Envoy:

Estatísticas do Istio

Os links seguintes fornecem informações sobre como obter dados de estatísticas do proxy Envoy:

Estatísticas do Apigee

O serviço remoto do Apigee para o Envoy envia estatísticas de pedidos para o Apigee para processamento de estatísticas. O Apigee comunica estes pedidos sob o nome do produto API associado.

Para ver informações sobre as estatísticas do Apigee, consulte o artigo Vista geral dos serviços de estatísticas.