Guia de operações

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Como conseguir uma chave de API

No exemplo a seguir, explicamos como conseguir uma chave de API que pode ser usada para validar chamadas de API a um serviço de destino por meio do adaptador da Apigee para Envoy.

OBSERVAÇÃO: se você for um usuário experiente da Apigee, as etapas a seguir serão conhecidas por serem configurações padrão da Apigee. No entanto, siga estas instruções com atenção, porque elas exigem que você insira configurações específicas do produto e do app do desenvolvedor.

1. Fazer login na Apigee

1. Abra a IU da Apigee em um navegador.
2. Na IU, selecione a mesma organização que você usou para configurar o adaptador da Apigee para Envoy.

2. Criar um desenvolvedor

Use um desenvolvedor atual para teste ou crie um novo da seguinte maneira:

1. Selecione Publicar > Desenvolvedores no menu de navegação lateral.
2. Clique em + Desenvolvedor.
3. Preencha a caixa de diálogo para criar um desenvolvedor. Use qualquer nome/e-mail de desenvolvedor.

3. Criar um produto da API

Siga o exemplo de criação do produto abaixo. Consulte também Sobre a configuração do produto da API.

1. Selecione Publicar > Produtos da API no menu de navegação lateral.
2. Clique em + Produto da API.
3. Preencha a página de detalhes do produto da maneira a seguir. Não clique em Salvar até receber uma instrução para isso.

Campo	Valor
Nome	httpbin-product
Nome de exibição	httpbin product
Ambiente	your_environment Defina-o como o ambiente usado quando você provisionou o adaptador da Apigee para Envoy com apigee-remote-service-cli.
Acesso	Private
Cota	Cinco solicitações a cada um minuto Consulte também Sobre os produtos de API.

4. Na seção Apigee remote service targets, clique em Add an Apigee remote service target.
5. Na caixa de diálogo de destino do serviço remoto da Apigee, adicione os seguintes valores:

   Atributo	Valor	Descrição
   Nome do destino	Digite o nome do serviço de destino. Por exemplo: httpbin.org	O endpoint de destino voltado para o proxy Envoy.
   Proxy de API	remote-service	O proxy remote-service que foi provisionado na Apigee durante a instalação do adaptador Envoy.
   Caminho	Insira um /resource_path para corresponder a um caminho específico. Por exemplo: /httpbin.	O caminho da solicitação para corresponder ao endpoint de destino. As chamadas de proxy de API para esse caminho corresponderão a esse produto da API.

6. Clique em Salvar.

4. Criar um app do desenvolvedor

1. Selecione Publicar > Apps no menu de navegação lateral.
2. Clique em + App.
3. Preencha a página do app do desenvolvedor da maneira a seguir. Não salve até receber uma instrução para fazer isso.

Nome	httpbin-app
Nome de exibição	httpbin app
Desenvolvedor	Selecione o desenvolvedor que você criou ou escolha um na lista.

4. Em seguida, adicione dois produtos ao app:
   1. Primeiro, na seção "Credenciais", clique em + Adicionar produto e selecione o produto que você acabou de configurar: httpbin-product.
   2. Adicione o produto remote-service. Esse produto foi criado automaticamente quando você provisionou a Apigee.
5. Clique em Criar.
6. Em "Credenciais", clique em Mostrar ao lado de Chave.
7. Copie o valor da chave do consumidor. Esse valor é a chave de API que você usará para fazer chamadas de API ao serviço httpbin.

Sobre os produtos de API

Os produtos da API são o principal ponto de controle do serviço remoto da Apigee. Ao criar um produto da API e vinculá-lo a um serviço de destino, você cria uma política que será aplicada a todas as solicitações configuradas para serem processadas pelo adaptador da Apigee para Envoy.

Definição de produto da API

Ao definir um produto da API na Apigee, é possível definir vários parâmetros que serão usados para avaliar as solicitações:

• Destino
• Caminho da solicitação
• Cota
• Escopos do OAuth

Destinos de serviço remoto

A definição do produto da API será aplicada a uma solicitação se ela corresponder à vinculação de destino, por exemplo, httpbin.org, e ao caminho da solicitação, por exemplo, /httpbin. Uma lista de possíveis destinos é armazenada como um atributo no produto da API.

Por padrão, o serviço remoto da Apigee verifica o cabeçalho :authority (host) especial do Envoy na lista de destinos. No entanto, ele pode ser configurado para usar outros cabeçalhos.

Caminho do recurso da API

O caminho inserido é correspondido de acordo com as seguintes regras:

• Apenas uma barra (/) corresponde a qualquer caminho.
• * é válido em qualquer lugar e combina com um segmento (entre barras).
• ** é válido no final e corresponde a tudo até o fim da linha.

Cota

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

Casos de uso de cota

As cotas permitem que você aplique o número de solicitações que um cliente pode fazer para um serviço em um determinado período. As cotas costumam ser usadas para impor contratos de negócios ou SLAs com desenvolvedores e parceiros, e não para gerenciamento de tráfego operacional. Por exemplo, uma cota pode ser usada para limitar o tráfego de um serviço gratuito, enquanto permite o acesso total a clientes pagantes.

A cota é definida em um produto da API

Os parâmetros de cota são configurados nos produtos da API. Por exemplo, ao criar um produto de API, você tem a opção de definir o limite de cota, a unidade de tempo e o intervalo permitidos.

Como as chaves de API mapeiam de volta para os produtos da API, cada vez que uma chave de API é verificada, o contador de cota apropriado pode ser reduzido, se uma cota for definida no produto associado.

