[Cloud Run][운영] Secret Manager secret를 환경변수와 volume mount로 언제 나누고 latest를 어디까지 허용하나

IT 리서치 노트

[Cloud Run][운영] Secret Manager secret를 환경변수와 volume mount로 언제 나누고 latest를 어디까지 허용하나

Cloud Run에 Secret Manager를 붙일 때 많은 팀이 secret를 환경변수로 줄지 volume mount로 줄지 마지막까지 미룬다. 하지만 2026년 8월 1일 기준 Cloud Run 공식 문서를 다시 보면, volume mount는 latest와 secret rotation에 잘 맞고 환경변수는 instance startup에서 resolve되므로 특정 버전 pin이 더 안전하다. 이 글은 secret를 두 방식 중 언제 나누고 latest를 어디까지 허용할지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 startup 시점에 고정해야 하는 값은 환경변수 + 특정 버전 pin, runtime에서 파일 재읽기로 rotation을 따라가야 하는 값은 volume mount + latest가 더 실용적이다. 두 방식을 같은 secret 주입으로 묶으면 rollout 통제와 장애 위치가 같이 섞인다.

특히 Cloud Run은 deploy 시점에 secret 접근 권한을 검사하지만, 환경변수 secret는 instance startup 전에 읽고 volume mount는 파일 read 시점에 실패할 수 있다. 같은 권한 누락이라도 어디서 터질지가 다르므로 운영 절차도 나눠야 한다.

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

실무에서 막히는 지점은 세 가지다. 첫째, 모든 secret에 latest를 붙여 두고 revision별 검증이 필요한 값까지 runtime drift에 맡긴다. 둘째, 반대로 모든 secret를 환경변수로 박아 두고 rotation 때마다 불필요하게 전체 revision을 다시 배포한다. 셋째, startup failure와 mounted file read failure를 같은 secret 오류로 기록해 incident triage가 길어진다.

Cloud Run 문서는 volume mount는 Secret Manager에서 최신값을 읽기 때문에 rotation에 잘 맞고, 환경변수는 startup 때 resolve되므로 특정 버전 pin을 권장한다고 적고 있다. 또 deploy와 runtime에서 secret를 검사하는 시점이 다르다고 분명히 설명한다. 이 문장들을 합치면 'latest를 쓸 수 있나'라는 질문은 곧 '이 값이 startup 고정형인가 runtime 회전형인가'라는 질문이 된다.

• 증상: secret를 바꿨는데 일부 revision만 이전 값을 쓴다.
• 실패: env-var secret에 latest를 붙여 revision 재현성을 잃는다.
• 막힘: volume mount를 넣고도 앱이 파일 재읽기를 하지 않는다.
• 누락: startup failure와 runtime file read failure 로그를 분리하지 않는다.

질문	먼저 볼 기준	실무 판단
배포 재현성이 중요한가	같은 revision이 같은 값을 써야 하는지	그렇다면 env-var pin이 더 낫다
rotation을 즉시 반영해야 하나	재배포 없이 파일 재읽기로 따라가야 하는지	그렇다면 volume latest를 우선 본다
장애를 어디서 잡을까	startup인지 runtime read인지	로그 위치와 알람 기준을 분리한다

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

운영 순서는 다섯 단계가 가장 짧다. 먼저 secret를 startup 고정형과 runtime 회전형으로 나눈다. 다음으로 startup 고정형은 환경변수에 특정 버전을 pin한다. 세 번째로 runtime 회전형은 volume mount로 주고 애플리케이션의 파일 재읽기 지원 여부를 확인한다. 네 번째로 deploy, startup, runtime read 세 구간의 로그를 따로 남긴다. 마지막으로 secret 버전 변경 시 어느 서비스가 재배포 대상인지 revision 메모에 고정한다.

1. startup 고정형과 runtime 회전형 secret를 나눈다.
2. 환경변수 secret는 특정 버전을 pin한다.
3. rotation 따라가야 하는 값은 volume latest를 검토한다.
4. startup failure와 runtime read failure 로그를 분리한다.
5. revision 교체 범위를 secret별로 문서화한다.

예를 들어 DB 비밀번호처럼 배포 검증을 엄격히 묶고 싶은 값은 DB_PASSWORD:7처럼 환경변수 pin으로 두고, 외부 API 키처럼 파일 재읽기와 교체 절차가 준비된 값은 /etc/secrets/payment/api-key:latest 같은 volume mount로 두는 식이다. 이 차이를 팀 문서와 incident playbook에 같이 남겨 두면 secret rotation 때 재배포 범위가 불필요하게 커지지 않는다.

secret_kind=startup_pinned|runtime_rotating
injection=env_var|volume_mount
version=7|latest
reload_strategy=revision_only|file_reopen
failure_stage=deploy|startup|runtime_read

이 메모를 남겨 두면 secret incident를 revision drift, startup blocker, runtime read failure로 빠르게 자를 수 있다. 특히 cross-project secret를 쓰는 서비스는 권한 주체와 주입 방식이 동시에 얽히므로 이 표가 더 중요해진다.

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

첫 공식 화면은 Cloud Run이 secret를 두 방식으로 노출한다고 설명하는 구간이다. 여기서 바로 잡아야 할 점은 volume mount와 환경변수가 같은 시점에 같은 값을 읽는 것이 아니라는 사실이다.

