Migrar para o Extensible Service Proxy V2 Beta

O Extensible Service Proxy V2 Beta (ESPv2 Beta) é um proxy baseado em Envoy que permite que o Cloud Endpoints forneça recursos de gerenciamento de APIs. O ESPv2 Beta substitui o Extensible Service Proxy (ESP) baseado em NGINX.

Neste documento, descrevemos como migrar uma implantação atual da API Endpoints do ESP para o ESPv2 Beta.

Antes de começar

Antes de iniciar a migração, considere os casos de uso não compatíveis e as alterações interruptivas da API descritas abaixo.

Casos de uso Beta não compatíveis do ESPv2

  • O ambiente flexível do App Engine não é compatível

    O ambiente flexível do App Engine conta com suporte integrado do Endpoints, que é ativado ao configurar endpoints_api_service no arquivo app.yaml do aplicativo. Esta implementação integrada do Endpoints aceita apenas o ESP. Não é possível migrá-lo para o ESPv2 Beta.

    Se você quiser usar o ESPv2 Beta com o ambiente flexível do App Engine, desative endpoints_api_service em app.yaml. Implante o ESPv2 Beta como um serviço separado do Cloud Run usado para gerenciar seu aplicativo no ambiente flexível do App Engine. A implantação funciona da mesma maneira que o ESPv2 Beta, que é compatível com o ambiente padrão do App Engine.

  • A configuração personalizada do NGINX não é compatível

    O ESPv2 Beta é um proxy baseado em Envoy. Ele não é compatível com a configuração personalizada do proxy NGINX. Se sua configuração do ESP usa as sinalizações -n ou --nginx_config, a implementação talvez use uma configuração personalizada do NGINX que não pode ser migrada facilmente para o ESPv2 Beta.

Alterações importantes

  • O formato de dados do cabeçalho X-Endpoint-API-UserInfo foi alterado. Se o aplicativo usar esse cabeçalho, ele precisará ser alterado para usar o novo formato. Consulte Processar JWTs no serviço de back-end para mais detalhes.
  • Se uma chave de API for necessária para uma solicitação, o ESP enviará o cabeçalho do X-Endpoint-API-Project-ID com o ID do projeto do consumidor ao aplicativo de back-end. O ESPv2 Beta usa dois cabeçalhos diferentes, X-Endpoint-API-Consumer-Type e X-Endpoint-API-Consumer-Number, para enviar os detalhes necessários. Consulte a documentação de referência do Service Infrastructure para mais detalhes sobre os Consumer-Type e Consumer-Number enviados com esses cabeçalhos.

  • Alteração no formato do corpo da resposta de erro HTTP. Quando o ESPv2 Beta rejeita uma solicitação HTTP, ele gera um corpo de resposta de erro em um novo formato. Se sua implementação usar o código do cliente para processar o corpo da resposta JSON de erro HTTP, o código do cliente precisará ser atualizado. Consulte Corpo da resposta JSON de erro HTTP para mais detalhes.

  • Novas sinalizações de inicialização estão disponíveis. Algumas sinalizações do ESP estão obsoletas ou foram substituídas no ESPv2 Beta. Consulte Alterações na sinalização de inicialização entre o ESP e o ESPv2 Beta.

Como migrar as APIs do Endpoints para usar o ESPv2 Beta

As etapas de migração necessárias para usar o ESPv2 Beta com plataformas sem servidor (Cloud Run, Cloud Functions, App Engine) são diferentes das etapas necessárias para plataformas sem servidor (Google Kubernetes Engine, Compute Engine e Kubernetes).

Veja abaixo as etapas de migração necessárias para cada tipo de plataforma:

Plataformas sem servidor: GKE, Compute Engine, Kubternetes

O ESPv2 Beta é uma substituição de reserva para o ESP. Na maioria das configurações, você só precisa atualizar para a tag de imagem do Docker.

No entanto, talvez seja necessário ajustar as sinalizações de inicialização se você tiver configurado o ESP com o seguinte:

  • Mais de uma porta por meio das sinalizações --http_port, http2_port e/ou --ssl_port.
  • SSL, DNS, Client IP ou outra sinalização raramente usada.

Novas sinalizações de inicialização estão disponíveis para o ESPv2 Beta. Algumas sinalizações do ESP estão obsoletas ou foram substituídas. Consulte Mudanças na sinalização de inicialização entre o ESP e o ESPv2 Beta para mais detalhes.

GKE e Kubernetes

Para migrar as configurações do Endpoints para GKE e Kubernetes, altere a tag de imagem do ESP de :1 para :2 no arquivo yaml da implantação. Exemplo:

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed",
  ]

Compute Engine

O ESP e o ESPv2 Beta são implantados no contêiner do Docker usando o comando docker run. Para migrar o Endpoints para Compute Engine para o ESPv2 Beta, atualize a tag de imagem do Docker de :1 para :2 no comando. Exemplo:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Plataformas sem servidor (Cloud Run, Cloud Functions, App Engine)

Para plataformas sem servidor, o ESPv2 Beta é implantado como um serviço do Cloud Run para gerenciar o aplicativo em execução no Cloud Run, Cloud Function ou App Engine. Para migrar o Endpoints para o ESPv2 Beta, você precisa criar a configuração do serviço do Endpoints em uma nova imagem do Docker do ESPv2 Beta e, em seguida, implantar a imagem no serviço Cloud Run do ESPv2 Beta.

As etapas de implantação para ESP e ESPv2 Beta são idênticas, exceto pelos seguintes detalhes:

  • Ao implantar o ESPv2 Beta no Cloud Run, a tag de imagem precisa ser alterada de :1 para :2 no ESPv2 Beta. Exemplo:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID
    
  • O download do script gcloud_build_image é feito em um local diferente. Ele usa gcr.io/endpoints-release/endpoints-runtime-serverless:2 como a imagem base.

  • Uma variável de ambiente é usada para especificar sinalizações de inicialização. O nome da variável do ESP é ESP_ARGS. O nome do ESPv2 Beta é ESPv2_ARGS. Consulte Opções de inicialização do Extensible Service Proxy V2 Beta para mais informações sobre como definir ESPv2_ARGS e as sinalizações de inicialização disponíveis.

Mudanças na sinalização de inicialização entre o ESP e o ESPv2 Beta

Assim como no Extensible Service Proxy, é possível especificar sinalizações de configuração ao implantar serviços de ESPv2 Beta. Com a mudança do ESP baseado em NGINX para o ESPv2 Beta baseado em Envoy, algumas sinalizações foram suspensas ou substituídas e novas sinalizações foram adicionadas. Esta seção usa três tabelas para descrever as alterações:

  • A Tabela 1 descreve novas sinalizações que substituem as sinalizações obsoletas.
  • A Tabela 2 descreve novas sinalizações.
  • A Tabela 3 descreve as sinalizações obsoletas.

Sinalizações substituídas

Novas sinalizações Sinalizações substituídas Descrição
--listener_port --http_port, --http2_port, --ssl_port Uma única porta do listener do Envoy é compatível com http, http2 e ssl no ESPv2 Beta. Não é necessário especificar portas separadas.
--ssl_server_cert_path --ssl_port Quando --ssl_server_cert_path é usado, o ESPv2 Beta usa certificados de arquivos server.key e server.crt. O ESPv2 Beta possibilita especificar caminhos de certificado do servidor diferentes de /etc/nginx/ssl. Essa sinalização substitui --ssl_port no ESP, que usa certificados dos caminhos de arquivo /etc/nginx/ssl/nginx.key e /etc/nginx/ssl/nginx.crt.
--ssl_client_cert_path --tls_mutual_auth, --enable_grpc_backend_ssl, --grpc_backend_ssl_private_key_file, --grpc_backend_ssl_cert_chain_file Quando --ssl_client_cert_path é usado, o ESPv2 Beta usa certificados de arquivos client.key e client.crt. O ESPv2 Beta possibilita especificar caminhos de certificado do cliente diferentes de /etc/nginx/ssl. Essa sinalização substitui --tls_mutual_auth no ESP, que usa certificados dos caminhos de arquivo /etc/nginx/ssl/backend.key e /etc/nginx/ssl/backend.crt.
--ssl_client_root_certs_file --grpc_backend_ssl_root_certs_file No ESPv2 Beta, --ssl_client_root_certs_file funciona para todos os back-ends. Essa sinalização substitui --grpc_backend_ssl_root_certs_file no ESP, que só funciona para back-ends do gRPC.
--ssl_minimum_protocol,--ssl_maximum_protocol --ssl_protocols Ao usar --ssl_protocols no ESP, você precisa listar todos os protocolos ssl desejados. No ESPv2 Beta, é possível especificar um protocolo mínimo e máximo.
--envoy_use_remote_address,--envoy_xff_num_trusted_hops --xff_trusted_proxy_list,--client_ip_header,--client_ip_position O Envoy exige que use_remote_address e xff_num_trusted_hops configurem a extração de IP do cliente.
--dns_resolver_addresses --dns A sinalização de substituição tem o mesmo comportamento, mas um valor padrão diferente. O ESP usa 8.8.8.8 como um resolvedor de DNS. O ESPv2 Beta usa o resolvedor de DNS configurado em /etc/resolv.conf.

Novas sinalizações

