Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 68 additions & 49 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,54 +8,56 @@ on:
workflow_dispatch:

jobs:
changes:
# Pattern 3: decide which suites and images this change needs (scripts/ci_changes.py).
# Pull requests run only what they touch; pushes to main and manual runs run everything.
name: What changed
runs-on: ubuntu-latest
outputs:
suites: ${{ steps.plan.outputs.suites }}
images: ${{ steps.plan.outputs.images }}
frontend: ${{ steps.plan.outputs.frontend }}
bicep: ${{ steps.plan.outputs.bicep }}
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
fetch-depth: 0

- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: "3.12"

- name: Plan the jobs
id: plan
env:
# Through env, never pasted into the script: a branch name is user-controlled text.
EVENT: ${{ github.event_name }}
BASE_REF: ${{ github.base_ref }}
run: |
set -euo pipefail
if [ "$EVENT" = "pull_request" ]; then
git diff --name-only "origin/$BASE_REF...HEAD" | tee changed.txt | python scripts/ci_changes.py
else
python scripts/ci_changes.py --all
fi

unit-tests:
name: Unit tests (${{ matrix.suite }})
needs: changes
if: needs.changes.outputs.suites != '[]'
runs-on: ubuntu-latest
strategy:
fail-fast: false
# Each suite gets its own install: gateway/app and every
# service's config.py share top-level module names, so they cannot
# run in one interpreter (see CLAUDE.md, "collision note").
# Built from scripts/service_table.py by scripts/ci_changes.py: one entry per suite to run.
matrix:
include:
- suite: repo-root
requirements: requirements-dev.txt
tests: tests/unit
- suite: gateway
requirements: gateway/requirements.txt
tests: gateway/tests
shared: fastapi
- suite: registry
requirements: registry/requirements.txt
tests: registry/tests
- suite: user
requirements: services/user/requirements.txt
tests: services/user/tests
shared: flask
- suite: catalog
requirements: services/catalog/requirements.txt
tests: services/catalog/tests
shared: flask
contracts: true
- suite: order
requirements: services/order/requirements.txt
tests: services/order/tests
shared: flask
contracts: true
- suite: payment
requirements: services/payment/requirements.txt
tests: services/payment/tests
shared: flask
contracts: true
- suite: inventory
requirements: services/inventory/requirements.txt
tests: services/inventory/tests
shared: flask
contracts: true
include: ${{ fromJSON(needs.changes.outputs.suites) }}
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

- uses: actions/setup-python@v5
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: "3.12"
cache: "pip"
Expand Down Expand Up @@ -83,14 +85,16 @@ jobs:

frontend:
name: Frontend (build)
needs: changes
if: needs.changes.outputs.frontend == 'true'
runs-on: ubuntu-latest
defaults:
run:
working-directory: frontend
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

- uses: actions/setup-node@v4
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: "20"
cache: "npm"
Expand All @@ -106,20 +110,15 @@ jobs:
# Pattern 9. Builds every image exactly as Azure will run it (linux/amd64), starts it, and checks
# it answers /health and does not run as root. Nothing is pushed anywhere.
name: Container image (${{ matrix.image }})
needs: changes
if: needs.changes.outputs.images != '[]'
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
- { image: user, dir: services/user, port: 5101, shared: true }
- { image: catalog, dir: services/catalog, port: 5102, shared: true }
- { image: order, dir: services/order, port: 5103, shared: true }
- { image: payment, dir: services/payment, port: 5104, shared: true }
- { image: inventory, dir: services/inventory, port: 5105, shared: true }
- { image: gateway, dir: gateway, port: 8100, shared: true }
- { image: registry, dir: registry, port: 8500, shared: false }
include: ${{ fromJSON(needs.changes.outputs.images) }}
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

- name: Stage shared package (shop_common)
if: matrix.shared
Expand Down Expand Up @@ -148,10 +147,30 @@ jobs:

bicep:
name: Bicep (build)
needs: changes
if: needs.changes.outputs.bicep == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

# Compiles the templates only; nothing is deployed and no login is needed.
- name: Build main.bicep
run: az bicep build --file infra/bicep/main.bicep --stdout > /dev/null

ci-ok:
# The one check to require before merging. Matrix jobs that a change skips report under names
# that never resolve, so requiring them would block forever; this job always runs and fails
# only if a job that did run failed or was cancelled.
name: CI ok
if: always()
needs: [changes, unit-tests, frontend, containers, bicep]
runs-on: ubuntu-latest
steps:
- name: Every job that ran passed
env:
RESULTS: ${{ join(needs.*.result, ' ') }}
run: |
echo "Job results: $RESULTS"
for result in $RESULTS; do
case "$result" in success|skipped) ;; *) exit 1 ;; esac
done
112 changes: 112 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
name: Deploy

