Introduction
When building a modern container environment using Podman, one of the most confusing topics for many engineers is deciding when to use pods, when to use networks, and how to structure services that talk to each other. After all, microservices often depend on one another — APIs talk to APIs, backend apps talk to databases, dashboards talk to internal services — and it’s not immediately clear what should go where.
This post breaks down a simple, clear set of rules and mental models to help you architect a Podman-driven environment without confusion, misconfiguration, or future headaches.
1. The Most Important Rule: Pods ≠ Grouping
A Podman pod is not a grouping mechanism for related services.
A pod is only useful when containers must share the same network namespace, which includes:
- Same IP address
- Same localhost
- Same port space
- Same network stack
- Same lifecycle
In other words, a pod represents a set of containers that behave almost like a single application process.
Use a pod only when services must share localhost or ports.
Typical examples:
- Jenkins master + Jenkins agent
- Application + sidecar (logging, metrics, proxy)
- A tightly coupled subsystem that must restart together
If you are simply running multiple services that talk over REST or TCP, they should not share a pod.
2. Networks Are the Real Way to Connect Services
Networks in Podman act like VLANs or virtual switches. Containers placed on the same network can communicate freely, even if they belong to different pods or are not in pods at all.
Use networks to:
- Group frontend-facing services
- Isolate backend databases
- Connect APIs that depend on each other
- Restrict access by attaching services to only the networks they need
Networks can be attached to individual containers or pods, making them extremely flexible. But if you assign a network to a pods, don’t attach network to that pods containers, that will cause conflict as all containers inside a pod inherits that pods networks.
3. REST Dependencies Do Not Justify Pods
A common misunderstanding is:
“My WebAPI1 calls WebAPI2, and WebAPI1 also calls WebAPI3, so maybe they all need to be in the same pod?”
The answer is: No. Absolutely not.
REST is remote communication by design.
REST implies:
- Independent lifecycles
- Separate logs
- Independent failure domains
- Separate scaling
- Independent restarts
- Clear network boundaries
Putting multiple REST APIs in the same pod:
- Creates tight coupling where none should exist
- Forces them to share networks unnecessarily
- Makes restarts ripple across unrelated services
- Breaks the microservice architecture model
If services talk over REST → they must NOT share a pod.
They simply need to be placed on the same network (usually i.e. backend-net).
4. UI Services Often Need Two Networks
Some services provide a user interface and require backend access (like databases). Examples include:
- pgAdmin
- Mathesar
- phpMyAdmin
- Admin dashboards
- Jenkins (in some architectures)
These services often need:
- frontend-net → for user/browser access
- backend-net → for database/API communication
This dual-network classification is clean, secure, and easy to reason about.
5. Jenkins Talking to Postgres — What Happens?
Jenkins is typically placed in a pod only because Jenkins master and Jenkins agent tightly depend on each other.
If Jenkins needs to connect to a backend database such as Postgres, the fix is simple:
Attach the Jenkins pod to both networks:
frontend-net
backend-net
This allows:
- Jenkins UI to remain public
- Jenkins pipelines & services to access internal databases
- Postgres to stay fully private on backend-net only
Podman networks are flexible, and this dual-network model is entirely valid.
6. Putting It All Together: A Clean Architecture
Here’s the recommended layout for a multi-service environment:
Pods
- PodA: Jenkins master + Jenkins agent
- No other pods needed (unless using sidecars)
Networks
- frontend-net: UIs, dashboards, publicly accessed services
- backend-net: databases, internal APIs, backend services
Service Placement
| Service | Pod? | frontend-net | backend-net |
|---|---|---|---|
| Jenkins | Yes | ✓ | ✓ |
| Jenkins Agent | Yes | ✓ | ✓ |
| Postgres | No | – | ✓ |
| pgAdmin | No | ✓ | ✓ |
| Mathesar | No | ✓ | ✓ |
| WebAPI1 | No | – | ✓ |
| WebAPI2 | No | – | ✓ |
| WebAPI3 | No | – | ✓ |
This model is simple, scalable, secure, and completely aligned with container best practices.
7. Final Guidelines
To summarize the rules: