[Cloud Run][운영] source deploy에서 cross-project service account를 붙일 때 deployer 권한과 service agent 권한을 어떤 순서로 다시 나누나

IT 리서치 노트

[Cloud Run][운영] source deploy에서 cross-project service account를 붙일 때 deployer 권한과 service agent 권한을 어떤 순서로 다시 나누나

Cloud Run에서 gcloud run deploy --source를 이미 잘 쓰고 있는데, runtime service identity를 다른 프로젝트의 service account로 바꾸는 순간 갑자기 어느 IAM부터 다시 봐야 할지 헷갈릴 때가 있다. 2026년 7월 31일 기준 Cloud Run 공식 문서를 다시 보면 cross-project service identity는 deployer, build service account, Cloud Run service agent, runtime service account를 같은 주체로 취급하면 안 된다. 이 글은 source deploy에서 cross-project service account를 붙일 때 어떤 권한부터 다시 나누는 편이 덜 꼬이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 cross-project Cloud Run source deploy는 deployer와 build service account를 먼저 분리한 뒤, 다른 프로젝트 service account에는 Cloud Run service agent의 토큰 발급 권한을 따로 얹는 순서가 안전하다. deployer가 service account를 붙일 수 있다는 사실과, Cloud Run service agent가 그 계정으로 토큰을 만들 수 있다는 사실은 같지 않다.

이미 build service account와 service identity를 같은 프로젝트 안에서 나누는 글이 첫 분리를 다뤘다면, 이번 글은 그 다음 단계인 다른 프로젝트 service account를 붙일 때 누락되는 권한 순서를 다룬다.

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

이 이슈가 길어지는 이유는 세 주체가 한 증상으로 보이기 때문이다. source deploy 자체는 되지만 revision이 실제 API 호출에서 막히거나, 반대로 service account를 붙이는 단계에서부터 실패한다. build 로그, deploy 로그, runtime 로그가 섞이면 어느 계정이 문제인지 빠르게 안 잡힌다.

Cloud Run service identity 문서는 다른 프로젝트의 service account를 쓰려면 Cloud Run service agent에 추가 권한과 org policy 검토가 필요하다고 설명한다. 또 같은 문서는 roles/iam.serviceAccountTokenCreator를 service agent에 줘야 한다고 적고 있다. source deploy 문서는 deployer에 필요한 역할이 따로 있음을 보여 준다. 이 셋을 같이 읽으면 deployer, build, service agent, runtime 계정을 다른 층으로 봐야 한다는 점이 분명해진다.

많은 팀이 deployer가 이미 강한 권한을 가졌으니 service identity 문제도 덮을 수 있다고 생각하거나, 다른 프로젝트 runtime service account에 API 역할만 주면 충분하다고 가정한다. 하지만 cross-project 경계에서는 service agent 토큰 발급 권한이 빠지면 계정이 존재해도 실제 런타임 인증이 성립하지 않을 수 있다.

• 증상: source deploy는 되는데 cross-project runtime 호출이 막히거나 service account 부착에서 실패한다.
• 실패: deployer가 강하면 service agent 권한도 충분할 것이라고 가정한다.
• 막힘: build 계정과 runtime 계정과 service agent를 같은 원인으로 묶는다.
• 누락: 다른 프로젝트 service account에 대한 Token Creator 권한을 빠뜨린다.

증상	먼저 볼 곳	유력 원인
service account 부착 자체가 막힌다	deployer 권한	attach 권한 부족
revision은 뜨지만 다른 프로젝트 API 호출이 실패한다	Cloud Run service agent의 Token Creator	cross-project 토큰 발급 권한 누락
빌드와 런타임 실패가 같이 보인다	build service account와 runtime service identity	주체 분리 실패

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

실무 순서는 다섯 단계가 가장 짧다. 먼저 deployer가 source deploy와 service account 부착을 수행할 수 있는지 확인한다. 다음으로 build service account를 현재 프로젝트 안에서 먼저 분리해 source build 실패를 따로 떼어 낸다. 세 번째로 다른 프로젝트 runtime service account에 Cloud Run service agent의 roles/iam.serviceAccountTokenCreator를 부여한다. 네 번째로 runtime service account에는 실제 API 최소 권한만 준다. 마지막으로 org policy와 실제 호출 로그를 같이 본다.

1. deployer 권한과 service account 부착 가능 여부를 먼저 확인한다.
2. build service account를 source deploy 단계에서 따로 고정한다.
3. Cloud Run service agent에 cross-project Token Creator 권한을 준다.
4. runtime service account에는 실제 API 최소 권한만 얹는다.
5. org policy와 runtime 호출 로그를 마지막에 검증한다.

이 순서를 지키면 어떤 실패가 deployer 계층인지, 어떤 실패가 cross-project 토큰 발급 계층인지, 어떤 실패가 실제 런타임 API 권한 부족인지 빨리 갈라진다. 특히 빌드와 런타임을 같은 service account로 묶지 않는 것이 중요하다. build 계정은 이미지 생성에만, runtime 계정은 실제 Google Cloud API 호출에만, service agent는 토큰 발급 보조에만 집중시키는 편이 least privilege를 유지하기 쉽다.

배포 명령 메모 예시

gcloud run deploy SERVICE_NAME \
  --source . \
  --build-service-account=cr-build@project-a.iam.gserviceaccount.com \
  --service-account=runtime@project-b.iam.gserviceaccount.com

이렇게 메모를 남겨 두면 source deploy, build, runtime identity를 한 명령에서 모두 재현할 수 있다. 이후 권한 회수나 조직 정책 변경이 들어와도 어떤 계정을 손대야 하는지 훨씬 빠르게 찾게 된다.

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

