---
status: accepted
date: 2026-04-07
---

# Three Named Deployment Profiles

**ID**: `cpt-cf-adr-deployment-profiles`

## Table of Contents

<!-- generated by `cypilot toc` -->

## Context and Problem Statement

ToolKit gears can theoretically be deployed in many combinations: in-process, one-per-process, several-per-process,
on the same host, across hosts, in Kubernetes pods, etc. Arbitrary combinations create a combinatorial explosion of
configurations that are hard to test, document, and support. How should the platform constrain deployment topologies?

## Decision Drivers

* **Testability**: Each supported topology must be fully tested in CI. Fewer named profiles = more thorough test coverage.
* **Operator clarity**: Platform operators need a clear menu, not an unbounded configuration space.
* **Backward compatibility**: The existing embedded (single-process) model must remain the default.
* **Future extensibility**: The chosen profiles must cover on-premise single-host, on-premise multi-host, and
  Kubernetes-native deployments.

## Considered Options

* **Option A**: Arbitrary composition — operators choose per-gear placement with no predefined profiles.
* **Option B**: Three named profiles — Embedded (1), Host+Workers (2), K8s Native (3).
* **Option C**: Two profiles only — Embedded and K8s Native (skip the on-premise multi-process case).

## Decision Outcome

Chosen option: **"Three named deployment profiles"**, because it covers the three distinct operational environments
(single-process, on-premise multi-process, Kubernetes) with a manageable test matrix while keeping the door open for
on-premise customers who cannot run Kubernetes.

### Profile 1: Embedded

All gears run in a single process managed by `HostRuntime`. This is the current default — no changes needed. Inter-gear
calls are in-process via ClientHub.

### Profile 2: Host + Workers

The Platform Host spawns OoP Worker processes on the same host (or across hosts for the multi-node P2 variant). Workers
communicate with the host via UDS (single-node) or TCP+mTLS (multi-node). The Platform Host runs Flight Control
(DirectoryService) and system gears; Workers run application gears.

### Profile 3: K8s Native

Each gear runs as an independent Kubernetes pod. Service discovery uses K8s DNS
(`{gear}.{namespace}.svc.cluster.local`) and optionally DirectoryService. An external gateway (Kong/Tyk/Envoy) handles
public API ingress. SA tokens provide platform-plane identity; mTLS+SPIFFE (cert-manager) is the next phase.

### Consequences

* The platform tests exactly three topologies — not arbitrary combinations.
* Operators choose a profile by name. Documentation, Helm charts, and configuration presets are organized per profile.
* Gear code is agnostic to the profile — the framework (bootstrap, ClientHub wiring, gateway registration) handles all
  topology differences. Gear developers never import profile-specific code.
* New profiles (e.g., serverless, edge) can be added later without changing the framework contract — they are new
  bootstrap implementations behind the same gear trait.

### Confirmation

* Architecture review: verify that all design components (bootstrap, gateway, codegen) are described in terms of the
  three profiles.
* Documentation review: verify that operator docs reference profiles by name.

## Traceability

- **PRD**: [PRD.md](../PRD.md)
- **DESIGN**: [DESIGN.md](../DESIGN.md)

This decision directly addresses the following requirements or design elements:

* `cpt-cf-fr-developer-transparency` — Gear code is profile-agnostic
* `cpt-cf-fr-k8s-native` — Profile 3 is dedicated to K8s
* `cpt-cf-principle-deploy-transparency` — The deployment transparency principle is grounded in this decision
* `cpt-cf-constraint-backward-compat` — Profile 1 preserves the existing embedded behavior
