[Cloud Run][운영] startup probe path가 맞지 않을 때 초기화가 반복되는 이유와 로그 확인 순서

IT 리서치 노트

[Cloud Run][운영] startup probe path가 맞지 않을 때 초기화가 반복되는 이유와 로그 확인 순서

Cloud Run에서 startup probe를 붙인 뒤 새 revision이 계속 초기화만 반복하면 timeout을 먼저 늘리는 경우가 많다. 하지만 2026년 6월 27일 기준 Cloud Run 공식 문서를 다시 보면, startup probe path는 실제 endpoint 이름과 정확히 맞아야 하고, startup 단계가 통과하기 전에는 liveness와 readiness도 뒤로 밀린다. 이 글은 path mismatch로 초기화가 반복되는 상황을 기준으로 로그를 어떤 순서로 읽어야 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 startup probe path mismatch는 느린 시작 문제와 다르게 timeout 값을 늘려도 안 풀릴 수 있다. path가 실제 endpoint와 다르면 probe는 계속 잘못된 주소를 때리고, startup 단계가 통과하지 못하므로 revision 교체나 503만 반복된다. 그래서 이 증상은 timeout보다 path, port, 실제 리스닝 로그를 먼저 봐야 한다.

이미 startup probe timeout과 failureThreshold 글이 느린 초기화 쪽을 다뤘다면, 이번 글은 path mismatch 분기다. 비용 영향까지 같이 보려면 health check 비용 글을 같이 보는 편이 좋다. 반대로 앱은 떠 있는데 connection refused가 반복된다면 startup probe port가 맞지 않을 때 revision이 준비되지 않는 경우를 이어서 확인하면 원인 분기가 더 빨라진다.

2. 어디서 실제로 막히는가

실무에서 흔한 증상은 세 가지다. 첫째, 애플리케이션은 포트를 열었는데 revision이 계속 준비되지 않는다. 둘째, Cloud Logging에는 probe 실패만 찍히고 실제 앱 로그는 정상처럼 보여 원인을 놓친다. 셋째, framework 업데이트 뒤 endpoint 이름이 /ready로 바뀌었는데 probe path는 /healthz에 그대로 남아 있다.

공식 health checks 문서는 startup probe가 성공하기 전까지 liveness와 readiness가 뒤로 밀린다고 적고 있다. 또 endpoint 이름은 probe configuration의 path와 맞아야 한다고 설명한다. 즉 startup path mismatch는 health check 체인의 가장 앞단에서 발생하는 설정 문제다.

이 문제를 timeout으로만 보면 원인 분리가 어려워진다. slow startup이라면 결국 늦게라도 200이 오겠지만, path mismatch라면 아무리 기다려도 404나 엉뚱한 응답만 반복될 수 있다. 특히 ingress rewrite, framework base path, custom router를 쓰는 서비스는 코드상 endpoint 이름과 외부 probe path가 살짝 어긋나기 쉽다.

• 증상: revision이 계속 준비되지 않고 probe 실패가 반복된다.
• 실패: timeout 값을 먼저 늘리고 path는 나중에 본다.
• 막힘: 앱 로그와 probe 로그를 같은 타임라인으로 보지 않는다.
• 누락: endpoint 이름 변경 후 startupProbe.path를 같이 수정하지 않는다.

증상	먼저 볼 곳	판단 기준
probe가 404를 낸다	startupProbe.path	실제 endpoint 이름과 맞는지 본다
늦게라도 200이 온다	timeoutSeconds, failureThreshold	slow startup인지 본다
앱은 떠 있는데 probe가 안 닿는다	port와 리스닝 로그	port mismatch 또는 routing 이슈를 본다

3. 실무에서 적용하는 순서

점검 순서는 다섯 단계가 가장 빠르다. 먼저 startupProbe.path를 현재 코드의 endpoint 이름과 대조한다. 다음으로 같은 revision의 startupProbe.port와 앱이 실제 리스닝한 포트를 비교한다. 세 번째로 앱 로그와 probe 실패 로그를 같은 타임라인에 놓는다. 네 번째로 timeout과 failureThreshold는 path와 port가 맞는 것이 확인된 뒤에만 조정한다. 마지막으로 revision diff를 남겨 다음 배포 때 다시 섞이지 않게 한다.

1. 현재 코드의 startup endpoint 이름을 확인한다.
2. startupProbe.path와 port를 revision 설정과 대조한다.
3. 앱 리스닝 로그와 probe 실패 로그를 같은 시간 순서로 본다.
4. path와 port가 맞을 때만 timeout 계열을 조정한다.
5. 수정한 probe 블록을 revision diff로 남긴다.

이때 path 이름을 프레임워크 기본값에 맡겨 두지 않는 편이 좋다. /ready, /health, /startup 중 어떤 endpoint를 startup 용도로 쓸지 명시하고, 앱 초기화가 끝나기 전에는 200을 반환하지 않게 두는 편이 안전하다. 그래야 startup probe가 readiness 역할도 일정 부분 대신할 수 있다.

점검 메모 예시

startup_endpoint=/ready
probe_path=/ready
probe_port=8080
app_listen_port=8080
first_200_at=12:00:17
first_probe_failure_at=12:00:07
timeout_tuned_after_path_check=true

