- Published on
pulumi aws iam role 구성과 운영 체크리스트
- Authors
- Name
- Indo Yoon
Pulumi에서 AWS IAM 역할은 aws.iam.Role로 정의하고, 신뢰 정책과 권한 정책을 분리해 관리하는 방식이 가장 안전해요. 역할 이름과 경로, assume role 정책을 먼저 고정한 뒤 관리형 정책 연결과 인라인 정책을 필요한 만큼만 붙이면 운영 중 권한 변경을 추적하기 쉬워요. 아래 내용은 공식 문서에서 확인한 범위를 기준으로 구성 순서와 점검 항목을 정리한 것이에요.
한눈에 보기
Pulumi에서 IAM 역할을 만들 때 핵심은 "누가 이 역할을 맡을 수 있는가"와 "이 역할이 무엇을 할 수 있는가"를 나눠서 보는 것이에요. 전자는 assumeRolePolicy로 표현하고, 후자는 관리형 정책 연결이나 인라인 정책으로 채워요. 역할 자체는 권한을 직접 가지지 않고, 정책이 붙을 때 비로소 권한이 생긴다는 점을 기준으로 코드 구조를 잡으면 좋아요.
aws.iam.Role: 역할의 이름, 경로, 설명, 신뢰 정책, 권한 경계 같은 기본 속성을 정의해요.aws.iam.RolePolicyAttachment: AWS 관리형 정책이나 고객 관리형 정책을 역할에 연결해요.aws.iam.RolePolicy: 역할에만 쓰는 인라인 정책을 정의해요.aws.iam.Policy: 여러 역할에서 재사용할 고객 관리형 정책을 만들어요.aws.iam.InstanceProfile: EC2 인스턴스에 역할을 전달할 때 함께 정의해요.aws.iam.OpenIdConnectProvider: EKS의 서비스 계정 역할처럼 외부 자격 증명 공급자와 신뢰 관계를 맺을 때 검토해요.
Pulumi 코드에서는 정책 문서를 문자열로 직접 붙이기보다 aws.iam.getPolicyDocument 데이터 소스를 쓰면 JSON 구조를 읽기 쉽게 유지할 수 있어요. 정책 문장이 길어질수록 문자열 결합보다 데이터 소스와 명시적인 변수 이름이 리뷰에 유리해요.
역할과 정책의 관계 비교
| 항목 | 하는 일 | Pulumi에서 주로 쓰는 리소스 | 확인할 점 |
|---|---|---|---|
| 역할 | AWS 서비스나 사용자가 맡을 수 있는 자격 증명 단위예요. | aws.iam.Role | 신뢰 정책의 주체와 조건을 먼저 확인해요. |
| 신뢰 정책 | 누가 역할을 맡을 수 있는지 정해요. | aws.iam.Role의 assumeRolePolicy | 서비스 주체, 계정, 외부 공급자 조건을 최소화해요. |
| 관리형 정책 연결 | 재사용 가능한 정책을 역할에 붙여요. | aws.iam.RolePolicyAttachment | AWS 관리형 정책인지 고객 관리형 정책인지 구분해요. |
| 인라인 정책 | 해당 역할에만 적용되는 권한을 정의해요. | aws.iam.RolePolicy | 역할과 함께 바뀌는 권한인지 검토해요. |
| 권한 경계 | 역할이 가질 수 있는 최대 권한을 제한해요. | aws.iam.Role의 permissionsBoundary | 경계 정책과 실제 정책의 교집합을 이해해요. |
| 인스턴스 프로파일 | EC2에 역할을 전달하는 컨테이너 역할을 해요. | aws.iam.InstanceProfile | 역할과 프로파일을 같은 스택에서 관리해요. |
| 태그 | 소유자, 환경, 비용 추적 기준을 남겨요. | aws.iam.Role의 tags | 조직의 태그 규칙과 일치하는지 확인해요. |
표에서 알 수 있듯이 역할은 "자격 증명"이고 정책은 "권한 내용"이에요. 역할 하나에 모든 권한을 인라인으로 넣으면 변경 이력이 역할 코드에 뒤섞이기 쉬워요. 반대로 재사용 범위가 넓은 정책을 무리하게 인라인으로 나누면 관리 지점이 늘어나요. 그래서 재사용할 권한은 고객 관리형 정책으로, 해당 역할에만 필요한 예외 권한은 인라인 정책으로 두는 식으로 경계를 정하는 편이 좋아요.
단계별로 역할 만들기
먼저 역할의 사용 목적을 짧은 문장으로 정리해요. 예를 들어 "Lambda 함수가 로그를 쓰고 특정 버킷을 읽는다"처럼 주체와 행동을 함께 적으면 신뢰 정책과 권한 정책을 나누기 쉬워요. 이 단계에서 역할 이름, 경로, 설명, 태그 규칙을 정해 두면 나중에 콘솔과 코드에서 같은 역할을 찾기 수월해요.
다음으로 신뢰 정책을 작성해요. aws.iam.Role의 assumeRolePolicy에는 역할을 맡을 주체를 적어요. AWS 서비스가 역할을 맡는 경우에는 서비스 주체를, 다른 계정이 역할을 맡는 경우에는 계정과 외부 ID 조건을 검토해요. 신뢰 정책은 권한 정책과 다르므로 "이 역할이 무엇을 할 수 있는가"가 아니라 "누가 이 역할을 맡을 수 있는가"를 기준으로 읽어야 해요.
그다음 권한을 붙여요. 여러 역할에서 반복되는 권한은 aws.iam.Policy로 고객 관리형 정책을 만들고 aws.iam.RolePolicyAttachment로 연결해요. AWS가 제공하는 관리형 정책을 쓸 때도 연결 리소스를 사용하면 역할 코드와 정책 연결 코드를 분리할 수 있어요. 해당 역할에만 필요한 좁은 권한은 aws.iam.RolePolicy로 인라인 정책을 두되, 정책 이름과 설명을 역할 목적에 맞게 적어요.
EC2에서 역할을 쓸 때는 aws.iam.InstanceProfile을 함께 만들어요. 인스턴스 프로파일은 EC2 인스턴스가 역할 자격 증명을 얻는 통로이므로 역할만 만들고 끝내면 인스턴스에 연결할 수 없어요. 오토스케일링 그룹이나 시작 템플릿을 코드로 관리한다면 인스턴스 프로파일 이름이 그쪽 설정과 연결되는지도 함께 확인해요.
마지막으로 pulumi preview에서 변경 범위를 확인하고 pulumi up을 실행해요. 역할 이름이나 경로를 바꾸면 교체가 발생할 수 있으므로 미리보기에서 replace 여부를 봐야 해요. 운영 중인 역할이라면 protect 옵션과 태그, 정책 연결 순서를 함께 점검해요. 역할을 기존에 수동으로 만들었다면 pulumi import로 상태에 가져온 뒤 코드와 실제 설정이 같은지 비교하는 절차가 필요해요.
상황별 선택 기준
Lambda 실행 역할은 함수가 로그를 쓰고 필요한 AWS API를 호출하는 데 필요한 권한만 붙여요. 신뢰 정책의 주체는 Lambda 서비스가 되고, 기본 실행 권한과 업무 권한을 분리하면 함수별 최소 권한을 관리하기 쉬워요. 함수 코드가 바뀔 때 역할 권한까지 함께 넓어지지 않도록 정책 연결을 별도 리소스로 두는 편이 좋아요.
ECS에서는 태스크 역할과 실행 역할을 구분해야 해요. 실행 역할은 ECS 에이전트가 이미지 풀과 로그 설정을 처리하는 데 쓰고, 태스크 역할은 애플리케이션 코드가 AWS API를 호출할 때 써요. 실행 역할과 태스크 역할을 합치면 애플리케이션 권한과 플랫폼 권한이 섞이므로, Pulumi 코드에서도 이름과 정책을 분리해 관리하는 것이 안전해요.
EKS의 서비스 계정 권한은 OIDC 공급자와 역할의 신뢰 정책을 함께 봐야 해요. 서비스 계정 토큰의 주체와 조건이 역할의 신뢰 정책과 맞지 않으면 권한이 있어도 역할을 맡을 수 없어요. 이 경우 aws.iam.OpenIdConnectProvider와 aws.iam.Role의 조건을 함께 리뷰하고, 클러스터의 서비스 계정 이름이 바뀌지 않도록 주의해요.
여러 계정을 운영한다면 계정 간 역할 위임을 검토해요. 신뢰 정책에는 대상 계정과 필요한 조건을 명시하고, 권한 정책은 위임받은 역할이 실제로 할 일만 남겨요. 계정 경계를 넘는 역할은 권한이 넓어지기 쉬우므로 Pulumi 스택을 계정별로 나누고, 중앙에서 정책을 배포하더라도 각 계정의 역할 정의는 명확히 남기는 편이 좋아요.
주의할 점
역할 이름과 경로는 처음 정하면 변경 비용이 커질 수 있어요. 이름을 바꾸면 새 역할이 만들어지고 기존 역할을 참조하던 서비스가 영향을 받을 수 있으므로, 처음 정의할 때 조직의 명명 규칙을 확인해요. protect 옵션은 실수로 역할을 삭제하는 일을 줄여 주지만, 폐기 절차까지 막는 것은 아니므로 별도의 해제 절차를 문서화해요.
신뢰 정책에 와일드카드 주체를 넣는 것은 특히 주의해요. 외부 계정이나 서비스가 역할을 맡을 수 있는 범위가 넓어지기 때문이에요. 조건 키를 사용해 특정 조직, 계정, 외부 ID로 제한할 수 있는지 검토하고, 불가피한 예외는 코드 주석과 변경 이력에 이유를 남겨요.
권한 정책은 콘솔에서 붙인 정책과 코드에서 붙인 정책이 쉽게 어긋나요. Pulumi로 관리하는 역할은 콘솔에서 직접 정책을 추가하지 않도록 운영 규칙을 정하고, 부득이하게 수동 변경이 필요하면 pulumi refresh로 상태를 확인한 뒤 코드에 반영해요. 정책 연결을 삭제할 때는 다른 역할이나 서비스가 같은 정책을 참조하지 않는지도 확인해야 해요.
권한 경계를 사용할 때는 경계 정책이 실제 권한을 대체하는 것이 아니라 상한을 정한다는 점을 기억해요. 역할의 권한 정책과 경계 정책의 교집합만 유효하므로, 경계를 추가한 뒤에는 실제 호출이 가능한지 검증해요. 또한 서비스 연결 역할은 서비스가 자동으로 만드는 경우가 많아 직접 관리하기 전에 공식 문서의 생성 조건을 확인하는 것이 좋아요.
자주 묻는 질문
Pulumi에서 IAM 역할과 정책을 꼭 분리해야 하나요?
반드시 분리해야 하는 것은 아니지만, 재사용할 권한과 해당 역할에만 필요한 권한을 구분하면 운영이 쉬워져요. 여러 역할에서 같은 권한을 반복한다면 고객 관리형 정책으로 만들고 RolePolicyAttachment로 연결하는 편이 변경 지점을 줄여 줘요. 역할에만 쓰는 예외 권한은 인라인 정책으로 두되, 이름과 설명을 명확히 남기는 것이 좋아요.
기존에 콘솔로 만든 역할을 Pulumi로 가져올 수 있나요?
pulumi import로 기존 역할을 상태에 가져올 수 있어요. 가져온 뒤에는 코드의 속성과 실제 역할의 신뢰 정책, 정책 연결, 태그가 같은지 확인하고, 미리보기에서 불필요한 교체가 없는지 봐야 해요. 가져오기 전에 역할 이름과 경로를 정확히 확인하는 것이 중요해요.
EC2에서 IAM 역할을 쓰려면 무엇을 함께 만들어야 하나요?
EC2에서는 역할 자체뿐 아니라 인스턴스 프로파일이 필요해요. aws.iam.Role과 aws.iam.InstanceProfile을 함께 정의하고, 인스턴스나 시작 템플릿이 그 프로파일을 참조하도록 연결해요. 역할의 신뢰 정책이 EC2 서비스 주체를 허용하는지도 확인해야 해요.
EKS 서비스 계정에 역할을 연결할 때 가장 먼저 볼 것은 무엇인가요?
OIDC 공급자와 역할의 신뢰 정책 조건을 먼저 봐요. 서비스 계정의 네임스페이스와 이름, 클러스터의 OIDC 공급자가 역할의 조건과 일치해야 해요. 권한 정책보다 신뢰 관계가 어긋나면 역할을 맡을 수 없으므로, Pulumi 코드에서 두 리소스를 같은 검토 단위로 묶는 것이 좋아요.
출처
- Pulumi AWS IAM 가이드: https://www.pulumi.com/docs/iac/clouds/aws/guides/iam/
- Pulumi AWS IAM Role API 문서: https://www.pulumi.com/registry/packages/aws/api-docs/iam/role/
- Pulumi AWS IAM RolePolicyAttachment API 문서: https://www.pulumi.com/registry/packages/aws/api-docs/iam/rolepolicyattachment/
- AWS IAM 역할 사용 설명서: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html
IAM 역할은 만들고 끝나는 리소스가 아니라 배포와 함께 계속 바뀌는 운영 자산이에요. Pulumi 스택 운영 방식과 변경 검토 절차를 함께 정리해 두면 역할 권한이 넓어지는 일을 줄이고, 장애 때 원인을 더 빠르게 찾을 수 있어요. 관련 운영 글은 Pulumi 스택 문서에서 확인할 수 있어요.