CloudFront SaaS Manager · AWS CLI 가이드

0. 구성 요소와 동작 원리

Cloudflare for SaaS의 "Custom Hostname"에 해당하는 것이 Distribution Tenant입니다. 공통 설정은 멀티테넌트 배포 하나에 두고, 고객 도메인마다 테넌트를 추가합니다.

1. 사전 준비 (SaaS 운영자, 1회) 멀티테넌트 배포 · 연결 그룹

1멀티테넌트 배포 생성

일반 배포와 같은 create-distribution이지만 ConnectionMode를 tenant-only로 둡니다. 배포 자체의 도메인은 없고(DomainName: -), 테넌트 도메인으로만 서비스됩니다. ViewerProtocolPolicy: redirect-to-https가 "HTTP 접속 시 HTTPS 자동 전환"을 담당합니다.

cat > mt-distribution.json <<'JSON'
{
  "CallerReference": "saas-mt-2026-09",
  "Comment": "SaaS multi-tenant distribution (template for tenants)",
  "Enabled": true,
  "ConnectionMode": "tenant-only",
  "HttpVersion": "http2and3",
  "ViewerCertificate": {
    "ACMCertificateArn": "arn:aws:acm:us-east-1:<ACCOUNT>:certificate/<TEMPLATE-CERT>",
    "SSLSupportMethod": "sni-only",
    "MinimumProtocolVersion": "TLSv1.2_2021"
  },
  "Origins": { "Quantity": 1, "Items": [ {
    "Id": "saas-origin",
    "DomainName": "<origin-alb-or-lambda-url-host>",
    "CustomOriginConfig": { "HTTPPort": 80, "HTTPSPort": 443, "OriginProtocolPolicy": "https-only",
                            "OriginSslProtocols": { "Quantity": 1, "Items": ["TLSv1.2"] } }
  } ] },
  "DefaultCacheBehavior": {
    "TargetOriginId": "saas-origin",
    "ViewerProtocolPolicy": "redirect-to-https",
    "AllowedMethods": { "Quantity": 3, "Items": ["GET","HEAD","OPTIONS"], "CachedMethods": { "Quantity": 2, "Items": ["GET","HEAD"] } },
    "Compress": true,
    "CachePolicyId": "4135ea2d-6df8-44a3-9df3-4b5a84be39ad",
    "OriginRequestPolicyId": "b689b0a8-53d0-40ab-baf2-68738e2966ac"
  },
  "TenantConfig": { "ParameterDefinitions": [ { "Name": "tenantName",
    "Definition": { "StringSchema": { "Comment": "tenant id, usable as {{tenantName}} in origin path", "DefaultValue": "root", "Required": false } } } ] }
}
JSON
aws cloudfront create-distribution --distribution-config file://mt-distribution.json \
  --query 'Distribution.[Id,DistributionConfig.ConnectionMode]' --output text
# → E1234567890ABC  tenant-only

캐시 정책 4135ea2d…는 관리형 CachingDisabled, 오리진 요청 정책 b689b0a8…는 관리형 AllViewerExceptHostHeader입니다. 정적 자산이 많으면 경로별 behavior와 캐시 정책을 추가합니다. ViewerCertificate는 tenant-only 배포에도 필요합니다(CloudFormation에서는 생략 시 생성 실패).

2연결 그룹 생성과 RoutingEndpoint 확인

aws cloudfront create-connection-group --name saas-prod-cg --enabled --ipv6-enabled \
  --query 'ConnectionGroup.[Id,RoutingEndpoint]' --output text
# → cg_3JhYw92ZATvxAiJ08zR8sDnkLYx   d10qyq5uv8bdn4.cloudfront.net

# 이미 있는 그룹 조회
aws cloudfront list-connection-groups --query 'ConnectionGroups[].[Id,Name,RoutingEndpoint,IsDefault]' --output table
aws cloudfront get-connection-group --identifier cg_3JhYw92ZATvxAiJ08zR8sDnkLYx --query 'ConnectionGroup.RoutingEndpoint' --output text

RoutingEndpoint가 고객에게 안내할 CNAME 값입니다. 연결 그룹을 지정하지 않으면 계정 기본 그룹이 쓰이지만, 운영에서는 명시적으로 만들어 두는 것이 좋습니다. 고정 IP가 필요한 고객이 있으면 Anycast IP 목록을 연결 그룹에 붙일 수 있습니다.

2. 고객 DNS 설정 (고객사가 수행) CNAME 1개

