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

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

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

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

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

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

Acesse o diretório $CLI_HOME.
Execute este comando para gerar os arquivos:
```
./apigee-remote-service-cli samples create -c ./config.yaml --template istio-1.12
```
Observação: o comando acima gera os arquivos usando o modelo do Istio 1.12. Para ver outras versões de modelo disponíveis, execute ./apigee-remote-service-cli samples templates

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

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:

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.

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