Esta página foi traduzida pela API Cloud Translation.

Guia de operações

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

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 para um serviço de destino por proxy usando o adaptador da Apigee para Envoy.

1. Fazer login na Apigee

Abra a IU da Apigee em um navegador.
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:

Selecione Publicar > Desenvolvedores no menu de navegação lateral.
Clique em + Desenvolvedor.
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.

Selecione Publicar > Produtos da API no menu de navegação lateral.
Clique em + Produto da API.
Preencha a página de detalhes do produto da maneira a seguir.

Campo	Valor
Nome	`httpbin-product`
Display Name	`httpbin product`
Ambiente	`your_environment` Defina isso como o ambiente usado quando você provisionou o adaptador da Apigee para Envoy.
Acesso	`Private`
Cota	5 solicitações a cada 1 minuto Consulte também Cota.

Na seção Apigee remote service targets, clique em Add an Apigee remote service target.

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.
Caminho	Insira um caminho de recurso no serviço para corresponder. Exemplo: `/headers`.	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.

Clique em Salvar.

4. Criar um app do desenvolvedor

Selecione Publicar > Apps no menu de navegação lateral.
Clique em + App.
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`
Display Name	`httpbin app`
Desenvolvedor	Selecione o desenvolvedor criado anteriormente ou escolha um desenvolvedor na lista.

Em seguida, adicione o produto da API ao app:

Na seção "Credenciais", clique em + Adicionar produto e selecione o produto que você acabou de configurar: httpbin-product.
Clique em Criar.
Em "Credenciais", clique em Mostrar ao lado de Chave.
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:

Objetivo
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 cotas

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 sem custo financeiro, 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 mantendo a cota. 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.

Informações gerais

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:

$CLI_HOME/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 curl:

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

Como usar o token JWT

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

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 https://myorg-eval-test.apigee.net/remote-service/certs

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

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

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

Depuração

Consulte Falha em chaves de API válidas.

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. Todos os registros são enviados para stdout e stderr.

Elemento	Obrigatório	Descrição
-l, --log-level	Níveis válidos: debugging, informação, aviso, 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 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.

Suporte ao ambiente multilocatário

Agora é possível ativar o adaptador para atender a vários ambientes em uma organização da Apigee. Esse recurso permite usar um adaptador do Apigee para Envoy associado a uma organização da Apigee para atender a vários ambientes. Antes dessa alteração, um adaptador sempre foi vinculado a um ambiente da Apigee.

Para configurar o suporte a vários ambientes, altere o valor de tenant:env_name para * no arquivo config.yaml. Exemplo:

Abra o arquivo config.yaml em um editor.

Altere o valor de tenant.env_name para *. Por exemplo:

apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://myorg-myenv.apigee.net/remote-service
      org_name: apigee-docs-hybrid-a
      env_name: *
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token

Salve o arquivo.
Aplique o arquivo:
```
kubectl apply -f $CLI_HOME/config.yaml
```

Ao configurar o modo de vários ambientes, você também precisa configurar o Envoy para enviar um valor de ambiente apropriado ao adaptador adicionando os seguintes metadados na seção virtual_hosts:routes do arquivo envoy-config.yaml. Exemplo:

Gere o arquivo envoy-config.yaml usando a CLI. Por exemplo:

$CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs

Abra o arquivo gerado (chamado envoy-config.yaml).

Adicione os seguintes metadados na seção virtual_host ou routes do arquivo:

typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

O exemplo a seguir ilustra a configuração de uma virtual_host com várias rotas definidas, em que cada rota envia tráfego para um ambiente específico:

filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod

Repita a última etapa para adicionar outros ambientes conforme necessário.
Salve o arquivo e aplique-o.
Observação: se env_name em config.yaml for definido com outro valor além de *, o adaptador retornará um erro para o Envoy e a solicitação será negada se a configuração do adaptador de env_name não for definida como * ou se a propriedade env_name não corresponder aos metadados apigee_environment transmitidos.
.

Como configurar mTLS entre o adaptador e o ambiente de execução da Apigee

É possível fornecer certificados TLS do lado do cliente na seção tenant do arquivo config.yaml do adaptador para usar mTLS entre o adaptador e o ambiente de execução da Apigee. Essa alteração se aplica a todas as plataformas compatíveis da Apigee. Além disso, permite o mTLS para análise da plataforma Apigee Edge para nuvem privada. Exemplo:

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false