SaaS 관리 화면에서 고객에게 아래 레코드를 안내합니다. 실제 고객은 자사 DNS(가비아, Cloudflare, Route 53 등)에 등록하고, 시연에서는 Route 53에 대신 등록합니다.

# Route 53 예시 (시뮬레이션): 고객 서브도메인 CNAME
aws route53 change-resource-record-sets --hosted-zone-id <ZONE-ID> --change-batch '{
  "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": {
    "Name": "shop.customer.com", "Type": "CNAME", "TTL": 60,
    "ResourceRecords": [ { "Value": "d10qyq5uv8bdn4.cloudfront.net" } ] } } ] }'

# 전파 확인은 권한 있는 네임서버에 직접 (로컬 리졸버의 NXDOMAIN 부정 캐시 회피)
dig +short @ns-716.awsdns-25.net shop.customer.com CNAME

3. 테넌트 생성 + 관리형 인증서 요청 (SaaS 온보딩 API) CreateDistributionTenant

고객이 DNS를 등록했다는 신호를 받으면 SaaS 백엔드가 이 명령 하나를 호출합니다. ManagedCertificateRequest가 있으면 CloudFront가 ACM 인증서를 대신 요청하고 갱신까지 관리합니다.

aws cloudfront create-distribution-tenant \
  --distribution-id E1234567890ABC \
  --connection-group-id cg_3JhYw92ZATvxAiJ08zR8sDnkLYx \
  --name customer-shop \
  --domains Domain=shop.customer.com \
  --enabled \
  --managed-certificate-request ValidationTokenHost=cloudfront,PrimaryDomainName=shop.customer.com,CertificateTransparencyLoggingPreference=enabled \
  --parameters Name=tenantName,Value=customer-123 \
  --tags 'Items=[{Key=customer,Value=customer-123}]' \
  --query 'DistributionTenant.[Id,Status,Domains[0].Status]' --output text
# → dt_3JhcwGuRQdQpkNCUVsEL4UuSam3   InProgress   inactive

4. 상태 확인 Get / List

# 테넌트 상태 (Status: InProgress → Deployed, Domains[].Status: inactive → active)
aws cloudfront get-distribution-tenant --identifier dt_3JhcwGuRQdQpkNCUVsEL4UuSam3 \
  --query 'DistributionTenant.{Status:Status,Enabled:Enabled,Domains:Domains,Cert:Customizations.Certificate.Arn}' --output json

# 관리형 인증서 상태 (pending-validation → issued) 와 검증 토큰 경로
aws cloudfront get-managed-certificate-details --identifier dt_3JhcwGuRQdQpkNCUVsEL4UuSam3 --output json

# 배포에 속한 테넌트 전체
aws cloudfront list-distribution-tenants --association-filter DistributionId=E1234567890ABC \
  --query 'DistributionTenantList[].[Name,Domains[0].Domain,Domains[0].Status,Status]' --output table

# 도메인으로 테넌트 찾기 / DNS 설정 검증
aws cloudfront get-distribution-tenant-by-domain --domain shop.customer.com --query 'DistributionTenant.Id' --output text
aws cloudfront verify-dns-configuration --domain shop.customer.com --identifier dt_3JhcwGuRQdQpkNCUVsEL4UuSam3

실측 소요 시간: 테넌트 생성 → 인증서 issued 약 5~10분. 온보딩 화면은 5~10초 간격으로 폴링하면 충분합니다.

5. 인증서 연결 (API 직접 호출 시 필요) UpdateDistributionTenant

관리형 인증서가 issued가 되어도 API 경로에서는 테넌트에 자동으로 붙지 않습니다. Customizations.Certificate가 비어 있으면 도메인은 inactive(HTTP 403, TLS 실패)에 머무릅니다. 발급된 인증서 ARN을 연결하면 약 1분 내 active가 됩니다.

TID=dt_3JhcwGuRQdQpkNCUVsEL4UuSam3
CERT=$(aws cloudfront get-managed-certificate-details --identifier $TID --query 'ManagedCertificateDetails.CertificateArn' --output text)
ETAG=$(aws cloudfront get-distribution-tenant --identifier $TID --query ETag --output text)

aws cloudfront update-distribution-tenant --id $TID --if-match $ETAG \
  --distribution-id E1234567890ABC --connection-group-id cg_3JhYw92ZATvxAiJ08zR8sDnkLYx \
  --domains Domain=shop.customer.com --enabled \
  --customizations "Certificate={Arn=$CERT}"

