쿠버네티스 환경에서 gRPC Stream 60초 Timeout 문제 해결하기

쿠버네티스 환경에서 gRPC Stream 60초 Timeout 문제 해결하기

 

쿠버네티스 환경에서 배포된 gRPC 통신을 하고있는데

CancellationToken 으로 Timeout 을 60초 넘게 주었음에도 60초가 넘어가면 무조건 Timeout 이 발생되었습니다.

알고 보니 이 문제는 Ingress Nginx 기본 설정 때문에 발생하는 것이었습니다.

 

원인

Ingress Nginx는 gRPC 통신을 지원하지만,

기본적으로 grpc_read_timeout과 같은 값들이 60초 정도로 제한되어 있습니다.

따라서 gRPC Stream처럼 장시간 연결을 유지해야 하는 경우에는 이 설정이 반드시 필요합니다.

공식 문서에서도 gRPC 지원을 위해 Nginx에서 적절한 timeout 설정을 해줄 것을 권장하고 있습니다.

 

해결방법

ingress-nginx 컨트롤러에 아래와 같이 grpc_read_timeout,  grpc_send_timeout, proxy-body-timeout 설정을 추가하면 됩니다.

 

1. 전역 설정 (ConfigMap 수정)

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
data:
  grpc-read-timeout: "300s"
  grpc-send-timeout: "300s"
  client-body-timeout: "300s"

 

2. 특정 Ingress에만 설정 (Annotations 추가)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grpc-app-ingress
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/grpc-read-timeout: "300"
    nginx.ingress.kubernetes.io/grpc-send-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-body-timeout: "300"
spec:
  ingressClassName: nginx
  rules:
    - host: grpc.example.com
      http:
        paths:
          - path: /
            pathType: ImplementationSpecific
            backend:
              service:
                name: grpc-service
                port:
                  number: 50051

 

각 설정 설명

• grpc-read-timeout
  서버에서 클라이언트로 응답을 보낼 때 대기하는 시간 (응답 스트리밍 시 중요)
• grpc-send-timeout
  클라이언트에서 서버로 요청을 보낼 때 대기하는 시간 (요청 스트리밍 시 필요)
• client-body-timeout (proxy-body-timeout)
  요청 본문이 전송되는 동안 대기하는 시간 (요청 스트리밍 시 반드시 필요)

응답 스트리밍만 사용하는 경우 → grpc-read-timeout만 변경
요청 스트리밍만 사용하는 경우 → grpc-send-timeout, client-body-timeout 변경
양방향 스트리밍을 사용하는 경우 → 세 가지 모두 변경

 

참고

아래 공식문서 링크로 들어가면 자세한 설명이 있습니다.

https://kubernetes.github.io/ingress-nginx/examples/grpc/

gRPC - Ingress-Nginx Controller

https://github.com/apache/apisix/issues/12357

help request: How to set grpc_read_timeout and grpc_send_timeout · Issue #12357 · apache/apisix

https://github.com/kubernetes/ingress-nginx/issues/12434

gRPC stream is closed after 60 seconds of idle even with timeout annotations set · Issue #12434 · kubernetes/ingress-nginx