feat(cloud-connection): 연결 가이드 API — 입력값·위치 + 추천 IAM 정책(전체본)

[dldnsgkr]

배경

클라우드 연결 화면에서 사용자는 무슨 값을 어디서 가져와 넣을지, 우리가 접근·처리하려면 어느 수준의 IAM 정책을 붙여야 할지 알 수 없습니다. 그 가이드를 BE 가 단일 소스로 서빙합니다.

API

GET /api/v1/cloud-connections/requirements?provider=AWS&credentialType=ROLE_ARN
→ {
    credentialOptions[{type,label,recommended,summary}],
    fields[{key,label,description,whereToFind,example,required,secret}],
    steps[{order,title,detail}],
    policyName, roleName,
    recommendedPolicy,   // IAM 권한 정책 전체본(JSON) — 그대로 복사해 콘솔에 붙여넣기
    trustPolicy,         // ROLE_ARN 신뢰 정책(JSON), ACCESS_KEY 는 null
    notes[]
  }

기본값 provider=AWS, credentialType=ROLE_ARN. 지금은 AWS만 지원(사용자 결정), GCP 는 400.

핵심 설계

• BE 서빙(하드코딩 금지): 추천 정책은 우리가 실제 호출하는 AWS 액션에서 나옵니다. FE 하드코딩이면 BE 가 액션을 늘릴 때 조용히 낡아 → 새 연결이 배포 때 권한부족으로 죽습니다. 정책을 프로비저닝 코드 옆 리소스 파일(aws/qeploy-aws-*.json)에 두고 통째로 서빙 = 단일 진실원.
• 최소권한: 코드베이스 전수 스캔으로 도출한 9개 서비스(ec2/rds/s3/cloudfront/acm/ssm/iam/sts). S3(qeploy-* 버킷)·SSM(/qeploy/*)·IAM(qeploy-instance-*)로 리소스 스코핑, PassRole 은 ec2.amazonaws.com 조건. ECR 은 image-transfer=ECR 일 때만이라 기본 정책에서 빼고 노트로 안내.
• ROLE_ARN 기본 권장(장기 키 미저장). 신뢰 정책 Principal = Qeploy 컨트롤 플레인 identity, 환경별로 달라 설정으로 받음(qeploy.cloud-connection.guide.platform-principal-arn, env QEPLOY_CLOUD_CONNECTION_PLATFORM_PRINCIPAL_ARN). 미설정이면 placeholder + 경고 노트.
• 왜 필요: 연결 검증은 STS GetCallerIdentity 만 확인하고 프로비저닝 권한은 확인 안 합니다. 그래서 정책을 미리 안 붙이면 연결이 CONNECTED 여도 배포에서 실패 — 이 함정을 화면에서 미리 알리는 게 목적.

검증

• 단위: 정책 리소스 파싱 + 코드가 쓰는 핵심 액션 전부 포함(드리프트 가드), ROLE_ARN/ACCESS_KEY 분기, 신뢰정책 placeholder 치환, GCP 미지원. 전체 스위트 통과.

분담

BE(엔드포인트·정책·콘텐츠·계약) = 이 PR. 슬라이드오버 UI 는 FE 세션에 계약 넘김(채팅 프리뷰 위로 슬라이드).

배포 후 필요

운영에서 QEPLOY_CLOUD_CONNECTION_PLATFORM_PRINCIPAL_ARN 설정 필요(미설정 시 신뢰정책이 placeholder).

🤖 Generated with Claude Code