llm-wiki/raw/company-tech-blogs/multitenancy-subdomain-resolution-patterns.md

title, source_type, status, confidence, url, archive_url, tags, related_projects, related_branches, created, last_reviewed

title	source_type	status	confidence	url	archive_url	tags	related_projects	related_branches	created	last_reviewed
Subdomain-based Tenant Resolution — Practical Notes (Vercel / Supabase 사례)	company-tech-blog	raw	medium	https://vercel.com/docs/multi-tenant		ca-multi-tenancy subdomain dns tls tenant-resolution vercel company-tech-blog	ca-skeleton-operational-contract	feature-tenant-context-policy feature-repository-access-permission-contract	2026-05-22	2026-05-27

Subdomain-based Tenant Resolution — 실무 메모

Layer: raw/company-tech-blogs/ — Vercel 의 multi-tenant 가이드 발췌. Vercel 은 platform vendor 이지만 본 자료는 product overview / blog style 이므로 company-tech-blog / 사례 로 취급. 공식 best practice 가 아닌 vendor 의 권장 패턴. ca-tmpl 이 subdomain 방식을 resolution 3순위 (fallback) 로 둔 결정의 대안 평가.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-tenant-context-policy	subdomain 을 tenant resolution 1순위 가 아닌 3순위 (fallback) 로 둔 결정 — Vercel 의 운영 비용 (wildcard cert, custom domain 자동화) 을 회피한다는 trade-off 근거
raw/branch-notes/feature-repository-access-permission-contract	tenant 식별이 hostname 에서 오는 경우 host header injection 방어 필요 — capability 검증 layer 의 trust boundary 결정 근거
raw/project-notes/ca-skeleton-operational-contract	§18. Control Plane Contract (Tenant Context Policy) — subdomain 채택 시점에 대한 future-state 참고 (end-user facing web 추가 시)

컨텍스트 / 왜 저장했는지

ca-tmpl 이 subdomain 방식을 resolution 3순위 (fallback) 로 둔 결정의 대안 평가. 만약 subdomain 을 1순위로 선택한다면 어떤 운영 부담이 있는지 정리.

출처 / Source

• 원본 URL: https://vercel.com/docs/multi-tenant — 2026-05-27 fetch 성공. 단 high-level overview 이며 세부 구현 (wildcard DNS / TLS rate limit / local dev) 은 다루지 않음
• 원래 가이드 (404): https://vercel.com/guides/nextjs-multi-tenant-application — 2026-05-27 확인 시 페이지 이전 / 통합
• 보조 (개념): Supabase, Cloudflare for SaaS (custom hostname) — 별도 자료
• 저자 / 조직: Vercel
• 발행일: page metadata last_updated: 2025-12-18
• 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Vercel for Platforms — opening] "A multi-tenant application serves multiple customers (tenants) from a single codebase."

[§Vercel for Platforms — opening] "Each tenant gets its own domain or subdomain, but you only have one Next.js (or similar) deployment running on Vercel. This approach simplifies your infrastructure, scales well, and keeps your branding consistent across all tenant sites."

[§Why build multi-tenant apps — example] "A root domain for your platform: acme.com / Subdomains for tenants: tenant1.acme.com, tenant2.acme.com / Fully custom domains for certain customers: tenantcustomdomain.com"

[§Why build multi-tenant apps] "Vercel's platform automatically issues SSL certificates, handles DNS routing via its Anycast network, and ensures each of your tenants gets low-latency responses from the closest CDN region."

[§Getting started — starter kit features] "Custom subdomain routing with Next.js middleware / Tenant-specific content and pages / Redis for tenant data storage / Admin interface for managing tenants / Compatible with Vercel preview deployments"

[§Multi-tenant features on Vercel] "Unlimited custom domains / Unlimited *.yourdomain.com subdomains / Automatic SSL certificate issuance and renewal / Domain management through REST API or SDK / Low-latency responses globally with the Vercel CDN / Preview environment support to test changes / Support for 35+ frontend and backend frameworks"

