Microservice Patterns
Bulkhead
Split resources into isolated compartments so one slow or failing dependency can exhaust only its own share — and everything else keeps working.
What you will learn
- Explain how a shared worker pool turns one slow dependency into a full outage.
- Size per-dependency limits and decide between rejecting and waiting.
- Compare semaphore, thread-pool and deployment-level bulkheads.
- Configure a Resilience4j bulkhead in Spring Boot.
Before you start
Overview
Ships are divided into watertight compartments called bulkheads. If the hull is breached, only one compartment floods and the ship stays afloat. In software, the "water" is waiting requests and the compartments are separate pools of threads, connections or instances.
A bulkhead caps how much of a shared resource one consumer may use. Instead of every outbound call drawing from the same worker pool, each dependency gets its own limit. When a dependency becomes slow, its calls hit the limit and are rejected immediately, while workers remain free for everything else.
The problem: one pool, one point of failure
A Shop API has 10 worker threads. Most requests are checkouts that call Payment; some are reports that call a heavy Reports service. When Reports slows down, each report request holds a worker for seconds. Within moments all 10 workers are waiting on Reports — and checkouts, which never touch Reports, have no worker left.
Run it
Compare Checkouts failed between the two scenarios. In B, open the inspector on the Reports bulkhead and change its size: too small rejects reports that could have succeeded, too large lets them starve the pool again.
Kinds of bulkheads
| Kind | How it isolates | Cost |
|---|---|---|
| Semaphore | Counts concurrent calls per dependency on the caller's thread; extra calls are rejected or wait briefly. | Very cheap. Does not protect against a call that blocks forever — pair it with a timeout. |
| Thread pool | Each dependency runs on its own small thread pool and queue. | Extra threads and context switches, but a hung call cannot block the request thread. |
| Connection pool | Separate database or HTTP connection pools per dependency or tenant. | More connections to manage. |
| Deployment | Separate instances (or clusters) for critical and non-critical workloads, or per tenant. | More infrastructure; strongest isolation. |
Implementation with Resilience4j
resilience4j:
bulkhead:
instances:
reports:
max-concurrent-calls: 3
max-wait-duration: 0 # reject immediately when full
payment:
max-concurrent-calls: 8
max-wait-duration: 20ms@Service
class ReportsClient {
private final RestClient reports;
ReportsClient(RestClient.Builder builder) {
this.reports = builder.baseUrl("http://reports-service").build();
}
@Bulkhead(name = "reports", fallbackMethod = "reportBusy")
public Report salesReport(ReportQuery query) {
return reports.post().uri("/sales").body(query).retrieve().body(Report.class);
}
private Report reportBusy(ReportQuery query, BulkheadFullException ex) {
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "Reports are busy, try again shortly");
}
}Advanced For blocking calls that may hang, prefer @Bulkhead(type = Bulkhead.Type.THREADPOOL) together with @TimeLimiter: the work runs on a dedicated pool (resilience4j.thread-pool-bulkhead.instances.reports.max-thread-pool-size, queue-capacity), so the request thread can give up after the timeout even if the pool thread stays stuck.
Trade-offs
| Benefits | Costs | |
|---|---|---|
| Availability | A failing dependency affects only the features that need it. | Requests over the limit are rejected even when other pools are idle. |
| Efficiency | Predictable resource use per dependency. | Partitioned pools waste capacity compared with one shared pool. |
| Operations | Clear signal: bulkhead rejections point at the slow dependency. | Limits need tuning and revisiting as traffic changes. |
Production considerations
- Combine with Timeout and Circuit Breaker: the bulkhead limits concurrency, the timeout limits duration, the breaker stops calling.
- Isolate by criticality, not just by dependency: checkout traffic should never compete with batch exports.
- Monitor available permits and rejections per bulkhead (
resilience4j_bulkhead_available_concurrent_calls).