Como usar o adaptador da Apigee para Envoy com a Apigee 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 com uma implantação da Apigee híbrida.

Pré-requisitos

Antes de começar:

Visão geral

Neste exemplo, explicamos como usar o adaptador da Apigee para Envoy com a Apigee híbrida. Neste exemplo, você implantará um serviço HTTP simples no mesmo cluster do Kubernetes em que a Apigee híbrida foi implantada. Em seguida, você configurará o adaptador da Apigee para Envoy para gerenciar chamadas de API a esse serviço com a Apigee.

Na figura a seguir, mostramos a arquitetura básica da integração da Apigee híbrida:

Uma visualização
de alto nível do Envoy Adapter integrado a um ambiente da Apigee híbrida, incluindo o
plano de gerenciamento, o plano de ambiente de execução e os serviços do GCP

Um proxy Envoy é implantado com o serviço HTTP de destino como um arquivo secundário do Istio na malha de serviço do Istio. O arquivo secundário controla o tráfego da API para e do serviço de destino e comunica-se com o serviço remoto. O serviço remoto também se comunica com o plano de gerenciamento híbrido para recuperar informações do produto e do proxy de API.

Verificar a configuração da gcloud

  1. Verifique se a configuração do gcloud está definida como o projeto do GCP associado à sua organização híbrida.

    Para listar as configurações atuais:

    gcloud config list

    Se necessário, defina o ID do projeto do GCP 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 do GCP:
    gcloud auth login

Provisionar a Apigee híbrida

Nesta etapa, você usará a CLI do serviço remoto para provisionar a Apigee híbrida com o proxy de API remote-service. O comando de provisionamento também configura um certificado na Apigee e gera credenciais que o serviço remoto usará para se conectar com segurança à Apigee.

  1. Acesse o diretório $CLI_HOME:
    cd $CLI_HOME
  2. Se você não for o proprietário do projeto do GCP associado à organização da Apigee híbrida, verifique se sua conta de usuário do GCP inclui o papel Apigee Organization Admin. Consulte Como conceder, alterar e revogar acesso a recursos.
  3. Execute este comando para receber um token de acesso:
    TOKEN=$(gcloud auth print-access-token);echo $TOKEN
  4. 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
    export AX_SERVICE_ACCOUNT=analytics_service_account

    Em que:

    Variável Descrição
    organization_name O nome da organização da Apigee para sua instalação da Apigee híbrida.
    environment_name O nome de um ambiente na sua organização da Apigee híbrida.
    host_alias_url Um URL que inclui o hostAlias de um host virtual definido na configuração híbrida. O URL precisa começar com https://. Por exemplo: https://apitest.apigee-hybrid-docs.net
    hybrid_runtime_namepace O namespace em que os componentes do 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 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.
  5. Execute o seguinte comando para provisionar o proxy de serviço remoto para a Apigee híbrida:

    Se você não está fazendo upgrade, use este comando para provisionar a Apigee:

    ./apigee-remote-service-cli provision --organization $ORG --environment $ENV \
         --runtime $RUNTIME --namespace $NAMESPACE --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:

    ./apigee-remote-service-cli provision --force-proxy-install --organization $ORG --environment $ENV \
         --runtime $RUNTIME --namespace $NAMESPACE --analytics-sa $AX_SERVICE_ACCOUNT --token $TOKEN > config.yaml
  6. Verifique o conteúdo do arquivo config.yaml. Ele será semelhante a este:
    # Configuration for apigee-remote-service-envoy (platform: GCP)
    # 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.example.com/remote-service
          org_name: hybrid-gke
          env_name: test
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.example.com/remote-service/token
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hybrid-gke-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: hybrid-gke-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
  7. Aplique a configuração do serviço (a resposta do arquivo ao comando de provisionamento) ao cluster:
    kubectl apply -f $CLI_HOME/config.yaml
  8. Verifique seu proxy e certificado. O seguinte comando deve retornar um JSON válido:
    curl -i $RUNTIME/remote-service/certs

    A resposta terá a seguinte aparência:

    {
        "keys": [
            {
                "alg": "RS256",
                "e": "AQAB",
                "kid": "2020-05-11T11:32:26-06:00",
                "kty": "RSA",
                "n": "0v-nbTQyAmtVZ-wZRP0ZPIbrVaX91YO9JZ9xCQPb4mOdOSS7yKfTDJGg0KM130sGVYBvR76alN8
                fhrrSDEG5VXG8YYMqPXarwRC7MRJWocCQ_ECYrjDD0_Q018M2HyXZYSd8fhAogi9mVUYsEmCKqJH53Dh1
                jqsHOQzBLKsX0iDO9hEZNFtjbX0UCbSxsUlmBCub7Uj2S-PahA6DEQOMhQjZM7bBMtkTMpFmaJ_RZTmow
                BHP57qMna17R8wHD4kUsO2u_-3HHs5PSj1NrEYoVU2dwLQw0GlkB__ZWeFgXTqot81vb-PmoM9YxwoZrm
                TcHdljugWy_s7xROPzTod0uw"
            }
        ]
    }

Criar arquivos de configuração de amostra

Use o comando apigee-remote-service-cli samples create para gerar arquivos de configuração de amostra.