Cloud Run 문서는 volume mount는 latest와 secret rotation에 잘 맞고, 환경변수는 startup 시점에 resolve되므로 특정 버전 pin을 권장한다고 설명한다.

즉 운영 기준은 단순한 취향 차이가 아니라 읽는 시점과 rollout 통제 범위의 차이다. 이미 cross-project secret attach 글이 권한 주체를 다뤘다면, 이번 글은 그 secret를 어떤 방식으로 주입할지의 다음 결정이다.

두 번째 자료는 deploy와 runtime에서 secret가 어떻게 검사되는지 설명하는 구간이다. 장애가 revision 생성에서 터지는지, instance startup에서 터지는지, 파일 read 시점에서 터지는지 여기서 갈라진다.

Cloud Run은 deploy 시점에 secret 접근 권한을 확인하고, 환경변수는 startup 이전에 읽으며, volume mount는 runtime read 시점에 실패할 수 있다고 설명한다.

그래서 env-var secret는 startup blocker, volume secret는 runtime read failure라는 차이를 팀 문서에 적어 두는 편이 좋다. 둘을 같은 secret error로 뭉개면 운영자가 로그 위치를 잘못 찾는다.

세 번째 화면은 콘솔 절차에서 버전을 고르는 부분이다. 환경변수와 volume mount 모두 특정 버전을 고를 수 있지만, default 선택값과 운영 의미는 다르다.

Cloud Run 콘솔 문서는 환경변수 secret는 버전을 직접 고르도록 안내하고, volume mount는 기본값으로 latest를 선택할 수 있다고 보여 준다.

실무에서는 여기서 pin과 latest의 경계를 정해야 한다. 배포 검증이 중요한 값은 버전을 고정하고, 파일 재읽기와 rotation 반영이 중요한 값은 volume latest를 쓰는 편이 더 예측 가능하다.

운영 판단은 표로 놓아야 빠르다. startup 고정값과 runtime 갱신값을 한 칸에 섞으면 secret 교체 때 어떤 revision을 다시 배포해야 하는지도 불분명해진다.

환경변수 secret와 volume mount를 rollout 통제, 장애 시점, latest 허용 여부 기준으로 나눈 표다.

특히 같은 Cloud Run 클러스터 안에서도 build identity 분리 글, cross-project service account 글과 이어서 봐야 rollout 전체 기준이 맞춰진다.

명령 예시는 env-var와 volume mount를 한 번에 비교하기 좋다. 같은 secret라도 옵션 문자열이 다르고, revision 교체 전략도 달라진다.

환경변수 pin과 volume latest를 각각 배포하는 gcloud 예시다.

이 메모를 남겨 두면 incident review에서 '왜 이 값은 startup에 박혀 있었고, 왜 저 값은 runtime에 바뀌었나'를 훨씬 쉽게 설명할 수 있다.

마지막 자료는 rollout 체크리스트다. secret 교체 때 revision을 다시 배포해야 하는지, 파일만 재읽으면 되는지 미리 적어 두지 않으면 rotation 시점에 배포 범위가 불필요하게 커진다.

Cloud Run secret rollout에서 env-var와 volume mount를 나누는 체크리스트다.

핵심은 latest를 전부 금지하거나 전부 허용하는 것이 아니라, 어떤 값이 startup 고정형인지 runtime 회전형인지 먼저 나누는 일이다.

5. 주의사항과 리스크

첫 번째 리스크는 환경변수 secret에 latest를 붙여 같은 revision이 언제 어떤 값을 썼는지 재현하지 못하는 것이다. 두 번째는 volume mount를 넣고도 애플리케이션이 파일을 다시 열지 않아 rotation 효과가 없는데 있다고 믿는 것이다. 세 번째는 mounted file latest를 쓰면서도 secret 교체 알람을 startup 실패 기준으로만 모으는 것이다.

운영 전에 확인할 때는 secret마다 injection 방식, 버전 정책, reload 전략, 실패 시점, 재배포 필요 여부를 한 줄로 남겨 두는 편이 좋다. 이 다섯 칸이 비어 있으면 secret rotation 때 서비스별 대응이 달라진다.

• latest 허용 여부는 secret 종류별로 달라야 한다.
• volume latest는 앱의 파일 재읽기 지원이 전제다.
• 환경변수 secret는 revision 재현성을 우선한다.

6. 결론

Cloud Run secret 운영의 핵심은 환경변수냐 volume이냐보다 startup 고정형 값과 runtime 회전형 값을 먼저 자르는 일이다. 배포 재현성이 중요한 값은 환경변수 pin, rotation 반영이 중요한 값은 volume latest로 나누고, deploy·startup·runtime read 로그를 따로 보관하면 incident와 rollout이 훨씬 짧아진다.

이 분기 다음에는 volume latest를 실제로 골랐을 때 파일 재로드와 revision-only rollback을 어디서 나눌지까지 봐야 한다. 같은 가지 후속 글인 secret volume에 latest를 쓸 때 파일 재로드와 revision-only rollback을 언제 나누나에서 reopen 지원 여부와 rollback runbook 분리 기준을 이어서 정리했다.

• startup 고정형 값은 env-var pin으로 둔다.
• rotation 반영형 값은 volume latest를 검토한다.
• secret error는 startup과 runtime read로 나눠 기록한다.

7. 참고 링크

1. https://docs.cloud.google.com/run/docs/configuring/services/secrets
2. https://cloud.google.com/secret-manager/docs/best-practices