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:
Faça o download e instale o serviço remoto e a interface de linha de comando (CLI) do 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.

Verificar a configuração da gcloud

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

Acesse o diretório $CLI_HOME:
```
cd $CLI_HOME
```
(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.

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.

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.

Receber um token de acesso:

TOKEN=$(gcloud auth print-access-token);echo $TOKEN

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

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

Observação: a imagem do Docker é executada como um usuário não raiz. Verifique se ele recebeu permissão de leitura para o arquivo config.yaml.

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

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

Verifique se você está no diretório $ENVOY_HOME.

Liste os modelos de configuração disponíveis:

$CLI_HOME/apigee-remote-service-cli samples templates

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:

Faça o download de um binário do Envoy ou crie ele.
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

Configure um produto da API e receba uma chave de API, conforme explicado em Como conseguir uma chave de API.
Chame o serviço httpbin sem uma chave de API:
```
curl -i http://localhost:8080/headers -H "HOST:httpbin.org"
```
Observação: é necessário incluir o cabeçalho HOST e defini-lo como o host de serviço remoto definido no produto da API.

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

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:

Remova o adaptador do envoy onde você escolheu executar (nativamente ou no Docker).
Exclua os proxies remote-service e remote-token dos ambientes da Apigee. Consulte Como excluir um proxy de API.
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.

Exemplo do Envoy nativo para Apigee e híbrida

Pré-requisitos

Verificar a configuração da gcloud

Provisionar a Apigee

Executar apigee-remote-service-envoy

Executar o serviço de forma nativa

Executar o serviço no Docker

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

Instalar e executar o proxy Envoy

Testar a instalação

Desinstalar o adaptador da Apigee Envoy

Próximas etapas

Executar `apigee-remote-service-envoy`