이렇게 남겨 두면 다음 배포에서 framework base path나 reverse proxy 구성이 바뀌어도 어디를 다시 봐야 하는지 분명해진다. probe 설정은 YAML 한 줄처럼 보여도 revision 안정성 전체를 흔들 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 startup probe가 먼저 동작한다는 설명이다. 이 문장을 먼저 읽어야 path mismatch 상황을 liveness 문제로 오해하지 않게 된다.

Cloud Run 문서는 startup probe가 성공하기 전까지 liveness와 readiness가 대기한다고 설명한다.

즉 초기화가 반복될 때는 liveness보다 startup probe가 먼저 원인일 수 있다. startup 단계가 통과하지 못하면 뒤 검사는 아직 시작도 안 했을 수 있다.

두 번째 자료는 path 일치 조건이다. 문서는 endpoint 이름이 probe configuration의 path와 맞아야 한다고 적고 있다.

startup endpoint 이름과 probe path는 정확히 맞아야 하며, HTTP probe는 HTTP/1 endpoint를 사용해야 한다.

여기서 /healthz와 /health, prefix 누락, rewrite 경로 차이 같은 사소한 어긋남이 바로 초기화 실패로 이어질 수 있다. path mismatch는 느린 시작과 다른 종류의 문제다.

세 번째 화면은 공식 샘플이다. sample YAML을 보면 startupProbe 블록에 path와 port가 한 묶음으로 들어가고, 이 둘을 함께 맞춰야 한다는 점이 눈에 들어온다.

공식 샘플은 startupProbe의 path와 port를 명시적으로 같이 설정한다.

실무에서는 path만 손보다가 port나 프록시 경로를 놓치기 쉽다. 샘플처럼 probe 블록 전체를 한 번에 보고 revision diff를 남기는 편이 안전하다.

path mismatch는 설정 diff를 한 장으로 보면 가장 빠르다. 잘못된 path와 고친 path를 나란히 보면 왜 초기화가 반복됐는지 바로 설명이 된다.

잘못된 startup probe path와 수정된 path를 비교한 예시다.

특히 프레임워크가 /ready는 만들었는데 /healthz는 안 만들거나, ingress 리라이트 뒤에만 특정 path가 살아 있는 경우에는 이런 diff가 로그보다 먼저 답을 준다.

다섯 번째 자료는 로그 순서다. 앱이 어느 시점에 실제로 startup endpoint를 열었는지와, 404나 503이 언제 찍혔는지를 같은 타임라인으로 보는 편이 좋다.

startup endpoint 준비 시점과 probe 실패 로그를 같은 순서로 읽는 예시다.

이 순서로 보면 느려서 timeout이 난 것인지, 아예 다른 path를 때리고 있어서 404가 난 것인지 구분된다. 이미 startup probe timeout 글을 봤다면 이번 글은 path 분기만 따로 좁힌 후속편이다.

마지막 자료는 triage 표다. startup path mismatch와 startup timeout은 증상이 비슷해 보여도 먼저 볼 로그와 설정이 다르다.

path mismatch, timeout, port mismatch를 나눠 보는 triage 표다.

이 표를 기준으로 보면 503이 보인다고 무조건 timeout 값을 올리는 실수를 줄일 수 있다. probe는 안정성뿐 아니라 비용에도 닿으므로 health check 비용 글과 같이 보는 편이 좋다.

5. 주의사항과 리스크

첫 번째 리스크는 path mismatch인데도 timeout만 키우는 것이다. 두 번째 리스크는 startup endpoint가 200을 너무 빨리 반환해 실제 readiness보다 먼저 통과시키는 것이다. 세 번째 리스크는 port와 path를 콘솔에서 따로 바꾸고 revision diff를 남기지 않아, 어느 배포에서 어긋났는지 다시 못 찾는 것이다.

운영 전에 확인할 때는 최소한 path mismatch, slow startup, port mismatch 세 가지를 분리한 triage 표를 팀에 남기는 편이 좋다. 그래야 503이나 probe failure가 보일 때 매번 처음부터 해석하지 않아도 된다.

• path mismatch와 slow startup은 먼저 볼 설정이 다르다.
• startup endpoint는 실제 준비 완료 시점과 가깝게 설계한다.
• probe 블록 변경은 revision diff로 기록해 둔다.

6. 결론

Cloud Run startup probe path mismatch는 timeout을 올린다고 해결되지 않을 수 있는 전형적인 설정 문제다. path와 port, 앱 리스닝 로그를 먼저 맞추고 그다음에 timeout을 조정하면 초기화 반복과 503을 훨씬 빨리 좁힐 수 있다.

• startupProbe.path를 실제 endpoint 이름과 먼저 맞춘다.
• path와 port가 확인된 뒤에만 timeout을 조정한다.
• 앱 로그와 probe 로그를 같은 타임라인으로 본다.

7. 참고 링크

1. https://docs.cloud.google.com/run/docs/configuring/healthchecks
2. https://docs.cloud.google.com/run/docs/troubleshooting
3. https://docs.cloud.google.com/run/docs/samples/cloudrun-healthchecks-startup-probe-http