# Pattern 3: the manual "Deploy" button. Nothing deploys on its own: a person presses
# "Run workflow" on main. Rebuilds only the services whose code changed since the commit they run
# (scripts/deploy_plan.py), tags each image with this commit, and updates those Container Apps.
#
# Signs in with OIDC (#8, make github-identity): GitHub asks Azure for a short-lived token, so no
# Azure password exists anywhere. The 3 ids it needs are secrets only so they stay masked in this
# public repo's logs.

on:
workflow_dispatch:

permissions:
id-token: write # to request the OIDC token
contents: read

concurrency:
group: deploy
cancel-in-progress: false

jobs:
deploy:
name: Deploy changed services to Azure
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
fetch-depth: 0 # deploy_plan diffs against the commit each app runs

- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: "3.12"

- name: Sign in to Azure (OIDC, no secret)
uses: azure/login@7184910d9eb2b1c5e48f7073824a90609bb9b6d6 # v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

- name: Find the registry and what each app runs now
id: running
run: |
set -euo pipefail
# Services, folders and resource group all come from scripts/service_table.py.
RESOURCE_GROUP=$(python scripts/deploy_plan.py --resource-group)
echo "RESOURCE_GROUP=$RESOURCE_GROUP" >> "$GITHUB_ENV"
python scripts/deploy_plan.py --services > services.txt
acr=$(az acr list -g "$RESOURCE_GROUP" --query "[0].name" -o tsv)
if [ -z "$acr" ]; then echo "Nothing provisioned in $RESOURCE_GROUP. Run make provision first."; exit 1; fi
echo "acr=$acr" >> "$GITHUB_OUTPUT"
running="{}"
while read -r app _dir; do
image=$(az containerapp show -n "$app" -g "$RESOURCE_GROUP" --query "properties.template.containers[0].image" -o tsv)
tag="${image##*:}"
# 'latest' or anything that is not a commit: unknown, so deploy_plan rebuilds it.
if [[ "$tag" =~ ^[0-9a-f]{7,40}$ ]]; then value="\"$tag\""; else value=null; fi
running=$(jq -c --arg app "$app" --argjson commit "$value" '.[$app] = $commit' <<< "$running")
done < services.txt
echo "$running" > running.json
cat running.json

- name: Decide what to rebuild
id: plan
run: |
set -euo pipefail
head=$(git rev-parse --short=12 HEAD)
services=$(python scripts/deploy_plan.py "$head" < running.json | tr '\n' ' ')
echo "head=$head" >> "$GITHUB_OUTPUT"
echo "services=$services" >> "$GITHUB_OUTPUT"
echo "Deploying commit $head: ${services:-nothing changed}"

- name: Build, push and roll out each changed service
if: steps.plan.outputs.services != ''
env:
ACR: ${{ steps.running.outputs.acr }}
HEAD_SHA: ${{ steps.plan.outputs.head }}
SERVICES: ${{ steps.plan.outputs.services }}
run: |
set -euo pipefail
echo "| Service | Commit | Image size | Health |" >> "$GITHUB_STEP_SUMMARY"
echo "|---|---|---|---|" >> "$GITHUB_STEP_SUMMARY"
for svc in $SERVICES; do
dir=$(awk -v s="$svc" '$1 == s {print $2}' services.txt)
cp -r shared "$dir/_shared"
az acr build --registry "$ACR" --resource-group "$RESOURCE_GROUP" \
--image "$svc:$HEAD_SHA" --build-arg "GIT_SHA=$HEAD_SHA" --platform linux/amd64 "$dir"
rm -rf "$dir/_shared"
size=$(az acr manifest show --registry "$ACR" --name "$svc:$HEAD_SHA" -o json | python scripts/deploy_plan.py --size)
az containerapp update -n "$svc" -g "$RESOURCE_GROUP" \
--image "$ACR.azurecr.io/$svc:$HEAD_SHA" --set-env-vars "IMAGE_SIZE_MB=${size:-0}" -o none
# "Update accepted" is not "running": wait until the service itself answers with the
# new commit (this also wakes a scaled-to-zero app). A crash-looping revision fails the run.
fqdn=$(az containerapp show -n "$svc" -g "$RESOURCE_GROUP" --query properties.configuration.ingress.fqdn -o tsv)
running=""
for attempt in $(seq 1 30); do
running=$(curl -sf --max-time 10 "https://$fqdn/debug/runtime" | jq -r .git_sha || true)
[ "$running" = "$HEAD_SHA" ] && break
sleep 10
done
if [ "$running" != "$HEAD_SHA" ]; then
echo "::error::$svc did not answer with $HEAD_SHA within 5 minutes (last seen: ${running:-nothing})"
exit 1
fi
echo "| $svc | \`$HEAD_SHA\` | ${size:-?} MB | answering |" >> "$GITHUB_STEP_SUMMARY"
done

