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. Inicie sessão na IU do Apigee.
  2. Selecione a mesma organização que usou para aprovisionar 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.

  1. Selecione Publicar > Produtos de API no menu de navegação lateral.
  2. Clique em +CRIAR.
  3. Preencha a secção Detalhes do produto da seguinte forma. A tabela seguinte indica apenas os campos obrigatórios:
    Campo Valor Descrição
    Nome httpbin-product O nome exclusivo do produto API.
    Nome a apresentar httpbin product O nome descritivo que quer ver na IU ou noutros contextos de apresentação.
    Acesso Public Para efeitos deste exemplo, Público é uma boa escolha.
  4. Na secção Operações, clique em +ADICIONAR UMA OPERAÇÃO.
  5. Na secção Origem, selecione Serviço remoto.
  6. Alterne o botão Origem para poder escrever manualmente o nome de um serviço remoto no campo Serviço remoto.
  7. No campo Serviço remoto, introduza o nome de um serviço remoto. Este é um serviço de destino para o qual o adaptador encaminha pedidos HTTP recebidos. Para fins de teste, use httpbin.org ou httpbin.default.svc.cluster.local com o Kubernetes.

    O botão de opção Serviço remoto está selecionado, a ativação/desativação da introdução de texto manual está ativada e o serviço remoto httpbin.org é introduzido no campo Serviço remoto.

  8. Na secção Operation, introduza / para o caminho. Para informações sobre as opções de caminho, consulte o artigo Configurar caminhos de recursos.
  9. Clique em GUARDAR para guardar a operação.
  10. Clique em GUARDAR para guardar o produto API.

Para mais informações, consulte o artigo Gerir produtos de API.

4. Crie uma app de programador

A app do programador contém a chave da API necessária para fazer chamadas de proxy da API através do adaptador.

  1. Selecione Publicar apps no menu de navegação lateral.
  2. Clique em + App.
  3. Preencha a secção Detalhes da app da seguinte forma. A tabela seguinte indica apenas os campos obrigatórios:
    4. Nome 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 através do Apigee Adapter for Envoy.

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 um 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 do pedido 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, pode usar o ponto final do 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"

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 has 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.

Usar o seu próprio fornecedor de identidade

Por predefinição, o Apigee Adapter for Envoy usa o proxy de API remote-token como um serviço de fornecedor de identidade para autenticar aplicações cliente e fornecer tokens JWT com base no tipo de concessão de credenciais do cliente OAuth 2.0. No entanto, em alguns casos, pode não conseguir usar o proxy remote-token. Se tiver de usar um fornecedor de identidade que não seja o fornecido pelo Apigee, pode configurar o adaptador para usar outro fornecedor de identidade. Para ver detalhes sobre este exemplo de utilização do fornecedor de identidade não Apigee e a configuração necessária, consulte este artigo na comunidade do Apigee: Usar o seu próprio fornecedor de identidade com o adaptador do Apigee Envoy.

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:

Apigee Analytics

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 de API associado.

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

Suporte de ambiente multi-inquilino

Agora, pode ativar o adaptador para servir vários ambientes numa organização do Apigee. Esta funcionalidade permite-lhe usar um adaptador do Apigee para o Envoy associado a uma organização do Apigee para prestar serviços a vários ambientes. Antes desta alteração, um adaptador estava sempre associado a um ambiente do Apigee.

Para configurar o suporte de vários ambientes, altere o valor de tenant:env_name para "*" no ficheiro config.yaml. Por exemplo:

  1. Abra o ficheiro config.yaml num editor.
  2. 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
  3. Guarde o ficheiro.
  4. Aplique o ficheiro: 
    kubectl apply -f $CLI_HOME/config.yaml

Quando configura o modo de vários ambientes, também tem de configurar o Envoy para enviar um valor de ambiente adequado ao adaptador adicionando os seguintes metadados na secção virtual_hosts:routes do ficheiro envoy-config.yaml. Por exemplo:

  1. Gere o ficheiro envoy-config.yaml através da CLI. Por exemplo: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  2. Abra o ficheiro gerado (denominado envoy-config.yaml).
  3. Adicione os seguintes metadados na secção virtual_host ou routes do ficheiro: 
    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 seguinte ilustra a configuração de um virtual_host com vários trajetos definidos, em que cada trajeto 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
  4. Repita o último passo para adicionar ambientes adicionais, conforme necessário.
  5. Guarde o ficheiro e aplique-o.

Capturar dados para relatórios personalizados

O adaptador suporta a transmissão de metadados do Envoy para a funcionalidade de captura de dados do Apigee, que envia dados capturados em variáveis que especificar para o Apigee Analytics para utilização em relatórios personalizados. Esta funcionalidade oferece uma capacidade semelhante à política de captura de dados do Apigee.

Para usar esta funcionalidade:

  1. Crie um recurso REST do coletor de dados.
  2. Defina variáveis de captura de dados através da API Apigee datacollectors.
  3. Se ainda não o fez, gere o ficheiro envoy-config.yaml através da CLI. Por exemplo: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. Abra o ficheiro gerado (denominado envoy-config.yaml).
  5. Use um filtro do Envoy para definir valores para as suas variáveis personalizadas no espaço de nomes envoy.filters.http.apigee.datacapture. Por exemplo, pode usar um filtro Cabeçalho para metadados ou um filtro Lua. Para mais informações sobre estes filtros, consulte os artigos Header-To-Metadata e Lua.

    Os nomes das variáveis personalizadas têm de estar 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
  6. Adicione o filtro pretendido ao ficheiro. Veja exemplos abaixo.
  7. Guarde o ficheiro e aplique-o.

Configurar mTLS entre o adaptador e o tempo de execução do Apigee

Pode fornecer certificados TLS do lado do cliente na secção tenant do ficheiro config.yaml do adaptador para usar o mTLS entre o adaptador e o tempo de execução do Apigee. Esta alteração aplica-se a todas as plataformas Apigee suportadas. Também ativa o mTLS para estatísticas para a plataforma Apigee Edge for Private Cloud. Por exemplo: 

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