첫 공식 화면은 Cloud Run service identity 문서의 cross-project 안내 구간이다. 여기서 먼저 봐야 할 핵심은 cross-project service account를 붙이는 순간 deployer 한 명만의 문제가 아니라 service agent와 org policy까지 같이 움직인다는 점이다.

Cloud Run 문서는 다른 프로젝트의 service account를 service identity로 쓰려면 추가 IAM 설정과 org policy 검토가 필요하다고 설명한다.

즉 같은 프로젝트 안에서 build 계정과 runtime 계정을 나누는 글과 달리, cross-project 경계에서는 붙이는 순서 자체를 잘못 잡으면 service identity가 있어도 토큰 발급 단계에서 막힐 수 있다.

두 번째 자료는 가장 자주 빠지는 권한이다. 문서는 Cloud Run service agent에 Service Account Token Creator를 줘야 cross-project service identity 토큰 발급이 가능하다고 못 박는다.

cross-project service identity를 쓰려면 Cloud Run service agent에 <code>roles/iam.serviceAccountTokenCreator</code>가 필요하다.

실무에서는 deployer가 이미 service account user 권한을 갖고 있으니 충분하다고 오해하기 쉽다. 하지만 deployer가 붙일 수 있는 권한과 service agent가 실제 토큰을 만들 수 있는 권한은 다른 층이다.

세 번째 화면은 source deploy 문서의 required roles 구간이다. 소스 배포는 Cloud Build와 Cloud Run API를 같이 타므로 deployer가 무엇을 할 수 있는지부터 명확히 적어 두는 편이 빠르다.

Cloud Run source deploy 문서는 deployer에 필요한 역할이 따로 있음을 보여 준다.

cross-project 문제를 runtime service account 쪽에서만 보면 빌드와 배포 단계의 실패를 같은 증상으로 묶게 된다. deployer, build service account, runtime service identity를 다시 나누는 이유가 여기서 분명해진다.

네 번째 자료는 권한 주체를 네 칸으로 분리한 표다. cross-project에서 가장 안전한 출발점은 누가 붙이고, 누가 빌드하고, 누가 토큰을 만들고, 누가 런타임 API를 호출하는지를 한 장에 고정하는 것이다.

deployer, build service account, Cloud Run service agent, runtime service identity를 분리한 표다.

이미 같은 프로젝트 안에서 build와 runtime identity를 나누는 글을 읽었다면, 이번 표는 그 다음 단계인 cross-project 추가 권한을 어디에 얹어야 하는지 보여 준다.

다섯 번째 자료는 배치 메모 예시다. cross-project 설정은 콘솔 클릭보다 누가 어떤 바인딩을 받았는지 짧은 텍스트로 남겨 두는 편이 rollback에 유리하다.

cross-project Cloud Run source deploy 점검 메모 예시다.

특히 다른 프로젝트의 service account를 붙일 때는 project number 기준 service agent와 실제 runtime service account 이메일을 같이 남겨 두어야 나중에 역할 회수와 재현이 빠르다.

마지막 자료는 rollout 순서표다. 이 순서를 고정해 두면 source deploy, cross-project service identity, org policy, runtime API 권한을 한 번에 바꾸다가 원인을 놓치는 일을 줄일 수 있다.

cross-project service identity rollout은 deployer, service agent, runtime 권한을 순차적으로 나누는 편이 안전하다.

또 Cloud NAT 운영 분기처럼 Cloud Run의 다른 운영 글들과 다르게, 이 이슈는 네트워크보다 IAM 문자열을 먼저 고정해야 해결 속도가 빨라진다.

5. 주의사항과 리스크

첫 번째 리스크는 deployer가 강한 권한을 가졌다는 이유로 runtime 토큰 발급도 자동으로 될 것이라고 생각하는 것이다. 두 번째는 cross-project runtime service account에 API 역할만 얹고 Token Creator를 빠뜨리는 것이다. 세 번째는 build service account와 runtime service identity를 다시 하나로 합쳐 문제를 더 넓게 만드는 것이다.

운영 전에 확인할 때는 최소한 deployer, build service account, Cloud Run service agent, runtime service identity 네 주체를 같은 표에 남기는 편이 좋다. 그래야 어느 계정이 어느 프로젝트에 있는지, 어느 바인딩이 cross-project인지 바로 보인다.

• deployer 권한과 service agent 토큰 발급 권한은 다른 층이다.
• cross-project runtime 계정에는 API 최소 권한과 Token Creator 보조 권한을 분리한다.
• build 계정과 runtime 계정을 다시 합치지 않는다.

6. 결론

Cloud Run source deploy에서 다른 프로젝트 service account를 runtime identity로 붙일 때는 service account 이메일보다 순서가 중요하다. deployer, build service account, Cloud Run service agent, runtime service identity를 네 칸으로 분리하고, cross-project Token Creator 권한을 service agent 쪽에 먼저 맞추면 실패 구간을 훨씬 짧게 좁힐 수 있다.

이후 단계에서 실제 secret 접근까지 붙는 순간에는 점검 순서가 한 번 더 달라진다. cross-project runtime identity 위에 Secret Manager 권한과 deploy 시점·startup 시점 차이를 얹어 다시 보는 후속 정리는 cross-project Secret Manager secret 권한 분기 글로 바로 이어진다.

• deployer와 service agent를 같은 권한으로 보지 않는다.
• cross-project에서는 Token Creator 누락을 가장 먼저 의심한다.
• build 계정과 runtime 계정은 계속 분리한다.

7. 참고 링크

1. https://docs.cloud.google.com/run/docs/configuring/services/service-identity
2. https://docs.cloud.google.com/run/docs/deploying-source-code
3. https://docs.cloud.google.com/run/docs/configuring/services/build-service-account