Prego 프로젝트 네이밍 규칙

목적: 서버·DB·테넌트·리소스·로그 등 프로젝트 전반에서 일관된 이름을 쓰기 위한 규칙 정리.
Ref: pulumi-ansible-step1-step2-plan.md, tenant-subdomain-dns-design.md, provision-tenant-workflow-design.md.

1. 공통 규칙

규칙	설명
프로젝트 접두사	인프라·리소스 이름은 `prego` 로 통일 (소문자).
구분자	단어 구분은 하이픈(-). 서브도메인·호스트명·DNS는 소문자·하이픈만.
숫자 패딩	노드·DB 등 순서 번호는 2자리: `01`, `02`, … (예: node-01, db-01).
ID 형식	비즈니스 식별자(tenant_id, job_id)는 UUID 또는 UUID 앞 8자(short_id) 사용.

2. 인프라 (Pulumi / Hetzner / Cloudflare)

2.1 서버 (Hetzner)

용도	패턴	예시
App 서버	`prego-node-{NN}`	`prego-node-01`, `prego-node-02`
DB 서버	`prego-db-{NN}`	`prego-db-01`
라벨 `node-id` (App)	`01`, `02`, …	서버 순번
라벨 `node-id` (DB)	`db01`, `db02`, …	DB 순번
라벨 `project`	`prego`	고정
라벨 `role`	`app` \| `db`	서버 역할

2.2 방화벽

용도	이름	비고
App 서버용	`prego-secure-fw`	SSH(22) 등
DB 서버용	`prego-db-fw`	SSH(22), 3306(App IP만)

2.3 DNS (Cloudflare, base domain: pregoi.com)

용도	패턴	예시
관리용 노드 FQDN	`node-{NN}.pregoi.com`	`node-01.pregoi.com`, `node-02.pregoi.com`
테넌트 canonical (내부)	`tenant-{short_id}.pregoi.com`	`tenant-a1b2c3d4.pregoi.com` (short_id = tenant_id UUID 앞 8자)
사용자 서브도메인	`{subdomain_slug}.pregoi.com`	`acme.pregoi.com` (CNAME → canonical)

2.4 스토리지·기타 리소스

리소스	패턴	예시
R2 버킷	`prego-{용도}`	`prego-static-assets`, `prego-usage-raw`
Placement group	`prego-spread`	Spread 배치용
Volume (Hetzner)	`prego-{role}-data`	`prego-app-data`, `prego-db-data`
SSH 키 (Hetzner 등록명)	`prego-admin`	Pulumi·Ansible 공통

2.5 Pulumi 스택·Config

항목	값
스택 이름	`sg`, `us`, `eu` (리전) 또는 `dev`
Config 네임스페이스	`prego-pulumi` (testMode, serverType, enableBackups 등)

3. 테넌트·사이트 (Frappe / Control Plane)

식별자	형식	용도
tenant_id	UUID	D1, 워크플로, API에서 테넌트 식별. 로그·트레이스에 사용.
short_id	tenant_id 앞 8자	canonical hostname·site_name 생성용.
canonical_hostname (= site_name)	`tenant-{short_id}.pregoi.com`	Frappe site명, DNS A/CNAME, 라우팅·로그의 고정 식별자.
subdomain_slug	사용자 입력 (소문자·하이픈·영숫자)	`acme`, `company-sg` → `acme.pregoi.com` (CNAME).
job_id	UUID	프로비저닝 작업 1건 식별. provision_jobs, 워크플로, 콜백.
node_id	`node-{NN}`	D1 `nodes` 테이블·배치 결과. 기존 노드 재사용 시 해당 노드 ID.

4. Ansible

4.1 인벤토리 호스트·그룹

구분	패턴	예시
그룹 (App)	`prego_nodes`	Frappe·bench 대상
그룹 (DB)	`prego_db_servers`	MariaDB 설치 대상
호스트 (App)	`node_{NN}`	`node_01`
호스트 (DB)	`db_{NN}`	`db_01`

4.2 변수·역할

변수/역할	규칙
`ansible_host`	IP 또는 FQDN (관리용은 `node-NN.pregoi.com` 가능).
컨테이너 이름 (Frappe bench)	`prego-frappe-bench` (기본값).
API Key 이름 (Frappe)	`prego-gateway` (동일 테넌트 내 구분용).
Artifact 파일	`artifacts/tenant_api_key.txt` (경로 통일).

5. Docker·컨테이너

리소스	이름	비고
Frappe bench 컨테이너	`prego-frappe-bench`	docker exec 대상.
MariaDB 컨테이너	mariadb_server role 기본값 유지	예: `prego-mariadb` 등 role에서 정의.

6. 이미지·스냅샷 (Hetzner)

용도	패턴	예시
App 서버 Golden 이미지	`prego-app-{YYYYMMDD}` 또는 `prego-frappe-bench-{v}`	`prego-app-20260221`, `prego-frappe-bench-v15`
DB 서버 이미지	`prego-db-{YYYYMMDD}`	선택.

7. 로그·트레이스·메트릭에서의 일관성

로그·에러 메시지·트레이스에 어디서 무엇이 일어났는지 드러나도록 아래 필드를 권장.

필드	형식	예시
프로젝트	고정 또는 prefix	`prego`
리전	`sg` \| `us` \| `eu`	`sg`
node_id	`node-{NN}` \| `db{NN}`	`node-01`, `db01`
tenant_id	UUID 또는 short_id	`a1b2c3d4-...` 또는 `a1b2c3d4`
job_id	UUID (프로비저닝 시)	`provision_jobs.job_id`
site_name	canonical_hostname	`tenant-a1b2c3d4.pregoi.com`

로그 포맷 예시 (구조화 로그)
[prego][region=sg][node_id=node-01][tenant_id=a1b2c3d4] message
또는 JSON:
{"project":"prego","region":"sg","node_id":"node-01","tenant_id":"a1b2c3d4","event":"..."}

에러·트레이스

provision_jobs 실패: job_id, tenant_id, stage(어느 단계에서 실패) 포함.
API 요청: tenant_id 또는 site_name(canonical) 포함 시 라우팅·과금 추적 용이.

8. 요약 표 (Quick reference)

영역	패턴	예시
서버 (App)	`prego-node-{NN}`	prego-node-01
서버 (DB)	`prego-db-{NN}`	prego-db-01
관리 DNS	`node-{NN}.pregoi.com`	node-01.pregoi.com
테넌트 canonical	`tenant-{short_id}.pregoi.com`	tenant-a1b2c3d4.pregoi.com
사용자 URL	`{subdomain_slug}.pregoi.com`	acme.pregoi.com
R2 버킷	`prego-{용도}`	prego-static-assets
Ansible 그룹	`prego_nodes`, `prego_db_servers`	—
Ansible 호스트	`node_01`, `db_01`	—
Docker (bench)	`prego-frappe-bench`	—
SSH 키 이름	`prego-admin`	—
API Key 이름	`prego-gateway`	Frappe 내부용
node_id (D1/워크플로)	`node-{NN}`	node-01
tenant_id	UUID	—
job_id	UUID	—

이 규칙을 기준으로 신규 리소스·변수·로그 필드를 정하면, 프로젝트 전반에서 이름이 일관되게 유지된다.