[§Let's Encrypt rate limit — 과거 정독, 본문 미수록 / 재검증 불가] "Let's Encrypt has a rate limit of 50 certificates per registered domain per week, which can throttle onboarding if not using wildcard or a CDN-managed cert provider."

[§Local dev — 과거 정독, 본문 미수록 / 재검증 불가] "Local development requires hosts file modification or a wildcard DNS provider like nip.io / lvh.me."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
MT-SUBDOM-C1	multi-tenant 앱은 단일 codebase 로 여러 고객 (tenant) 에게 서비스 — 각 tenant 는 자신의 domain 또는 subdomain 을 가짐	[§Vercel for Platforms — opening] "A multi-tenant application serves multiple customers (tenants) from a single codebase." + "Each tenant gets its own domain or subdomain, but you only have one Next.js (or similar) deployment running on Vercel."	company-case-study	Vercel 의 platform 모델을 따르는 Next.js / 유사 framework 배포	"단일 codebase" 가 모든 multi-tenant 패턴의 요건이라는 뜻은 아님 (Deployment Stamps 같은 multi-deployment 패턴 별도)
MT-SUBDOM-C2	tenant 식별의 hostname 패턴: root domain (acme.com) + per-tenant subdomain (tenant1.acme.com) + 일부 enterprise 의 fully custom domain (tenantcustomdomain.com)	[§Why build multi-tenant apps — example] "A root domain for your platform: acme.com / Subdomains for tenants: tenant1.acme.com, tenant2.acme.com / Fully custom domains for certain customers: tenantcustomdomain.com"	company-case-study	subdomain + custom domain 혼합 운영하는 SaaS	custom domain 이 항상 enterprise tier 전용이어야 한다는 뜻 아님 — Vercel 의 운영 패턴 사례
MT-SUBDOM-C3	Vercel platform 은 SSL 인증서 자동 발급, Anycast DNS routing, CDN 최적화를 platform 차원에서 제공	[§Why build multi-tenant apps] "Vercel's platform automatically issues SSL certificates, handles DNS routing via its Anycast network, and ensures each of your tenants gets low-latency responses from the closest CDN region."	company-case-study	Vercel platform 사용 시	self-host 시에도 동일한 자동화가 보장된다는 뜻 아님 — Vercel 종속적 capability
MT-SUBDOM-C4	Vercel 의 multi-tenant feature: 무제한 custom domain, 무제한 *.yourdomain.com subdomain, SSL 자동 갱신, REST API/SDK 기반 domain 관리, preview environment 지원	[§Multi-tenant features on Vercel] "Unlimited custom domains / Unlimited *.yourdomain.com subdomains / Automatic SSL certificate issuance and renewal / Domain management through REST API or SDK / Low-latency responses globally with the Vercel CDN / Preview environment support to test changes"	company-case-study	Vercel for Platforms 가입	"무제한" 의 정확한 fair-use / pricing 임계는 본 인용 범위 밖 — /docs/multi-tenant/limits 별도 확인
MT-SUBDOM-C5	Next.js middleware 가 custom subdomain routing 의 표준 구현 패턴 (Vercel starter kit 의 feature 로 명시)	[§Getting started — starter kit features] "Custom subdomain routing with Next.js middleware"	company-case-study	Next.js + Vercel 조합	middleware 가 hostname 을 어떻게 파싱/검증하는지의 구체 구현은 본 인용 범위 밖 — starter kit 코드 별도 확인
MT-SUBDOM-C6	Let's Encrypt 의 인증서 발급 rate limit (도메인당 주 50개) 이 tenant onboarding 속도의 제약 — wildcard 또는 CDN-managed cert provider 사용 시 회피 가능	[§Let's Encrypt rate limit — 과거 정독] "Let's Encrypt has a rate limit of 50 certificates per registered domain per week, which can throttle onboarding if not using wildcard or a CDN-managed cert provider."	needs-confirmation	Let's Encrypt 사용 SaaS	본 Vercel docs 본문에는 미수록. Let's Encrypt 공식 rate limit 문서로 직접 verbatim 검증 필요
MT-SUBDOM-C7	local dev 환경에서 subdomain 테스트는 hosts 파일 수정 또는 nip.io / lvh.me 같은 wildcard DNS provider 가 필요	[§Local dev — 과거 정독] "Local development requires hosts file modification or a wildcard DNS provider like nip.io / lvh.me."	needs-confirmation	local 개발 환경에서 subdomain routing 테스트	본 Vercel docs 본문에는 미수록. 별도 dev 가이드 확인 필요

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • C1~C5: Vercel 의 multi-tenant feature 와 hostname 패턴 (root / subdomain / custom domain)
  • Next.js middleware 가 Vercel 의 표준 subdomain routing 구현임 (starter kit 의 feature)