- name: Nothing to deploy
if: steps.plan.outputs.services == ''
run: echo "Every service already runs ${{ steps.plan.outputs.head }}." >> "$GITHUB_STEP_SUMMARY"
18 changes: 16 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA
(FastAPI), `registry/` (FastAPI), `shared/` (`shop_common`), `contracts/`, `frontend/`, `infra/`,
`scripts/`, `tests/`.
- **One service table**: `scripts/service_table.py` lists every local process, folder and port, plus
`REPLICA_PORTS` (order also on 5113) and `CONTRACT_SUITES`. `setup.py`, `run_local.py`,
`REPLICA_PORTS` (order also on 5113), `CONTRACT_SUITES`, each service's `azure`/`shared` flags,
`AZURE_SERVICES` and `AZURE_RESOURCE_GROUP`. CI matrices, provision and the Deploy workflow read it. `setup.py`, `run_local.py`,
`provision.py` and the smoke tests all read it. Add a service there.
- Ports: user 5101, catalog 5102, order 5103 + 5113, payment 5104, inventory 5105, gateway 8100,
registry 8500, Redis 6390, frontend 5273.
Expand All @@ -47,7 +48,20 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA
- Background threads (heartbeat, relay, consumer) start only where `is_serving_process(app)` is true:
Flask's debug reloader runs a watcher plus a worker, and both build the app.
- Containers (pattern 9): multi-stage Dockerfiles, uid 10001, `.dockerignore` per service, `GIT_SHA`
build arg, `/debug/runtime`. CI job "Container image" builds, runs and checks all 7 images.
build arg, `/debug/runtime` (also `image_size_mb` from `IMAGE_SIZE_MB`). CI job "Container image"
builds, runs and checks the images a change touches.
- CI-CD (pattern 3, M3b): `scripts/ci_changes.py` turns changed files into the CI matrices (suites,
images, frontend, bicep) from the service table. `.github/workflows/deploy.yml` is manual, main
only, OIDC via `infra/github_identity.py` (`make github-identity`, run by the owner; ids stored as
GitHub secrets so they stay masked in public logs); `scripts/deploy_plan.py` picks services whose
code changed since their running commit (CI-only files rebuild nothing) and waits until each service
answers `/debug/runtime` with the new commit. All workflow actions are pinned to commit SHAs. "CI ok"
is the one job to require in branch protection.
- Azure (M3b): provision keeps `image_tag`, `image_sizes` and `jwt_key_b64` in infra/.state.json so
`--skip-build` and re-runs neither break image pulls nor log users out. It tags images with the 12-char commit, imports `redis:7.4-alpine` into ACR,
generates the JWT key (`openssl`, passed base64 as a secure param, user reads `JWT_PRIVATE_KEY_B64`),
and re-grants the deploy identity's role on the new resource group. Redis is an internal TCP app
(`redis://redis:6379/0`), 1 replica; `make resume` keeps it at exactly 1. Registry is not deployed.
- **`shop_common`** (`shared/`): every service calls `shop_common.flask_support.install(app, name, db)`
inside its app context. It adds `/health`, `/health/db`, `/debug/spans`, `/metrics`,
`POST /debug/crash` (only with `CHAOS_ENABLED=1`), the `X-Instance-Id` header, tracing, JSON logs,
Expand Down
6 changes: 5 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
.PHONY: setup run provision pause resume teardown verify test contracts smoke clean
.PHONY: setup run github-identity provision pause resume teardown verify test contracts smoke clean

setup:
python3.12 scripts/setup.py

run:
python3.12 scripts/run_local.py

# Once, by the owner (#8): the Azure identity the Deploy workflow signs in as. No secrets created.
github-identity:
python3.12 infra/github_identity.py

provision:
python3.12 infra/provision.py --budget-email "$(BUDGET_EMAIL)" $(ARGS)

Expand Down
25 changes: 21 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,24 @@ collector. Without it, traces stay in each process's memory and the Observabilit

## Cloud

