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.

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.
Display Name	`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 ou httpbin.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:

Nome	`httpbin-app`
Desenvolvedor	Selecione o desenvolvedor que você criou ou escolha um na lista.

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.

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

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

Como depurar

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

Por 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. Exemplo:

Abra o arquivo config.yaml em um editor.

Altere o valor de tenant.env_name para "*". 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. Exemplo:

Gere o arquivo envoy-config.yaml usando a CLI. 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 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. 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. Exemplo:

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