REST Resource: projects.locations.grpcRoutes

리소스: GrpcRoute

GrpcRoute는 메시 또는 게이트웨이 리소스에서 라우팅한 gRPC 트래픽이 라우팅되는 방식을 정의하는 리소스입니다.

JSON 표현 
{
  "name": string,
  "selfLink": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "description": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
필드
name

string

필수 항목. GrpcRoute 리소스의 이름입니다. projects/*/locations/global/grpcRoutes/<grpc_route_name> 패턴과 일치합니다.
createTime

string (Timestamp format)

출력 전용입니다. 리소스가 생성된 타임스탬프입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
updateTime

string (Timestamp format)

출력 전용입니다. 리소스가 업데이트된 타임스탬프입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
labels

map (key: string, value: string)

선택사항. GrpcRoute 리소스와 연결된 라벨 태그 집합입니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
description

string

선택사항. 리소스에 대한 자유 텍스트 설명입니다. 최대 길이는 1,024자(영문 기준)입니다.
hostnames[]

string

필수 항목. 이 경로에서 트래픽을 설명하는 선택적 포트가 있는 서비스 호스트 이름입니다.

형식: [:]

호스트 이름은 네트워크 호스트의 정규화된 도메인 이름입니다. 이 이름은 호스트 이름의 RFC 1123 정의와 일치하지만 주목할 만한 2가지 예외가 있습니다. - IP는 허용되지 않습니다. - 호스트 이름 앞에 와일드 카드 라벨(*.)이 추가될 수 있습니다. 와일드 카드 라벨은 첫 번째 라벨로 단독으로 표시되어야 합니다.

호스트 이름은 '정확'(네트워크 호스트의 끝점이 없는 도메인 이름(예: foo.example.com))하거나 '와일드 카드'(단일 와일드 카드 라벨로 프리픽스가 지정된 도메인 이름(예: *.example.com))일 수 있습니다.

RFC1035 및 RFC1123에 따라 라벨은 소문자 영숫자 문자 또는 '-'로 구성되어야 하며 영숫자 문자로 시작하고 끝나야 합니다. 다른 구두점은 허용되지 않습니다.

메시 또는 게이트웨이와 연결된 경로에는 고유한 호스트 이름이 있어야 합니다. 호스트 이름이 충돌하는 여러 경로를 연결하려고 하면 구성이 거부됩니다.

예를 들어 호스트 이름 *.foo.bar.com 및 *.bar.com의 경로를 같은 경로에 연결할 수 있지만 두 경로 모두 *.bar.com 또는 bar.com에 연결할 수 없습니다.

포트가 지정된 경우 gRPC 클라이언트는 포트가 있는 채널 URI를 사용하여 이 규칙을 일치시켜야 합니다(예: 'xds:///service:123'). 그러지 않으면 포트가 없는 URI를 제공해야 합니다(예: 'xds:///service').
meshes[]

string

선택사항. 메시는 이 GrpcRoute가 연결된 메시 목록을 메시에서 제공하는 요청을 라우팅하는 라우팅 규칙 중 하나로 정의합니다.

각 메시 참조는 projects/*/locations/global/meshes/<mesh_name> 패턴과 일치해야 합니다.
gateways[]

string

선택사항. 게이트웨이는 이 GrpcRoute가 연결된 게이트웨이 목록을 게이트웨이에서 제공하는 요청을 라우팅하는 라우팅 규칙 중 하나로 정의합니다.

각 게이트웨이 참조는 projects/*/locations/global/gateways/<gateway_name> 패턴과 일치해야 합니다.
rules[]

object (RouteRule)

필수 항목. 트래픽을 라우팅하는 방법을 정의하는 세부 규칙 목록입니다.

단일 GrpcRoute 내에서 일치하는 첫 번째 GrpcRoute.RouteRule과 연결된 GrpcRoute.RouteAction이 실행됩니다. 규칙을 1개 이상 선택해야 합니다.

RouteRule

트래픽을 라우팅하는 방법을 설명합니다.

JSON 표현 
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
필드
matches[]

object (RouteMatch)

선택사항. 일치는 들어오는 gRPC 요청과 규칙을 일치시키는 데 사용되는 조건을 정의합니다. 각 일치는 독립적입니다. 즉, 일치 중 하나라도 충족되면 이 규칙이 일치합니다. 일치 필드가 지정되지 않으면 이 규칙은 무조건 트래픽과 일치합니다.
action

object (RouteAction)

필수 항목. 트래픽을 라우팅하는 방법을 정의하는 세부 규칙입니다. 필수 필드입니다.

RouteMatch

트래픽 일치 기준입니다. 제공된 모든 필드가 일치하면 RouteMatch가 일치하는 것으로 간주됩니다.

JSON 표현 
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "method": {
    object (MethodMatch)
  }
}
필드
headers[]

object (HeaderMatch)

선택사항. 일치시킬 헤더 모음을 지정합니다.
method

object (MethodMatch)

선택사항. 일치시킬 gRPC 메서드입니다. 이 필드가 비어 있거나 생략되면 모든 메서드와 일치합니다.

MethodMatch

메서드와의 일치를 지정합니다.

JSON 표현 
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,
  "caseSensitive": boolean
}
필드
type

enum (Type)

선택사항. 이름과 일치시킬 방법을 지정합니다. 지정하지 않으면 기본값인 'EXACT'가 사용됩니다.
grpcService

string

필수 항목. 일치시킬 서비스의 이름입니다. 지정하지 않으면 모든 서비스를 일치시킵니다.
grpcMethod

string

필수 항목. 일치시킬 메서드의 이름입니다. 지정하지 않으면 모든 메서드를 일치시킵니다.
caseSensitive

boolean

선택사항. 일치에서 대소문자를 구분하도록 지정합니다. 기본값은 true입니다. caseSensitive를 REGULAR_EXPRESSION 유형과 함께 사용하면 안 됩니다.

유형

일치 유형입니다.

열거형
TYPE_UNSPECIFIED 지정되지 않음.
EXACT 제공된 정확한 이름과만 일치합니다.
REGULAR_EXPRESSION grpcMethod 및 grpcService를 정규식으로 해석합니다. RE2 구문이 지원됩니다.

HeaderMatch

헤더 모음과의 일치입니다.

JSON 표현 
{
  "type": enum (Type),
  "key": string,
  "value": string
}
필드
type

enum (Type)

선택사항. 헤더 값과 일치시키는 방법을 지정합니다. 지정하지 않으면 기본값인 EXACT가 사용됩니다.
key

string

필수 항목. 헤더 키입니다.
value

string

필수 항목. 헤더 값입니다.

유형

일치 유형입니다.

열거형
TYPE_UNSPECIFIED 지정되지 않음.
EXACT 제공된 정확한 값과만 일치합니다.
REGULAR_EXPRESSION 값으로 지정된 프리픽스에 따라 경로를 일치시킵니다. RE2 구문이 지원됩니다.

RouteAction

일치하는 트래픽을 라우팅하는 방법을 지정합니다.

JSON 표현 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "idleTimeout": string
}
필드
destinations[]

object (Destination)

선택사항. 트래픽을 전달해야 하는 대상 서비스입니다. 대상이 여러 개 지정된 경우 트래픽은 이러한 대상의 가중치 필드에 따라 백엔드 서비스 사이에서 분할됩니다.
faultInjectionPolicy

object (FaultInjectionPolicy)

선택사항. 대상 서비스 장애에 대한 클라이언트의 복원력을 테스트하기 위해 트래픽에 도입된 결함 주입 사양입니다. 결함 주입의 일환으로 클라이언트가 요청을 대상에 전송할 때 요청을 대상 서비스로 전송하기 전에 요청 일부에서 지연이 발생할 수 있습니다. 마찬가지로 클라이언트의 요청 중 일정 비율이 중단될 수 있습니다.

faultInjectionPolicy로 구성된 클라이언트는 timeout 및 retryPolicy를 무시합니다.
timeout

string (Duration format)

선택사항. 선택한 경로의 제한 시간을 지정합니다. 제한 시간은 요청이 완전히 처리된 시간(즉, 스트림 종료)부터 응답이 완전히 처리될 때까지 계산됩니다. 제한 시간에는 모든 재시도 횟수가 포함됩니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
retryPolicy

object (RetryPolicy)

선택사항. 이 경로와 연결된 재시도 정책을 지정합니다.
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

선택사항. 쿠키 기반 스테이트풀(Stateful) 세션 어피니티를 지정합니다.
idleTimeout

string (Duration format)

선택사항. 선택한 경로의 유휴 제한 시간을 지정합니다. 유휴 시간 제한은 업스트림 또는 다운스트림 연결에서 전송되거나 수신되는 바이트가 없는 기간으로 정의됩니다. 설정하지 않으면 기본 유휴 시간 제한은 1시간입니다. 0으로 설정하면 제한 시간이 사용 중지됩니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

대상

트래픽이 라우팅될 대상입니다.

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
}
필드
통합 필드 destination_type. 트래픽을 라우팅할 대상의 종류를 지정합니다. destination_type은 다음 중 하나여야 합니다.
serviceName

string

필수 항목. 트래픽을 라우팅할 대상 서비스의 URL입니다. BackendService 또는 ServiceDirectoryService를 참조해야 합니다.
weight

integer

선택사항. serviceName 필드에서 참조하는 백엔드로 전달되는 요청의 비율을 지정합니다. 이 값은 - 가중치/합계(이 대상 목록의 가중치)로 계산됩니다. 0이 아닌 값의 경우 구현에서 지원하는 정밀도에 따라 여기에 정의된 정확한 비율에서 약간의 엡실론이 있을 수 있습니다.

serviceName이 하나만 지정되고 가중치가 0보다 큰 경우 트래픽의 100%가 해당 백엔드로 전달됩니다.

하나의 서비스 이름에 가중치를 지정하는 경우 모든 서비스 이름에 가중치를 지정해야 합니다.

모든 서비스에 가중치가 지정되지 않은 경우 트래픽이 모든 서비스에 동일한 비율로 분산됩니다.

FaultInjectionPolicy

대상 서비스 장애에 대한 클라이언트의 복원력을 테스트하기 위해 트래픽에 도입된 결함 주입 사양입니다. 결함 주입의 일환으로 클라이언트가 요청을 대상에 전송할 때 요청을 대상 서비스로 전송하기 전에 요청 일부에서 지연이 발생할 수 있습니다. 마찬가지로 클라이언트의 요청 중 일정 비율이 중단될 수 있습니다.

JSON 표현 
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
필드
delay

object (Delay)

클라이언트 요청에 지연을 삽입하기 위한 사양입니다.
abort

object (Abort)

클라이언트 요청을 중단하기 위한 사양입니다.

지연

대상에 전송되기 전에 결함 주입의 일환으로 클라이언트 요청이 지연되는 방식을 지정합니다.

JSON 표현 
{
  "fixedDelay": string,
  "percentage": integer
}
필드
fixedDelay

string (Duration format)

요청을 전달하기 전에 고정 지연 시간을 지정합니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
percentage

integer

지연이 주입될 트래픽의 비율입니다.

값은 0~100 사이여야 합니다.

취소

대상에 전송되기 전에 결함 주입의 일환으로 클라이언트 요청이 중단되는 방식을 지정합니다.

JSON 표현 
{
  "httpStatus": integer,
  "percentage": integer
}
필드
httpStatus

integer

요청을 중단하는 데 사용되는 HTTP 상태 코드입니다.

값은 200~599(포함) 사이여야 합니다.
percentage

integer

중단될 트래픽의 비율입니다.

값은 0~100 사이여야 합니다.

RetryPolicy

재시도 사양입니다.

JSON 표현 
{
  "retryConditions": [
    string
  ],
  "numRetries": integer
}
필드
retryConditions[]

string

  • connect-failure: 연결 제한 시간 등으로 인해 백엔드 서비스 연결에 실패할 경우 라우터에서 재시도합니다.
  • refused-stream: 백엔드 서비스에서 REFUSED_STREAM 오류 코드로 스트림을 재설정하면 라우터에서 재시도합니다. 이 재설정 유형은 재시도해도 안전함을 나타냅니다.
  • cancelled: 응답 헤더의 gRPC 상태 코드가 cancelled로 설정된 경우 라우터에서 재시도합니다.
  • deadline-exceeded: 응답 헤더의 gRPC 상태 코드가 deadline-exceeded로 설정된 경우 라우터에서 재시도합니다.
  • resource-exhausted: 응답 헤더의 gRPC 상태 코드가 resource-exhausted로 설정된 경우 라우터에서 재시도합니다.
  • unavailable: 응답 헤더의 gRPC 상태 코드가 unavailable로 설정된 경우 라우터에서 재시도합니다.
numRetries

integer (uint32 format)

허용되는 재시도 횟수를 지정합니다. 이 숫자는 0보다 커야 합니다. 지정하지 않으면 기본값은 1입니다.

StatefulSessionAffinityPolicy

데이터 영역에서 특정 대상 호스트를 인코딩하는 'GSSA'라는 이름의 '세션 쿠키'를 제공하고 대상 호스트가 정상적으로 작동하는 한 이 쿠키가 포함된 각 요청이 해당 호스트로 전달되는 쿠키 기반 스테이트풀(Stateful) 세션 어피니티의 사양입니다.

gRPC 프록시리스 메시 라이브러리 또는 사이드카 프록시가 세션 쿠키를 관리하지만 클라이언트 애플리케이션 코드는 세션의 각 RPC에서 다음 RPC로 쿠키를 복사하는 역할을 담당합니다.

JSON 표현 
{
  "cookieTtl": string
}
필드
cookieTtl

string (Duration format)

필수 항목. 데이터 영역에서 생성된 Set-Cookie 헤더의 쿠키 TTL 값입니다. 쿠키의 수명은 1~86,400초(24시간 포함) 사이의 값으로 설정할 수 있습니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

메서드

create

 특정 프로젝트와 위치에 새 GrpcRoute를 만듭니다.

delete

 단일 GrpcRoute를 삭제합니다.

get

 단일 GrpcRoute의 세부정보를 가져옵니다.

list

 특정 프로젝트와 위치의 GrpcRoutes를 나열합니다.

patch

 단일 GrpcRoute의 파라미터를 업데이트합니다.

setIamPolicy

 지정된 리소스의 액세스 제어 정책을 설정합니다.

testIamPermissions

 지정된 리소스에 대해 호출자가 보유한 권한을 반환합니다.