Azure Container Apps (one app per service plus the gateway, all scale-to-zero) + MySQL Flexible
Server, provisioned with `make provision` and removed with `make teardown`. About $0.21 for an
8-hour session. See [cost_estimate.md](cost_estimate.md). Nothing from M1, M2 or M3a has been deployed
yet. In Azure, discovery uses Container Apps DNS (no registry), and the demo switches stay off.
Azure Container Apps (one app per service plus the gateway, all scale-to-zero; Redis as an
always-on internal bus) + MySQL Flexible Server. About $0.21 for an 8-hour session; see
[cost_estimate.md](cost_estimate.md). In Azure, discovery uses Container Apps DNS (no registry), and
the demo switches stay off. Redis is reachable only from apps inside the environment and has no
password, which is fine for a demo where every app is ours. Nothing has been deployed yet: the first
Azure run is issue #11.

```bash
make github-identity # once: the Azure identity the Deploy workflow uses (OIDC, no secret)
make provision BUDGET_EMAIL=you@example.com # everything, images tagged with the current commit
# then GitHub → Actions → Deploy → Run workflow: rebuilds only the services that changed
make teardown && make verify # remove everything, then prove nothing is left
```

### CI-CD (pattern 3)
- **CI on every pull request** runs only what the change touches (`scripts/ci_changes.py`, driven
by the service table): a change to one service runs its tests and its image; a change to shared
code, CI or the service table runs everything. Pushes to main run everything.
- **Deploy** is a manual workflow on main. It signs in to Azure with OIDC (no password stored),
rebuilds only services whose code changed since the commit they run, tags each image with the
commit, and records each image's size.
6 changes: 5 additions & 1 deletion cost_estimate.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,15 @@ locally (plain Python/Node processes, SQLite, zero Docker, zero Azure) at **$0 c
| Azure Database for MySQL Flexible Server | **Burstable B1ms** (1 vCore/2GiB), single server hosting 4 logical databases (monolith_db, user_db, product_db, order_db) provisioned upfront | Cheapest managed MySQL tier (no free tier exists for managed MySQL); sharing one server across 4 logical DBs avoids paying for 4 separate servers (documented tradeoff: less isolation than 4 servers, acceptable for a demo) | $0.019 (compute) | $0.15 | **~$14.50** (compute + 20GB storage) | SQLite (already used for local dev; not used in Azure to keep the "real MySQL in prod" story) |
| Azure Static Web Apps | **Free tier** | 100GB bandwidth/mo, 1GB storage, free SSL | $0 | $0 | **$0** | N/A — already free |
| Application Insights / Log Analytics | Pay-as-you-go, workspace-based | First 5GB/day ingestion free; demo-scale traffic stays inside this | $0 | $0 | **~$0** | N/A |
| Redis Container App (event bus, M3a/M3b) | **Consumption plan, 0.25 vCPU / 0.5 GiB, exactly 1 replica** (never scales to zero: undelivered events live in its memory) | Azure Cache for Redis starts near $16/mo; a Container App inside the same environment, internal TCP only, costs nothing within the monthly free grant | ~$0 (free grant) | **$0** (7,200 vCPU-s and 14,400 GiB-s, inside the free grant) | **~$4 idle to ~$14 busy** (after the 180,000 vCPU-s / 360,000 GiB-s free grant; consumption rates of about $0.000003 idle or $0.000024 active per vCPU-s and $0.000003 per GiB-s, re-check before provisioning) | None cheaper for an always-on bus; `make pause` scales it to 0 |
| Cost Management budget alert | n/a | Free, created by `provision.py` before any billable resource | $0 | $0 | $0 | — |
| Contributor role assignment (bff's managed identity, scoped to this one resource group only) | n/a | Free — control-plane only, lets the bff create the microservices' Container Apps itself during a live migration | $0 | $0 | $0 | — |

**Total estimated cost for an 8-hour test session: ~$0.21**
**Total estimated cost if resources are accidentally left running for 30 days: ~$19.51**
**Total estimated cost if resources are accidentally left running for 30 days: ~$19.51 before M3b,
~$24 to ~$34 with the always-on Redis (M3b).** The upper end is above the $25/month budget alert,
which then fires: that is the alert doing its job. Run `make teardown` (or at least `make pause`)
after every session.

These figures are **unchanged** from the original estimate — the only thing that changed is *when*
each Container App gets created (monolith + bff at `make provision`; user-/product-/order-service
Expand Down
1 change: 1 addition & 0 deletions frontend/src/api/gatewayClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,7 @@ export interface RuntimeInfo {
arch?: string;
python?: string;
git_sha?: string;
image_size_mb?: number | null;
unreachable?: boolean;
}

Expand Down
Loading
Loading