Neste exemplo, você precisa destes arquivos gerados:

  • httpbin.yaml: uma configuração de implantação de um serviço HTTP.
  • apigee-envoy-adapter.yaml: uma configuração de implantação do serviço remoto para Envoy.
  • envoyfilter-sidecar.yaml: uma configuração que instala um EnvoyFilter. no namespace padrão.

Para gerar as amostras:

  1. Acesse o diretório $CLI_HOME.
  2. Execute este comando para gerar os arquivos:

    ./apigee-remote-service-cli samples create -c ./config.yaml

    Estes arquivos são gravados no diretório ./samples:

    ls samples
    apigee-envoy-adapter.yaml envoyfilter-sidecar.yaml httpbin.yaml request-authentication.yaml
    

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

Implantar um serviço de teste no cluster

Nesta etapa, você implantará um serviço de teste de solicitação/resposta HTTP simples no mesmo cluster em que a Apigee híbrida está implantada.

  1. Ative a injeção do Istio no namespace default do cluster. Em uma etapa posterior, você implantará um arquivo secundário do Envoy nesse mesmo cluster. Ativar a injeção do Istio possibilita a implantação do arquivo secundário. Neste exemplo, usamos o namespace default, e todas as instruções subsequentes pressupõem que este é o caso.
    kubectl label namespace default istio-injection=enabled
  2. Aplique o serviço httpbin simples ao cluster no namespace padrão:
    kubectl apply -f $CLI_HOME/samples/httpbin.yaml
  3. Agora, teste o serviço. Inicie um serviço curl em execução no cluster e abra um terminal:
    kubectl run -it curl --image=curlimages/curl --restart=Never -- sh
  4. Chame o serviço de dentro do cluster para testá-lo:
    curl -i httpbin.default.svc.cluster.local/headers

    Se for bem-sucedido, você verá o status 200 e o serviço retornará uma lista de cabeçalhos. Exemplo:

    HTTP/1.1 200 OK
    server: envoy
    date: Tue, 12 May 2020 17:09:01 GMT
    content-type: application/json
    content-length: 328
    access-control-allow-origin: *
    access-control-allow-credentials: true
    x-envoy-upstream-service-time: 7
    
    {
      "headers": {
        "Accept": "*/*",
        "Content-Length": "0",
        "Host": "httpbin.default.svc.cluster.local",
        "User-Agent": "curl/7.70.0-DEV",
        "X-B3-Parentspanid": "69f88bc3e322e157",
        "X-B3-Sampled": "0",
        "X-B3-Spanid": "8dd725f30e393d8b",
        "X-B3-Traceid": "38093cd817ad30a569f88bc3e322e157"
      }
    }

Executar o serviço remoto para Envoy

Nesta etapa, você inicia o serviço remoto para o cliente Envoy na malha de serviço em que a Apigee híbrida está instalada. Esse serviço fornece os endpoints para os arquivos secundários do Istio instalados nos serviços de destino. Você também instala um arquivo secundário com o serviço httpbin.

  1. Aplique o serviço remoto da Apigee à malha de serviço:
    kubectl apply -f $CLI_HOME/samples/apigee-envoy-adapter.yaml
  2. Aplique o EnvoyFilter aos arquivos secundários do Istio no namespace padrão. O EnvoyFilter permite que o arquivo secundário httpbin se comunique com o serviço remoto da Apigee.
    kubectl apply -f $CLI_HOME/samples/envoyfilter-sidecar.yaml

Testar a instalação

  1. Agora, volte para o shell curl aberto na etapa Implantar um serviço de teste no cluster e chame o serviço httpbin:
    curl -i httpbin.default.svc.cluster.local/headers
    

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

    curl -i httpbin.default.svc.cluster.local/headers
    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
  2. Configure um produto de API e receba uma chave de API, conforme explicado em Como conseguir uma chave de API.
  3. Faça uma chamada de API usando a chave:
    export APIKEY=YOUR_API_KEY
    curl -i httpbin.default.svc.cluster.local/headers -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": "kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS",
        "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": "kyOTalNNLMPfOSy6rnVeclmVSL6pA2zS",
        "X-Apigee-Developeremail": "jdoe@example.com",
        "X-Apigee-Environment": "envoy",
        "X-Apigee-Organization": "acme-org",
        "X-Apigee-Scope": "",
        "X-B3-Parentspanid": "1476f9a2329bbdfa",
        "X-B3-Sampled": "0",
        "X-B3-Spanid": "1ad5c19bfb4bc96f",
        "X-B3-Traceid": "6f329a34e8ca07811476f9a2329bbdfa"
      }
    }

A seguir

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

  • Se você configurou o produto de API conforme explicado em Como conseguir uma chave de API, o limite de cota foi definido como cinco solicitações por minuto. Tente chamar o serviço httpbin mais algumas vezes para acionar a cota. Quando a cota é esgotada, um erro de status HTTP 403 é retornado.
  • Acesse o Apigee Analytics na IU da Apigee. Acesse Analisar > Métricas da API > Desempenho do proxy de API.
  • Gere e use os tokens JWT para autenticar as chamadas de API.
  • Use a CLI para gerenciar, criar tokens e controlar vinculações. Para detalhes da CLI, consulte a Referência.