Exemplo do Envoy nativo para Apigee e híbrida

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

Confira a documentação da Apigee Edge.

Neste exemplo, demonstramos como usar o adaptador da Apigee para Envoy instalando e executando o Envoy localmente, não dentro de um cluster do Kubernetes. É possível seguir o exemplo neste documento para as instalações da Apigee e da Apigee híbrida.

As chamadas de proxy de API passam pelo Envoy em execução como um aplicativo nativo. A Apigee oferece serviços de gerenciamento de APIs, como a criação de produtos de API e de apps para desenvolvedores. O Envoy se comunica com o plano de gerenciamento da Apigee por meio do serviço remoto do adaptador. O adaptador também envia dados de análise à Apigee, onde eles podem ser vistos no Apigee Analytics.

Pré-requisitos

Antes de começar:

Verificar a configuração da gcloud

  1. Verifique se a configuração gcloud está definida como o projeto do Google Cloud associado à sua organização da Apigee.

    Para listar as configurações atuais. Consulte também gcloud config.

    gcloud config list

    Se necessário, defina o ID do projeto do Google Cloud correto com este comando:

    gcloud config set project project-id
  2. Você precisa ser autenticado com o SDK do Google Cloud (gcloud) no seu projeto. Consulte também gcloud auth login.
    gcloud auth login

Provisionar a Apigee

Nesta etapa, você usará a CLI do serviço remoto para provisionar recursos do adaptador da Apigee para Envoy à Apigee. O comando de provisionamento implanta proxies de API usados para operações de adaptador da Apigee, configura um certificado na Apigee e gera credenciais que o serviço remoto usará para se conectar com segurança do sistema à Apigee.

  1. Acesse o diretório $CLI_HOME:
    cd $CLI_HOME
  2. (Opcional) Por padrão, o adaptador procura credenciais de conta de serviço padrão no projeto do Google Cloud para ter permissão de envio de dados de análise para a Apigee. Se você não quiser usar as credenciais padrão da conta de serviço, crie uma conta de serviço e faça referência à chave no comando de provisionamento. A conta de serviço deve ter o papel apigee.analyticsAgent. Veja instruções em Como criar e gerenciar contas de serviço.
  3. Crie as variáveis de ambiente a seguir. Essas variáveis serão usadas como parâmetros para o script de provisionamento:
    export ORG=organization_name
    export ENV=environment_name
    export RUNTIME=host_alias_url
    export NAMESPACE=hybrid_runtime_namespace  ## Apigee hybrid only
    export AX_SERVICE_ACCOUNT=analytics_service_account  ## Optional

    Em que:

    Variável Descrição
    organization_name O nome da sua organização da Apigee.
    environment_name O nome de um ambiente na organização.
    host_alias_url
    • Para a Apigee híbrida, um URL que inclui o hostAlias de um host virtual definido na configuração híbrida.
    • Para Apigee, um nome do host do grupo de ambientes que inclui o ambiente. É possível encontrar grupos de ambiente na IU da Apigee em Administrador > Ambientes > Grupos.
    • Observação: o URL precisa começar com https://. Exemplo: https://apitest.mydomain.net

    hybrid_runtime_namepace (Somente Apigee híbrida) O namespace em que os componentes de ambiente de execução híbrido são implantados.

    Observação: o namespace padrão de uma implantação híbrida é apigee.

    analytics_service_account (Opcional) O caminho para o arquivo JSON da chave da conta de serviço do Google Cloud que tem o papel Apigee Analytics Agent. Para ver uma descrição detalhada desse parâmetro, consulte o comando Provision.
  4. Se você não for proprietário do projeto do Google Cloud associado à organização da Apigee, verifique se sua conta de usuário do Google Cloud inclui o papel de Administrador da organização do Apigee ou os papéis de Criador da API e Implantador. Consulte Como conceder, alterar e revogar acesso a recursos.
  5. Receber um token de acesso:
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  6. Provisione o proxy de serviço remoto para a Apigee. A resposta ao comando é redirecionada para um arquivo de configuração que você usará em uma etapa posterior.

    Se você não está fazendo upgrade, use este comando para provisionar a Apigee. Se você estiver provisionando para a Apigee híbrida, adicione o parâmetro --namespace $NAMESPACE:

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
         --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml

    Se você está fazendo upgrade, use este comando com a sinalização --force-proxy-install para provisionar a Apigee. Se você estiver provisionando para a Apigee híbrida, adicione o parâmetro --namespace $NAMESPACE:

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
         --runtime $RUNTIME --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
  7. Verifique o conteúdo do arquivo config.yaml. O código será semelhante a este:
    # Configuration for apigee-remote-service-envoy (platform: Google Cloud)
    # generated by apigee-remote-service-cli provision on 2020-11-20 02:49:28
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee
    data:
      config.yaml: |
        tenant:
          remote_service_api: https://apitest.mydomain.com/remote-service
          org_name: my-org
          env_name: test
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.mydomain.com/remote-service/token
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: my-org-new-test-policy-secret
      namespace: apigee
    type: Opaque
    data:
      remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
      remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
      remote-service.properties: a2lkPTIwMjAtMDctMDZ...
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: my-org-new-test-analytics-secret
      namespace: apigee
    type: Opaque
    data:
      client_secret.json: ewogICJ0eXBlIjogInNlcnZ...
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee

Executar apigee-remote-service-envoy

Execute o serviço remoto como um binário nativo ou no Docker.

Executar o serviço de forma nativa

Execute o binário do serviço com o arquivo de configuração que foi gerado pelo comando de provisionamento:

$REMOTE_SERVICE_HOME/apigee-remote-service-envoy -c config_file_path/config.yaml

Executar o serviço no Docker

As imagens do Docker são publicadas com tags de lançamento. Para esta instalação, use a versão mais recente. É possível escolher entre três variações de imagens:

Variação Image
Distribuições do Google google/apigee-envoy-adapter:v2.0.3
Ubuntu google/apigee-envoy-adapter:v2.0.3-ubuntu
Ubuntu com Boring Crypto google/apigee-envoy-adapter:v2.0.3-boring

Por exemplo, para executar a imagem de rascunho com o config.yaml local disponível como /config.yaml por meio de um suporte de volume, use este comando:

docker run -v ./config.yaml:/config.yaml google/apigee-envoy-adapter:v2.0.3

Criar um arquivo de configuração de amostra do Envoy

Gere um arquivo de configuração do Envoy de amostra usando a CLI:

  1. Verifique se você está no diretório $ENVOY_HOME.
  2. Liste os modelos de configuração disponíveis:
    $CLI_HOME/apigee-remote-service-cli samples templates
  3. Execute o comando de amostras. Para TEMPLATE, substitua um dos modelos de Envoy compatíveis:

    $CLI_HOME/apigee-remote-service-cli samples create --template TEMPLATE -c ./config.yaml

    O comando cria o arquivo ./samples/envoy-config.yaml.

Para mais informações, consulte Comandos de amostra.

Instalar e executar o proxy Envoy

Siga estas etapas para instalar e executar o proxy Envoy:

  1. Faça o download de um binário do Envoy ou crie ele.
  2. Execute o Envoy usando um arquivo de configuração de amostra que você gerou anteriormente para o serviço httpbin.org:
    envoy -c ./samples/envoy-config.yaml

Testar a instalação

  1. Configure um produto da API e receba uma chave de API, conforme explicado em Como conseguir uma chave de API.
  2. Chame o serviço httpbin sem uma chave de API:
    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
    

    O serviço está sendo gerenciado pela Apigee e, como você não forneceu uma chave de API, a chamada retorna o erro a seguir.

    curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
    HTTP/1.1 403 Forbidden
    date: Tue, 12 May 2020 17:51:36 GMT
    server: envoy
    content-length: 0
    x-envoy-upstream-service-time: 11
  3. Faça uma chamada de API usando a chave:
    export APIKEY=YOUR_API_KEY
    curl -i http://localhost:8080/headers -H "HOST:httpbin.org" -H "x-api-key: $APIKEY"

    A chamada deve ter o status 200 e retornar uma lista de cabeçalhos na resposta. Exemplo:

    curl -i httpbin.default.svc.cluster.local/headers -H "x-api-key: kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS"
    HTTP/1.1 200 OK
    server: envoy
    date: Tue, 12 May 2020 17:55:34 GMT
    content-type: application/json
    content-length: 828
    access-control-allow-origin: *
    access-control-allow-credentials: true
    x-envoy-upstream-service-time: 301
    
    {
      "headers": {
        "Accept": "*/*",
        "Content-Length": "0",
        "Host": "httpbin.default.svc.cluster.local",
        "User-Agent": "curl/7.70.0-DEV",
        "X-Api-Key": "kyOTalNNLMPfOSy6rneclmVSL6pA2zS",
        "X-Apigee-Accesstoken": "",
        "X-Apigee-Api": "httpbin.default.svc.cluster.local",
        "X-Apigee-Apiproducts": "httpbin",
        "X-Apigee-Application": "httpbin",
        "X-Apigee-Authorized": "true",
        "X-Apigee-Clientid": "kyOTalNNLMPfOSy6rVeclmVSL6pA2zS",
        "X-Apigee-Developeremail": "user@mydomain.com",
        "X-Apigee-Environment": "test",
        "X-Apigee-Organization": "my-org",
        "X-Apigee-Scope": "",
        "X-B3-Parentspanid": "1476f9a2329bbdfa",
        "X-B3-Sampled": "0",
        "X-B3-Spanid": "1ad5c19bfb4bc96f",
        "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
      }
    }

Desinstalar o adaptador da Apigee Envoy

Para remover uma instalação do adaptador da Apigee Envoy:

  1. Remova o adaptador do envoy onde você escolheu executar (nativamente ou no Docker).
  2. Exclua os proxies remote-service e remote-token dos ambientes da Apigee. Consulte Como excluir um proxy de API.
  3. Remova todos os produtos ou operações da API não utilizados que foram utilizados pelos casos de uso do adaptador do Envoy. Consulte Como excluir um produto de API.

Próximas etapas

O tráfego da API para o serviço httpbin agora é gerenciado pela Apigee. Veja alguns recursos para você explorar e testar:

  • Acesse o Apigee Analytics na IU do Edge. Acesse Analisar > Métricas da API > Desempenho do proxy de API.
  • Explore as opções da CLI em Referência.