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 é uma substituição do Extensible Service Proxy (ESP) lançado com a versão Beta inicial do Endpoints para Cloud Functions e Cloud Run.

Este documento descreve como migrar uma implantação existente de uma API Endpoints para Cloud Functions ou Cloud Run do ESP para o ESPv2 Beta.

Este documento também descreve dois problemas que você deve considerar antes de migrar as APIs:

Como migrar as APIs do Endpoints para usar o ESPv2 Beta

Para migrar as APIs para o ESPv2 Beta, você só precisa criar sua configuração do serviço de API em uma nova imagem docker do ESPv2 Beta e, em seguida, implantar a imagem. Para migrar as APIs, consulte:

Não é necessário modificar a especificação da API nem modificar o serviço de back-end, a menos que precise solucionar problemas descritos nas Notas da versão ou lidar com os outros problemas de migração descritos abaixo.

Como atualizar a variável usada para especificar opções de inicialização

Para especificar opções de inicialização para ESP, é possível definir a variável de ambiente ESP_ARGS.

Com o ESPv2 Beta, você usa o mesmo mecanismo para definir opções de inicialização, mas a variável de ambiente agora é denominada ESPv2_ARGS. Consulte Opções de inicialização do Extensible Service Proxy V2 Beta para receber mais informações sobre a configuração de ESPv2_ARGS e as opções disponíveis para definir ESPv2_ARGS.

Gerenciar os JWTs no serviço de back-end

Ao usar os JWTs para executar a autenticação, o ESP geralmente encaminha todos os cabeçalhos recebidos. No entanto, o ESP pode modificar o cabeçalho Authorization original quando o endereço de back-end é especificado por x-google-backend, na especificação da OpenAPI, ou BackendRule, na configuração do serviço gRPC. Se uma solicitação tiver o cabeçalho Authorization, o valor dela será copiado para um novo cabeçalho X-Forwarded-Authorization caso o ESP precise substituí-lo.

Ambos os proxies enviam o resultado da autenticação em X-Endpoint-API-UserInfo à API de back-end. É recomendável usar esse cabeçalho em vez do cabeçalho Authorization original. No entanto, o formato do cabeçalho é diferente.

No ESP, o cabeçalho X-Endpoint-API-UserInfo contém um objeto JSON codificado em Base64 que inclui o payload do JWT, assim como outros campos adicionados pelo ESP.

Se estiver disponível no JWT, o ESP adicionará as 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
   }
}

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.

O ESPv2 Beta define o cabeçalho X-Endpoint-API-UserInfo de uma maneira diferente do ESP. Com o ESPv2 Beta, o cabeçalho X-Endpoint-API-UserInfo contém somente o payload codificado com Base64 do JWT original, sem modificação.

Se o serviço de back-end esperar que o cabeçalho X-Endpoint-API-UserInfo use a representação do ESP, atualize o serviço para usar esse novo formato.

A seguir

Saiba mais sobre: