Exemplo híbrido do Apigee com Kubernetes

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 visã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 Google Cloud

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 gcloud está definida como o projeto do Google Cloud associado à sua organização híbrida.

    Para listar as configurações atuais:

    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:
    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 proprietário do projeto do Google Cloud associado à organização híbrida 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 oImplantador.

    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. (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.
  5. 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  ## Optional

    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 (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.
  6. 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
  7. Verifique o conteúdo do arquivo config.yaml. Ele 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.example.com/remote-service
          org_name: hybrid-gke
          env_name: test
        analytics:
          collection_interval: 10s
        auth:
          jwt_provider_key: https://apitest.example.com/remote-token/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
  8. Aplique a configuração do serviço (a resposta do arquivo ao comando de provisionamento) ao cluster:
    kubectl apply -f $CLI_HOME/config.yaml
  9. Verifique seu proxy e certificado. O seguinte comando deve retornar um JSON válido:
    curl -i $RUNTIME/remote-token/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 --template istio-1.12

    Os arquivos a seguir 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.

    Se estiver usando o Istio de código aberto:

    kubectl label namespace default istio-injection=enabled --overwrite

    Se estiver usando o ASM:

    kubectl label namespace default istio-injection=enabled istio.io/rev=REVISION --overwrite
  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. 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, o servidor 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 da 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:

  • Acesse o Apigee Analytics na IU do Edge. Acesse Analisar > Métricas da API > Desempenho do proxy de API.
  • Use a CLI para gerenciar, criar tokens e controlar vinculações. Para detalhes da CLI, consulte a Referência.

Desinstalar o adaptador da Apigee para 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.

Além disso, é possível executar os seguintes comandos:

kubectl delete -f $CLI_HOME/samples/envoyfilter-sidecar.yaml
  kubectl delete -f $CLI_HOME/samples/apigee-envoy-adapter.yaml
  kubectl delete -f $CLI_HOME/samples/httpbin.yaml
  kubectl delete -f $CLI_HOME/config.yaml