6. 접속 검증 (고객 시연) HTTPS · 자동 전환 · 인증서

# DNS
dig +short shop.customer.com            # → d10qyq5uv8bdn4.cloudfront.net → CloudFront IP

# HTTP → HTTPS 자동 전환 (배포의 ViewerProtocolPolicy)
curl -sI http://shop.customer.com/ | grep -iE "^HTTP|^location"
# HTTP/1.1 301 Moved Permanently
# Location: https://shop.customer.com/

# 인증서: 발급자 Amazon, SAN = 고객 도메인, 유효기간 (자동 갱신)
echo | openssl s_client -servername shop.customer.com -connect shop.customer.com:443 2>/dev/null \
  | openssl x509 -noout -issuer -subject -dates

# 오리진이 본 테넌트 호스트
curl -s https://shop.customer.com/api/whoami

브라우저 시연 동선: 주소창에 http://shop.customer.com 입력 → 주소가 https://로 바뀌는 것 확인 → 자물쇠 클릭 → 발급자 Amazon과 도메인 확인 → 서비스 화면 정상 노출.

7. 도메인 해제 (오프보딩) Disable → Delete

테넌트는 비활성화가 배포에 반영된 뒤에만 삭제할 수 있습니다. 세 단계로 진행합니다.

TID=dt_3JhcwGuRQdQpkNCUVsEL4UuSam3
ETAG=$(aws cloudfront get-distribution-tenant --identifier $TID --query ETag --output text)

# 1) 비활성화
aws cloudfront update-distribution-tenant --id $TID --if-match $ETAG \
  --distribution-id E1234567890ABC --connection-group-id cg_3JhYw92ZATvxAiJ08zR8sDnkLYx \
  --domains Domain=shop.customer.com --no-enabled

# 2) 배포 반영 대기 (Status: InProgress → Deployed, 보통 30~60초)
until [ "$(aws cloudfront get-distribution-tenant --identifier $TID --query 'DistributionTenant.Status' --output text)" = Deployed ]; do sleep 10; done

# 3) 삭제 (새 ETag 필요)
ETAG=$(aws cloudfront get-distribution-tenant --identifier $TID --query ETag --output text)
aws cloudfront delete-distribution-tenant --id $TID --if-match $ETAG

# 고객 DNS 레코드 정리는 고객사가 수행 (시연에서는 Route 53 DELETE)

삭제해도 발급된 ACM 인증서는 남습니다. 다른 CloudFront 리소스에 재사용할 수 있고, 불필요하면 aws acm delete-certificate로 정리합니다. 도메인을 다른 배포로 옮길 때는 삭제 대신 update-domain-association을 씁니다.

8. 온보딩 서비스의 최소 IAM 권한

SaaS 온보딩 백엔드(예: ECS 태스크 역할)에 필요한 권한만 부여합니다. 배포 자체를 바꾸는 권한(UpdateDistribution)은 포함하지 않습니다.

{
  "Version": "2012-10-17",
  "Statement": [
    { "Sid": "TenantLifecycle", "Effect": "Allow", "Action": [
        "cloudfront:CreateDistributionTenant", "cloudfront:UpdateDistributionTenant", "cloudfront:DeleteDistributionTenant",
        "cloudfront:GetDistributionTenant", "cloudfront:GetDistributionTenantByDomain", "cloudfront:ListDistributionTenants",
        "cloudfront:GetManagedCertificateDetails", "cloudfront:VerifyDnsConfiguration", "cloudfront:ListDomainConflicts",
        "cloudfront:TagResource", "cloudfront:UntagResource", "cloudfront:ListTagsForResource" ], "Resource": "*" },
    { "Sid": "ReadShared", "Effect": "Allow", "Action": [
        "cloudfront:GetConnectionGroup", "cloudfront:ListConnectionGroups", "cloudfront:GetDistribution", "cloudfront:ListDistributions" ], "Resource": "*" },
    { "Sid": "ManagedCertificates", "Effect": "Allow", "Action": [
        "acm:RequestCertificate", "acm:DescribeCertificate", "acm:ListCertificates", "acm:AddTagsToCertificate", "acm:GetCertificate" ], "Resource": "*" },
    { "Sid": "ServiceLinkedRole", "Effect": "Allow", "Action": "iam:CreateServiceLinkedRole", "Resource": "*",
      "Condition": { "StringLike": { "iam:AWSServiceName": "cloudfront.amazonaws.com" } } }
  ]
}

9. 주의사항 · 한도 · 비용

10. Cloudflare for SaaS 대응표