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) para seu projeto do GCP:
    gcloud auth login

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. Acesse o diretório do serviço remoto:
    cd $REMOTE_SERVICE_HOME
  2. 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
  3. Aplique o serviço httpbin simples ao cluster no namespace padrão:
    kubectl apply -f samples/istio/httpbin.yaml
  4. 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
  5. 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"
      }
    }

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

    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.
  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 --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 --token $TOKEN > config.yaml
  6. Verifique o conteúdo do arquivo config.yaml. Ele será semelhante a este:
    # Configuration for apigee-remote-service-envoy
    # generated by apigee-remote-service-cli provision on 2020-07-06 18:03:58
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: apigee-remote-service-envoy
      namespace: apigee
    data:
      config.yaml: |
        tenant:
          remote_service_api: https://apitest.apigee-hybrid-docs.net/remote-service
          org_name: hybrid-docs
          env_name: envoy
          allow_unverified_ssl_cert: true
        analytics:
          collection_interval: 10s
          fluentd_endpoint: apigee-udca-hybrid-docs-envoy.apigee:20001
          tls:
            ca_file: /opt/apigee/tls/ca.crt
            key_file: /opt/apigee/tls/tls.key
            cert_file: /opt/apigee/tls/tls.crt
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: hybrid-docs-envoy-policy-secret
      namespace: apigee
    type: Opaque
    data:
      remote-service.crt: eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJhbGci...
      remote-service.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS...
      remote-service.properties: a2lkPTIwMjAtMDctMDZ...
  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 --http1.1 -i $RUNTIME/remote-service/certs

    A saída 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"
            }
        ]
    }

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. Em uma etapa posterior, você instalará um arquivo secundário com o serviço httpbin.

  1. Abra $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml em um editor.
  2. Poderá ser necessário ajustar a configuração se você não estiver usando a versão mais recente do serviço remoto. Se você estiver usando a versão mais recente, vá para a próxima etapa. Se não estiver usando a versão mais recente, defina o elemento image: para referir-se à sua versão. Por exemplo, se você estiver usando a versão v1.0.0-beta.4, altere a tag image para:
    image: "gcr.io/apigee-api-management-istio/apigee-remote-service-envoy:v1.0.0-beta.4"
  3. Defina o elemento tls-volume.secretName como sua organização e ambiente:
    ...
      volumes:
        - name: tls-volume
           secret:
             defaultMode: 420
             secretName: apigee-runtime-$ORG-$ENV-tls
         - name: policy-secret
           secret:
             defaultMode: 420
             secretName: $ORG-$ENV-policy-secret
    

    Exemplo:

    ...
      volumes:
        - name: tls-volume
           secret:
             defaultMode: 420
             secretName: apigee-runtime-myorg-myenv-tls
         - name: policy-secret
           secret:
             defaultMode: 420
             secretName: myorg-myenv-policy-secret
    ...
  4. Aplique o serviço remoto da Apigee à malha de serviço:
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml
  5. 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 $REMOTE_SERVICE_HOME/samples/istio/envoyfilter-sidecar.yaml

Teste 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, 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. Veja alguns recursos para você explorar e testar:

  • Se você configurou o produto da 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 você ultrapassa a cota, vê o seguinte erro:
    HTTP/1.1 429 Too Many Requests
  • Acesse o Apigee Analytics na IU do Edge. 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.