Module 2: Service Boundaries, Runtime Isolation, and Containers

Module Overview

Module 1 introduced partial failure and network uncertainty. Module 2 makes those ideas concrete by separating two small services into independent runtime units.

The central question is: what makes two services truly independent rather than merely two pieces of code in the same project? Containers give us a practical way to explore that question, but the course focus is not Docker trivia. The focus is distributed-systems reasoning: boundaries, configuration, deployment independence, failure isolation, observability, and operational judgment.

Why This Topic Matters

Enterprise systems depend on services that can be deployed, restarted, scaled, and debugged independently. If Service A and Service B always ship as one unit, share hidden configuration, and fail together, they are not operationally independent even if their source code lives in different folders.

Containers help teams make boundaries explicit. They package runtime dependencies, define entry points, expose ports, attach networks, set environment variables, and create a repeatable way to start each service. That repeatability is what lets us test partial failure in class instead of only talking about it.

Required Preparation

• Review Module 1’s discussion of partial failure and lost responses.
• Install Docker Desktop, Docker Engine, Podman, or another instructor-approved OCI-compatible runtime.
• Confirm that you can run docker --version or an equivalent runtime command.
• Bring your Module 1 Service A and Service B notes or starter code.
• Skim the Dockerfile and networking references listed at the end.

Process Boundaries and Service Boundaries

A process boundary means the operating system can run two programs separately. A service boundary means the system can treat a component as an independently owned, configured, deployed, observed, and failed unit.

Two processes on one host can still be tightly coupled if they share a deploy step, assume local filesystem paths, depend on hardcoded ports, or cannot be restarted independently. A useful service boundary makes those assumptions visible and controllable.

flowchart LR
  host[Host machine]
  procA[Service A process]
  procB[Service B process]
  shared[Shared runtime config]
  host --> procA
  host --> procB
  procA --> shared
  procB --> shared

Runtime Isolation with Containers

A container is not a tiny virtual machine. It is a process with controlled runtime isolation. The container runtime gives it a filesystem view, environment, network namespace, user settings, and resource constraints. That makes it easier to reproduce and inspect service behavior.

flowchart LR
  runtime[Container runtime]
  net[Shared container network]
  containerA[Container for Service A]
  containerB[Container for Service B]
  imageA[Image A]
  imageB[Image B]
  runtime --> containerA
  runtime --> containerB
  imageA --> containerA
  imageB --> containerB
  containerA --> net
  containerB --> net

Image Versus Container

An image is the artifact you build. A container is what runs. The same image can produce many containers with different environment variables, ports, networks, names, or storage attachments.

flowchart LR
  source[Source code]
  deps[Dependency file]
  dockerfile[Container definition]
  image[Container image]
  runtime[Container runtime]
  c1[Container instance one]
  c2[Container instance two]
  source --> image
  deps --> image
  dockerfile --> image
  image --> runtime
  runtime --> c1
  runtime --> c2

Ports, Networks, and Service Names

Published ports make a container reachable from the host. Container networks let containers call each other. The distinction matters because localhost changes meaning depending on where the code runs.

flowchart LR
  browser[Browser]
  host[Host port 8080]
  container[Service A container]
  app[App listens on port 5000]
  browser --> host
  host --> container
  container --> app

flowchart LR
  net[Shared container network]
  serviceA[Service A container]
  serviceB[Service B container]
  endpoint[service-b port 5001]
  serviceA --> net
  net --> endpoint
  endpoint --> serviceB

Configuration and Secret Boundaries

Hardcoded endpoint URLs make a service brittle. A service should learn the location of its dependencies through runtime configuration. In this module, simple environment variables are enough. In production systems, secrets should come from a protected secret-management path rather than source code, image layers, or copied local files.

flowchart TB
  image[Image with code and dependencies]
  env[Environment variables]
  secrets[Secret source]
  container[Running container]
  risk[Do not copy secrets into image]
  image --> container
  env --> container
  secrets --> container
  secrets -.-> risk

