REST Resource: projects.locations.grpcRoutes

Recurso: GrpcRoute

O GrpcRoute é o recurso que define como o tráfego gRPC roteado por um recurso Mesh ou Gateway é roteado.

Representação JSON
{
  "name": string,
  "selfLink": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "description": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
Campos
name

string

Obrigatório. Nome do recurso GrpcRoute. Corresponde ao padrão projects/*/locations/global/grpcRoutes/<grpc_route_name>

createTime

string (Timestamp format)

Apenas saída. O carimbo de data/hora em que o recurso foi criado.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Apenas saída. O carimbo de data/hora em que o recurso foi atualizado.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

labels

map (key: string, value: string)

Opcional. Conjunto de tags de rótulo associadas ao recurso GrpcRoute.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

description

string

Opcional. Uma descrição em texto livre do recurso. Comprimento máximo de 1.024 caracteres.

hostnames[]

string

Obrigatório. Nomes de host de serviço com uma porta opcional para a qual esta rota descreve o tráfego.

Formato: [:]

O nome do host é o nome de domínio totalmente qualificado de um host de rede. Isso corresponde à definição RFC 1123 de um nome de host com duas exceções importantes: - IPs não são permitidos. - Um nome do host pode ser prefixado com um rótulo de caractere curinga (*.). O rótulo de caractere curinga precisa aparecer sozinho como o primeiro rótulo.

O nome do host pode ser "preciso" que é um nome de domínio sem o ponto final de um host de rede (por exemplo, foo.example.com) ou "caractere curinga", que é um nome de domínio prefixado com um único rótulo de caractere curinga (por exemplo, *.example.com).

De acordo com o RFC1035 e o RFC1123, um identificador precisa consistir de caracteres alfanuméricos minúsculos ou "-", além de começar e terminar com um caractere alfanumérico. Não é permitida nenhuma outra pontuação.

As rotas associadas a uma rede mesh ou gateway precisam ter nomes de host exclusivos. Se você tentar anexar várias rotas com nomes de host conflitantes, a configuração será rejeitada.

Por exemplo, embora seja aceitável que as rotas dos nomes de host *.foo.bar.com e *.bar.com sejam associadas à mesma rota, não é possível associar duas rotas a *.bar.com ou ambas a bar.com.

Se uma porta for especificada, os clientes gRPC precisarão usar o URI do canal com a porta para corresponder a essa regra (por exemplo, "xds:///service:123"). Caso contrário, eles precisarão fornecer o URI sem uma porta (ou seja, "xds:///service").

meshes[]

string

Opcional. As malhas definem uma lista de malhas a que essa GrpcRoute está anexada, como uma das regras de roteamento para rotear as solicitações atendidas pela malha.

Cada referência de malha precisa corresponder ao padrão: projects/*/locations/global/meshes/<mesh_name>

gateways[]

string

Opcional. "Gateways" define uma lista de gateways a que este GrpcRoute está anexado, como uma das regras de roteamento para rotear as solicitações atendidas pelo gateway.

Cada referência de gateway precisa corresponder ao padrão: projects/*/locations/global/gateways/<gateway_name>

rules[]

object (RouteRule)

Obrigatório. Uma lista de regras detalhadas que definem como rotear o tráfego.

Em uma única GrpcRoute, a GrpcRoute.RouteAction associada à primeira GrpcRoute.RouteRule correspondente será executada. É necessário fornecer pelo menos uma regra.

RouteRule

Descreve como rotear o tráfego.

Representação JSON
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
Campos
matches[]

object (RouteMatch)

Opcional. As correspondências definem as condições usadas para corresponder a regra às solicitações gRPC recebidas. Cada correspondência é independente. Ou seja, essa regra será atendida se QUALQUER uma das correspondências for atendida. Se nenhum campo de correspondência for especificado, a regra corresponderá ao tráfego incondicionalmente.

action

object (RouteAction)

Obrigatório. Uma regra detalhada que define como rotear o tráfego. Este campo é obrigatório.

RouteMatch

Critérios para o tráfego correspondente. Um RouteMatch será considerado correspondente quando todos os campos fornecidos corresponderem.

Representação JSON
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "method": {
    object (MethodMatch)
  }
}
Campos
headers[]

object (HeaderMatch)

Opcional. Especifica uma coleção de cabeçalhos para correspondência.

method

object (MethodMatch)

Opcional. Um método gRPC para correspondência. Se esse campo estiver vazio ou omitido, vai corresponder a todos os métodos.

MethodMatch

Especifica uma correspondência com um método.

Representação JSON
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,
  "caseSensitive": boolean
}
Campos
type

enum (Type)

Opcional. Especifica como fazer a correspondência com o nome. Se não for especificado, um valor padrão de "EXACT" será usado.

grpcService

string

Obrigatório. Nome do serviço para correspondência. Se não for especificado, corresponderá a todos os serviços.

grpcMethod

string

Obrigatório. Nome do método de correspondência. Se não for especificado, corresponderá a todos os métodos.

caseSensitive

boolean

Opcional. Especifica que as correspondências diferenciam maiúsculas de minúsculas. O valor padrão é verdadeiro. caseSensitive não pode ser usado com o tipo REGULAR_EXPRESSION.

Tipo

O tipo de correspondência.

Enums
TYPE_UNSPECIFIED Não especificado.
EXACT Só vai corresponder ao nome exato fornecido.
REGULAR_EXPRESSION Interpretará grpcMethod e grpcService como regexes. A sintaxe RE2 é suportada.

HeaderMatch

Uma correspondência com uma coleção de cabeçalhos.

Representação JSON
{
  "type": enum (Type),
  "key": string,
  "value": string
}
Campos
type

enum (Type)

Opcional. Especifica como fazer a correspondência com o valor do cabeçalho. Se não for especificado, será usado um valor padrão EXACT.

key

string

Obrigatório. A chave do cabeçalho.

value

string

Obrigatório. O valor do cabeçalho.

Tipo

O tipo de correspondência.

Enums
TYPE_UNSPECIFIED Não especificado.
EXACT Corresponderá apenas ao valor exato fornecido.
REGULAR_EXPRESSION Corresponderá aos caminhos de acordo com o prefixo especificado pelo valor. A sintaxe RE2 é compatível.

RouteAction

Especifica como rotear o tráfego correspondente.

Representação JSON
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "idleTimeout": string
}
Campos
destinations[]

object (Destination)

Opcional. Os serviços de destino para os quais o tráfego precisa ser encaminhado. Se vários destinos forem especificados, o tráfego será dividido entre os serviços de back-end de acordo com o campo de peso desses destinos.

faultInjectionPolicy

object (FaultInjectionPolicy)

Opcional. A especificação para injeção de falhas introduzida no tráfego para testar a resiliência dos clientes à falha do serviço de destino. Como parte da injeção de falhas, quando os clientes enviam solicitações para um destino, é possível introduzir atrasos em uma porcentagem de solicitações antes de enviar essas solicitações para o serviço de destino. Da mesma forma, as solicitações de clientes podem ser abortadas por uma porcentagem de solicitações.

O tempo limite e a retryPolicy serão ignorados por clientes configurados com uma faultInjectionPolicy.

timeout

string (Duration format)

Opcional. Especifica o tempo limite da rota selecionada. O tempo limite é calculado a partir do momento em que a solicitação é totalmente processada (ou seja, o fim da transmissão) até que a resposta seja totalmente processada. O tempo limite inclui todas as novas tentativas.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

retryPolicy

object (RetryPolicy)

Opcional. Especifica a política de nova tentativa associada a essa rota.

statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

Opcional. Especifica a afinidade de sessão com estado baseada em cookies.

idleTimeout

string (Duration format)

Opcional. Especifica o tempo limite de inatividade da rota selecionada. O tempo limite de inatividade é definido como o período em que não há bytes enviados ou recebidos na conexão upstream ou downstream. Se não for definido, o tempo limite de inatividade padrão será de uma hora. Se definido como 0s, o tempo limite será desativado.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

Destino

O destino para onde o tráfego será roteado.

Representação JSON
{

  // Union field destination_type can be only one of the following:
  "serviceName": string
  // End of list of possible types for union field destination_type.
  "weight": integer
}
Campos
Campo de união destination_type. Especifica o tipo de destino para onde o tráfego será roteado. destination_type pode ser apenas de um dos tipos a seguir:
serviceName

string

Obrigatório. O URL de um serviço de destino para o qual rotear tráfego. Precisa se referir a um BackendService ou ServiceDirectoryService.

weight

integer

Opcional. Especifica a proporção de solicitações encaminhadas ao back-end referenciado pelo campo serviceName. Isso é calculado como: - peso/soma(pesos na lista de destinos). Para valores diferentes de zero, pode haver um valor epsilon da proporção exata definida aqui, dependendo da precisão com que uma implementação é compatível.

Se apenas um serviceName for especificado e tiver um peso maior que 0, 100% do tráfego será encaminhado para esse back-end.

Se os pesos for especificados para um nome de serviço, eles precisarão ser especificados para todos.

Se os pesos não forem especificados para todos os serviços, o tráfego será distribuído em proporções iguais a todos eles.

FaultInjectionPolicy

A especificação para injeção de falhas introduzida no tráfego para testar a resiliência dos clientes à falha do serviço de destino. Como parte da injeção de falhas, quando os clientes enviam solicitações para um destino, é possível introduzir atrasos em uma porcentagem de solicitações antes de enviar essas solicitações para o serviço de destino. Da mesma forma, as solicitações de clientes podem ser canceladas por uma porcentagem das solicitações.

Representação JSON
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
Campos
delay

object (Delay)

A especificação para injetar atraso nas solicitações do cliente.

abort

object (Abort)

A especificação para cancelamento de solicitações do cliente.

Atraso

Especificação de como as solicitações do cliente são atrasadas como parte da injeção de falhas antes de serem enviadas a um destino.

Representação JSON
{
  "fixedDelay": string,
  "percentage": integer
}
Campos
fixedDelay

string (Duration format)

Especifique um atraso fixo antes de encaminhar a solicitação.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

percentage

integer

A porcentagem de tráfego em que o atraso será injetado.

O valor precisa estar entre [0, 100]

Cancelar

Especificação de como as solicitações do cliente são canceladas como parte da injeção de falhas antes de serem enviadas a um destino.

Representação JSON
{
  "httpStatus": integer,
  "percentage": integer
}
Campos
httpStatus

integer

O código de status HTTP usado para abortar a solicitação.

O valor precisa estar entre 200 e 599.

percentage

integer

A porcentagem de tráfego que será cancelada.

O valor precisa estar entre [0, 100]

RetryPolicy

As especificações para novas tentativas.

Representação JSON
{
  "retryConditions": [
    string
  ],
  "numRetries": integer
}
Campos
retryConditions[]

string

  • connect-failure: o roteador vai tentar novamente em falhas de conexão com os serviços de back-end, por exemplo, devido a tempos limite de conexão.
  • refused-stream: o roteador vai tentar novamente se o serviço de back-end redefinir o stream com um código de erro REFUSED_STREAM. Esse tipo de redefinição indica que é seguro tentar novamente.
  • cancelado: o roteador tentará novamente se o código de status gRPC no cabeçalho da resposta estiver definido como cancelado
  • deadline-exceeded: o roteador vai tentar novamente se o código de status do gRPC no cabeçalho de resposta estiver definido como deadline-exceeded.
  • resource-exhausted: o roteador tenta fazer uma nova tentativa se o código de status gRPC no cabeçalho da resposta está definido como "resource-exhausted"
  • indisponível: o roteador vai tentar novamente se o código de status do gRPC no cabeçalho de resposta estiver definido como "indisponível".
numRetries

integer (uint32 format)

Especifica o número permitido de novas tentativas. Esse número precisa ser maior que 0. Se não for especificado, o padrão será 1.

StatefulSessionAffinityPolicy

A especificação para afinidade de sessão stateful baseada em cookies, em que o plano de dados fornece um "cookie de sessão" com o nome "GSSA", que codifica um host de destino específico, e cada solicitação que contém esse cookie é direcionada a esse host enquanto ele permanecer ativo e saudável.

A biblioteca de malha sem proxy do gRPC ou o proxy sidecar vai gerenciar o cookie de sessão, mas o código do aplicativo cliente é responsável por copiar o cookie de cada RPC na sessão para a próxima.

Representação JSON
{
  "cookieTtl": string
}
Campos
cookieTtl

string (Duration format)

Obrigatório. O valor de TTL do cookie para o cabeçalho Set-Cookie gerado pelo plano de dados. A vida útil do cookie pode ser definida como um valor de 1 a 86.400 segundos (24 horas).

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

Métodos

create

Cria um novo GrpcRoute em um determinado projeto e local.

delete

Exclui um único GrpcRoute.

get

Recebe detalhes de uma única GrpcRoute.

getIamPolicy

Busca a política de controle de acesso de um recurso.

list

Lista GrpcRoutes em um determinado projeto e local.

patch

Atualiza os parâmetros de uma única GrpcRoute.

setIamPolicy

Define a política de controle de acesso no recurso especificado.

testIamPermissions

Retorna permissões do autor da chamada no recurso especificado.