시크릿 관리

truloop의 시크릿 관리는 Pulumi ESC와 AWS Secrets Manager 두 계층으로 구성됩니다.

아키텍처

Pulumi ESC (Environments, Secrets, Configuration)

ESC 환경 구조

butbeautiful/
├── aws-base          # AWS OIDC 인증 설정 (공통)
├── infra-dev         # Dev 환경 (aws-base 상속)
└── infra-prod        # Prod 환경 (aws-base 상속)

• aws-base: OIDC Provider를 통한 AWS 인증 설정. pulumi-esc-role을 assume하여 AWS 자격증명을 발급합니다.
• infra-dev: Dev 환경 전용 설정. aws-base를 상속받아 AWS 인증 + Dev Secrets Manager 접근.
• infra-prod: Prod 환경 전용 설정. aws-base를 상속받아 AWS 인증 + Prod Secrets Manager 접근.

OIDC 인증 흐름

Pulumi ESC는 AWS와 OIDC로 연동됩니다. pulumi-esc-role IAM Role이 sts:AssumeRoleWithWebIdentity를 통해 임시 자격증명을 발급합니다.

{
  "Effect": "Allow",
  "Principal": {
    "Federated": "arn:aws:iam::{account}:oidc-provider/api.pulumi.com/oidc"
  },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": {
      "api.pulumi.com/oidc:aud": "aws:butbeautiful"
    }
  }
}

정보

Pulumi ESC OIDC Role에는 AdministratorAccess 정책이 연결되어 있습니다. 인프라 관리에 필요한 모든 AWS API 호출이 가능합니다.

Stack과 ESC 환경 연결

각 Pulumi 스택의 YAML 파일에서 environment 필드로 ESC 환경을 참조합니다.

# Pulumi.dev.yaml
environment:
  - truloop/infra-dev

# Pulumi.prod.yaml
environment:
  - truloop/infra-prod

AWS Secrets Manager

시크릿 패턴

ECS 서비스가 시작할 때 Execution Role을 통해 다음 패턴의 시크릿에 접근할 수 있습니다.

패턴	서비스
dev/truloop-core-*, prod/truloop-core-*	truloop-core (번들 시크릿)
truloop-core-dev/*, truloop-core-prod/*	truloop-core (개별 시크릿)
truloop-ai-server/*	AI Server
truloop-media-service-dev/*, truloop-media-service-prod/*	Media Service
dev/chatter-*, prod/chatter-*	Assistant (Chatter)
dev/truloop-assistant-*, prod/truloop-assistant-*	Assistant
rds!cluster-*	RDS 자동 생성 시크릿
grafana-*-admin-password-*	Grafana 관리자 비밀번호

ECS Task Definition에서의 사용

ECS Task Definition에서 secrets 필드를 통해 Secrets Manager 값을 환경변수로 주입합니다.

{
  "containerDefinitions": [{
    "secrets": [
      {
        "name": "DATABASE_URL",
        "valueFrom": "arn:aws:secretsmanager:ap-northeast-2:{account}:secret:dev/truloop-core-db-url"
      }
    ]
  }]
}

주의

Task Definition은 각 서비스의 CI/CD에서 관리합니다. truloop-infra는 Execution Role의 시크릿 접근 권한만 관리합니다.

IAM 역할 구조

정보

ECS IAM Role과 Policy는 AWS에서 사전 생성되어 있으며, truloop-infra의 EcsRoles 컴포넌트에서 Role.get()과 Policy.get()으로 참조합니다. Pulumi는 Role/Policy 자체는 수정하지 않고, Policy Attachment만 관리합니다.

ECS Task Role (truloop-core-task-role-{env})

서비스가 실행 중 사용하는 권한:

• S3 접근 (미디어 업로드/다운로드)
• SQS 권한 (메시지 송수신)
• RDS/ElastiCache 연결 권한
• CloudWatch Logs/Metrics 권한
• Parameter Store/Secrets Manager 읽기 권한

ECS Execution Role (truloop-core-execution-role-{env})

컨테이너 시작 시 필요한 권한:

• ECR 이미지 풀 권한
• CloudWatch Logs 스트림 생성 권한
• Secrets Manager 시크릿 읽기 권한

정보

Execution Policy 이름이 환경별로 다릅니다: Dev는 truloop-ecs-execution-policy-dev, Prod는 truloop-ecs-execution-policy-prod-v2.

정책 업데이트 방법

정책 파일 수정

ECS Task/Execution 정책은 AWS IAM에서 직접 관리됩니다. truloop-infra의 EcsRoles 컴포넌트는 기존 Role과 Policy를 Role.get(), Policy.get()으로 참조하고, Policy Attachment만 Pulumi로 관리합니다.

Pulumi 적용

pulumi up

Policy Attachment 변경사항이 자동으로 반영됩니다. Execution Role에는 AWS 관리형 AmazonECSTaskExecutionRolePolicy도 함께 연결됩니다.

검증

ECS 서비스는 자동으로 새 권한을 사용합니다. 서비스 재시작이 필요하지 않습니다.

환경 변수 관리

Pulumi Config vs Secrets Manager

용도	저장 위치	예시
인프라 설정	Pulumi Config (YAML)	VPC CIDR, S3 버킷 이름
런타임 자격증명	AWS Secrets Manager	DB 비밀번호, API 키
AWS 인증	Pulumi ESC (OIDC)	AWS Access Key (임시)

위험

시크릿을 Pulumi Config YAML이나 코드에 직접 저장하지 않습니다. 모든 민감한 값은 AWS Secrets Manager에 저장하고, ESC를 통해 참조합니다.

변경 이력

날짜	변경 내용
2026-03-10	소스 코드 검증: IAM 역할 관리 방식(Role.get 참조) 명시, Execution Policy Prod 환경 이름 차이(v2) 추가, AmazonECSTaskExecutionRolePolicy 연결 정보 추가