Partial Failure, Health, and State

When Service B stops, Service A may still be healthy. That does not mean the whole workflow is healthy. Service A must decide whether to return a controlled error, retry, degrade, or queue work for later. The logs should tell that story clearly.

flowchart LR
  client[Client]
  serviceA[Service A running]
  serviceB[Service B stopped]
  logs[Logs]
  client --> serviceA
  serviceA -. request fails .-> serviceB
  serviceA --> logs

flowchart LR
  runtime[Container runtime]
  check[Health check]
  unhealthy[Marked unhealthy]
  restart[Restart container]
  healthy[Healthy again or still failing]
  runtime --> check
  check --> unhealthy
  unhealthy --> restart
  restart --> healthy

flowchart LR
  c1[Running container]
  temp[Ephemeral container storage]
  volume[Persistent volume]
  c2[Replacement container]
  c1 --> temp
  c1 --> volume
  temp -. lost on remove .-> c2
  volume --> c2

Worked Example

Suppose Service A exposes a public endpoint on host port 8080 and calls Service B on the shared container network.

1. Build an image for Service A.
2. Build an image for Service B.
3. Create a shared network.
4. Run Service B with name service-b.
5. Run Service A with SERVICE_B_URL=http://service-b:5001.
6. Publish Service A from container port 5000 to host port 8080.
7. Stop Service B and call Service A again.
8. Inspect Service A logs to explain the partial failure.

The important idea is not the exact command syntax. The important idea is that Service A now depends on a network-visible service name and a configured endpoint, not a hardcoded localhost assumption.

In-Class Discussion Prompts

• When does a code module become a service?
• What should Service A return when Service B is stopped?
• What does a health check need to prove?
• What state should survive a container restart?
• Which Dockerfile choices change the security boundary?

Lab: Containerizing Independent Services

This lab builds on the Module 1 Service A and Service B exercise. You will containerize both services, run them independently, connect them through a shared container network, observe partial failure, and explain what recovered and what did not.

Lab Objectives

• Containerize Service A.
• Containerize Service B.
• Run each service independently.
• Connect services through a shared container network.
• Configure the Service B endpoint through an environment variable.
• Stop one service and observe partial failure.
• Restart the service and observe recovery.
• Inspect logs.
• Explain what data or state was lost.
• Document one improvement for graceful failure handling.

Prerequisites

• Docker, Podman, or another approved OCI-compatible runtime.
• A terminal and text editor.
• Two small HTTP services from the Module 1 activity, or the baseline Flask structure below.
• Basic comfort running commands from a project folder.

Expected Folder Structure

module-02-lab/
+-- service-a/
|   +-- app.py
|   +-- requirements.txt
|   +-- Dockerfile
|   +-- .dockerignore
+-- service-b/
|   +-- app.py
|   +-- requirements.txt
|   +-- Dockerfile
|   +-- .dockerignore
+-- compose.yaml

Baseline Service A

import os
import requests
from flask import Flask, jsonify

app = Flask(__name__)
service_b_url = os.environ.get("SERVICE_B_URL", "http://service-b:5001")

@app.get("/health")
def health():
    return jsonify(status="ok", service="a")

@app.get("/call-b")
def call_b():
    try:
        response = requests.get(f"{service_b_url}/health", timeout=2)
        return jsonify(service="a", dependency=response.json())
    except requests.RequestException as exc:
        app.logger.warning("dependency failure: %s", exc)
        return jsonify(service="a", dependency="unavailable"), 503

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Baseline Service B

from flask import Flask, jsonify

app = Flask(__name__)

@app.get("/health")
def health():
    return jsonify(status="ok", service="b")

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5001)

Requirements Files

Use explicit dependency versions where reasonable.

Flask==3.0.3
requests==2.32.3

Service B does not need requests unless your version of Service B calls another dependency.

Sample Dockerfile

Use one Dockerfile per service. Adjust the port and dependency list for each service.

