Visão geral das frases de destaque

As extensões de serviço permitem fazer uma frase de destaque de proxies de rede. As extensões de frase de destaque são compatíveis com a maioria dos balanceadores de carga de aplicativo. Elas também são compatíveis com Secure Web Proxy (em pré-lançamento).

Fluxo de dados de frases de destaque

Um proxy de rede se comunica com uma frase de destaque usando um dos seguintes protocolos gRPC do Envoy:

  • O protocolo de processamento externo ou ext_proc.

    Esse protocolo é compatível com extensões de rota, tráfego e autorização e é usado por padrão.

    O protocolo ext_proc permite que o serviço de extensão responda a eventos no ciclo de vida de uma solicitação HTTP examinando e modificando os cabeçalhos ou o corpo da solicitação.

  • O protocolo de autorização externa ou ext_authz.

    Esse protocolo é compatível apenas com extensões de autorização. O suporte para ext_authz está em pré-lançamento.

    O protocolo ext_authz delega decisões de autorização para solicitações recebidas a um serviço externo e independente. Essa API permite que o serviço de extensão responda a eventos no ciclo de vida de uma solicitação HTTP para uma decisão de autorização complexa, examinando os cabeçalhos ou metadados da solicitação.

    É possível especificar esse protocolo com a opção wireFormat ao configurar uma extensão de autorização.

É possível implantar esses serviços de extensão em instâncias de máquina virtual (VM) ou no GKE e configurar um grupo de instâncias ou um grupo de endpoints de rede (NEG) para representar os endpoints desses serviços.

Exemplo de cenário de implantação

O diagrama a seguir mostra um exemplo de cenário de implantação. É possível implantar o serviço de back-end de frase de destaque com um servidor gRPC em um recurso de computação gerenciado pelo usuário, como uma instância de VM ou um cluster do Google Kubernetes Engine (GKE), e representá-lo para o balanceador de carga como um serviço de back-end normal.

Os balanceadores de carga de aplicativo usam callouts para incluir lógica personalizada de serviços de back-end de callout.
Os balanceadores de carga de aplicativo enviam chamadas de Service Extensions para serviços de back-end de chamada (clique para ampliar).

Como as frases de destaque funcionam com ext_proc

Confira a seguir uma versão abreviada da API gRPC ext_proc.

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

Depois de receber os cabeçalhos de uma solicitação HTTP, os proxies do balanceador de carga de aplicativo e do Secure Web Proxy enviam a mensagem ProcessingRequest para o serviço de extensão com o campo request_headers definido como os cabeçalhos HTTP do cliente.

O serviço de extensão precisa responder à mensagem ProcessingRequest com uma mensagem ProcessingResponse correspondente que contenha todas as mudanças configuradas nos cabeçalhos ou no corpo da mensagem ProcessingRequest. Como alternativa, o serviço pode definir o campo immediate_response para fazer com que o proxy de rede encerre o processamento da solicitação e envie a resposta especificada de volta ao cliente.

Para eventos REQUEST_HEADER e RESPONSE_HEADER, o serviço de extensão pode manipular os cabeçalhos HTTP na solicitação ou resposta. O serviço pode adicionar, modificar ou excluir cabeçalhos definindo o campo request_headers ou response_headers na mensagem ProcessingResponse de maneira adequada. Use o campo raw_value para cabeçalhos.

As extensões de tráfego permitem mudar os cabeçalhos e o corpo das solicitações e respostas. O servidor de extensão pode substituir o modo de processamento de forma dinâmica e permitir que ele ative ou desative a extensão para as fases subsequentes do processamento de solicitações. Os balanceadores de carga não reavaliam as regras de rota depois de chamar uma extensão de tráfego.

As extensões de borda, autorização e rota oferecem suporte apenas a cabeçalhos HTTP. Essas extensões não podem inspecionar ou alterar corpos HTTP.

Para extensões de rota e tráfego, as frases de destaque podem ser executadas de forma assíncrona quando observabilityMode para a extensão é definido como true e o modo de processamento do corpo é STREAMED (padrão). As chamadas para o back-end de extensão são realizadas de forma assíncrona, sem pausar o processamento da solicitação em andamento. As respostas, se houver, são ignoradas.

