[Cloud Run][운영] secret version alias를 latest로 둘 때 incident 중 alias retarget과 disabled version enable을 어느 기준으로 먼저 나누나

IT 리서치 노트

[Cloud Run][운영] secret version alias를 latest로 둘 때 incident 중 alias retarget과 disabled version enable을 어느 기준으로 먼저 나누나

Cloud Run secret volume을 latest나 alias로 돌리면 rotation은 편해지지만 장애 복구 손잡이가 늘어난다. 2026년 8월 6일 기준 Cloud Run과 Secret Manager 공식 문서를 다시 보면 Cloud Run은 런타임에 secret volume 값을 읽고, Secret Manager alias는 다른 version으로 다시 가리킬 수 있으며, disabled version은 다시 enable하기 전까지 접근할 수 없다. 이 글은 secret version alias를 latest처럼 운용할 때 incident 중 alias retarget과 disabled version enable을 어느 기준으로 먼저 나누는 편이 좋은지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 alias target version이 enabled인지부터 확인하고, enabled라면 retarget을 먼저, disabled라면 enable 또는 다른 enabled version으로 retarget을 먼저 검토하는 편이 짧다. 앱이 file reopen을 못 하는 구조라면 그다음 질문은 retarget이 아니라 인스턴스 재기동 또는 redeploy다.

즉 latest 계열 incident는 revision rollback과 다른 층이 하나 더 있다. alias pointer와 target state를 먼저 닫아야 rollback 판단도 빨라진다.

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

실무에서 먼저 꼬이는 지점은 세 가지다. 첫째, alias가 잘못된 version을 가리키는데도 Cloud Run revision만 다시 본다. 둘째, alias target이 disabled인데 retarget과 enable을 같은 조치로 본다. 셋째, alias를 release label처럼 쓰는 팀과 runtime pointer처럼 쓰는 팀의 규칙이 뒤섞여 incident 메모 기준이 불명확해진다.

Cloud Run 문서는 secret volume이 런타임에서 값을 읽는다고 설명하고, Secret Manager는 alias를 다시 지정할 수 있다고 설명한다. 또 disable/enable 문서는 disabled version은 재접근 전에 enable이 필요하다고 분명히 적고 있다. 따라서 incident triage는 revision id보다 먼저 alias target과 target state를 적어야 한다.

이 차이를 놓치면 retarget 한 번이면 끝날 장애를 재배포로 길게 끌거나, 반대로 disabled version을 alias 변경만으로 고칠 수 있다고 착각하게 된다. secret incident는 pointer 문제와 state 문제를 분리해야 한다.

• 증상: 같은 revision인데 어떤 요청은 새 값을 읽고 어떤 요청은 실패한다.
• 실패: alias target과 target state를 incident 첫 줄에 안 적는다.
• 막힘: retarget과 enable을 같은 손잡이처럼 본다.
• 누락: alias policy가 release label인지 runtime pointer인지 정리해 두지 않는다.

질문	먼저 볼 것	실무 판단
잘못된 값이 들어왔나	alias target version	target이 틀렸으면 retarget부터 본다
접근 자체가 막혔나	target state가 disabled인지	disabled면 enable 또는 다른 target으로 전환한다
retarget 후에도 안 바뀌나	앱의 reopen 지원과 instance lifecycle	runtime read 구조를 다시 본다

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

실무 순서는 다섯 단계가 가장 짧다. 먼저 reference가 latest인지 alias인지 적는다. 다음으로 alias라면 현재 target version과 state를 확인한다. 세 번째로 enabled인데 값만 틀렸다면 retarget을 먼저 검토한다. 네 번째로 disabled라면 enable과 다른 enabled version으로 retarget 중 더 짧은 경로를 고른다. 마지막으로 앱의 reopen 지원 유무에 따라 인스턴스 재기동이나 redeploy 필요 여부를 결정한다.

콘솔 기준으로 적으면 더 빠르다. Secret Manager의 Versions 탭을 열고 alias target version을 확인한다. 상태 열이 disabled면 Enable 버튼 경로를 먼저 보고, enabled인데 값만 잘못됐으면 alias 수정 필드에서 retarget 후보를 고른다. 그다음 Cloud Run 쪽에서는 로그와 설정을 확인하고, file reopen이 안 되면 재시작이나 redeploy 버튼까지 이어서 판단한다.

1. latest인지 alias인지 기록한다.
2. alias target version과 state를 적는다.
3. enabled target이 틀렸으면 retarget을 본다.
4. disabled target이면 enable 또는 다른 enabled target 전환을 고른다.
5. retarget 뒤 runtime reopen 경로를 확인한다.

이 순서가 중요한 이유는 revision rollback과 Secret Manager 조치를 섞지 않게 해 주기 때문이다. alias target 자체가 잘못되면 Secret Manager 쪽 손잡이가 먼저고, target은 맞는데 앱이 다시 안 읽으면 Cloud Run runtime 쪽 손잡이가 먼저다.

점검 순서 예시

reference=alias
target_version=42
target_state=disabled
retarget_candidate=41
runtime_reopen_supported=false
next_action=enable 42 or repoint to 41, then restart instances

이렇게 남겨 두면 같은 latest incident라도 pointer 문제인지 state 문제인지, Cloud Run 쪽 reopen 문제인지 바로 갈린다. secret 운영은 값보다 pointer와 state가 먼저다.

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

첫 공식 화면은 Cloud Run secrets 문서의 volume 읽기 설명이다. 이 문장은 alias를 latest처럼 운용할 때 revision이 살아 있어도 런타임에 읽는 값이 달라질 수 있다는 전제를 고정해 준다. 화면의 설명 문장과 결과 표시를 먼저 확인해 두면 incident 때 revision 탭보다 secret read 경로를 먼저 보게 된다.