FROM python:3.12-slim

WORKDIR /app

RUN useradd --create-home --shell /usr/sbin/nologin appuser

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

USER appuser

EXPOSE 5000

HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:5000/health', timeout=2)"

CMD ["python", "app.py"]

For Service B, expose and check port 5001.

Sample .dockerignore

__pycache__/
.venv/
.env
.git/
*.pyc

Build Images

docker build -t cmpe273-service-a:week2 ./service-a
docker build -t cmpe273-service-b:week2 ./service-b

Create a Network

docker network create cmpe273-week2

Run Service B

docker run --rm \
  --name service-b \
  --network cmpe273-week2 \
  -p 5001:5001 \
  cmpe273-service-b:week2

Open another terminal before starting Service A.

Run Service A

docker run --rm \
  --name service-a \
  --network cmpe273-week2 \
  -e SERVICE_B_URL=http://service-b:5001 \
  -p 8080:5000 \
  cmpe273-service-a:week2

Call Service A from the host:

curl http://localhost:8080/health
curl http://localhost:8080/call-b

Demonstrate Partial Failure

Stop Service B:

docker stop service-b

Call Service A again:

curl -i http://localhost:8080/call-b

Expected observation: Service A still responds, but the dependency call fails with a controlled 503 response. Inspect logs:

docker logs service-a

Restart Service B and observe recovery:

docker run --rm \
  --name service-b \
  --network cmpe273-week2 \
  -p 5001:5001 \
  cmpe273-service-b:week2

Optional Compose Configuration

services:
  service-a:
    build: ./service-a
    ports:
      - '8080:5000'
    environment:
      SERVICE_B_URL: http://service-b:5001
    depends_on:
      - service-b
  service-b:
    build: ./service-b
    ports:
      - '5001:5001'

Run with:

docker compose up --build

Checkpoints

• Service A and Service B images build successfully.
• Each service runs in its own container.
• Service A reaches Service B by service name on a shared network.
• Service A remains reachable when Service B stops.
• Service A logs the dependency failure.
• You can explain whether any state was lost.

Common Errors

• Using localhost from Service A to reach Service B.
• Publishing the wrong host or container port.
• Forgetting to attach both containers to the same network.
• Copying a local .env file into the image.
• Running as root without a reason.
• Writing state only to the container filesystem and expecting it to survive removal.
• Adding a health check that tests the wrong port.

Troubleshooting Guidance

• Use docker ps to confirm containers and published ports.
• Use docker logs service-a and docker logs service-b to inspect behavior.
• Use docker network inspect cmpe273-week2 to confirm network membership.
• Rebuild after Dockerfile or dependency changes.
• Check that Flask binds to 0.0.0.0, not only 127.0.0.1.
• Confirm that Service A uses SERVICE_B_URL=http://service-b:5001.

Cleanup Commands

docker stop service-a service-b
docker network rm cmpe273-week2
docker image rm cmpe273-service-a:week2 cmpe273-service-b:week2

If you used Compose:

docker compose down

Reflection Questions

• What changed when Service A stopped assuming localhost?
• What evidence showed that Service A remained available during Service B failure?
• Did restart equal recovery? Why or why not?
• What state would be lost if a container were removed?
• What would you change before running this design in production?
• What AI-generated Dockerfile issue would you check first?

Submission Guidance

Submit the required lab artifacts in Canvas when the assignment is released. Do not submit through this portal.

Connection to the Semester Project

Every final project must include at least three independently deployable components. Module 2 starts that path by making independence visible at runtime. Your project should eventually explain each component’s deployment unit, configuration boundary, persistent state, health behavior, failure mode, and security or trust boundary.

Connection to Agentic Systems

Agentic systems often coordinate multiple tools, APIs, model endpoints, memory stores, approval gates, and observability services. Container boundaries help teams test whether an agent can degrade safely when a tool is unavailable, whether risky actions require human approval, and whether logs can reconstruct a multi-step workflow.