Como as frases de destaque funcionam com ext_authz

A API ext_authz oferece suporte apenas a extensões de frase de destaque de autorização.

Confira a seguir uma versão abreviada da API.

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

Depois de receber os cabeçalhos de uma solicitação HTTP, o balanceador de carga envia a mensagem CheckRequest para o serviço de extensão.

O serviço de extensão precisa responder à mensagem CheckRequest com uma mensagem CheckResponse correspondente que contenha as seguintes informações:

  • status: indica o status. OK indica que a solicitação é permitida. Qualquer outro status indica que a solicitação foi negada.

  • denied_response ou ok_response: indica se a resposta é permitida ou negada. Esse campo é acompanhado pelos atributos de resposta HTTP relacionados para uma verificação de autorização.

    • O campo ok_response é usado quando o serviço de autorização permite a solicitação. O serviço pode modificar, adicionar ou remover qualquer cabeçalho de solicitação original e atualizar os cabeçalhos de resposta HTTP enviados ao cliente. Use o campo raw_value para cabeçalhos.

    • O campo denied_response é usado quando o serviço de autorização nega a solicitação. O serviço pode atualizar os cabeçalhos de resposta HTTP enviados ao cliente.

    Se o serviço de extensão retornar um nome ou valor de cabeçalho não permitido pela mensagem CheckResponse, a solicitação será rejeitada com o código de status 500 Internal Error. Para informações sobre cabeçalhos não permitidos, consulte Limitações com a manipulação de cabeçalhos.

  • dynamic_metadata: inclui metadados opcionais para uso por extensões chamadas após a extensão de autorização, como extensões de tráfego.

Modos de processamento do corpo

Para extensões que oferecem suporte ao processamento do corpo, é possível configurar um dos dois modos de envio a seguir para o processamento do corpo da solicitação e da resposta, definindo o valor dos campos request_body_send_mode ou response_body_send_mode, respectivamente.

O modo padrão é STREAMED, recomendado para a maioria dos casos de uso.

Modo Descrição Eventos aceitos necessários Extensões aceitas
STREAMED

As chamadas são executadas no modo de streaming. Essa configuração padrão também é usada se o modo não estiver definido.

O proxy envia blocos de corpo para o serviço de extensão e espera uma única resposta por bloco. A extensão pode enviar blocos modificados de volta, reconhecer blocos sem alterações ou excluir blocos.

O proxy envia apenas uma quantidade limitada de dados por vez. Portanto, o serviço de extensão precisa reconhecer os blocos o mais rápido possível.

Embora o modo de corpo não possa ser alterado dinamicamente, um servidor de extensão avançado pode selecionar dinamicamente os eventos HTTP futuros a serem recebidos. Ao retornar a opção ext_proc mode_override durante uma solicitação de cabeçalhos, um servidor de frase de destaque pode ativar ou desativar cabeçalhos, corpo ou eventos de trailers futuros.

 Precisa incluir REQUEST_BODY para solicitações ou RESPONSE_BODY para respostas. Extensões de tráfego (para solicitações e respostas).
FULL_DUPLEX_STREAMED

As chamadas são executadas no modo full duplex.

O proxy envia blocos à medida que chegam e não os armazena em buffer. Como não há buffer, o proxy é menos sensível à latência de extensão.

O proxy pode receber quantos blocos de resposta forem necessários. Os blocos de resposta são desconectados dos blocos enviados pelo proxy. Os blocos subsequentes são enviados para processamento à medida que chegam ao proxy, sem esperar que os blocos e eventos anteriores sejam totalmente processados.

A extensão pode armazenar em buffer, modificar e reagrupar livremente o conteúdo do corpo. Se a extensão não enviar o conteúdo do corpo de volta, a próxima extensão na cadeia vai receber um corpo vazio.