Ao contrário do ambiente de execução da Apigee, as cotas inseridas na definição do produto são aplicadas automaticamente pelo serviço remoto da Apigee. Se a solicitação for autorizada, ela será contabilizada na cota permitida.

Onde as cotas são mantidas

As cotas são mantidas e verificadas localmente pelo processo do serviço remoto e mantidas de modo assíncrono com o ambiente de execução da Apigee. Isso significa que as cotas não são precisas e provavelmente serão excedidas se você tiver mais de um serviço remoto que as mantenha. Se a conexão com o ambiente de execução da Apigee for interrompida, a cota local continuará como uma cota independente até que seja possível se reconectar ao Apigee Runtime.

Escopos do OAuth

Se você estiver usando tokens JWT, poderá restringi-los aos subconjuntos dos escopos permitidos do OAuth. Os escopos atribuídos ao token JWT emitido serão verificados com base nos escopos do produto da API.

Sobre os apps do desenvolvedor

Depois de configurar os produtos da API, você criará um app associado a um desenvolvedor. O app permite que um cliente acesse os produtos da API associados com uma chave de API ou um token JWT.

Como usar a autenticação baseada em JWT

É possível usar um token JWT para fazer chamadas de proxy de API autenticadas, em vez de usar uma chave de API. Nesta seção, explicamos como usar o comando apigee-remote-service-cli token para criar, inspecionar e fazer a rotação de tokens JWT. No ambiente da Apigee híbrida, use esse comando para criar o secret do Kubernetes que armazenará os JWTs.

Visão geral

A verificação e a autenticação JWT são processadas pelo Envoy usando o filtro de autenticação JWT (em inglês).

Depois de autenticado, o filtro ext-authz do Envoy envia os cabeçalhos da solicitação e o JWT para apigee-remote-service-envoy. Ele corresponde as declarações api_product_list e scope do JWT aos produtos da API da Apigee para autorizá-la no destino da solicitação.

Como criar tokens JWT da Apigee

É possível criar tokens JWT da Apigee usando a CLI:

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

Também é possível usar o endpoint de token OAuth padrão. Exemplo de curva:

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"

OBSERVAÇÃO: o cabeçalho do tipo de conteúdo é obrigatório.

Como usar o token JWT

Quando você tiver o token, basta enviá-lo ao Envoy no cabeçalho "Authorization". Exemplo:

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

Falha no token JWT

Rejeição do Envoy

Se o Envoy rejeitar o token, você verá uma mensagem como esta:

Jwks remote fetch is failed

Neste caso, verifique se sua configuração do Envoy contém um URI válido na seção remote_jwks, que pode ser acessado pelo Envoy, e se você definiu os certificados corretamente ao instalar o proxy da Apigee. Será possível chamar o URI diretamente com uma chamada GET e receber uma resposta JSON válida.

Exemplo:

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

OBSERVAÇÃO: a sinalização --http1.1 é necessária para a Apigee híbrida.

Outras mensagens do Envoy podem ser assim:

• "Audiences in Jwt are not allowed"
• "Jwt issuer is not configured"

Elas fazem parte dos requisitos da configuração do Envoy que talvez você tenha que modificar.

Inspecionar um token

Use a CLI para inspecionar um 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

Como depurar

Consulte Falha em uma chave de API válida.

Geração de registros

É possível ajustar o nível de geração de registros no serviço $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. A geração de registros na íntegra é enviada ao stderr.

Elemento	Obrigatório	Descrição
-l, --log_level	Níveis válidos: depuração, informação, alerta, erro.	Ajusta o nível de geração de registros. Padrão: info
-j, --json_log		Emite a saída de registro como registros JSON.

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

• Geração de registros de aplicativos (em inglês)
• Registros de acesso (em inglês)
• Stackdriver Logging com GKE (em inglês)

Como alterar o nome do secret da política

Um secret do Kubernetes implantado no cluster inclui as credenciais que o adaptador precisa para autenticar a comunicação com o proxy de serviço remoto. Esse secret requer um ponto de montagem do volume, que é configurável. Por padrão, o ponto de montagem é /policy-secret. Para alterá-lo, siga estas etapas:

1. Execute este comando:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   Exemplo:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. Abra $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml em um editor.
3. Altere o nome do ponto de montagem:

   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. Salve o arquivo e aplique-o à malha de serviço:

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml

Como usar um proxy de rede

Um proxy HTTP pode ser inserido usando as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY no ambiente do binário apigee-remote-service-envoy. Ao usá-las, a variável de ambiente NO_PROXY também pode ser usada para impedir que hosts específicos sejam enviados por meio 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 precisa estar acessível no apigee-remote-service-envoy.

Sobre métricas e análises

Um endpoint de métricas do Prometheus está disponível em :5001/metrics. É possível configurar esse número de porta. Consulte Arquivo de configuração.

Análise do Envoy

Os links a seguir fornecem informações sobre como acessar os dados de análise do proxy do Envoy:

• Interface Admin (em inglês)
• Estatísticas (em inglês)
• Estatísticas do cluster (em inglês)

Análise do Istio

Os links a seguir fornecem informações sobre como acessar os dados de análise do proxy do Envoy:

• Tarefas de observabilidade (em inglês)
• Configuração de telemetria (em inglês)

Análise da Apigee

O serviço remoto da Apigee para Envoy envia estatísticas de solicitação à Apigee para processamento de análises. A Apigee relata essas solicitações com o nome do produto da API associado.

Para informações sobre as análises da Apigee, consulte a Visão geral dos serviços de análise.