---
type: Axis
title: orchestration (deployment-topology axis)
description: The orchestration infra architecture axis — how deployable units are packaged, composed, and reconciled (none → single-container → compose → kubernetes → multi-cluster). An infra-altitude (altitude:infra), system-singleton axis whose commitment surface is the deployment configuration-schema (and, at the upper rungs, the orchestrator's durable runtime state). Orthogonal to host-binding (RFC #97 / RFC #75 5A).
tags: [axis, architecture, infra, orchestration, deployment, kubernetes, rfc-97, deep]
timestamp: 2026-06-26T00:00:00Z
---

# Orchestration (deployment-topology axis)

> **DEEP infra axis (4.8.0a2 / #912).** The first of the three infra-altitude
> axes (`altitude: infra`), parallel to the architecture-altitude DEEP axes one
> altitude over. Full §6 depth + the project-type-classifier worked examples.
> It is **orthogonal to host-binding** (orchestration ⊥ host-binding): a tier on
> this axis says nothing about how cloud-coupled the running services are.

## Concept

Orchestration is the **deployment-topology** axis (RFC #97 §"Infra axes"): how a
project's deployable units are packaged, composed, and **reconciled toward a
desired state**. The ladder runs `none` (run the process directly on a host) →
`single-container` (one image, one runtime contract) → `compose` (a declared
multi-container topology on one host) → `kubernetes` (a reconciling control
plane: declared desired state, self-healing, scheduling) → `multi-cluster`
(federated control planes across failure domains). Its **commitment surface is
the deployment configuration-schema** (§4) — the Dockerfile, the compose file,
the k8s manifests are a configuration contract CI, operators, and downstream
deploys depend on — and at the `kubernetes`/`multi-cluster` rungs it additionally
commits **durable runtime state** (the control plane's reconciled desired-state
store). Its **scope is system-singleton** (§5): a project picks one orchestration
tier for the whole deployment.

The project-type classifier gates engagement: a `script` sits at `none`; a `web`
app typically `single-container`/`compose`; a `distributed` system reaches
`kubernetes`+.

## Why it is an axis (discriminator test — §2)

1. **Ordered tiers** — each rung adds a reconciliation/composition capability
   (image → multi-container topology → desired-state control plane → federation).
2. **Cross-cutting bundle** — a rung ripples through the build (image), the
   deploy artifacts, health/liveness, scaling, the CI pipeline, and the tests.
3. **Asymmetric migration cost** — adopting k8s manifests + a control plane is a
   one-way commitment: rolling back to a compose file means discarding the
   reconciliation, scheduling, and self-healing contracts consumers now assume.
4. **Requirement-keyed selection** — falsifiable probes (below) pick the rung.

## Orthogonality (the load-bearing note)

**orchestration ⊥ host-binding.** A `kubernetes` tier on this axis does NOT imply
cloud-specific component use — a Kubernetes project on EKS may *still* use AWS
Cognito for auth, or may be wholly portable CNCF components. Whether the running
services are cloud-coupled is a separate **host-binding** tier choice. So the
render phase NEVER infers "k8s ⇒ cloud services" from this axis; it reads the
host-binding tier. The "k8s needs cloud hosting" intuition is a **soft**
`interactions.yaml` product (`k8s-cloud-affinity`), not a hard requires —
bare-metal / on-prem Kubernetes exists.

## Schema view (the §6 entry — validated by `axis_catalog`)

```yaml
id: orchestration
kind: architecture-axis
altitude: infra
scope: system-singleton
selection:
  probes:
    - "Does the project run a process directly on a host with no packaging? → none."
    - "Is there exactly one deployable image with a single runtime contract? → single-container."
    - "Are multiple containers composed into one declared topology on a single host? → compose."
    - "Must the deployment self-heal, schedule, and reconcile a declared desired state? → kubernetes."
    - "Must the deployment span clusters / failure domains under a federated control plane? → multi-cluster."
    - "Reached a reconciling control plane? It does NOT imply cloud services — that is the host-binding tier (orthogonal)."
composes_with:
  - "k8s-cloud-affinity = orchestration × hosting (SOFT — k8s does not require cloud)"
applies_when: []
tiers:
  - tier: none
    commitment_delta:
      surface: configuration-schema
      delta: "no orchestration artifact; the process is started directly on a host. No image, no topology file."
    admin_tool: "none — start/stop the process by hand or a unit file."
    enforcement:
      - "no hidden container/orchestrator boundary; the host's runtime is the only contract."
    tests:
      - "the process starts + serves on a bare host."
    forecloses: "reproducible packaging; the runtime depends on the host's ambient state."
    migration_cost_to_next: "low — write a Dockerfile + pin the runtime in one image."
  - tier: single-container
    commitment_delta:
      surface: configuration-schema
      delta: "one image with a declared build (Dockerfile) + a single runtime contract (entrypoint, ports, env)."
    admin_tool: "image build + registry push; docker run."
    enforcement:
      - "the image is the deploy unit; the Dockerfile is the reproducible build contract."
    tests:
      - "the image builds reproducibly + the container serves the happy path."
    forecloses: "running outside the image's pinned runtime."
    migration_cost_to_next: "low — declare the multi-container topology in a compose file."
  - tier: compose
    commitment_delta:
      surface: configuration-schema
      delta: "a declared multi-container topology on one host (compose.yaml): services, networks, volumes, depends-on."
    admin_tool: "compose up/down; per-service logs."
    enforcement:
      - "every service + its wiring is declared in the compose file; no undeclared sidecar."
    tests:
      - "compose up brings the full topology to ready; inter-service wiring resolves."
    forecloses: "single-host simplicity becomes a multi-service contract; ad-hoc service starts are off-contract."
    migration_cost_to_next: "high — adopt a control plane: manifests + desired-state reconciliation + scheduling."
  - tier: kubernetes
    commitment_delta:
      surface: durable-runtime-state
      delta: "a reconciling control plane holds the declared desired state (Deployments/Services/etc.) and self-heals toward it; scheduling + scaling are first-class."
    admin_tool: "kubectl apply/rollout; the cluster's desired-state store + controllers."
    enforcement:
      - "every workload is a declared manifest the control plane reconciles; no imperative drift from desired state."
      - "liveness/readiness probes are declared so the control plane can self-heal."
    tests:
      - "applying the manifests converges to ready; killing a pod is self-healed; a rollout is reversible."
    forecloses: "single-host assumptions; the deploy is now a desired-state contract a control plane owns."
    migration_cost_to_next: "high — federate across clusters: cross-cluster identity, networking, and state."
  - tier: multi-cluster
    commitment_delta:
      surface: durable-runtime-state
      delta: "multiple control planes across failure domains under a federation/placement layer; workloads + state are cluster-aware."
    admin_tool: "fleet/federation console; cross-cluster placement + failover."
    enforcement:
      - "every cross-cluster path tolerates a cluster loss; placement + identity span clusters."
    tests:
      - "a cluster loss degrades gracefully; cross-cluster placement + failover are verified."
    forecloses: "single-control-plane reasoning; everything is failure-domain-aware."
    migration_cost_to_next: "n/a — top of the ladder."
examples:
  - "A `web` project climbs none → single-container (a Dockerfile) → compose (app + db + cache on one host) when the dependency set grows. A `distributed` project reaches kubernetes once it needs self-healing + scheduling across replicas. The skill's own daemon sits at `none`/`single-container` by design (per-project, single-machine — see the distribution axis): the orchestration climb is unjustified for a single-operator tool, and a k8s tier here would NOT imply cloud services (host-binding stays cross-host)."
```

## Selection procedure (§8)

Run the bidirectional check: a de-escalation pass (YAGNI — "can I drop a rung?
does anything actually need a control plane?") and an escalation pass ("does any
requirement force self-healing / scheduling / federation?"), gated by the
project-type classifier. The chosen tier is recorded in the project's
`DeploymentRecord` tier vector with rationale + confidence; the drift phase (P4)
flags a deployment whose actual artifacts (a stray compose file under a declared
`kubernetes` tier) diverge from the record.

## Composition (§5)

Orchestration × hosting yields the **soft** `k8s-cloud-affinity` product — k8s is
*often* run on cloud-managed control planes, but bare-metal/on-prem k8s exists,
so the rule is advisory, not a hard requires (authored in `interactions.yaml`).
Orchestration is deliberately kept **orthogonal to host-binding**: the
reconciling-control-plane tier never implies cloud-specific component use.
