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.
1. Fazer login na Apigee
- Faça login na IU da Apigee.
- Selecione a mesma organização que você usou para provisionar 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.
- Selecione Publicar > Produtos da API no menu de navegação lateral.
- Clique em +CRIAR.
- Preencha a página Detalhes do produto da maneira a seguir. Somente os campos obrigatórios são
mencionados na tabela a seguir:
Campo Valor Descrição Nome httpbin-product
O nome exclusivo do produto de API. Nome de exibição httpbin product
O nome descritivo que você quer ver na IU ou em outros contextos de exibição. Acesso Public
Para os fins deste exemplo, Público é uma boa opção. - Na seção Operações, clique em ADICIONAR UMA OPERAÇÃO.
- Na seção Origem, selecione Serviço remoto.
- Ative a opção Origem para digitar manualmente o nome de um serviço remoto no campo "Serviço remoto".
- No campo Serviço remoto, digite o nome de um serviço remoto. Este é um serviço de destino em que o adaptador
encaminhará solicitações HTTP recebidas. Para fins de teste, use
httpbin.org
ouhttpbin.default.svc.cluster.local
com o Kubernetes. - Na seção Operação, insira
/
como o caminho. Para mais informações sobre as opções de caminhos, consulte Como configurar caminhos de recursos. - Clique em SALVAR para salvar a operação.
- Clique em SALVAR para salvar o produto da API.
Para mais informações, consulte Como gerenciar produtos de API.
4. Criar um app do desenvolvedor
O app do desenvolvedor contém a chave de API necessária para fazer chamadas de proxy de API pelo adaptador.
- Selecione Publicar apps no menu de navegação lateral.
- Clique em + App.
- Preencha a seção Detalhes do app da seguinte maneira. Somente os campos obrigatórios são mencionados na tabela a seguir:
- 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
usando o adaptador da Apigee para Envoy.
Nome | httpbin-app
|
Desenvolvedor | Selecione o desenvolvedor que você criou ou escolha um na lista. |
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. Em um ambiente de 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 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". 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 has 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
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 Falha em uma chave de API válida.Como usar seu próprio provedor de identidade
Por padrão, o adaptador da Apigee para Envoy usa o proxy de API remote-token
como um serviço de provedor de identidade para autenticar aplicativos
clientes e enviar tokens JWT com base no tipo de concessão de credenciais de cliente OAuth 2.0. Em alguns casos, no entanto, talvez não seja possível usar o proxy remote-token
.
Se você precisar usar um provedor de identidade que não seja o fornecido pela Apigee, configure
o adaptador para usar outro provedor de identidade. Para detalhes sobre o caso de uso do provedor de identidade que não é da Apigee e a configuração
necessária, consulte este artigo na comunidade
da Apigee:
Como usar seu próprio provedor de identidade com o adaptador da Apigee Envoy.
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: debug, info, warn, error | 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:
- 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
- Abra
$CLI_HOME/samples/apigee-envoy-adapter.yaml
em um editor. - 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
- Salve o arquivo e aplique-o à malha de serviço:
kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.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.
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
. Por 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://apitest.mydomain.net/remote-service org_name: my-org env_name: "*"" allow_unverified_ssl_cert: true analytics: collection_interval: 10s auth: jwt_provider_key: https://apitest.mydomain.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
. Por 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
ouroutes
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. .
Como capturar dados para relatórios personalizados
O adaptador é compatível com a transmissão de metadados Envoy para o recurso de captura de dados da Apigee, que envia dados capturados nas variáveis especificadas à Apigee para uso em relatórios personalizados. Esse recurso oferece um recurso semelhante à Política de captura de dados da Apigee.
Para usar este recurso, siga estas etapas:
- Crie um recurso REST do coletor de dados.
- Defina variáveis de captura de dados usando a API de coleta de dados da Apigee.
- Se você ainda não tiver feito isso, 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
). - Use um filtro de Envoy para definir valores para suas variáveis personalizadas no namespace
envoy.filters.http.apigee.datacapture
. Por exemplo, use um filtro Cabeçalho para metadados ou Lua. Para mais informações sobre esses filtros, consulte Cabeçalho de metadados e Lua.Os nomes das variáveis personalizadas precisam ser formatados como
dc.XXXXX
.Exemplo de filtro de cabeçalho para metadados:
- name: envoy.filters.http.header_to_metadata typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config request_rules: - header: "Host" on_header_present: metadata_namespace: envoy.filters.http.apigee.datacapture key: dc.host # host (without the prefix) also works type: STRING remove: false
Exemplo de filtro Lua:
- name: envoy.filters.http.lua typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua inline_code: | function envoy_on_request(request_handle) metadata = request_handle:streamInfo():dynamicMetadata() metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.") end
- Adicione o filtro desejado ao arquivo. Veja os exemplos abaixo.
- Salve o arquivo e aplique-o.
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. Por exemplo:
tenant: tls: ca_file: path/ca.pem cert_file: path/cert.pem key_file: path/key.pem allow_unverified_ssl_cert: false