UML Deployment Diagrams

A deployment diagram shows where software physically runs: the machines, containers and managed services, which build artifacts are installed on each, and how they talk over the network. Operations engineers, SREs, security reviewers and architects read it.

1. What a Deployment Diagram Shows

Every other UML structure diagram describes software in the abstract. The deployment diagram ties it to reality: this container image runs in these two tasks, in these availability zones, talking to this database over that protocol. It is the diagram you want during an incident, a security review, or a cost discussion.

It has two flavours. A specification-level diagram shows node types ("an app server"), useful early in design. An instance-level diagram shows the actual machines ("web-01, web-02"), useful for operations.

2. Notation

A node is a 3D box: hardware («device») or a software runtime («executionEnvironment», such as a JVM, a container or a Kubernetes cluster). Nodes nest. An artifact is a dog-eared rectangle representing a deployable file: a JAR, wheel, container image or SQL script. A solid line between nodes is a communication path, usually labelled with the protocol. A dashed «deploy» arrow can connect an artifact to its node, and «manifest» links an artifact to the component it implements.

3. Example 1: Online Shop on AWS

Walkthrough: browsers connect over HTTPS to an Application Load Balancer, which spreads requests over two ECS tasks in different availability zones. Both run the same artifact, shop-api:1.4. Each task talks to Postgres on RDS, Redis on ElastiCache and S3 for images. The picture immediately raises useful questions: is RDS also multi-AZ? Which security groups allow the task-to-Redis path? What happens when version 1.5 is half-rolled out?

4. Example 2: A Data Pipeline on Kubernetes

Walkthrough: a Spark job runs inside a Kubernetes cluster as one driver pod (carrying etl.py) and N executor pods. It reads from a three-broker Kafka cluster over TLS and writes to a cloud warehouse over JDBC. Nesting pods inside the cluster node shows that Kubernetes is an execution environment, while the external Kafka and warehouse are separate nodes with their own failure domains.

5. Pros, Cons, and When to Use

Pros

Connects software to real infrastructure, failure domains and networks.
Essential for incident response, security and capacity reviews.
Makes single points of failure easy to spot.
Shows exactly which version of which artifact runs where.
Readable by operations staff who never read class diagrams.
Pairs naturally with infrastructure-as-code reviews.

Cons

Goes stale fast in autoscaling, cloud-native environments.
UML node shapes are often replaced by vendor icon sets in practice.
Instance-level diagrams get huge quickly.
Does not show request flow order (use a sequence diagram).
Network details (subnets, firewalls) need extra conventions.

When to use

Architecture and security reviews.
Runbooks and on-call documentation.
Planning migrations between data centres or clouds.

When not to use

When the platform is fully managed and a vendor diagram already exists.
For logical design questions that do not depend on infrastructure.

6. Reading Tips and Common Mistakes

Trace one user request from the outermost node inward and name the protocol on every hop; any hop you cannot label is a gap in your understanding. Then cover one node with your hand and ask what fails. If the answer is "everything", you have found a single point of failure.

Common mistakes: drawing logical components as if they were nodes; omitting managed services because "the cloud runs them" (they are still failure domains with quotas and network paths); and leaving artifact versions off, which makes the diagram useless during a partial rollout. For cloud work, many teams use the C4 deployment view or provider icon sets; the ideas are the same as UML nodes and artifacts.

7. As Diagrams-as-Code

PlantUML supports node, artifact, database and cloud elements:

@startuml
node Browser
node "ALB" as alb
node "ECS task (AZ a)" as t1 {
  artifact "shop-api:1.4" as a1
}
node "ECS task (AZ b)" as t2 {
  artifact "shop-api:1.4" as a2
}
database "RDS Postgres" as rds
node "ElastiCache Redis" as redis
cloud "S3" as s3
Browser -- alb : HTTPS
alb -- t1
alb -- t2
t1 -- rds
t2 -- rds
t1 -- redis
t1 -- s3
@enduml

Mermaid has no deployment diagram; its architecture-beta diagram or a flowchart with subgraphs is the usual substitute.

UML Diagrams — overview of all 14 UML diagram types and when to use each
Component Diagrams — the logical parts that artifacts manifest
Package Diagrams — how the code inside each artifact is organised
Composite Structure Diagrams — internal structure of one deployed service