Cloud Run은 secret volume을 읽을 때 Secret Manager에서 값을 가져온다고 설명한다.

즉 incident가 났을 때 질문은 revision을 되돌릴까보다 먼저 alias가 현재 무엇을 가리키는가다. 같은 revision이라도 alias target이 바뀌면 런타임 값이 달라질 수 있다. Cloud Run 로그를 보기 전에 이 전제를 먼저 확인해야 triage 순서가 짧아진다.

두 번째 자료는 Secret Manager alias 문서다. alias는 숫자 version과 별개로 다시 가리킬 수 있으므로, incident 복구 손잡이로도 release label로도 쓸 수 있다. 문서의 alias 설명과 예시 필드를 보고 팀 메모에 alias 이름과 target version 칸을 따로 두는 편이 좋다.

Secret Manager는 secret version에 alias를 붙이고 다시 지정할 수 있다고 설명한다.

그래서 같은 latest 계열 운영이라도 alias를 runtime pointer로 볼지, 배포 라벨로 볼지 먼저 정해야 한다. 이 선택이 retarget과 re-enable 우선순위를 바꾼다.

세 번째 공식 화면은 Secret Manager의 enable 문서다. disabled 상태의 version은 접근할 수 없고, 다시 쓰려면 enable이 필요하다. Versions 탭의 상태 열과 Enable 버튼 경로를 같이 확인해 두면 retarget과 enable을 같은 조치로 섞지 않게 된다.

Secret Manager는 disabled version을 다시 접근 가능하게 하려면 enable이 필요하다고 설명한다.

이 지점 때문에 alias target이 disabled version인지부터 확인해야 한다. alias 이름은 그대로여도 실제 target state가 막혀 있으면 retarget보다 enable이 먼저일 수 있다. 상태가 enabled인지 disabled인지 메모에 적고 실패 로그와 함께 남겨야 다음 호출에서도 같은 판단을 반복하지 않는다.

네 번째 자료는 Secret Manager access 문서다. latest나 alias를 지정해 secret version에 접근할 수 있다는 설명이 보인다. 문서에서 latest와 alias 표현을 확인해 두면 incident 메모의 reference_kind 필드를 빈칸으로 두지 않게 된다.

Secret Manager는 latest나 alias로 secret version에 접근할 수 있다고 설명한다.

즉 incident 메모에는 latest인지 alias인지, alias라면 실제 target version이 무엇인지까지 함께 적어야 한다. 이름만 적어 두면 같은 장애를 다시 재현하기 어렵다. 최소한 reference_kind, alias_name, target_version, target_state, follow_up 다섯 필드를 표처럼 채워 두는 편이 안전하다.

다섯 번째 자료는 retarget과 re-enable을 갈라 놓은 분기표다. 이전 글이 disabled version과 revision rollback을 나눴다면, 이번 표는 alias pointer가 있는 운영에서 retarget과 enable 중 무엇이 먼저인지 더 좁게 자르는 단계다.

Cloud Run alias incident에서 alias retarget과 disabled version enable을 가르는 판단표다.

이미 disabled version 복구와 revision rollback 글을 읽었다면, 이번 표는 rollback 이전에 alias 자체를 어떻게 다룰지 결정하는 후속편이다.

마지막 자료는 운영 메모 예시다. alias name, target version, target state, reopen 지원 여부를 같은 줄에 두면 retarget과 enable 사이 판단이 짧아진다.

Cloud Run secret alias incident 메모 예시다.

이 정도만 남겨도 Secret Manager 쪽 문제인지 Cloud Run runtime 쪽 문제인지 갈라진다. file reload와 revision-only rollback 글과도 자연스럽게 이어진다.

5. 주의사항과 리스크

첫 번째 리스크는 alias가 잘못된 enabled version을 가리키는데도 disabled version 복구 playbook을 타는 것이다. 두 번째 리스크는 disabled target인데 retarget 이력만 남기고 enable 여부를 빠뜨리는 것이다. 세 번째 리스크는 alias policy가 release label인지 runtime pointer인지 팀 문서에 없어서 incident 때마다 해석이 달라지는 것이다.

운영 전에 확인할 때는 최소한 alias_name, alias_target_version, target_state, runtime_reopen_supported, preferred_recovery 다섯 칸을 같은 메모에 두는 편이 좋다. 그래야 secret incident가 Cloud Run rollout 문제인지 Secret Manager pointer 문제인지 바로 갈린다.

• pointer 문제와 state 문제를 분리한다.
• retarget과 enable의 우선순위를 state 기준으로 정한다.
• alias policy를 release 문서에 미리 적어 둔다.

6. 결론

Cloud Run alias incident는 revision rollback 전에 alias target과 target state를 먼저 닫는 편이 빠르다. enabled면 retarget, disabled면 enable 또는 다른 enabled target 전환, 그리고 마지막에 runtime reopen 여부를 확인하면 같은 latest 계열 장애도 훨씬 짧게 풀 수 있다.

• alias target과 target state를 incident 첫 줄에 적는다.
• enabled와 disabled를 같은 조치로 보지 않는다.
• retarget 뒤에는 runtime reopen 경로까지 닫는다.

7. 참고 링크

1. https://docs.cloud.google.com/run/docs/configuring/services/secrets
2. https://docs.cloud.google.com/secret-manager/docs/assign-alias-to-secret-version
3. https://docs.cloud.google.com/secret-manager/docs/enable-secret-version
4. https://docs.cloud.google.com/secret-manager/docs/access-secret-version