• 이 자료가 증명하지 않는 것:
  • C6, C7: Let's Encrypt rate limit 과 local dev workaround 는 본 docs 본문에 없음 (needs-confirmation)
  • subdomain takeover 의 위험 / 방어 패턴 (본 docs 미언급)
  • host header injection 방어 (본 docs 미언급)
  • cross-subdomain cookie / SSO 설정 (본 docs 미언급)
  • mobile app 의 UX 차이 (본 docs 는 web 중심)
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 이 subdomain 으로 전환 시 self-host (non-Vercel) 환경에서 cert-manager + Let's Encrypt 자동화 cost
  • subdomain 1순위 채택의 trigger 조건 (end-user facing UI 추가 / brand 가치 / API 외 web 확장)
  • JWT claim 과 subdomain 이 mismatch 일 때의 처리 정책 (예: JWT 의 tenant ≠ hostname tenant)

메모 / Notes (내 해석, 미검증)

• isolation 수준: resolution 방식이라 isolation과 직교. shared/schema/db 어느 모델과도 결합 가능.
• tenant resolution 방식: subdomain 단독. 보통 reverse proxy/gateway가 Host header에서 tenant 추출 후 downstream에 X-Tenant-Id 또는 context로 전파.
• scale 한계:
  • DNS propagation 시간 (수 분~수십 분)
  • TLS 인증서 발급 rate limit (Let's Encrypt 주 50개/도메인) — C6 참조
  • wildcard 인증서를 쓰면 위 제약 없으나 custom domain 지원 시 별도 자동화 필요
• 운영 복잡도:
  • DNS 관리 자동화 (Route53/Cloudflare API)
  • TLS 자동화 (cert-manager, ACM)
  • local dev 환경 (lvh.me 등) — C7 참조
  • CORS 설정이 wildcard origin으로 복잡
• security:
  • Host header injection 방어 필수 (allowlist)
  • subdomain takeover 위험 (tenant 삭제 후 DNS record 미정리)
• 장점:
  • UX (북마크, 공유)
  • tenant 별 brand
  • CDN 캐싱 정책을 hostname 단위로 분리 가능
• 단점:
  • 위 운영 부담 전반
  • mobile app에서는 UX 이점이 적음 (사용자가 URL을 보지 않음)
  • JWT/session 쿠키 domain 설정 까다로움 (cross-subdomain SSO 필요 시 parent domain cookie)
• ca-tmpl과의 차이:
  • ca-tmpl은 B2B API 중심 가정 → subdomain의 UX 이점이 약함 → JWT claim 우선.
  • subdomain 1순위 채택 시점: end-user facing web app + tenant brand가 product value의 일부일 때 (e.g. Notion, Slack, Linear).

Related / 관련

• 같은 주제 다른 raw:
  • raw/company-tech-blogs/multitenancy-auth0-tenant-resolution (JWT claim 우선 vs subdomain 비교)
  • raw/company-tech-blogs/multitenancy-atlassian-tenant-context
  • raw/official-docs/multitenancy-azure-architecture-patterns
• 인용하는 branch / project:
  • raw/branch-notes/feature-tenant-context-policy
  • raw/branch-notes/feature-repository-access-permission-contract
  • raw/project-notes/ca-skeleton-operational-contract (§18 Control Plane Contract)
• 대안 그룹: Topic 6 — Multi-tenancy (대안 6종). 본 source 의 위치: 대안 1 — subdomain-based resolution.
• 인용한 wiki 요약: (미작성)