A opção ext_proc mode_override não é aplicável, e o modo não pode ser alterado dinamicamente.

 Precisa incluir REQUEST_BODY e REQUEST_TRAILERS para solicitações ou RESPONSE_BODY e RESPONSE_TRAILERS para respostas. Extensões de tráfego (para solicitações e respostas).

Extensões de rota (para solicitações).

Back-ends aceitos para serviços de back-end de frase de destaque gerenciados pelo usuário

É possível hospedar extensões de frase de destaque gerenciadas pelo usuário em um serviço de back-end que usa um dos seguintes tipos de back-ends que executam serviços gRPC do Envoy:

Otimizações recomendadas para frases de destaque

A integração de uma extensão ao caminho de processamento gera latência adicional para solicitações e respostas. Cada tipo de dado processado pelo serviço de extensão, incluindo cabeçalhos de solicitação, corpo da solicitação, cabeçalhos de resposta e corpo da resposta, conforme aplicável, adiciona latência.

Considere as seguintes otimizações para minimizar a latência:

  • Implante frases de destaque nas mesmas zonas que o serviço de back-end de destino normal para o proxy.

    Ao usar um balanceador de carga de aplicativo interno entre regiões, coloque os back-ends do serviço de extensão na mesma região que as sub-redes somente proxy do balanceador de carga.

  • Ao usar um balanceador de carga de aplicativo externo global, coloque os back-ends do serviço de frase de destaque nas regiões geográficas em que as VMs de destino, as cargas de trabalho do GKE e as funções do Cloud Run do balanceador de carga normal estão localizadas.

  • Quando possível, configure a extensão para processar apenas os dados necessários. Por exemplo, para modificar apenas os cabeçalhos de solicitação para extensões de rota e tráfego, defina o campo supported_events na extensão como REQUEST_HEADERS.

Limitações das frases de destaque

Esta seção lista algumas limitações das frases de destaque.

Limitações com a manipulação de cabeçalhos

Não é possível mudar alguns cabeçalhos. Confira a seguir as limitações da manipulação de cabeçalhos:

  • A manipulação de cabeçalhos não é aceita para os seguintes cabeçalhos:

    • X-user-IP
    • CDN-Loop
    • Cabeçalhos que começam com X-Forwarded, X-Google, X-GFE ou X-Amz-
    • connection
    • keep-alive
    • transfer-encoding, te
    • upgrade
    • proxy-connection, proxy-authenticate, proxy-authorization
    • trailers

    Para extensões de tráfego e autorização, a manipulação de cabeçalhos também não é aceita para estes: :method, :authority, :scheme ou cabeçalhos de host.

  • Quando um servidor gRPC especifica valores de cabeçalho em HeaderMutation, o campo value é ignorado.

Limitações com o processamento do corpo

Confira a seguir as limitações com clientes e back-ends HTTP/1.1 em relação ao corpo da mensagem, que é aplicável a ext_proc, mas não a ext_authz.

  • Ao configurar REQUEST_BODY ou RESPONSE_BODY para uma extensão, se o proxy receber uma solicitação correspondente, ele vai remover o cabeçalho Content-Length da resposta e mudar para a codificação de corpo em blocos.

  • Ao transmitir um corpo da mensagem para o servidor ext_proc, no final, o proxy poderá enviar uma mensagem ProcessingRequest de cauda com um corpo vazio com end_stream definido como true para indicar que o fluxo terminou.

Outras limitações

Confira a seguir as limitações com mensagens de resposta gRPC:

  • O tamanho máximo de uma mensagem de resposta é de 128 KB. Se uma mensagem recebida estiver acima desse limite, o fluxo será fechado com um erro RESOURCE_EXHAUSTED.

  • O serviço de back-end de frase de destaque não pode usar políticas do Cloud Armor, do IAP ou do Cloud CDN.

  • O serviço de back-end de frase de destaque precisa usar HTTP/2 como protocolo.

  • Para extensões de autorização, o balanceador de carga não encaminha nenhum corpo de solicitação para o serviço de back-end de frase de destaque.

  • Para extensões de rota, o serviço de back-end de frase de destaque não pode substituir o modo de processamento do fluxo ext_proc.

A seguir