PlantUML deployment diagrams: blue-green, canary, and rolling deployments

Deployment diagrams describe the physical structure of your software — which servers, containers, and networks it runs on. PlantUML’s deployment view precisely captures servers, containers, network topology, and deployment strategies.

What is a Deployment Diagram

A deployment diagram shows how software is physically deployed — which servers/containers it runs on, whether there’s a load balancer, where the database lives. It answers “how does this system actually run.”

Compared to:

Component diagram: describes relationships between software modules (logical structure)
Deployment diagram: describes hardware/container/network topology (physical structure)

Use cases: architecture design reviews, ops handoffs, incident postmortems, technical spec documents.

Minimal Deployment Diagram

@startuml
skinparam componentStyle rectangle

node "Web Server" {
    component "Frontend" as fe
}

node "API Server" {
    component "Backend" as be
}

database "PostgreSQL" as db

fe --> be : HTTPS
be --> db : SQL
@enduml

node = physical node (server/container)
component = software component
--> = connection arrow
database = database node (special shape)

Blue-Green Deployment

Blue-green uses two identical production environments (blue + green). Traffic switches atomically at the load balancer; rollback = switch back.

@startuml
skinparam componentStyle rectangle

title Blue-Green Deployment

node "Load Balancer" as lb {
    component "Nginx"
}

node "Blue Environment v1.0" as blue {
    component "App-Blue" as app_blue
    component "Worker-Blue" as w_blue
}

node "Green Environment v1.1" as green {
    component "App-Green" as app_green
    component "Worker-Green" as w_green
}

database "Redis" as redis
database "PostgreSQL" as db

lb -[#green,dashed]-> app_green : Traffic → Green\n(after switch)
lb -[#blue, bold]-> app_blue : Traffic → Blue\n(current prod)

app_blue --> redis
app_blue --> db
app_green --> redis
app_green --> db
@enduml

Key points:

Both environments are identical except for version
Switch happens at the load balancer (change upstream config)
Switch is atomic — users don’t notice
Rollback = switch traffic back to old environment

Canary Release

Canary gradually shifts traffic from old to new version — 5% first, observe, then expand.

@startuml
skinparam componentStyle rectangle

title Canary Release

node "Load Balancer" as lb {
    component "Nginx"
}

node "Old version v1.0" as old {
    component "App v1.0" as app_old
    note bottom: 95% traffic\ncurrent prod
}

node "New version v1.1 (Canary)" as new {
    component "App v1.1" as app_new
    note bottom: 5% traffic\ncanary test
}

database "Shared DB" as db

lb --> app_old : 95%
lb -[#red,dashed]--> app_new : 5% (Canary)
promote criteria:\n- Error rate < 0.1%\n- P99 < 200ms

app_old --> db
app_new --> db
@enduml

Key points:

Traffic split at the load balancer (Nginx upstream weight)
Monitor: error rate, latency, business metrics
Promote criteria written in diagram as notes for the team
Safer than blue-green — canary failure only affects 5% of users

Rolling Deployment

Rolling upgrades replace instances one at a time within the same pool, managed by Kubernetes ReplicaSet:

@startuml
skinparam componentStyle rectangle

title Rolling Deployment

node "Kubernetes Cluster" as k8s {
    node "Pod-1 (v1.0 → v1.1)" as pod1 {
        component "App v1.0"
    }
    node "Pod-2 (v1.0)" as pod2 {
        component "App v1.0"
    }
    node "Pod-3 (v1.0)" as pod3 {
        component "App v1.0"
    }
}

node "Service" as svc {
    component "K8s Service\n(type: LoadBalancer)"
}

database "Backend DB" as db

svc --> pod1
svc --> pod2
svc --> pod3
pod1 --> db
pod2 --> db
pod3 --> db
@enduml

Key points:

Some Pods are old version, some are new during rollout
Advantage: no double the resources needed
Disadvantage: version coexistence period has compatibility risks
Kubernetes default: 25% maxUnavailable + 25% maxSurge

Kubernetes Deployment Topology

@startuml
skinparam componentStyle rectangle
skinparam nodesep 50
skinparam ranksep 50

title Kubernetes Deployment Architecture

node "Cloud / AWS" {
    node "Region: us-east-1" {
        node "Namespace: production" {
            
            node "Ingress" {
                component "Nginx Ingress"
            }
            
            node "Frontend" {
                component "Deployment\nfrontend-v3\nReplicas: 3" as fe
                component "Service\nClusterIP" as fe_svc
            }
            
            node "API Gateway" {
                component "Deployment\napi-gateway\nReplicas: 2" as api
                component "Service\nClusterIP" as api_svc
            }
            
            node "Backend" {
                component "Deployment\nbackend-v2\nReplicas: 3" as be
                component "Service\nClusterIP" as be_svc
            }
            
            database "Database Tier" {
                database "RDS PostgreSQL\nMulti-AZ" as rds
                database "ElastiCache Redis\nCluster mode" as redis
            }
        }
    }
}

Ingress --> fe
fe --> api_svc
api_svc --> api
api --> be_svc
api --> rds
api --> redis
be --> be_svc
be --> rds
be --> redis
@enduml

Notation Best Practices

Node hierarchy

1	Cloud Provider > Region > VPC/Namespace > AZ > Node > Pod > Container > Process

Draw to Pod level (container granularity) — don’t go to process level.

Connection line semantics

@startuml
A --> B : synchronous call
A ->> B : async message
A o-- oB : weak dependency
A *-- B : composition (lifecycle-bound)
A ..> B : dependency (no reference held)
@enduml

Color semantics

Color	Meaning
Red dashed	New version / Canary
Green dashed	Standby environment
Blue solid	Current production traffic
Orange	Alert / special handling

Deployment vs C4 Deployment Diagram

Dimension	PlantUML Deployment	C4 Deployment
Granularity	precise (node + component)	abstract (system/container/component)
Standard	UML	C4 model (non-UML)
K8s support	native	requires PlantUML C4 lib
Readability for complex diagrams	gets messy	C4 is cleaner
Best audience	Ops / DevOps	Architects / product

Architects and PMs → C4 Deployment. Ops and DevOps → PlantUML Deployment (more precise).

Common Errors

Error	Cause	Fix
Node not rendering	`node` spelling error	Check `node "name" as alias` syntax
Connection lines messy	default auto layout	Add `skinparam linetype ortho`
Component outside node	component not inside node block	Move component declaration inside the node block
Dashed becoming solid	`-->` vs `..>` mixed up	`-->` is solid, `..>` is dashed

Recap

4 things to remember:

node = physical/container node, component = software component, database = database
Blue-green = two environments + load balancer atomic switch, cheap rollback
Canary = traffic split (5% → 30% → 100%), safer with observation
Rolling = same pool, replace one at a time, K8s-native, needs compatibility consideration

Deployment diagram convention: hierarchy cloud → Region → Namespace → Pod; line semantics clear (sync/async/dependency); use color to distinguish old vs new versions.