Repository · Registry · IAM 권한 차이
ECR 레포별 정책, 레지스트리 전체 정책, IAM 권한을 나눠서 이해하고 이미지 push/pull, cross-account 접근, 권한 오류를 점검하는 기준을 정리합니다.
Amazon ECR 정책 설정 방법을 설명합니다. Repository Policy, Registry Policy, IAM Policy 차이와 이미지 push/pull, 레포별 권한, 레지스트리 전체 권한, cross-account 설정 기준을 정리합니다.
Amazon ECR 권한이 헷갈리는 이유
Amazon ECR은 컨테이너 이미지를 저장하는 서비스지만 권한 구조는 단순하지 않습니다. 이미지를 push하거나 pull하려면 IAM 권한, repository policy, registry policy, 인증 토큰 권한이 함께 맞아야 합니다.
특히 레포별로 접근을 열어야 하는지, 계정의 ECR 전체에 정책을 걸어야 하는지, IAM Role에만 권한을 주면 되는지 헷갈리는 경우가 많습니다.
이 글에서는 ECR 정책을 세 가지로 나눠 설명합니다. 첫째, 레포별로 설정하는 Repository Policy. 둘째, 레지스트리 전체 수준에서 설정하는 Registry Policy. 셋째, 사용자나 Role에 붙이는 IAM Policy입니다.
ECR 권한 구조 한눈에 보기
공식 문서 기준으로 Amazon ECR repository policy는 개별 repository에 붙는 resource-based policy입니다. 특정 사용자, Role, 계정, 서비스가 해당 repository에서 어떤 작업을 할 수 있는지 제어합니다.
Registry policy는 private registry 수준에서 AWS principal에게 권한을 부여하는 정책입니다. repository creation, pull-through cache, replication 같은 레지스트리 수준 기능에서 중요합니다.
IAM Policy는 principal에 붙는 identity-based policy입니다. 사용자가 ECR API를 호출할 수 있는지, 어떤 repository ARN에 접근할 수 있는지 제어합니다.
| 정책 | 적용 범위 | 주요 용도 |
|---|---|---|
| Repository Policy | 개별 ECR repository | 특정 레포 push/pull, cross-account 접근 |
| Registry Policy | ECR private registry 전체 | replication, pull-through cache, repository 생성 등 |
| IAM Policy | IAM User/Role | ECR API 호출 권한과 레포 접근 권한 |
| Auth Token 권한 | ECR registry 인증 | docker login 전 ecr:GetAuthorizationToken 필요 |
레포별로 설정하기: ECR Repository Policy
레포별 권한을 주고 싶다면 Repository Policy를 사용합니다. 예를 들어 특정 CI/CD Role만 특정 repository에 push할 수 있게 하거나, 다른 계정의 ECS/EKS 배포 Role이 특정 이미지만 pull할 수 있게 할 때 사용합니다.
Repository Policy는 resource-based policy이므로 Principal을 명시할 수 있습니다. 같은 계정의 Role뿐 아니라 외부 계정의 Role도 Principal로 지정할 수 있습니다.
다만 모든 권한을 repository policy에 몰아넣는 것은 좋지 않습니다. 내부 사용자와 Role의 일반적인 권한은 IAM Policy로 관리하고, cross-account 접근이나 특정 repository 공유는 Repository Policy로 관리하는 방식이 깔끔합니다.
레포 전체가 아니라 계정 전체에 설정하기: ECR Registry Policy
ECR Registry Policy는 개별 repository가 아니라 private registry 수준에서 권한을 부여합니다. 공식 문서 기준으로 registry policy는 private registry level에서 AWS principal에게 권한을 주는 정책입니다.
Registry Policy는 replication configuration, pull-through cache rule creation, repository creation 같은 레지스트리 수준 기능에서 사용됩니다. 최근 ECR은 registry policy에서 모든 ECR action을 정책에 넣을 수 있고, 모든 ECR 요청에 registry policy를 적용할 수 있습니다.
하지만 `ecr:*`처럼 넓게 여는 것은 권장하지 않습니다. 공식 문서도 필요한 feature에 맞는 구체적인 action만 추가하는 것을 모범 사례로 설명합니다.
IAM Policy로 권한 설정하기
IAM Policy는 사용자나 Role이 어떤 ECR API를 호출할 수 있는지 정합니다. 예를 들어 CI Role에는 push 권한, ECS task execution role에는 pull 권한, 운영자 Role에는 describe와 lifecycle policy 관리 권한을 줄 수 있습니다.
ECR에서 중요한 예외가 있습니다. 이미지를 push하거나 pull하려면 `ecr:GetAuthorizationToken` 권한이 필요합니다. 공식 문서 기준으로 이 권한은 IAM Policy를 통해 허용되어야 registry 인증을 할 수 있습니다.
Repository Policy가 특정 repository 접근을 허용하더라도, Docker login을 위한 authorization token 권한이 없으면 push/pull 전에 인증 단계에서 막힐 수 있습니다.
Repository Policy와 IAM Policy는 둘 다 필요한가
공식 문서 기준으로 ECR repository policy와 IAM policy는 모두 권한 평가에 사용됩니다. 같은 계정의 principal이라면 둘 중 하나가 action을 허용해도 권한이 허용될 수 있습니다. 단 명시적 Deny가 있으면 거부됩니다.
다른 계정 접근은 다르게 봐야 합니다. 외부 계정의 Role이 내 repository에 접근하려면 내 repository policy에서 외부 principal을 허용하고, 외부 계정의 IAM Policy에서도 해당 repository 접근을 허용해야 합니다.
따라서 같은 계정 운영은 IAM Policy 중심으로 단순화하고, cross-account 공유는 Repository Policy와 외부 IAM Policy를 함께 설계하는 것이 좋습니다.
| 상황 | 필요 정책 | 설명 |
|---|---|---|
| 같은 계정 Role 접근 | IAM Policy 또는 Repository Policy | 명시적 Deny가 없으면 허용 가능 |
| 외부 계정 Role 접근 | Repository Policy + 외부 IAM Policy | 양쪽 권한 필요 |
| Docker login | IAM Policy | ecr:GetAuthorizationToken 필요 |
| Replication/Pull-through cache | Registry Policy | 레지스트리 수준 권한 필요 |
이미지 Pull 권한에 필요한 Action
이미지를 pull할 때는 단순히 `ecr:GetDownloadUrlForLayer`만 있으면 되는 것이 아닙니다. 일반적으로 image manifest 조회와 layer 다운로드를 위한 여러 action이 필요합니다.
ECS, EKS, EC2에서 이미지를 pull하는 Role에는 `ecr:GetAuthorizationToken`, `ecr:BatchCheckLayerAvailability`, `ecr:GetDownloadUrlForLayer`, `ecr:BatchGetImage` 권한이 필요합니다.
repository policy로 외부 계정에 pull 권한을 줄 때도 이 action들을 기준으로 최소 권한을 구성하는 것이 좋습니다.
이미지 Push 권한에 필요한 Action
이미지를 push하려면 layer upload를 시작하고, 분할 업로드하고, 업로드를 완료한 뒤 image manifest를 등록하는 권한이 필요합니다.
CI/CD에서 push 권한을 줄 때는 대상 repository ARN을 좁히는 것이 좋습니다. 운영 계정 전체 repository에 push 권한을 주면 잘못된 이미지가 다른 서비스 repository에 올라갈 수 있습니다.
또한 image tag immutability, scan on push, lifecycle policy 같은 저장소 운영 설정도 함께 고려해야 합니다.
레포별 권한 설계 예시
레포별 권한 설계는 서비스 단위로 repository를 나누는 환경에 적합합니다. 예를 들어 `payment-api`, `user-api`, `batch-worker` repository가 있고 각 서비스 CI Role만 자기 repository에 push하도록 구성할 수 있습니다.
배포 Role은 pull 권한만 가져야 하고, CI Role은 push 권한을 가져야 합니다. 운영자 Role은 describe와 lifecycle policy 관리 권한을 별도로 가질 수 있습니다.
이렇게 역할을 분리하면 이미지 오염, 실수 push, 불필요한 repository 접근을 줄일 수 있습니다.
| Role | 권한 | 범위 |
|---|---|---|
| CI Role | Push | 자기 서비스 repository |
| Deploy Role | Pull | 배포 대상 repository |
| Security Role | Describe, scan finding 조회 | 전체 repository 또는 태그 조건 |
| Platform Role | repository 생성/정책 관리 | 제한된 운영 계정 |
레지스트리 전체 권한 설계 예시
Registry Policy는 개별 repository push/pull보다 플랫폼 운영 기능에 더 가깝습니다. 예를 들어 중앙 플랫폼 계정이 여러 애플리케이션 계정의 repository를 만들거나, cross-account replication을 구성하거나, pull-through cache를 관리하는 경우에 사용합니다.
조직 단위로 ECR을 운영한다면 registry policy는 매우 강한 권한이 될 수 있습니다. 따라서 특정 feature에 필요한 action만 허용하고, 가능하면 특정 principal로 제한해야 합니다.
레지스트리 전체 정책은 실수 영향 범위가 크기 때문에 변경 전후로 CloudTrail, EventBridge, AWS Config 같은 감사 흐름을 함께 두는 것이 좋습니다.
Tag 기반 ECR 권한 제어
Amazon ECR은 tag 기반 권한 제어에도 사용할 수 있습니다. 공식 문서 기준으로 ECR은 `aws:ResourceTag`, `ecr:ResourceTag`, `aws:RequestTag`, `aws:TagKeys` 같은 조건키를 지원합니다.
예를 들어 `Environment=prod` 태그가 붙은 repository에는 특정 운영 Role만 push할 수 있게 하고, 개발 repository에는 개발팀 CI Role만 접근하게 만들 수 있습니다.
다만 태그 기반 권한은 태그 변경 권한과 함께 봐야 합니다. repository tag를 마음대로 바꿀 수 있는 주체가 있으면 권한 우회가 가능해질 수 있습니다.
Cross-Account ECR 접근 권한 설정
다른 계정에서 이미지를 pull하거나 push해야 한다면 cross-account 권한을 설계해야 합니다. 예를 들어 빌드 계정에서 운영 계정 ECR로 push하거나, 운영 계정 ECS가 중앙 ECR 이미지를 pull하는 구조입니다.
이때 repository owner 계정에서는 repository policy로 외부 Role을 Principal에 추가해야 합니다. 외부 계정에서는 해당 Role의 IAM Policy에 ECR action과 대상 repository ARN을 허용해야 합니다.
권한 오류가 발생하면 양쪽 계정의 CloudTrail을 확인해야 합니다. 한쪽 정책만 보면 원인을 놓치기 쉽습니다.
ECR 권한 오류 점검 순서
ECR 권한 오류는 대부분 인증 토큰, repository ARN, cross-account policy, 명시적 Deny, region 불일치에서 발생합니다.
먼저 `ecr:GetAuthorizationToken` 권한이 있는지 확인합니다. 그다음 Docker가 로그인한 registry와 실제 push/pull 대상 repository의 account, region이 맞는지 확인합니다.
그 후 IAM Policy, Repository Policy, Registry Policy, SCP, Permission Boundary를 순서대로 보면 됩니다.
운영 기준: 어떤 정책을 어디에 써야 하나
운영 기준은 명확하게 나누는 것이 좋습니다. 일반 사용자와 애플리케이션 Role의 권한은 IAM Policy로 관리하고, 외부 계정이나 특정 repository 공유는 Repository Policy로 관리합니다.
Registry Policy는 repository 생성, replication, pull-through cache 같은 registry-level 기능에 제한적으로 사용합니다. 모든 repository 접근을 registry policy 하나로 해결하려 하면 영향 범위가 커집니다.
결론적으로 ECR 권한은 레포별, 레지스트리 전체, IAM 권한을 섞어 쓰되 책임 범위를 명확히 해야 합니다.
| 목적 | 권장 정책 | 이유 |
|---|---|---|
| 서비스별 push/pull | IAM Policy | Role 중심 최소 권한 관리 |
| 외부 계정 pull 허용 | Repository Policy + 외부 IAM Policy | resource 기반 공유 필요 |
| Replication | Registry Policy | 레지스트리 수준 기능 |
| Pull-through cache | Registry Policy | 레지스트리 수준 rule 관리 |
| Repository 생성 권한 | IAM Policy 또는 Registry Policy | 운영 모델에 따라 선택 |
이 글은 Amazon ECR repository policies, registry permissions, IAM integration, tag-based access control 공식 문서를 기준으로 작성했습니다.
SUMMARY
FAQ
ECR Repository Policy만 있으면 이미지를 pull할 수 있나요?
repository 접근은 허용될 수 있지만 registry 인증을 위해 ecr:GetAuthorizationToken 권한이 IAM Policy에 필요합니다.
Registry Policy는 모든 repository 권한을 관리하는 용도인가요?
가능한 action 범위는 넓지만, 운영상 replication, pull-through cache, repository creation 같은 registry-level 기능에 제한적으로 쓰는 것이 안전합니다.
Cross-account ECR 접근은 어디에 권한을 줘야 하나요?
repository owner 계정의 Repository Policy와 외부 계정의 IAM Policy가 모두 필요합니다. 양쪽 중 하나라도 빠지면 접근이 실패할 수 있습니다.
Amazon ECR 정책은 레포별 정책, 레지스트리 전체 정책, IAM 권한을 구분해서 설계해야 합니다. Repository Policy는 특정 repository 공유와 cross-account 접근에 적합하고, Registry Policy는 replication이나 pull-through cache 같은 registry-level 기능에 적합합니다. 일반적인 push/pull 권한과 인증 토큰은 IAM Policy로 관리하는 것이 기본입니다. 운영 환경에서는 ecr:* 같은 넓은 권한보다 CI Role, Deploy Role, Platform Role을 나눠 최소 권한으로 설계하는 것이 안전합니다.


















