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:
Faça o download e instale o serviço remoto e a CLI do adaptador da Apigee para Envoy, conforme explicado em Primeiros passos.
Verifique se o SDK do Google Cloud está instalado. O SDK inclui a ferramenta de linha de comando `gcloud`.
Verifique se o `kubectl` está instalado.

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

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

Acesse o diretório $CLI_HOME:
```
cd $CLI_HOME
```
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.
Execute este comando para receber um token de acesso:
```
TOKEN=$(gcloud auth print-access-token);echo $TOKEN
```

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

Execute o seguinte comando para provisionar o proxy de serviço remoto para a Apigee híbrida:
OBSERVAÇÃO: se a instalação do ambiente de execução híbrido foi configurada usando certificados TLS autoassinados para o virtualhost, use a sinalização --insecure com o comando provision mostrado abaixo.

OBSERVAÇÃO: a resposta ao comando é redirecionada para um arquivo de configuração que você usará em uma etapa posterior.

SE VOCÊ ESTIVER FAZENDO UPGRADE: se você estiver fazendo upgrade de um adaptador da Apigee para Envoy atual, será necessário adicionar a sinalização --force-proxy-install ao comando provision. Essa sinalização força a substituição do proxy da Apigee pelo mais recente.

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
```

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

Aplique a configuração do serviço (a resposta do arquivo ao comando de provisionamento) ao cluster:
```
kubectl apply -f $CLI_HOME/config.yaml
```

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:

Acesse o diretório $CLI_HOME.
Execute este comando para gerar os arquivos:
```
./apigee-remote-service-cli samples create -c ./config.yaml
```
Observação: por padrão, o comando gera arquivos usando o modelo do Istio 1.6. Para o Istio 1.7, especifique a flag --template istio-1.7

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.

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
```
Aplique o serviço httpbin simples ao cluster no namespace padrão:
```
kubectl apply -f $CLI_HOME/samples/httpbin.yaml
```
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
```

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"
  }
}

DICA: deixe o cliente curl em execução e o shell aberto. Ele será usado em uma etapa posterior.

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.

Aplique o serviço remoto da Apigee à malha de serviço:

kubectl apply -f $CLI_HOME/samples/apigee-envoy-adapter.yaml

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

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
```
Configure um produto da API e receba uma chave de API, conforme explicado em Como conseguir uma chave de API.

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