Skip to content
SaaS ERP SaaS ERP Docs

English

Purpose

Operators and internal automation can evaluate where a tenant would land (existing node vs new server) without going through the public API gateway (Zuplo). Call the Control Plane Worker directly with Authorization: Bearer (same secret as other internal routes).

Algorithm: decidePlacement_unified_v1 — single path shared with production decidePlacement (prego-control-plane computePlacementDecision in allocation-snapshot.ts).

Endpoint

POST {CONTROL_PLANE_URL}/internal/placement/compute

  • Auth: Authorization: Bearer INTERNAL_API_KEY (or SKIP_INTERNAL_API_AUTH in dev only).
  • Body (JSON):
FieldRequiredDescription
plan_tierNoOne of free, basic, professional, enterprise. Alias: tier. Default basic.
regionNosg, us, or eu. Omitted uses resolveRegion defaults (see placement module).
tenant_idNoEchoed in the response for tracing only; does not change placement (tenant-specific rules are not applied in v1).
  • Response (JSON): placement, candidates, cluster, selected_node_id, decision_reason, region, thresholds, algorithm, optional tenant_id.

Legacy alias

POST /internal/placement-dry-run returns the older shape (createNewServer, etc.) but uses the same unified algorithm and env thresholds (PLACEMENT_MEMORY_PCT_MAX, PLACEMENT_MAX_TENANTS_PER_NODE).

Compute vs apply (enqueue)

ActionRouteEffect
Compute onlyPOST /internal/placement/computeRead-only: no D1 writes, no provision job, no GitHub workflow.
Enqueue provisionPOST /v1/tenants (public) or POST /internal/tenants/:tenantId/enqueue-provisionCreates or updates tenant/job rows and may call triggerProvisionPipeline (Queue or GitHub workflow_dispatch).

Use compute for dashboards and dry-runs; use enqueue when you intend to run Ansible/Pulumi via the existing pipeline.

Idempotency and automation

  • Enqueue paths support idempotency keys where implemented (see tenant create handlers). Calling compute repeatedly is safe (read-only).
  • Do not spam enqueue for the same tenant without checking provision_jobs status — duplicate jobs risk conflicting runs. Prefer checking job status or using documented idempotency keys.

Zuplo

  • These routes are not exposed through Zuplo. Browser clients should not hold INTERNAL_API_KEY. Use server-side scripts, CI, or operator tools with secrets.

Related: Provision pipeline field mapping, Hetzner monitoring & provisioning DoD

한국어

목적

공개 게이트웨이(Zuplo) 없이 Control Plane Worker에 직접 Bearer 인증으로 배치 결과를 조회합니다. 프로덕션과 동일한 decidePlacement_unified_v1 알고리즘을 사용합니다.

엔드포인트

  • POST /internal/placement/compute — 본문: plan_tier(또는 tier), 선택 region, 선택 tenant_id(응답에만 반영).
  • POST /internal/placement-dry-run — 이전 응답 형식 호환.

계산만 vs 적용(enqueue)

  • compute: D1 쓰기 없음, 프로비저닝 큐 없음.
  • enqueue: POST /internal/tenants/:tenantId/enqueue-provision 등 기존 경로 — 실제 파이프라인 트리거.

멱등성

  • compute는 반복 호출 안전.
  • enqueue는 job 중복 방지·idempotency 키 정책을 따르세요.

관련: Provision 필드 매핑, DoD

Help