The deployment model

A deployment diagram answers one question the C4 levels never do: where does the software actually run?

C4 tells you an API and a database exist and talk to each other. Deployment tells you the API runs as three pods across two availability zones, and the database is a managed instance with a standby replica. Same system — a completely different question.

A separate axis, not a fifth level

It's tempting to treat "where it runs" as just another C4 zoom level. It isn't. C4 zooms through logical structure; deployment zooms through infrastructure. The two are orthogonal:

graph TD
  subgraph Logical["Logical model (C4)"]
    API["Container: API"]
    DB["Container: Database"]
  end
  subgraph Infra["Deployment model"]
    P1["Instance: API pod 1"]
    P2["Instance: API pod 2"]
    P3["Instance: API pod 3"]
    DBI["Instance: Managed DB + replica"]
  end
  API -.->|"deploys as"| P1
  API -.->|"deploys as"| P2
  API -.->|"deploys as"| P3
  DB -.->|"deploys as"| DBI
  • A single container (logical) may map to many running instances (replicas across zones).
  • One deployment node may host several different containers.
  • The same logical model deploys differently per environment — dev on one node, production across a cluster.

Forcing "where it runs" onto a Container diagram is the most common way Container diagrams turn into unreadable mush. That's exactly why deployment gets its own diagram.

The building blocks

  • Deployment node — a piece of infrastructure: an environment, a region, a cluster, a host, or a managed service. Nodes nest to show containment — a region holding a cluster holding compute hosts.
  • Container instance — a deployed copy of a container from your logical model, placed inside the node that hosts it. This is the bridge between the two worlds: a node contains instances of containers you already defined in C4.
  • Connection — a link between nodes or instances that communicate across infrastructure, labeled with the transport where it matters.

The golden rule for staying consistent: reuse the containers from your logical model rather than inventing new boxes. That shared identity is what lets a reader cross from "what the system is" to "where it lives" without guessing.

Deployment has its own altitude

Just as C4 zooms, infrastructure zooms — and you pick the altitude that suits the audience. Choose one per diagram and stay there:

AltitudeShowsAudience
ConceptualEnvironments and tiers, no vendor specificsArchitects, reviewers, customers
PlatformNamed platform constructs — clusters, node pools, managed servicesPlatform and app engineers
PhysicalConcrete instances, sizes, zones, networkingOps, SRE, whoever provisions it

A conceptual diagram for a customer and a physical one for your SRE team are two views of the same topology. Don't merge them — mixing altitudes serves no single reader well.

One diagram per environment

Dev, staging, and production usually differ enough that a single diagram either misrepresents some of them or drowns in conditionals. When environments diverge, draw a view per environment. The fan-out — one logical container becoming several running instances — is the whole point of the diagram, and it looks different in each environment.

Tips & tricks

  • Show instance counts. "× 3" on an instance tells the scaling story at a glance.
  • Name what connects to what. Label connections crossing infrastructure with their transport where it matters.
  • Include the plumbing that shapes behavior — load balancers, gateways, queues — and connect them; an orphaned box is clutter.
  • Draw the actual topology, not the aspirational one. A diagram of the deployment you wish you had misleads everyone.
  • Reuse logical containers. Every instance should trace back to a container in your C4 model — an instance with no logical counterpart means the two views have drifted.

Common pitfalls

  • Collapsing deployment into Container. Regions, nodes, and replica counts showing up on a Container diagram is the signal to split deployment out.
  • Mixing altitudes. Conceptual tiers sitting next to concrete instance sizes on one canvas.
  • One diagram for all environments. Prefer a view per environment when they diverge.
  • Modeling infrastructure you don't deploy. Show the topology your system occupies, not the entire cloud account.

Where next