Novas sinalizações Descrição
--http_request_timeout_s Define o tempo limite para todas as chamadas remotas http/https, exceto para chamadas de back-end e chamadas do Google Service Control, em segundos.
--service_control_check_timeout_ms Define o tempo limite para as chamadas de Verificação de controle dos Serviços do Google em milissegundos.
--service_control_report_timeout_ms Define o tempo limite para chamadas de Relatório de controle dos Serviços do Google.
--service_control_quota_timeout_ms Define o tempo limite para chamadas de Cota de controle dos Serviços do Google.
--service_control_check_retries Especifica o número de repetição de chamadas de Verificação de controle dos Serviços do Google.
--service_control_report_retries Especifica o número de repetição de chamadas do Relatório de controle dos Serviços do Google.
--service_control_quota_retries Especifica o número de repetição de chamadas de Cota de controle dos Serviços do Google.
--backend_dns_lookup_family Configuração específica do Envoy usada para definir a família da busca DNS de todos os back-ends.
--disable_tracing Uma sinalização geral usada para desativar todos os traces.
--tracing_project_id Usado para definir o ID do projeto que tem os dados de rastreamento.
--tracing_incoming_context Usado para especificar o contexto de trace de entrada.
--tracing_outgoing_context Usado para especificar o contexto de saída.

Sinalizações obsoletas

Sinalizações obsoletas Descrição
--enable_websocket O Websocket é ativado por padrão no Envoy.
--experimental_proxy_backend_host_header Incompatível.
--allow_invalid_headers Incompatível. Esta é uma configuração do NGINX: ignore_invalid_headers. Se uma solicitação HTTP tiver nomes de cabeçalho inválidos, ela será rejeitada pelo ESPv2 Beta. Nomes de cabeçalho válidos são compostos de letras em inglês, dígitos, hífens e possivelmente sublinhados. No ESPv2 Beta, a sinalização --underscores_in_headers determina se sublinhados são permitidos em cabeçalhos.
--client_max_body_size A configuração do NGINX é incompatível.
--client_body_buffer_size A configuração do NGINX é incompatível.
--large_client_header_buffers A configuração do NGINX é incompatível.
--keepalive_timeout A configuração do NGINX é incompatível.
--client_body_timeout A configuração do NGINX é incompatível.
--rewrite Incompatível.
--experimental_enable_multiple_api_configs Incompatível.
--enable_backend_routing Desnecessário. O roteamento de back-end é ativado automaticamente nas plataformas sem servidor.
--rollout_fetch_throttle_window_in_s Desnecessário.
--nginx_config Incompatível.

Consulte Opções de inicialização do Extensible Service Proxy V2 Beta para mais detalhes sobre as sinalizações de inicialização do ESPv2 Beta. Outros exemplos genéricos e textos de ajuda para sinalizações podem ser encontrados no repositório do GitHub.

Gerenciar os JWTs no serviço de back-end

Ao usar os JWTs para executar a autenticação, ambos os proxies enviam o resultado da autenticação no cabeçalho X-Endpoint-API-UserInfo para a API de back-end. Recomendamos usar esse cabeçalho em vez do cabeçalho Authorization original porque o Authorization pode ser modificado em plataformas sem servidor. No entanto, o formato do cabeçalho foi alterado para o ESPv2 Beta.

No ESP, o cabeçalho X-Endpoint-API-UserInfo contém um objeto JSON codificado em Base64Url que contém o payload do JWT e alguns campos específicos adicionados pelo ESP.

Se disponíveis no JWT, o ESP adicionará os valores das propriedades id, issuer, email e audiences ao objeto JSON codificado. Ele também adiciona a propriedade claims que inclui o payload original do JWT. O objeto JSON tem este formato:

{
  "id": "from-sub",
  "issuer": "from-iss",
  "email": "from-email",
  "audiences": ["from-aud"],
  "claims": {
     original-jwt-payload
   }
}

No ESPv2 Beta, o cabeçalho X-Endpoint-API-UserInfo contém somente o payload codificado com Base64Url do JWT original, sem modificação.

Se o serviço de back-end esperar que o cabeçalho X-Endpoint-API-UserInfo use o formato JSON do ESP, atualize o serviço para gerenciar o novo formato simplificado.

Consulte Como usar um método personalizado para autenticar usuários e Como autenticar entre serviços, para saber mais sobre como usar JWTs com uma autenticação.

Formato de corpo de resposta JSON de erro

Quando uma solicitação HTTP é rejeitada pelo ESP ou ESPv2 Beta, o corpo da resposta contém um código de status e uma mensagem de erro no formato JSON. O formato do corpo da resposta foi alterado no ESPv2 Beta, conforme mostrado nos exemplos abaixo:

Corpo da resposta de erro do ESP

{
 "code": 5,
 "message": "Method does not exist.",
 "details": [
  {
   "@type": "type.googleapis.com/google.rpc.DebugInfo",
   "stackEntries": [],
   "detail": "service_control"
  }
 ]
}

Corpo da resposta de erro do ESPv2 Beta

{
 "code": 400,
 "message": "Method does not exist.",
}

Há duas diferenças principais:

  • No ESPv2 Beta, o campo code contém um código de status HTTP, em vez do código de status RPC encontrado no ESP.
  • O corpo da resposta de erro no ESPv2 Beta não contém um campo details.

A seguir

Saiba mais sobre: