Code has to run somewhere. A UML deployment diagram shows the machines and runtimes (nodes), what software is installed on each (artifacts), and the network links between them, labelled with their protocol.
This sample is a classic three-tier web app: a CDN for static files, a load balancer, three identical app servers and a PostgreSQL primary with a read replica.
1. The Diagram
The browser loads static files (JavaScript, CSS, images) from the nearest CDN edge. On a cache miss the CDN fetches from the object storage origin.
API calls go to the load balancer over HTTPS. It terminates TLS, runs health checks and spreads requests across healthy app nodes.
Each app node is a VM running one container, api:1.42, which holds the deployed artifact app.jar. All three run the same version, so any of them can serve any request.
App nodes reach the database over TCP port 5432. Writes go to db-primary; read-heavy queries can go to db-replica.
The primary streams its write-ahead log (WAL) to the replica. Replication is asynchronous, so the replica can be a moment behind; reads that must see the latest write should go to the primary.
2. How to Read It
Nodes can nest: a VM node contains a container execution environment, which contains the artifact. Communication paths are plain lines; the arrow on WAL streaming is only to show the direction of replication.
3. Variant: Same App on Kubernetes
On Kubernetes the VMs disappear from the diagram. The cluster is one execution environment; an Ingress replaces the load balancer, a Service gives the pods one stable address, and a Deployment keeps three pods running, scaled to ten by the Horizontal Pod Autoscaler. The database moves to a managed cloud service with a standby in another availability zone.
4. Pros and Cons
Pros
Shows where every piece runs, which is what operations and security teams need.
Protocols and ports on links feed straight into firewall and security-group rules.
Single points of failure stand out: count the boxes at each tier.
Useful for cost estimates and capacity planning.
A good companion to infrastructure-as-code reviews (Terraform, Helm).
Cons
Goes stale quickly in autoscaled or serverless setups.
Says nothing about code structure or behaviour.
Cloud vendor icons are often used instead of UML nodes, so teams mix styles.
Too much detail (every subnet, every port) hides the main picture.
5. When to Use It
Use it when
Planning a production rollout or a migration to the cloud.
Reviewing high availability, disaster recovery and network security.
The whole app runs on one machine; one sentence is enough.
6. As Diagrams-as-Code
The main diagram written for PlantUML:
@startuml
node "User browser" <<device>> as Browser
cloud "CDN edge" <<cloud service>> as CDN
storage "Object storage" as S3
node "Load balancer" <<device>> as LB
node "app-1 (VM)" as A1 {
node "api:1.42" <<container>> {
artifact "app.jar"
}
}
node "app-2 (VM)" as A2
node "app-3 (VM)" as A3
database "db-primary\nPostgreSQL 16" as P
database "db-replica\nPostgreSQL 16" as R
Browser -- CDN : <<HTTPS>> static files
CDN -- S3 : <<HTTPS>> origin
Browser -- LB : <<HTTPS>> /api
LB -- A1 : <<HTTP>> :8080
LB -- A2 : <<HTTP>> :8080
LB -- A3 : <<HTTP>> :8080
A1 -- P : <<TCP 5432>> writes
A2 -- P
A3 -- P
A1 -- R : <<TCP 5432>> reads
P --> R : <<WAL streaming>>
@enduml
PlantUML has shapes for node, cloud, storage, database and artifact, which map to UML deployment elements. Only app-1 is expanded to keep the text short.