재시도

원문 보기 위키 갱신 2026.10.03

재시도 (Retries)

Linkerd는 실패한 응답을 받았을 때 그 실패를 즉시 클라이언트에게 반환하는 대신 요청을 자동으로 재시도하도록 구성할 수 있어요. 이는 일시적인 실패가 발생하는 상황에서 성공률을 높이는 데 유용한 도구예요.

재시도는 클라이언트 쪽 동작이므로 Linkerd 프록시의 아웃바운드 쪽에서 수행돼요.¹ 멀티 백엔드 HTTPRoute나 GRPCRoute에 재시도가 구성되어 있으면, 요청의 각 재시도는 다른 백엔드로 보내질 수 있어요. 요청 본문이 64KiB보다 크면 재시도되지 않아요.

출처: Linkerd Retries

본문

재시도 구성하기

재시도는 Kubernetes Service 리소스나, Service를 부모로 하는 HTTPRoute나 GRPCRoute에 설정할 수 있는 일련의 어노테이션으로 구성돼요. 그러면 클라이언트 프록시는 해당 Service 또는 라우트에 대한 실패한 요청을 재시도해요. 라우트 리소스에 재시도 구성 어노테이션이 있으면, 부모 Service의 모든 재시도 구성 어노테이션을 재정의해요.

경고

이렇게 구성된 재시도는 ServiceProfiles와 호환되지 않아요. Service에 ServiceProfile이 정의되어 있으면, 프록시는 ServiceProfile 재시도 구성을 사용하고 어떤 재시도 어노테이션도 무시해요.

HTTP 재시도

HTTP 재시도를 구성하려면 Service 또는 HTTPRoute에 retry.linkerd.io/http를 설정하세요. 이 어노테이션은 GRPCRoute 리소스에서는 유효하지 않아요.

retry.linkerd.io/http는 재시도해야 할 HTTP 응답 코드의 쉼표로 구분된 목록이에요. 목록의 각 요소는 다음과 같을 수 있어요:

xxx 단일 응답 코드를 재시도 (예: "504" — 어노테이션 값은 문자열이어야 한다는 점을 기억하세요!)
xxx-yyy 응답 코드 범위를 재시도 (예: 500-504)
gateway-error 응답 코드 502-504를 재시도
5xx 모든 5XX 응답 코드를 재시도

gRPC 재시도

gRPC 재시도를 구성하려면 Service 또는 GRPCRoute에 retry.linkerd.io/grpc를 설정하세요. 이 어노테이션은 HTTPRoute 리소스에서는 유효하지 않아요.

retry.linkerd.io/grpc는 재시도해야 할 gRPC 상태 코드의 쉼표로 구분된 목록이에요. 목록의 각 요소는 다음과 같을 수 있어요:

cancelled
deadline-exceeded
internal
resource-exhausted
unavailable

일반 재시도 구성

이 어노테이션은 Service, HTTPRoute, GRPCRoute 리소스 모두에서 유효해요.

retry.linkerd.io/limit: 요청을 재시도할 수 있는 최대 횟수예요. 지정하지 않으면 기본값은 1이에요.
retry.linkerd.io/timeout: 요청이 취소되고 재시도되는 재시도 타임아웃이에요 (재시도 한도에 아직 도달하지 않은 경우). 지정하지 않으면 재시도 타임아웃이 적용되지 않아요. 이 값에는 단위를 지정해야 해요 — 5s와 200ms는 모두 유효하지만 5는 유효하지 않아요. 자세한 내용은 GEP-2257을 참고하세요.

예시 (Examples)

`kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: schlep-default
  namespace: schlep
  annotations:
    retry.linkerd.io/http: 5xx
    retry.linkerd.io/limit: "2"
    retry.linkerd.io/timeout: 300ms
spec:
  parentRefs:
    - name: schlep
      kind: Service
      group: core
      port: 80
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: "/"
`

`kind: GRPCRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
  name: schlep-default
  namespace: schlep
  annotations:
    retry.linkerd.io/grpc: internal
    retry.linkerd.io/limit: "2"
    retry.linkerd.io/timeout: 400ms
spec:
  parentRefs:
    - name: schlep
      kind: Service
      group: core
      port: 8080
  rules:
    - matches:
        - method:
            type: Exact
            service: schlep.Schlep
            method: Get
`

¹ 파드 안에서 클러스터 나머지로의 연결을 처리하는 프록시 부분이에요. ↩︎

재시도